@bubblebrain-ai/bubble 0.0.58 → 0.0.60

package/dist/context/compact.js

@@ -59,7 +59,9 @@ export function isCompactionSummaryMessage(message) {
 }
 /** A message the user actually typed (not a projected reminder, not a summary). */
 export function isRealUserMessage(message) {
-    if (message.role !== "user")
+    // Tool screenshots ride in a user-role message for the provider, but they
+    // belong to the tool turn: never a turn boundary.
+    if (message.role !== "user" || message.toolObservation)
         return false;
     const text = messageText(message);
     if (!text.trim() || isInternalBlockContent(text))
@@ -197,10 +199,8 @@ export function compactSessionEntries(entries, options = {}) {
 export function compactMessages(messages, options = {}) {
     const keepRecentTurns = options.keepRecentTurns ?? 2;
     const maxSummaryItems = options.maxSummaryItems ?? 4;
-    // Replace semantics: prior summaries (any form, any position) die here —
-    // at most one summary exists after every compaction. Their content is
-    // template-grade (goal truncated to 140 chars, constant next-steps line);
-    // the pinned original instruction is the durable record, not old summaries.
+    // Replace envelopes, not their contents: prior LLM summaries can be the only
+    // surviving record of decisions and constraints. Merge their prose below.
     const { leading, body } = splitLeadingContext(messages);
     const priorSummaries = body.filter(isCompactionSummaryMessage);
     const bodyMessages = body.filter((message) => !isCompactionSummaryMessage(message));
@@ -232,7 +232,31 @@ export function compactMessages(messages, options = {}) {
     if (!summary) {
         return { compacted: false };
     }
-    const summaryWithFiles = appendFileBlocks(summary, collectCompactionFileOps(oldMessages, priorSummaries));
+    // Flatten prior envelopes and dedupe lines instead of nesting summaries on
+    // every pass. Keep an explicitly bounded prose record (head + recent tail),
+    // with a durable warning when the heuristic cannot retain everything.
+    const pinOverflow = pinnedMessage
+        ? messageText(pinnedMessage).slice(PINNED_INSTRUCTION_MAX_CHARS)
+        : "";
+    const summaryLines = [
+        ...priorSummaries.map((message) => stripFileBlocks(messageText(message))),
+        ...(pinOverflow ? [`Original instruction beyond retained pin:\n${pinOverflow}`] : []),
+        summary,
+    ].join("\n")
+        .replace(/<\/?bubble_internal_(?:context|reminder)\b[^>]*>/g, "")
+        .split("\n")
+        .map((line) => line.trim()
+        .replace(/^Another language model previously worked on this task[^\n]*?Summary:\s*/, "")
+        .replace(/^Previous conversation summary:\s*/, "")
+        .replace(/^Earlier in this turn \(compacted to free context\):\s*/, ""))
+        .filter(Boolean);
+    const mergedSummary = [...new Set(summaryLines)].join("\n");
+    const proseLimit = 8192;
+    const overflowNotice = "\n[Heuristic compaction degraded: accumulated summary exceeded 8192 characters; middle omitted.]\n";
+    const boundedSummary = mergedSummary.length <= proseLimit ? mergedSummary
+        : mergedSummary.slice(0, 4096) + overflowNotice
+            + mergedSummary.slice(-(proseLimit - 4096 - overflowNotice.length));
+    const summaryWithFiles = appendFileBlocks(boundedSummary, collectCompactionFileOps(oldMessages, priorSummaries));
     const compactedMessages = [
         ...leading.map((message) => cloneMessage(message)),
         ...(pinnedMessage ? [clonePinnedUserMessage(pinnedMessage)] : []),
@@ -243,6 +267,11 @@ export function compactMessages(messages, options = {}) {
         compacted: true,
         summary: summaryWithFiles,
         messages: compactedMessages,
+        // The pin survives verbatim only up to its cap; the tail beyond it exists
+        // nowhere else, so an external summarizer must see it in the pin's place.
+        evictedMessages: [...priorSummaries, ...oldMessages.flatMap((message, index) => index !== pinnedIndex ? [message]
+                : pinOverflow ? [{ role: "user", content: `Original instruction beyond retained pin:\n${pinOverflow}` }] : [])],
+        summaryIndex: leading.length + (pinnedMessage ? 1 : 0),
         droppedEntries: summaryInput.length,
     };
 }
@@ -275,7 +304,9 @@ export function compactCurrentTurnToolGroups(messages, options = {}) {
                 groups.push(current);
             current = { assistant: msg, toolResults: [] };
         }
-        else if (msg.role === "tool" && current) {
+        else if ((msg.role === "tool" || (msg.role === "user" && msg.toolObservation)) && current) {
+            // A screenshot observation follows its tool result: it lives and dies
+            // with that group instead of vanishing from kept groups.
             current.toolResults.push(msg);
         }
     }
@@ -317,6 +348,8 @@ export function compactCurrentTurnToolGroups(messages, options = {}) {
         compacted: true,
         summary,
         messages: compactedMessages,
+        evictedMessages: [...priorSubturnSummaries, ...evictable.flatMap((g) => [g.assistant, ...g.toolResults])],
+        summaryIndex: leading.length + preTurn.length,
         droppedEntries: evictable.length,
     };
 }

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

@@ -1,11 +1,13 @@
 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_COMPACTION_PROMPT = "You are performing a CONTEXT CHECKPOINT COMPACTION. The conversation below is about to be removed from the model's context and replaced by your summary. Another LLM will resume the task seeing only your summary, the user's original instruction, and the most recent messages. Anything you leave out is gone.\n\nWrite a handoff summary that lets it continue without repeating the investigation. Cover:\n- Goal and constraints: what the user wants, in their terms. Explicit requirements, preferences, and anything they ruled out. Quote exact wording where precision matters.\n- Decisions made and why, including approaches that were tried and rejected, so they are not retried.\n- Current state: what is done and verified, what is in progress, what is broken or still unverified. Keep verified facts distinct from assumptions.\n- Specifics needed to continue: file paths, identifiers, commands, error messages, config values, ids, URLs. Exact, never paraphrased.\n- Next steps in order, starting with the immediate one.\n\nLength follows content: as long as needed to preserve the above, and no longer. Spend words on what cannot be cheaply re-derived (decisions, constraints, findings). Do not reproduce file contents or tool output that can simply be read again, and do not narrate the conversation turn by turn. The lists of files read and modified are recorded separately; name only the files that matter for the next steps.\n\nCarry forward every fact from prior summaries and the original user constraints. If the input says parts of the history were omitted, say so explicitly.";
 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. */
+    /** Total estimated request ceiling, including the compaction prompt. */
     maxInputTokens?: number;
+    providerId?: string;
+    contextWindow?: number;
     /** Number of trailing (assistant + tool-results) groups in the current turn to keep verbatim. */
     keepRecentGroups?: number;
     abortSignal?: AbortSignal;
@@ -15,5 +17,37 @@ export interface LLMCompactResult {
     summary?: string;
     messages?: Message[];
     reason?: string;
+    /** Explicit lossy-input diagnostics; also persisted in a successful summary. */
+    degradation?: string;
 }
 export declare function compactWithLLM(messages: Message[], options: LLMCompactOptions): Promise<LLMCompactResult>;
+/** Fit the summarization input under the model's window, degrading breadth-first:
+ *  1. everything verbatim;
+ *  2. cap tool payloads (results and tool-call arguments alike) at the LARGEST
+ *     common length that fits — short payloads such as paths and commands stay
+ *     whole, only long ones lose their middle, and every group still informs
+ *     the summary;
+ *  3. only when even empty payloads do not fit, drop the oldest assistant/tool
+ *     group and search again, so what survives is as complete as the room allows.
+ * The cap is derived from the budget, never a fixed size. Prior summaries, user
+ * constraints and runtime context are never trimmed; if they alone exceed the
+ * budget this fails explicitly and the caller chooses a fallback.
+ * `degradation` is the durable part: whole steps the summary never saw. Trimmed
+ * middles are stated in the input only — that loss is inherent to summarizing.
+ * Exported for regression tests only — callers use compactWithLLM. */
+export declare function fitSummaryInput(messages: Message[], prompt: string, maxTokens: number, providerId: string): {
+    historyText: string;
+    degradation?: string;
+} | undefined;
+/** One trimming pass: the cap, how to price text, and whether anything was cut. */
+interface PayloadTrim {
+    cap: number;
+    estimate: (text: string) => number;
+    trimmed: boolean;
+}
+/** Keep the head and tail of a payload longer than `cap`; the marker states
+ * exactly how much is missing so the summarizer never mistakes it for the whole.
+ * Returns the text unchanged (and leaves `trim.trimmed` alone) when cutting would
+ * not make it cheaper. Exported for regression tests only. */
+export declare function capPayload(text: string, trim: PayloadTrim | undefined): string;
+export {};

package/dist/context/llm-compactor.js

@@ -10,23 +10,41 @@
 // Failure modes are explicit: returns { compacted: false, reason } so the
 // caller can fall back to algorithmic compaction without an exception.
 import { sanitizeInternalReminderBlocks } from "../agent/internal-reminder-sanitizer.js";
-import { estimateContextTokens } from "./budget.js";
+import { estimateTextTokens, getMaxInputTokens } from "./budget.js";
+import { getTokenEstimator } from "./token-estimator.js";
+import { getModelContextWindow } from "../model-catalog.js";
 import { appendFileBlocks, stripFileBlocks } from "./compaction-files.js";
-import { collectCompactionFileOps, messageText, buildCompactionSummaryMessage, clonePinnedUserMessage, findFirstRealUserIndex, isCompactionSummaryMessage, isRealUserMessage, splitLeadingContext, } from "./compact.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.
+import { collectCompactionFileOps, messageText, buildCompactionSummaryMessage, clonePinnedUserMessage, findFirstRealUserIndex, isCompactionSummaryMessage, isRealUserMessage, splitLeadingContext, PINNED_INSTRUCTION_MAX_CHARS, } from "./compact.js";
+export const LLM_COMPACTION_PROMPT = `You are performing a CONTEXT CHECKPOINT COMPACTION. The conversation below is about to be removed from the model's context and replaced by your summary. Another LLM will resume the task seeing only your summary, the user's original instruction, and the most recent messages. Anything you leave out is gone.
 
-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
+Write a handoff summary that lets it continue without repeating the investigation. Cover:
+- Goal and constraints: what the user wants, in their terms. Explicit requirements, preferences, and anything they ruled out. Quote exact wording where precision matters.
+- Decisions made and why, including approaches that were tried and rejected, so they are not retried.
+- Current state: what is done and verified, what is in progress, what is broken or still unverified. Keep verified facts distinct from assumptions.
+- Specifics needed to continue: file paths, identifiers, commands, error messages, config values, ids, URLs. Exact, never paraphrased.
+- Next steps in order, starting with the immediate one.
 
-Be concise, structured, and focused on helping the next LLM seamlessly continue the work.`;
+Length follows content: as long as needed to preserve the above, and no longer. Spend words on what cannot be cheaply re-derived (decisions, constraints, findings). Do not reproduce file contents or tool output that can simply be read again, and do not narrate the conversation turn by turn. The lists of files read and modified are recorded separately; name only the files that matter for the next steps.
+
+Carry forward every fact from prior summaries and the original user constraints. If the input says parts of the history were omitted, say so explicitly.`;
 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;
+    if (abortSignal?.aborted)
+        return { compacted: false, reason: "compactor cancelled" };
+    const providerId = options.providerId ?? modelId.split(":")[0];
+    const catalogModelId = modelId.startsWith(`${providerId}:`) ? modelId.slice(providerId.length + 1) : modelId;
+    // Unknown models use a conservative window rather than an unbounded 100k call.
+    const contextWindow = options.contextWindow ?? getModelContextWindow(providerId, catalogModelId) ?? 8192;
+    // getMaxInputTokens already reserves the window's answer space, which is what
+    // the summary is written into. No fixed output ceiling: summary length is
+    // judged against what it replaces, below, and by the caller's before/after
+    // budget comparison.
+    const maxInputTokens = Math.min(options.maxInputTokens ?? Infinity, getMaxInputTokens(contextWindow) ?? 0);
+    if (![contextWindow, maxInputTokens].every((n) => Number.isFinite(n) && n > 0)) {
+        return { compacted: false, reason: "invalid compactor token budget" };
+    }
+    const keepRecentGroups = Math.max(0, Math.floor(options.keepRecentGroups ?? 2));
     // Positional leading prefix, not role-global filtering: filtering by role
     // used to relocate mid-history system messages (including prior summaries)
     // to the head, where the projector then fused them into the system prompt.
@@ -72,9 +90,13 @@ export async function compactWithLLM(messages, options) {
                 groups.push(active);
             active = { assistant: msg, toolResults: [] };
         }
-        else if (msg.role === "tool" && active) {
+        else if (active) {
             active.toolResults.push(msg);
         }
+        else {
+            // Preserve interleaved reminders and other context, not just tool results.
+            active = { assistant: msg, toolResults: [] };
+        }
     }
     if (active)
         groups.push(active);
@@ -91,6 +113,10 @@ export async function compactWithLLM(messages, options) {
             role: "user",
             content: `[Prior compaction summary]\n${stripFileBlocks(messageText(m))}`,
         })),
+        // The pin is capped; its tail is protected summary input, never silently lost.
+        ...(pinnedFirstUser && messageText(pinnedFirstUser).length > PINNED_INSTRUCTION_MAX_CHARS
+            ? [{ role: "user", content: `[Original instruction beyond retained pin]\n${messageText(pinnedFirstUser).slice(PINNED_INSTRUCTION_MAX_CHARS)}` }]
+            : []),
         ...summarizablePriorTurns,
         ...evictedGroups.flatMap((g) => [g.assistant, ...g.toolResults]),
     ];
@@ -101,12 +127,18 @@ export async function compactWithLLM(messages, options) {
     if (toSummarize.length === 0) {
         return { compacted: false, reason: "nothing to evict" };
     }
-    const trimmedHistory = trimToFitTokenBudget(toSummarize, maxInputTokens);
-    const historyText = serializeHistoryAsText(trimmedHistory);
+    const prompt = LLM_COMPACTION_PROMPT;
+    const fitted = fitSummaryInput(toSummarize, prompt, maxInputTokens, providerId);
+    if (!fitted) {
+        return { compacted: false, reason: "compactor input budget cannot retain prior summaries and user constraints" };
+    }
+    const { historyText, degradation } = fitted;
     const summaryInput = [
-        { role: "system", content: LLM_COMPACTION_PROMPT },
+        { role: "system", content: prompt },
         { role: "user", content: historyText },
     ];
+    if (abortSignal?.aborted)
+        return { compacted: false, reason: "compactor cancelled" };
     let summaryText;
     try {
         summaryText = await provider.complete(summaryInput, {
@@ -118,6 +150,9 @@ export async function compactWithLLM(messages, options) {
     catch (err) {
         return { compacted: false, reason: `compactor call failed: ${err.message}` };
     }
+    // Some providers resolve even after abort; never apply that late result.
+    if (abortSignal?.aborted)
+        return { compacted: false, reason: "compactor cancelled" };
     if (!summaryText || summaryText.trim().length === 0) {
         return { compacted: false, reason: "compactor returned empty summary" };
     }
@@ -125,10 +160,20 @@ export async function compactWithLLM(messages, options) {
     // (resident history holds them after pruned-mode projection), and models
     // quote their input. This summary is persisted via onCompactionApplied, so
     // scrub markup before it can reach the session file.
-    summaryText = sanitizeInternalReminderBlocks(summaryText).trim();
+    summaryText = stripFileBlocks(sanitizeInternalReminderBlocks(summaryText)).trim();
     if (!summaryText) {
         return { compacted: false, reason: "compactor returned only internal markup" };
     }
+    // The only meaningful length bound is relative: a summary that is not shorter
+    // than the history it replaces (a model echoing its input) compacts nothing.
+    // Judge the model's prose alone — the deterministic file lists are not its
+    // output — and reject rather than clip decisions/constraints out of it.
+    if (estimateTextTokens(summaryText, providerId) >= estimateTextTokens(serializeHistoryAsText(toSummarize), providerId)) {
+        return { compacted: false, reason: "compactor summary is not shorter than the history it replaces", degradation };
+    }
+    if (degradation)
+        summaryText = `${degradation}\n\n${summaryText}`;
+    const summaryWithFiles = appendFileBlocks(summaryText, fileOps);
     // 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):
@@ -152,23 +197,169 @@ export async function compactWithLLM(messages, options) {
     ];
     return {
         compacted: true,
+        degradation,
         // Same payload the resident message carries (minus the envelope prefix —
         // session replay adds its own "Previous conversation summary:" header), so
         // the persisted checkpoint matches the in-memory state, file blocks included.
-        summary: appendFileBlocks(summaryText, fileOps),
+        summary: summaryWithFiles,
         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;
+/** Fit the summarization input under the model's window, degrading breadth-first:
+ *  1. everything verbatim;
+ *  2. cap tool payloads (results and tool-call arguments alike) at the LARGEST
+ *     common length that fits — short payloads such as paths and commands stay
+ *     whole, only long ones lose their middle, and every group still informs
+ *     the summary;
+ *  3. only when even empty payloads do not fit, drop the oldest assistant/tool
+ *     group and search again, so what survives is as complete as the room allows.
+ * The cap is derived from the budget, never a fixed size. Prior summaries, user
+ * constraints and runtime context are never trimmed; if they alone exceed the
+ * budget this fails explicitly and the caller chooses a fallback.
+ * `degradation` is the durable part: whole steps the summary never saw. Trimmed
+ * middles are stated in the input only — that loss is inherent to summarizing.
+ * Exported for regression tests only — callers use compactWithLLM. */
+export function fitSummaryInput(messages, prompt, maxTokens, providerId) {
+    // Group by pending tool-call ids, not adjacency: an interleaved meta reminder
+    // between a call and its result must not split the pair — otherwise dropping
+    // can remove the call while keeping an orphan `TOOL_RESULT[tool]` line that
+    // has lost its name and provenance.
+    const groups = [];
+    const groupByCallId = new Map();
+    for (const message of messages) {
+        if (message.role === "tool") {
+            const group = groupByCallId.get(message.toolCallId);
+            if (group) {
+                group.push(message);
+                continue;
+            }
+        }
+        const group = [message];
+        groups.push(group);
+        if (message.role === "assistant" && message.toolCalls) {
+            for (const toolCall of message.toolCalls)
+                groupByCallId.set(toolCall.id, group);
+        }
+    }
+    const promptTokens = estimateTextTokens(prompt, providerId);
+    const render = (cap, dropped, estimate = (text) => estimateTextTokens(text, providerId)) => {
+        const degradation = dropped
+            ? `[Compaction input degraded: omitted ${dropped} older assistant/tool groups to fit the model window.]`
+            : undefined;
+        const trim = cap === undefined ? undefined : { cap, estimate, trimmed: false };
+        const body = serializeHistoryAsText(groups.flat(), trim);
+        // The note is part of the cost, so it appears only when something was cut:
+        // an input with nothing to trim must measure exactly like the verbatim one.
+        const trimNote = trim?.trimmed
+            ? `[Tool results and tool-call arguments longer than ${cap} characters show only their head and tail.]`
+            : undefined;
+        const historyText = [degradation, trimNote, body].filter(Boolean).join("\n\n");
+        // Measure the actual serialized payload (including labels and prompt), with
+        // the same conservative first-turn safety margin as the context budget.
+        const tokens = Math.ceil((promptTokens + estimate(historyText) + 32) * 1.25);
+        // What the note itself costs: trimming that saves less than this makes the
+        // input LARGER than the verbatim one.
+        const noteTokens = trimNote ? Math.ceil((estimate(trimNote) + 2) * 1.25) + 1 : 0;
+        return { fits: tokens <= maxTokens, overBy: tokens - maxTokens, noteTokens, trimmed: !!trim?.trimmed, fitted: { historyText, degradation } };
+    };
+    /** Largest cap the predicate accepts, assuming it is monotone; the returned
+     * cap is always one that was actually probed and accepted. */
+    const searchCap = (longest, accepts) => {
+        let low = 0;
+        let high = longest;
+        while (low < high) {
+            const middle = Math.ceil((low + high) / 2);
+            if (accepts(middle))
+                low = middle;
+            else
+                high = middle - 1;
+        }
+        return low;
+    };
+    // A provider tokenizer is not monotone in the cap: the tiktoken estimator
+    // switches to the heuristic above a length limit and BPE counts wobble at cut
+    // points, so a failing midpoint can hide a fitting interval above it. The
+    // character-class heuristic IS monotone (every character only adds), so it
+    // also proposes a cap; whichever real-estimator-verified cap is larger wins.
+    const heuristicOnly = getTokenEstimator(providerId) === getTokenEstimator();
+    for (let dropped = 0; groups.length > 0; dropped++) {
+        // Empty payloads are the cheapest probe and the floor of what trimming can reach.
+        const floor = render(0, dropped);
+        if (floor.fits) {
+            if (!floor.trimmed)
+                return floor.fitted; // Nothing to trim: this IS the verbatim input.
+            const whole = render(undefined, dropped);
+            if (whole.fits)
+                return whole.fitted;
+            const longest = longestPayload(groups);
+            let bestCap = searchCap(longest, (cap) => render(cap, dropped).fits);
+            if (!heuristicOnly) {
+                const proposed = searchCap(longest, (cap) => render(cap, dropped, (text) => estimateTextTokens(text)).fits);
+                if (proposed > bestCap && render(proposed, dropped).fits)
+                    bestCap = proposed;
+            }
+            return render(bestCap, dropped).fitted;
+        }
+        // Emptying the payloads is not always the smallest rendering. With the
+        // additive heuristic the verbatim input can only be smaller when trimming
+        // saves less than its note costs, i.e. within that cost of the budget, so it
+        // is probed just then. A provider tokenizer gives no such bound: past its
+        // length limit it switches to the (cheaper) heuristic, so a longer verbatim
+        // input can measure far below a shorter trimmed one — always probe there.
+        if (floor.trimmed && (!heuristicOnly || floor.overBy <= floor.noteTokens)) {
+            const whole = render(undefined, dropped);
+            if (whole.fits)
+                return whole.fitted;
+        }
+        const removable = groups.findIndex((group) => group.every((m) => m.role === "assistant" || m.role === "tool"));
+        if (removable < 0)
+            return undefined;
+        groups.splice(removable, 1);
+    }
+    return undefined;
+}
+function longestPayload(groups) {
+    let longest = 0;
+    for (const group of groups) {
+        for (const message of group) {
+            if (message.role === "tool")
+                longest = Math.max(longest, message.content.length);
+            else if (message.role === "assistant") {
+                for (const toolCall of message.toolCalls ?? [])
+                    longest = Math.max(longest, (toolCall.arguments || "").length);
+            }
+        }
+    }
+    return longest;
+}
+/** Keep the head and tail of a payload longer than `cap`; the marker states
+ * exactly how much is missing so the summarizer never mistakes it for the whole.
+ * Returns the text unchanged (and leaves `trim.trimmed` alone) when cutting would
+ * not make it cheaper. Exported for regression tests only. */
+export function capPayload(text, trim) {
+    if (!trim || text.length <= trim.cap)
+        return text;
+    let headEnd = Math.ceil(trim.cap / 2);
+    let tailStart = text.length - (trim.cap - headEnd);
+    // Never cut a surrogate pair in half: a lone surrogate is invalid Unicode that
+    // some provider endpoints reject outright.
+    if (headEnd > 0 && isHighSurrogate(text.charCodeAt(headEnd - 1)))
+        headEnd--;
+    if (tailStart < text.length && isLowSurrogate(text.charCodeAt(tailStart)))
+        tailStart++;
+    const capped = `${text.slice(0, headEnd)}[... ${tailStart - headEnd} of ${text.length} characters omitted ...]${text.slice(tailStart)}`;
+    // Worth it only if it is cheaper in TOKENS. Fewer characters is taken as
+    // cheaper without pricing (large payloads, every probe); a marker longer than
+    // what it replaces can still be cheaper for token-dense text such as CJK, and
+    // that case is always short enough to price exactly.
+    if (capped.length >= text.length && trim.estimate(capped) >= trim.estimate(text))
+        return text;
+    trim.trimmed = true;
+    return capped;
 }
-function serializeHistoryAsText(messages) {
+const isHighSurrogate = (code) => code >= 0xd800 && code <= 0xdbff;
+const isLowSurrogate = (code) => code >= 0xdc00 && code <= 0xdfff;
+function serializeHistoryAsText(messages, trim) {
     const lines = [];
     const toolNameByCallId = new Map();
     for (const msg of messages) {
@@ -187,39 +378,31 @@ function serializeHistoryAsText(messages) {
                 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)}`);
+                        lines.push(`TOOL_CALL[${tc.name}]: ${capPayload(summarizeToolCallArgs(tc), trim)}`);
                     }
                 }
                 break;
             }
             case "tool": {
                 const name = toolNameByCallId.get(msg.toolCallId) ?? "tool";
-                lines.push(`TOOL_RESULT[${name}]: ${truncateInline(msg.content, 1500)}`);
+                lines.push(`TOOL_RESULT[${name}]: ${capPayload(msg.content, trim)}`);
                 break;
             }
+            case "meta":
+                // Expired runtime reminders remain in history but are no longer model
+                // context. Prior summaries have already been folded into user input.
+                if (msg.includeInLlm !== false)
+                    lines.push(`CONTEXT: ${msg.content}`);
+                break;
             default:
+                lines.push(`CONTEXT: ${messageText(msg)}`);
                 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)}...`;
+    return tc.arguments || "{}";
 }
 function cloneMessage(message) {
     if (message.role === "assistant") {

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;