@bubblebrain-ai/bubble 0.0.7 → 0.0.9

package/dist/context/compact.js

@@ -76,6 +76,135 @@ export function compactMessages(messages, options = {}) {
         droppedEntries: oldMessages.length,
     };
 }
+export function compactCurrentTurnToolGroups(messages, options = {}) {
+    const keepRecentGroups = options.keepRecentGroups ?? 2;
+    const maxSummaryItems = options.maxSummaryItems ?? 8;
+    const preserved = messages.filter((m) => m.role === "system" || m.role === "meta");
+    const body = messages.filter((m) => m.role !== "system" && m.role !== "meta");
+    let lastUserIndex = -1;
+    for (let i = body.length - 1; i >= 0; i--) {
+        if (body[i].role === "user") {
+            lastUserIndex = i;
+            break;
+        }
+    }
+    if (lastUserIndex < 0)
+        return { compacted: false };
+    const preTurn = body.slice(0, lastUserIndex + 1);
+    const turnBody = body.slice(lastUserIndex + 1);
+    const groups = [];
+    let current = null;
+    for (const msg of turnBody) {
+        if (msg.role === "assistant") {
+            if (current)
+                groups.push(current);
+            current = { assistant: msg, toolResults: [] };
+        }
+        else if (msg.role === "tool" && current) {
+            current.toolResults.push(msg);
+        }
+    }
+    if (current)
+        groups.push(current);
+    if (groups.length <= keepRecentGroups)
+        return { compacted: false };
+    // Only drop groups that have tool_calls — text-only assistant messages don't
+    // free much context, and dropping them confuses the conversation flow.
+    const evictable = groups.slice(0, groups.length - keepRecentGroups)
+        .filter((g) => g.assistant.role === "assistant" && (g.assistant.toolCalls?.length ?? 0) > 0);
+    if (evictable.length === 0)
+        return { compacted: false };
+    const summary = buildToolGroupsSummary(evictable, maxSummaryItems);
+    if (!summary)
+        return { compacted: false };
+    const survivingGroups = groups.filter((g) => !evictable.includes(g));
+    const flatSurvivors = [];
+    for (const g of survivingGroups) {
+        flatSurvivors.push(cloneMessage(g.assistant));
+        for (const t of g.toolResults)
+            flatSurvivors.push(cloneMessage(t));
+    }
+    const compactedMessages = [
+        ...preserved.map(cloneMessage),
+        ...preTurn.map(cloneMessage),
+        {
+            role: "system",
+            content: `Earlier in this turn (compacted to free context):\n${summary}`,
+        },
+        ...flatSurvivors,
+    ];
+    return {
+        compacted: true,
+        summary,
+        messages: compactedMessages,
+        droppedEntries: evictable.length,
+    };
+}
+function buildToolGroupsSummary(groups, maxItems) {
+    const toolCounts = new Map();
+    const fileSet = new Set();
+    let totalResultChars = 0;
+    const findings = [];
+    for (const group of groups) {
+        if (group.assistant.role !== "assistant" || !group.assistant.toolCalls)
+            continue;
+        const toolNameByCallId = new Map();
+        for (const tc of group.assistant.toolCalls) {
+            toolCounts.set(tc.name, (toolCounts.get(tc.name) ?? 0) + 1);
+            toolNameByCallId.set(tc.id, tc.name);
+            try {
+                const parsed = JSON.parse(tc.arguments || "{}");
+                for (const key of ["file_path", "path", "paths", "file"]) {
+                    const v = parsed[key];
+                    if (typeof v === "string" && v)
+                        fileSet.add(v);
+                    else if (Array.isArray(v)) {
+                        for (const item of v)
+                            if (typeof item === "string" && item)
+                                fileSet.add(item);
+                    }
+                }
+            }
+            catch {
+                // ignore unparseable args
+            }
+        }
+        for (const r of group.toolResults) {
+            if (r.role !== "tool")
+                continue;
+            const content = typeof r.content === "string" ? r.content : "";
+            totalResultChars += content.length;
+            if (findings.length < maxItems) {
+                const toolName = toolNameByCallId.get(r.toolCallId) ?? "tool";
+                findings.push(`${toolName}: ${summarizeText(content)}`);
+            }
+        }
+    }
+    const lines = [];
+    const toolList = [...toolCounts.entries()]
+        .map(([name, n]) => (n > 1 ? `${name}×${n}` : name))
+        .join(", ");
+    lines.push(`Tools used: ${toolList || "none"}`);
+    if (fileSet.size > 0) {
+        const fileList = [...fileSet].slice(0, 12);
+        lines.push(`Files touched: ${fileList.join(", ")}${fileSet.size > 12 ? ` (+${fileSet.size - 12} more)` : ""}`);
+    }
+    lines.push(`Discarded ~${formatChars(totalResultChars)} of earlier tool output. Re-run the relevant tool if you need specifics.`);
+    if (findings.length > 0) {
+        lines.push("");
+        lines.push("Earlier findings:");
+        for (const f of findings)
+            lines.push(`- ${f}`);
+    }
+    return lines.join("\n");
+}
+function formatChars(count) {
+    if (count < 1000)
+        return `${count} chars`;
+    if (count < 1_000_000)
+        return `${(count / 1000).toFixed(1)}K chars`;
+    return `${(count / 1_000_000).toFixed(2)}M chars`;
+}
 function buildCompactionSummary(entries, maxSummaryItems) {
     const messages = entriesToMessages(entries);
     return buildMessageSummary(messages, maxSummaryItems);

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

@@ -0,0 +1,19 @@
+import type { Message, Provider } from "../types.js";
+export declare const LLM_COMPACTION_PROMPT = "You are performing a CONTEXT CHECKPOINT COMPACTION. Create a handoff summary for another LLM that will resume the task.\n\nInclude:\n- Current progress and key decisions made\n- Important context, constraints, or user preferences\n- What remains to be done (clear next steps)\n- Any critical data, examples, or references needed to continue\n\nBe concise, structured, and focused on helping the next LLM seamlessly continue the work.";
+export declare const LLM_SUMMARY_PREFIX = "Another language model previously worked on this task and produced this handoff summary. Build on what's already done; avoid re-running the same investigation. Summary:";
+export interface LLMCompactOptions {
+    provider: Provider;
+    modelId: string;
+    /** Compactor model call must complete within this token-cost ceiling. */
+    maxInputTokens?: number;
+    /** Number of trailing (assistant + tool-results) groups in the current turn to keep verbatim. */
+    keepRecentGroups?: number;
+    abortSignal?: AbortSignal;
+}
+export interface LLMCompactResult {
+    compacted: boolean;
+    summary?: string;
+    messages?: Message[];
+    reason?: string;
+}
+export declare function compactWithLLM(messages: Message[], options: LLMCompactOptions): Promise<LLMCompactResult>;

package/dist/context/llm-compactor.js

@@ -0,0 +1,200 @@
+// LLM-driven context compaction.
+//
+// When the budget says we're approaching the context window, ask the model to
+// produce a handoff summary of the conversation so far. Replace the bulky middle
+// of history with that summary while keeping the initial system context and the
+// user's latest ask intact. Architecturally this mirrors Codex CLI's approach
+// (codex-rs/core/src/compact.rs + templates/compact/prompt.md): trust the model
+// to pick what matters instead of writing a template.
+//
+// Failure modes are explicit: returns { compacted: false, reason } so the
+// caller can fall back to algorithmic compaction without an exception.
+import { estimateContextTokens } from "./budget.js";
+export const LLM_COMPACTION_PROMPT = `You are performing a CONTEXT CHECKPOINT COMPACTION. Create a handoff summary for another LLM that will resume the task.
+
+Include:
+- Current progress and key decisions made
+- Important context, constraints, or user preferences
+- What remains to be done (clear next steps)
+- Any critical data, examples, or references needed to continue
+
+Be concise, structured, and focused on helping the next LLM seamlessly continue the work.`;
+export const LLM_SUMMARY_PREFIX = `Another language model previously worked on this task and produced this handoff summary. Build on what's already done; avoid re-running the same investigation. Summary:`;
+export async function compactWithLLM(messages, options) {
+    const { provider, modelId, abortSignal } = options;
+    const maxInputTokens = options.maxInputTokens ?? 100_000;
+    const keepRecentGroups = options.keepRecentGroups ?? 2;
+    const preserved = messages.filter((m) => m.role === "system" || m.role === "meta");
+    const body = messages.filter((m) => m.role !== "system" && m.role !== "meta");
+    let lastUserIndex = -1;
+    for (let i = body.length - 1; i >= 0; i--) {
+        if (body[i].role === "user") {
+            lastUserIndex = i;
+            break;
+        }
+    }
+    if (lastUserIndex < 0) {
+        return { compacted: false, reason: "no user message in history" };
+    }
+    // Pivot the body around the last user message:
+    //   priorTurns:   everything from earlier user turns (multi-turn case)
+    //   lastUser:     the user's current ask (always kept verbatim)
+    //   currentTurn:  the assistant + tool groups produced in response so far
+    const priorTurns = body.slice(0, lastUserIndex);
+    const lastUser = body[lastUserIndex];
+    const currentTurn = body.slice(lastUserIndex + 1);
+    const groups = [];
+    let active = null;
+    for (const msg of currentTurn) {
+        if (msg.role === "assistant") {
+            if (active)
+                groups.push(active);
+            active = { assistant: msg, toolResults: [] };
+        }
+        else if (msg.role === "tool" && active) {
+            active.toolResults.push(msg);
+        }
+    }
+    if (active)
+        groups.push(active);
+    const keptGroupCount = Math.min(keepRecentGroups, groups.length);
+    const evictedGroups = groups.slice(0, groups.length - keptGroupCount);
+    const keptGroups = groups.slice(groups.length - keptGroupCount);
+    // What we'll send to the model to summarize: prior turns + the older groups
+    // in the current turn (everything we're about to evict).
+    const toSummarize = [
+        ...priorTurns,
+        ...evictedGroups.flatMap((g) => [g.assistant, ...g.toolResults]),
+    ];
+    if (toSummarize.length === 0) {
+        return { compacted: false, reason: "nothing to evict" };
+    }
+    const trimmedHistory = trimToFitTokenBudget(toSummarize, maxInputTokens);
+    const historyText = serializeHistoryAsText(trimmedHistory);
+    const summaryInput = [
+        { role: "system", content: LLM_COMPACTION_PROMPT },
+        { role: "user", content: historyText },
+    ];
+    let summaryText;
+    try {
+        summaryText = await provider.complete(summaryInput, {
+            model: modelId,
+            temperature: 0.2,
+            abortSignal,
+        });
+    }
+    catch (err) {
+        return { compacted: false, reason: `compactor call failed: ${err.message}` };
+    }
+    if (!summaryText || summaryText.trim().length === 0) {
+        return { compacted: false, reason: "compactor returned empty summary" };
+    }
+    // New history shape (prefix-cache-friendly: preserved system+meta stay at the
+    // absolute prefix unchanged; summary is injected after as a user-role envelope
+    // so it can't pollute the cacheable system-prompt prefix):
+    //
+    //   [...preserved system+meta]                       ← stable prefix
+    //   user: "<SUMMARY_PREFIX>\n<summary>"               ← evicted history compressed
+    //   user: <original last user message>                ← the current ask
+    //   [...kept current-turn (assistant + tool) groups]  ← recent tool work
+    const flatKept = [];
+    for (const g of keptGroups) {
+        flatKept.push(cloneMessage(g.assistant));
+        for (const t of g.toolResults)
+            flatKept.push(cloneMessage(t));
+    }
+    const compacted = [
+        ...preserved.map(cloneMessage),
+        {
+            role: "user",
+            content: `${LLM_SUMMARY_PREFIX}\n${summaryText.trim()}`,
+        },
+        cloneMessage(lastUser),
+        ...flatKept,
+    ];
+    return {
+        compacted: true,
+        summary: summaryText,
+        messages: compacted,
+    };
+}
+function trimToFitTokenBudget(messages, maxTokens) {
+    // Drop from the front (oldest first) until estimate fits. Front-trim matches
+    // Codex's pattern and preserves the most recent context the user cares about.
+    let working = [...messages];
+    while (working.length > 0 && estimateContextTokens(working) > maxTokens) {
+        working = working.slice(1);
+    }
+    return working;
+}
+function serializeHistoryAsText(messages) {
+    const lines = [];
+    const toolNameByCallId = new Map();
+    for (const msg of messages) {
+        switch (msg.role) {
+            case "user": {
+                const text = typeof msg.content === "string"
+                    ? msg.content
+                    : msg.content.filter((p) => p.type === "text").map((p) => p.text).join(" ");
+                lines.push(`USER: ${text}`);
+                break;
+            }
+            case "assistant": {
+                if (msg.content.trim()) {
+                    lines.push(`ASSISTANT: ${msg.content}`);
+                }
+                if (msg.toolCalls && msg.toolCalls.length > 0) {
+                    for (const tc of msg.toolCalls) {
+                        toolNameByCallId.set(tc.id, tc.name);
+                        lines.push(`TOOL_CALL[${tc.name}]: ${summarizeToolCallArgs(tc)}`);
+                    }
+                }
+                break;
+            }
+            case "tool": {
+                const name = toolNameByCallId.get(msg.toolCallId) ?? "tool";
+                lines.push(`TOOL_RESULT[${name}]: ${truncateInline(msg.content, 1500)}`);
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    return lines.join("\n\n");
+}
+function summarizeToolCallArgs(tc) {
+    try {
+        const parsed = JSON.parse(tc.arguments || "{}");
+        const pairs = Object.entries(parsed)
+            .filter(([, v]) => typeof v === "string" || typeof v === "number" || typeof v === "boolean")
+            .map(([k, v]) => `${k}=${JSON.stringify(v).slice(0, 200)}`);
+        return pairs.join(" ") || "(no args)";
+    }
+    catch {
+        return truncateInline(tc.arguments || "", 200);
+    }
+}
+function truncateInline(text, max) {
+    const normalized = text.replace(/\s+/g, " ").trim();
+    if (normalized.length <= max)
+        return normalized;
+    return `${normalized.slice(0, max - 3)}...`;
+}
+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/projector.js

@@ -1,6 +1,14 @@
 import { getContextBudget } from "./budget.js";
-import { compactMessages } from "./compact.js";
+import { compactCurrentTurnToolGroups, compactMessages } from "./compact.js";
 import { pruneMessages } from "./prune.js";
+// Prefix-cache invariant: every projected output starts with the concatenation
+// of (in order) system + meta messages from the input, followed by the
+// conversational body. Compactors (compactMessages, compactCurrentTurnToolGroups,
+// compactMessagesWithLLM, compactWithLLM) MUST preserve every existing
+// system/meta message in its original position so the cacheable prefix
+// stays byte-identical across turns where compaction didn't fire. Inserting
+// new dynamic content (summaries, etc.) AFTER system+meta is safe; inserting
+// it within or before them is not.
 export function projectMessages(messages, options = {}) {
     const mode = options.mode ?? "full";
     const projectedBody = [];
@@ -48,18 +56,26 @@ export function projectMessages(messages, options = {}) {
         if (!budget.shouldCompact) {
             return pruned;
         }
-        const compacted = compactMessages(pruned, { keepRecentTurns: 2 });
-        if (!compacted.compacted || !compacted.messages) {
-            return pruned;
-        }
-        const compactedMessages = compacted.messages;
-        const afterFirstPass = getContextBudget(options.providerId, options.modelId, compactedMessages);
-        if (!afterFirstPass.shouldCompact) {
-            return repairToolCallChains(compactedMessages);
+        // 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);
+            if (!after.shouldCompact)
+                break;
         }
-        const tighter = compactMessages(pruned, { keepRecentTurns: 1 });
-        const finalMessages = (tighter.compacted && tighter.messages ? tighter.messages : compactedMessages);
-        return repairToolCallChains(finalMessages);
+        return repairToolCallChains(working);
     }
     return repaired;
 }

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-output-truncate.d.ts

@@ -0,0 +1,8 @@
+export interface ToolTruncationResult {
+    content: string;
+    truncated: boolean;
+    originalTokens: number;
+    finalTokens: number;
+    limit: number | undefined;
+}
+export declare function truncateToolOutputForModel(content: string, providerId: string, modelId: string): ToolTruncationResult;

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

@@ -0,0 +1,59 @@
+// Tool-output truncation honoring the model's server-declared limit.
+//
+// Codex backend's /models endpoint reports per-model `truncation_policy.limit`
+// (e.g. 10000 tokens for gpt-5.5). The expectation is that the CLIENT truncates
+// each tool result to that budget before adding it to history; sending raw
+// 50-100k tool dumps will blow through the input window after a handful of
+// calls. Codex CLI does this via TruncationPolicy::Tokens; mirror it here.
+//
+// Strategy: middle-truncate (preserve head + tail with an explicit marker in
+// between). Heads usually carry structure/headers; tails often carry totals,
+// errors, or conclusions — losing either is worse than losing the middle.
+import { getToolOutputTokenLimit } from "../model-catalog.js";
+import { estimateTextTokens } from "./budget.js";
+export function truncateToolOutputForModel(content, providerId, modelId) {
+    const limit = getToolOutputTokenLimit(providerId, modelId);
+    const originalTokens = estimateTextTokens(content, providerId);
+    if (!limit || originalTokens <= limit) {
+        return { content, truncated: false, originalTokens, finalTokens: originalTokens, limit };
+    }
+    const truncated = middleTruncateToTokenBudget(content, limit, providerId);
+    const finalTokens = estimateTextTokens(truncated, providerId);
+    return { content: truncated, truncated: true, originalTokens, finalTokens, limit };
+}
+function middleTruncateToTokenBudget(content, tokenBudget, providerId) {
+    // Convert token budget to a char budget via the estimator's effective ratio.
+    // The estimator may under/overcount, so we iterate one round if needed.
+    const tokensAll = estimateTextTokens(content, providerId);
+    if (tokensAll <= tokenBudget)
+        return content;
+    const charsPerToken = content.length / Math.max(1, tokensAll);
+    let charBudget = Math.floor(tokenBudget * charsPerToken);
+    const marker = (dropped) => `\n\n[... middle ${formatChars(dropped)} truncated by model policy (${tokenBudget}-token cap) ...]\n\n`;
+    // Reserve some room for the marker itself.
+    const reserveForMarker = 200;
+    charBudget = Math.max(200, charBudget - reserveForMarker);
+    const half = Math.floor(charBudget / 2);
+    const head = content.slice(0, half);
+    const tail = content.slice(content.length - (charBudget - half));
+    const droppedChars = content.length - head.length - tail.length;
+    let truncated = `${head}${marker(droppedChars)}${tail}`;
+    // Tighten if our estimate of charsPerToken undercounts and we're still over.
+    let safety = 3;
+    while (estimateTextTokens(truncated, providerId) > tokenBudget && safety-- > 0) {
+        const newHalf = Math.floor(head.length * 0.8);
+        const newTailLen = Math.floor(tail.length * 0.8);
+        const newHead = content.slice(0, newHalf);
+        const newTail = content.slice(content.length - newTailLen);
+        const newDropped = content.length - newHead.length - newTail.length;
+        truncated = `${newHead}${marker(newDropped)}${newTail}`;
+    }
+    return truncated;
+}
+function formatChars(count) {
+    if (count < 1000)
+        return `${count} chars`;
+    if (count < 1_000_000)
+        return `${(count / 1000).toFixed(1)}K chars`;
+    return `${(count / 1_000_000).toFixed(2)}M chars`;
+}

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;