@bubblebrain-ai/bubble 0.0.63 → 0.0.65

package/dist/context/session-write-lock.js

@@ -0,0 +1,162 @@
+import { randomUUID } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { writeFileSync, linkSync, readFileSync, unlinkSync } from "node:fs";
+function ownerPid(token) {
+    const pid = Number(token.split(":")[0]);
+    return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+}
+function deadOwner(token) {
+    const pid = ownerPid(token);
+    if (pid === undefined)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return false;
+    }
+    catch (error) {
+        return error.code === "ESRCH";
+    }
+}
+/** 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 function processStartId(pid) {
+    try {
+        if (process.platform === "linux") {
+            return linuxStartId(readFileSync(`/proc/${pid}/stat`, "utf8"), readFileSync("/proc/sys/kernel/random/boot_id", "utf8"));
+        }
+        if (process.platform === "win32")
+            return undefined;
+        // lstart is rendered in the caller's locale and time zone. Owner and
+        // contender can be different hosts (terminal TUI vs GUI desktop) with
+        // different environments, so pin both or a live owner looks recycled.
+        return execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+            encoding: "utf8", timeout: 2_000, stdio: ["ignore", "pipe", "ignore"],
+            env: { PATH: process.env.PATH ?? "/bin:/usr/bin", LC_ALL: "C", TZ: "UTC" },
+        }).trim() || undefined;
+    }
+    catch {
+        return 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 function linuxStartId(stat, bootId) {
+    const startTicks = stat.slice(stat.lastIndexOf(")") + 2).split(" ")[19];
+    return startTicks && bootId.trim() ? `${bootId.trim()}/${startTicks}` : undefined;
+}
+let ownStartId = null;
+function ownerToken() {
+    if (ownStartId === null)
+        ownStartId = processStartId(process.pid);
+    // Start ids contain ":" (ps lstart) — keep pid and uuid as the leading fields.
+    return `${process.pid}:${randomUUID()}${ownStartId ? `:${ownStartId}` : ""}`;
+}
+/** The pid is alive but belongs to a different process than the one that took
+ * the lock. Elapsed age is deliberately NOT evidence: a live writer can be
+ * suspended or stalled in fsync for arbitrarily long. */
+function recycledOwner(token) {
+    const pid = ownerPid(token);
+    const recorded = token.split(":").slice(2).join(":");
+    if (pid === undefined || !recorded)
+        return false; // Legacy token: unknown, never expire.
+    const current = processStartId(pid);
+    return current !== undefined && current !== recorded;
+}
+function release(path, token) {
+    try {
+        if (readFileSync(path, "utf8") === token)
+            unlinkSync(path);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+/** Publish a fully written owner atomically. No empty lock can be left by a crash. */
+function publish(path, token) {
+    // Only pid and uuid: the start id may hold spaces and colons.
+    const owner = `${path}.${token.split(":").slice(0, 2).join("-")}.owner`;
+    writeFileSync(owner, token, { mode: 0o600, flag: "wx" });
+    try {
+        linkSync(owner, path);
+    }
+    finally {
+        unlinkSync(owner);
+    }
+}
+/** A live owner held the lock past the bounded wait. Nothing was written. */
+export class SessionWriteLockBusyError extends Error {
+    constructor(path) {
+        super(`Session write lock is held by another live writer: ${path}`);
+        this.name = "SessionWriteLockBusyError";
+    }
+}
+const LIVE_OWNER_WAIT_MS = 2_000;
+const sleepCell = new Int32Array(new SharedArrayBuffer(4));
+function sleepSync(ms) { Atomics.wait(sleepCell, 0, 0, ms); }
+/** 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 function withSessionWriteLock(path, action, waitMs = LIVE_OWNER_WAIT_MS) {
+    const token = ownerToken();
+    const deadline = Date.now() + waitMs;
+    const verifiedLive = new Set(); // One incarnation probe per observed owner.
+    for (let delay = 2;; delay = Math.min(delay * 2, 50)) {
+        try {
+            publish(path, token);
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const timedOut = Date.now() >= deadline;
+            let observed;
+            try {
+                observed = readFileSync(path, "utf8");
+            }
+            catch (readError) {
+                if (readError.code !== "ENOENT")
+                    throw readError;
+                if (timedOut)
+                    throw new SessionWriteLockBusyError(path);
+                continue;
+            }
+            // kill(0) is cheap and re-checked every round. The incarnation probe may
+            // spawn `ps`, so an owner is probed when first seen and once more before
+            // giving up: it can exit and have its pid recycled while we wait.
+            const abandoned = () => deadOwner(observed)
+                || ((timedOut || !verifiedLive.has(observed)) && recycledOwner(observed));
+            if (!abandoned()) {
+                if (timedOut)
+                    throw new SessionWriteLockBusyError(path);
+                verifiedLive.add(observed);
+                sleepSync(delay);
+                continue;
+            }
+            // Serialize recovery. Recovery locks themselves use the same owner-safe
+            // protocol, so killing a recovering process cannot permanently block it.
+            withSessionWriteLock(`${path}.recovery`, () => {
+                try {
+                    if (readFileSync(path, "utf8") === observed && abandoned())
+                        unlinkSync(path);
+                }
+                catch (recoveryError) {
+                    if (recoveryError.code !== "ENOENT")
+                        throw recoveryError;
+                }
+            }, Math.max(0, deadline - Date.now()));
+        }
+    }
+    try {
+        return action();
+    }
+    finally {
+        release(path, token);
+    }
+}

package/dist/context/token-estimator.d.ts

@@ -0,0 +1,14 @@
+export interface TokenEstimator {
+    estimate(text: string): number;
+}
+export declare class HeuristicEstimator implements TokenEstimator {
+    estimate(text: string): number;
+}
+export declare class TiktokenEstimator implements TokenEstimator {
+    private encoder;
+    private initFailed;
+    private readonly fallback;
+    estimate(text: string): number;
+    private getEncoder;
+}
+export declare function getTokenEstimator(providerId?: string): TokenEstimator;

package/dist/context/token-estimator.js

@@ -0,0 +1,106 @@
+// Token estimation strategy layer.
+//
+// Different providers use different tokenizers; a single "chars/4" rule under-counts
+// dense content (HTML, CJK) and lets auto-compact fire too late. This module routes
+// per-provider: OpenAI / OpenAI-Codex uses js-tiktoken with the o200k_base BPE; every
+// other provider uses a CJK-aware heuristic. Drop in a new strategy per provider as
+// their tokenizers become important without touching call sites.
+// Tiktoken's pre-tokenization regex is catastrophic on inputs with long single-char
+// runs ("x".repeat(4000) → 1.4s; bigger → minutes/hang). Two guards: a hard length
+// cap, and a cheap scan for any run ≥ MAX_RUN_LEN of the same code unit. Both catch
+// production hazards (binary blobs, base64 dumps, leaked buffers) and synthetic test
+// fixtures alike. Normal prose / code / markdown stays well under both.
+const TIKTOKEN_MAX_CHARS = 80_000;
+const MAX_RUN_LEN = 64;
+function hasPathologicalRun(text) {
+    if (text.length < MAX_RUN_LEN)
+        return false;
+    let last = text.charCodeAt(0);
+    let run = 1;
+    for (let i = 1; i < text.length; i++) {
+        const code = text.charCodeAt(i);
+        if (code === last) {
+            run++;
+            if (run >= MAX_RUN_LEN)
+                return true;
+        }
+        else {
+            last = code;
+            run = 1;
+        }
+    }
+    return false;
+}
+// Cheap codepoint check: CJK ideographs + Hiragana/Katakana + Hangul.
+// Each such char is roughly 1 token (vs ~0.25 token for ASCII), so weighting them
+// 1.0 cuts the heuristic's CJK undercount by ~4x without needing a real tokenizer.
+function isCjkCodePoint(code) {
+    return ((code >= 0x3000 && code <= 0x9fff) || // CJK symbols + unified ideographs (incl. Hiragana/Katakana)
+        (code >= 0xac00 && code <= 0xd7af) || // Hangul syllables
+        (code >= 0xf900 && code <= 0xfaff) || // CJK compatibility ideographs
+        (code >= 0x20000 && code <= 0x2ffff) // CJK extensions B–F (surrogate pairs)
+    );
+}
+export class HeuristicEstimator {
+    estimate(text) {
+        if (!text)
+            return 0;
+        let cjk = 0;
+        let other = 0;
+        for (let i = 0; i < text.length; i++) {
+            const code = text.codePointAt(i);
+            if (code > 0xffff)
+                i++; // skip surrogate low half
+            if (isCjkCodePoint(code))
+                cjk++;
+            else
+                other++;
+        }
+        return Math.ceil(cjk + other / 4);
+    }
+}
+export class TiktokenEstimator {
+    encoder = null;
+    initFailed = false;
+    fallback = new HeuristicEstimator();
+    estimate(text) {
+        if (!text)
+            return 0;
+        if (text.length > TIKTOKEN_MAX_CHARS)
+            return this.fallback.estimate(text);
+        if (hasPathologicalRun(text))
+            return this.fallback.estimate(text);
+        const enc = this.getEncoder();
+        if (!enc)
+            return this.fallback.estimate(text);
+        try {
+            return enc.encode(text).length;
+        }
+        catch {
+            return this.fallback.estimate(text);
+        }
+    }
+    getEncoder() {
+        if (this.encoder)
+            return this.encoder;
+        if (this.initFailed)
+            return null;
+        try {
+            // Lazy require: defers ~1MB of BPE table load until OpenAI is actually used.
+            const tiktoken = require("js-tiktoken");
+            this.encoder = tiktoken.getEncoding("o200k_base");
+            return this.encoder;
+        }
+        catch {
+            this.initFailed = true;
+            return null;
+        }
+    }
+}
+const HEURISTIC = new HeuristicEstimator();
+const TIKTOKEN = new TiktokenEstimator();
+export function getTokenEstimator(providerId) {
+    if (providerId === "openai" || providerId === "openai-codex")
+        return TIKTOKEN;
+    return HEURISTIC;
+}

package/dist/context/tool-images.d.ts

@@ -0,0 +1,3 @@
+import type { ToolResult, UserMessage } from "../types.js";
+/** All tool responses must precede the observation (valid for every provider). */
+export declare function toolImageObservation(results: ToolResult[]): UserMessage | null;

package/dist/context/tool-images.js

@@ -0,0 +1,35 @@
+/** All tool responses must precede the observation (valid for every provider). */
+export function toolImageObservation(results) {
+    const content = [];
+    let bytes = 0;
+    for (const result of results) {
+        if (result.isError)
+            continue;
+        for (const image of result.images ?? []) {
+            if (content.length >= 8 ||
+                !["image/png", "image/jpeg"].includes(image.mimeType))
+                continue;
+            if (typeof image.data !== "string" ||
+                image.data.length > 4_000_000 ||
+                !/^[a-zA-Z0-9+/]+={0,2}$/.test(image.data))
+                continue;
+            const raw = Buffer.from(image.data, "base64");
+            if (bytes + raw.length > 6_000_000)
+                continue;
+            if (image.mimeType === "image/png"
+                ? raw.subarray(0, 8).toString("hex") !== "89504e470d0a1a0a"
+                : raw.subarray(0, 3).toString("hex") !== "ffd8ff")
+                continue;
+            bytes += raw.length;
+            content.push({
+                type: "text",
+                text: `Screenshot observation from the preceding tool result (not a new user request):\n${result.content.slice(0, 2000)}`,
+            });
+            content.push({
+                type: "image_url",
+                image_url: { url: `data:${image.mimeType};base64,${image.data}` },
+            });
+        }
+    }
+    return content.length ? { role: "user", content, toolObservation: true } : null;
+}

package/dist/context/tool-output-truncate.d.ts

@@ -0,0 +1,24 @@
+import type { ToolResult } from "../types.js";
+export declare const DEFAULT_TOOL_OUTPUT_BYTE_LIMIT: number;
+export declare const TOOL_OUTPUT_BATCH_BYTE_LIMIT: number;
+export interface ToolTruncationOptions {
+    /** Override used by a sibling tool batch to divide its aggregate budget. */
+    hardByteLimit?: number;
+}
+export interface ToolTruncationResult {
+    content: string;
+    truncated: boolean;
+    originalTokens: number;
+    finalTokens: number;
+    originalBytes: number;
+    finalBytes: number;
+    /** Provider/model-declared token cap, when one exists. */
+    limit: number | undefined;
+    hardByteLimit: number;
+}
+export declare function truncateToolOutputForModel(content: string, providerId: string, modelId: string, options?: ToolTruncationOptions): ToolTruncationResult;
+export declare function normalizeToolResultForModel(result: ToolResult, providerId: string, modelId: string, options?: ToolTruncationOptions): ToolResult;
+/** Return the longest prefix that fits without splitting a Unicode code point. */
+export declare function utf8Prefix(content: string, maxBytes: number): string;
+/** Return the longest suffix that fits without splitting a Unicode code point. */
+export declare function utf8Suffix(content: string, maxBytes: number): string;

package/dist/context/tool-output-truncate.js

@@ -0,0 +1,181 @@
+// Tool-output bounding for both live results and restored session history.
+//
+// A provider-declared token cap is useful when present, but it cannot be the
+// only guard: several providers (including GLM coding-plan models) declare no
+// per-tool limit at all. Every model-visible tool result therefore has a hard
+// byte ceiling as well. The stricter of the two policies wins.
+import { getToolOutputTokenLimit } from "../model-catalog.js";
+import { estimateTextTokens } from "./budget.js";
+export const DEFAULT_TOOL_OUTPUT_BYTE_LIMIT = 64 * 1024;
+export const TOOL_OUTPUT_BATCH_BYTE_LIMIT = 160 * 1024;
+export function truncateToolOutputForModel(content, providerId, modelId, options = {}) {
+    const limit = getToolOutputTokenLimit(providerId, modelId);
+    const hardByteLimit = Math.max(0, Math.floor(options.hardByteLimit ?? DEFAULT_TOOL_OUTPUT_BYTE_LIMIT));
+    const originalTokens = estimateTextTokens(content, providerId);
+    const originalBytes = Buffer.byteLength(content, "utf8");
+    if (originalBytes <= hardByteLimit && (!limit || originalTokens <= limit)) {
+        return {
+            content,
+            truncated: false,
+            originalTokens,
+            finalTokens: originalTokens,
+            originalBytes,
+            finalBytes: originalBytes,
+            limit,
+            hardByteLimit,
+        };
+    }
+    if (hardByteLimit === 0) {
+        return {
+            content: "",
+            truncated: content.length > 0,
+            originalTokens,
+            finalTokens: 0,
+            originalBytes,
+            finalBytes: 0,
+            limit,
+            hardByteLimit,
+        };
+    }
+    // Start with the byte ceiling. If a token policy is tighter, use the
+    // observed token/byte ratio to choose a smaller first candidate.
+    let candidateByteBudget = hardByteLimit;
+    if (limit && originalTokens > limit) {
+        candidateByteBudget = Math.min(candidateByteBudget, Math.max(1, Math.floor(originalBytes * (limit / originalTokens) * 0.9)));
+    }
+    let truncated = middleTruncateToByteBudget(content, candidateByteBudget, buildMarker(originalBytes, hardByteLimit, limit));
+    // Token estimation varies across providers and scripts. Tighten until both
+    // invariants hold; byte truncation itself is UTF-8 safe on every pass.
+    for (let pass = 0; pass < 8 && limit && estimateTextTokens(truncated, providerId) > limit; pass++) {
+        const tokens = estimateTextTokens(truncated, providerId);
+        candidateByteBudget = Math.max(1, Math.floor(candidateByteBudget * (limit / Math.max(1, tokens)) * 0.9));
+        truncated = middleTruncateToByteBudget(content, candidateByteBudget, buildMarker(originalBytes, hardByteLimit, limit));
+    }
+    // Extremely small model caps may not even fit the descriptive marker.
+    // Continue shrinking deterministically rather than violating the contract.
+    while (limit && estimateTextTokens(truncated, providerId) > limit && truncated.length > 0) {
+        candidateByteBudget = Math.max(0, Math.floor(candidateByteBudget * 0.75));
+        truncated = middleTruncateToByteBudget(content, candidateByteBudget, buildMarker(originalBytes, hardByteLimit, limit));
+    }
+    const finalTokens = estimateTextTokens(truncated, providerId);
+    const finalBytes = Buffer.byteLength(truncated, "utf8");
+    return {
+        content: truncated,
+        truncated: true,
+        originalTokens,
+        finalTokens,
+        originalBytes,
+        finalBytes,
+        limit,
+        hardByteLimit,
+    };
+}
+export function normalizeToolResultForModel(result, providerId, modelId, options = {}) {
+    const bounded = truncateToolOutputForModel(result.content, providerId, modelId, options);
+    if (!bounded.truncated)
+        return result;
+    return {
+        ...result,
+        content: bounded.content,
+        metadata: {
+            ...result.metadata,
+            truncated: true,
+            toolOutputTruncation: {
+                originalBytes: bounded.originalBytes,
+                finalBytes: bounded.finalBytes,
+                originalTokens: bounded.originalTokens,
+                finalTokens: bounded.finalTokens,
+                hardByteLimit: bounded.hardByteLimit,
+                ...(bounded.limit ? { modelTokenLimit: bounded.limit } : {}),
+            },
+        },
+    };
+}
+function buildMarker(originalBytes, hardByteLimit, tokenLimit) {
+    const policy = tokenLimit
+        ? `${formatBytes(hardByteLimit)} hard cap; ${tokenLimit}-token model cap`
+        : `${formatBytes(hardByteLimit)} hard cap`;
+    return `\n\n[... middle of ${formatBytes(originalBytes)} output truncated by model policy (${policy}) ...]\n\n`;
+}
+function middleTruncateToByteBudget(content, byteBudget, marker) {
+    if (byteBudget <= 0)
+        return "";
+    if (Buffer.byteLength(content, "utf8") <= byteBudget)
+        return content;
+    let safeMarker = marker;
+    if (Buffer.byteLength(safeMarker, "utf8") > byteBudget) {
+        safeMarker = utf8Prefix(safeMarker, byteBudget);
+    }
+    const markerBytes = Buffer.byteLength(safeMarker, "utf8");
+    const payloadBytes = Math.max(0, byteBudget - markerBytes);
+    const headBudget = Math.floor(payloadBytes / 2);
+    const tailBudget = payloadBytes - headBudget;
+    const head = utf8Prefix(content, headBudget);
+    const tail = utf8Suffix(content, tailBudget);
+    return `${head}${safeMarker}${tail}`;
+}
+/** Return the longest prefix that fits without splitting a Unicode code point. */
+export function utf8Prefix(content, maxBytes) {
+    if (maxBytes <= 0 || content.length === 0)
+        return "";
+    if (Buffer.byteLength(content, "utf8") <= maxBytes)
+        return content;
+    let low = 0;
+    let high = content.length;
+    while (low < high) {
+        const mid = Math.ceil((low + high) / 2);
+        const safeMid = isLowSurrogateAt(content, mid) ? mid - 1 : mid;
+        if (Buffer.byteLength(content.slice(0, safeMid), "utf8") <= maxBytes)
+            low = mid;
+        else
+            high = mid - 1;
+    }
+    let end = Math.min(low, content.length);
+    if (isLowSurrogateAt(content, end))
+        end -= 1;
+    while (end > 0 && Buffer.byteLength(content.slice(0, end), "utf8") > maxBytes)
+        end -= 1;
+    if (isLowSurrogateAt(content, end))
+        end -= 1;
+    return content.slice(0, Math.max(0, end));
+}
+/** Return the longest suffix that fits without splitting a Unicode code point. */
+export function utf8Suffix(content, maxBytes) {
+    if (maxBytes <= 0 || content.length === 0)
+        return "";
+    if (Buffer.byteLength(content, "utf8") <= maxBytes)
+        return content;
+    let low = 0;
+    let high = content.length;
+    while (low < high) {
+        const length = Math.ceil((low + high) / 2);
+        let start = content.length - length;
+        if (isLowSurrogateAt(content, start))
+            start += 1;
+        if (Buffer.byteLength(content.slice(start), "utf8") <= maxBytes)
+            low = length;
+        else
+            high = length - 1;
+    }
+    let start = Math.max(0, content.length - low);
+    if (isLowSurrogateAt(content, start))
+        start += 1;
+    while (start < content.length && Buffer.byteLength(content.slice(start), "utf8") > maxBytes)
+        start += 1;
+    if (isLowSurrogateAt(content, start))
+        start += 1;
+    return content.slice(Math.min(start, content.length));
+}
+function isLowSurrogateAt(content, index) {
+    if (index <= 0 || index >= content.length)
+        return false;
+    const code = content.charCodeAt(index);
+    return code >= 0xdc00 && code <= 0xdfff;
+}
+function formatBytes(count) {
+    if (count < 1024)
+        return `${count}B`;
+    if (count < 1024 * 1024)
+        return `${(count / 1024).toFixed(1)}KiB`;
+    return `${(count / (1024 * 1024)).toFixed(2)}MiB`;
+}

package/dist/context/usage.d.ts

@@ -0,0 +1,34 @@
+import type { SkillSummary } from "../skills/types.js";
+import type { Message, ToolRegistryEntry } from "../types.js";
+export interface ContextUsageBucket {
+    label: string;
+    tokens: number;
+    detail?: string;
+}
+export interface ContextUsageSnapshot {
+    providerId: string;
+    modelId: string;
+    contextWindow?: number;
+    usedTokens: number;
+    freeTokens?: number;
+    buckets: {
+        systemPrompt: ContextUsageBucket;
+        tools: ContextUsageBucket;
+        skills: ContextUsageBucket;
+        deferredTools: ContextUsageBucket;
+        other: ContextUsageBucket;
+    };
+    toolCount: number;
+    deferredToolCount: number;
+    skillCount: number;
+    messageCount: number;
+}
+export declare function buildContextUsageSnapshot(input: {
+    providerId: string;
+    modelId: string;
+    messages: Message[];
+    toolEntries: ToolRegistryEntry[];
+    deferredToolEntries?: ToolRegistryEntry[];
+    skills: SkillSummary[];
+}): ContextUsageSnapshot;
+export declare function formatContextUsage(snapshot: ContextUsageSnapshot): string;