@superblocksteam/vite-plugin-file-sync 1.99.99-next.2 → 2.0.0-SNAPSHOT.2143e2e95d0107ab

package/dist/ai-service/llm/context-v2/context.js

@@ -0,0 +1,1666 @@
+import { randomUUID } from "node:crypto";
+import { performance } from "node:perf_hooks";
+import { setImmediate } from "node:timers/promises";
+import { getErrorMeta, getPrefixedLogger } from "../../../util/logger.js";
+import { LLMObsTracer } from "../../llmobs/tracer.js";
+import { findBreakpoints } from "./caching.js";
+import { SERVER_COMPACTION_INTERRUPTED_SUMMARY, SERVER_COMPACTION_SUMMARY, ServerSideCompactionStrategy, } from "./compaction/server-side.js";
+import { compactionThresholdTokens, DEFAULT_CACHING, resolveContextOptionsV2, } from "./config.js";
+import { recordContextPersist, recordPreflightCompaction, recordServerCompaction, recordTurnsSinceLastCompaction, } from "./context-metrics.js";
+import { OperationQueue } from "./operation-queue.js";
+import { CLIENT_COMPACTION_MARKER } from "./storage/event-types.js";
+import { estimateMessagesTokens, getTotalInputTokens, } from "./token-tracker.js";
+import { toStoredMessage, toSdkMessages, CACHE_BREAKPOINT_PROVIDER_OPTIONS, normalizeToolMessage, stripUndefinedFromToolOutputs, repairBrokenToolCalls, repairOrphanedToolResults, enforceToolUsePairing, normalizeReasoningProviderOptions, stripUnsignedReasoning, stripTrailingAssistantPrefill, extractTokenUsage, } from "./types.js";
+import { uniquifyFilePartFilenames } from "./uniquify-filenames.js";
+import { makeJsonSafeValue } from "./well-formed-text.js";
+const logger = getPrefixedLogger("[context-v2]");
+/**
+ * Persists slower than this get a warning log with the message count.
+ * Diagnostic threshold for APPS-4690: large-history apps can cross it on
+ * every turn (each response rewrites the full context file), so treat it as
+ * a signal that the context is oversized, not as a per-occurrence alert.
+ * Raise or remove once per-turn full-file rewrites are addressed.
+ */
+const SLOW_PERSIST_WARN_MS = 500;
+/**
+ * Deadline for the pre-flight oversize compaction pass.
+ *
+ * Sits just above the summarizer's own per-call budget
+ * (`DEFAULT_COMPACTION_SUMMARY_TIMEOUT_MS`, 240s) so the deadline stops firing
+ * before the work it is waiting on can even finish.
+ *
+ * Picked from production rather than from taste. Measured over the four weeks
+ * to 2026-09-01, client-side compaction
+ * (`superblocks.clark.context.server_compaction.duration_seconds`, filtered to
+ * `path:client`) ran 6,690 times with a mean of 36.8s, an hourly-worst-case p99
+ * of 238.7s, and a peak of 382.8s. The earlier 120s value sat under the p90 of
+ * the hourly maxima, so it abandoned passes that would have succeeded on
+ * exactly the largest histories, which are the ones this check exists to
+ * rescue. Even 250s does not cover the peak; a pass past it degrades to the
+ * provider rejecting the request, reported as `context_too_large`.
+ *
+ * A longer deadline is only affordable because of the latch. Without
+ * `oversizeCompactionExhausted` a doomed pass would be restarted on every
+ * prompt, so the wait would be paid per message rather than once per
+ * conversation.
+ *
+ * `compact()` accepts no abort signal, so a pass past its deadline is abandoned
+ * rather than cancelled and keeps running (and billing) in the background.
+ * `oversizeCompactionSettled` is what keeps a sibling pass out while that
+ * orphan is live; raising this value without real cancellation lengthens the
+ * orphan window it has to cover.
+ */
+export const PREFLIGHT_COMPACTION_TIMEOUT_MS = 250_000;
+/** Thrown by `withDeadline` so a slow pass can be told apart from a broken one. */
+class DeadlineExceededError extends Error {
+}
+/**
+ * Resolve `promise`, or reject once `timeoutMs` elapses.
+ *
+ * Deliberately local rather than reusing `withRpcTimeout`: that helper logs
+ * "RPC timed out", which would misdirect anyone triaging a summarizer stall.
+ */
+async function withDeadline(promise, timeoutMs) {
+    let timeoutId;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_resolve, reject) => {
+                timeoutId = setTimeout(() => reject(new DeadlineExceededError(`compaction did not settle within ${timeoutMs}ms`)), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timeoutId !== undefined) {
+            clearTimeout(timeoutId);
+        }
+    }
+}
+/**
+ * Which family a compaction strategy belongs to.
+ *
+ * Read by instance rather than from a field on the interface: there are exactly
+ * two implementations, `ServerSideCompactionStrategy` is already imported here,
+ * and a `kind` member would have to be added to every strategy and every test
+ * mock to answer the same question.
+ */
+function compactionStrategyKind(strategy) {
+    return strategy instanceof ServerSideCompactionStrategy ? "server" : "client";
+}
+/** Messages replayed between explicit event-loop yields in initializeWith. */
+const REPLAY_YIELD_INTERVAL = 100;
+/**
+ * Usage attributed to messages replayed from history (no live usage data).
+ * Token accounting is intentionally zeroed for replayed messages — the first
+ * real response after replay restores accurate cumulative tracking via
+ * `getLastKnownInputTokens` monotonicity.
+ */
+const ZERO_USAGE = {
+    inputTokens: 0,
+    outputTokens: 0,
+    totalTokens: 0,
+    inputTokenDetails: {
+        noCacheTokens: 0,
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0,
+    },
+    outputTokenDetails: {
+        textTokens: 0,
+        reasoningTokens: 0,
+    },
+};
+/**
+ * Whether an assistant message contains `tool-call` content parts whose
+ * matching `tool-result` messages have not been stored yet. Used by
+ * `runCompactionIfNeeded` to defer compaction past the assistant turn that
+ * produced the call until the tool result arrives (otherwise the assistant
+ * tool_use gets summarized away and the upcoming tool_result is orphaned).
+ */
+function hasPendingToolCalls(msg) {
+    if (msg.role !== "assistant" || !Array.isArray(msg.content)) {
+        return false;
+    }
+    return msg.content.some((part) => typeof part === "object" &&
+        part !== null &&
+        "type" in part &&
+        part.type === "tool-call");
+}
+/** Check if a tool message contains an unstripped screenshot media result. */
+function hasScreenshotMedia(msg) {
+    if (msg.role !== "tool" || !Array.isArray(msg.content)) {
+        return false;
+    }
+    return msg.content.some((part) => typeof part === "object" &&
+        part !== null &&
+        "type" in part &&
+        part.type === "tool-result" &&
+        "toolName" in part &&
+        part.toolName === "build_captureScreenshot" &&
+        "output" in part &&
+        part.output?.type === "content");
+}
+function isUiOnlyToolChatRow(message) {
+    if (message.role !== "assistant" || typeof message.content !== "string") {
+        return false;
+    }
+    const row = message;
+    return (typeof row.toolCallId === "string" &&
+        (row.type === "tool" ||
+            row.type === "tool-result" ||
+            row.type === "tool-error"));
+}
+/** Strip base64 media from screenshot tool results, replacing with a text placeholder. */
+function stripScreenshotMediaFromToolMessage(msg) {
+    if (msg.role !== "tool" || !Array.isArray(msg.content)) {
+        return msg;
+    }
+    let modified = false;
+    const strippedContent = msg.content.map((part) => {
+        if (typeof part === "object" &&
+            part !== null &&
+            "type" in part &&
+            part.type === "tool-result" &&
+            "toolName" in part &&
+            part.toolName === "build_captureScreenshot" &&
+            "output" in part) {
+            const output = part.output;
+            if (output &&
+                typeof output === "object" &&
+                "type" in output &&
+                output.type === "content") {
+                modified = true;
+                return {
+                    ...part,
+                    output: {
+                        type: "text",
+                        value: "[screenshot captured]",
+                    },
+                };
+            }
+        }
+        return part;
+    });
+    if (!modified) {
+        return msg;
+    }
+    logger.info("Stripped screenshot media from tool message before storage");
+    return { ...msg, content: strippedContent };
+}
+export class ContextV2 {
+    systemPrompt;
+    messages = [];
+    attachments;
+    config;
+    caching;
+    queue = new OperationQueue();
+    onPersist;
+    tracer;
+    rootDir;
+    skillsNeedReload = false;
+    readSystemSkills = new Set();
+    getModeState;
+    /**
+     * Real provider usage captured when `runCompactionIfNeeded` defers past an
+     * assistant turn with pending tool calls. Consumed (one-shot) by the check
+     * that closes the deferral if that message arrives with zeroed placeholder
+     * usage — the tool-permission flow does exactly that (ENG-4792). In-memory
+     * only: if the context is recreated mid-deferral, the check degrades to the
+     * strategy's existing zero-usage skip.
+     */
+    deferredCompactionUsage;
+    eventStore;
+    contextId;
+    metricIdentity;
+    compaction;
+    compactionCallbacks;
+    serverCompactionMessageId;
+    activeServerCompactionGeneration;
+    activeServerCompactionStartedAt;
+    endedServerCompactionGeneration;
+    serverCompactionGeneration = 0;
+    // Set when a compaction completion is synthesized before its text-start
+    // chunk arrives (reversed event ordering). The completion already rendered a
+    // full start+complete row, so the late start belongs to that same compaction
+    // and must be swallowed instead of opening a second, never-completed row.
+    // Scoped to the current turn; cleared when the next user message begins.
+    serverCompactionCompletedBeforeStart = false;
+    completedTurnCount = 0;
+    lastCompactionAtTurnIndex = 0;
+    // When disposed, this context may still be referenced by in-flight streams.
+    // Keep it inert so stale generations cannot persist cleared history.
+    isDisposed = false;
+    /** Shared by concurrent callers so only one oversize pass ever runs. */
+    oversizeCompactionInFlight;
+    /**
+     * Largest `extraInputTokens` any caller attached to the in-flight pass.
+     *
+     * Callers sharing a pass can have sized different tool surfaces, and the
+     * shared promise would otherwise silently decide on whichever one happened to
+     * start it. Max fails safe: under-counting skips a compaction the request
+     * needed, over-counting only runs one it could have skipped. Read when the
+     * queued callback actually runs, so anything attaching before then counts.
+     *
+     * Defensive rather than an observed bug: both callers have to be on the SAME
+     * ContextV2, and the nested one-shot path uses `context: { mode: "stateless" }`,
+     * so it never shares this instance.
+     */
+    oversizeCompactionExtraTokens = 0;
+    /**
+     * The summarizer call itself, unbounded by the deadline the caller waits on.
+     * `compactIfOversized` holds the in-flight guard until this settles, so an
+     * abandoned `compact()` cannot run alongside a fresh pass.
+     */
+    oversizeCompactionSettled;
+    /**
+     * Set once a pass has ended with the payload STILL over the threshold, for
+     * any reason: the strategy declined, the pass threw, the deadline rejected,
+     * or it ran and reclaimed too little. While set, `compactIfOversized` returns
+     * immediately and starts no new paid pass.
+     *
+     * The restore-time version of this check got the same protection for free,
+     * because `ContextManagerV2` only invoked it while a pending flag was set and
+     * a pass that tried and failed never re-flagged. Moving the check onto every
+     * `streamText` dropped that, so a summarizer that hangs would stall every
+     * later prompt for the full deadline and stack concurrent billable
+     * summarizations over the same history. The provider rejecting an oversized
+     * request takes ~130ms; this took two minutes per prompt. Worse than the
+     * wedge it exists to fix.
+     *
+     * Deliberately NOT cleared when a pass succeeds and the payload now fits, so
+     * later regrowth can still be rescued. Reset only in `setCompactionStrategy`:
+     * a different strategy is the one real change that could produce a different
+     * outcome, and New Chat resets it for free by constructing a fresh instance.
+     */
+    oversizeCompactionExhausted = false;
+    // Persists currently mid-flight. A persist that has already passed the
+    // dispose guard is committed to writing the snapshot, so `dispose()` alone
+    // cannot stop it; `drainPersists()` lets a caller that is about to overwrite
+    // the snapshot (checkpoint restore) wait for those writes to land first.
+    inFlightPersists = new Set();
+    constructor(options) {
+        this.rootDir = options.rootDir;
+        this.config = resolveContextOptionsV2(options.config);
+        this.caching = { ...DEFAULT_CACHING, ...options.caching };
+        this.onPersist = options.onPersist;
+        this.tracer = options.tracer;
+        this.getModeState = options.getModeState;
+        this.eventStore = options.eventStore;
+        this.contextId = options.contextId;
+        this.metricIdentity = options.metricIdentity;
+        this.compaction = options.compaction ?? new ServerSideCompactionStrategy();
+    }
+    // Cached result of getMessages() normalization. Avoids recomputing
+    // 10+ repair/normalization passes when messages haven't changed.
+    // Invalidated by any operation that modifies this.messages or systemPrompt.
+    // NOTE: Returns a shallow copy of the cached array. Element references are
+    // shared — callers must treat returned message objects as read-only.
+    _cachedMessages = null;
+    /**
+     * Call this before AND after every operation that modifies `this.messages`
+     * or `this.systemPrompt`. Pre-enqueue call prevents fast-path cache hits
+     * while the mutation is queued; post-mutation call handles the scenario where
+     * a `getMessages()` queue op ran and cached a result between enqueue and
+     * execution.
+     *
+     * CHECKLIST for new mutation methods:
+     * - Synchronous mutations: call once after the mutation.
+     * - Async queue mutations: call once before enqueue, once after the mutation
+     *   inside the queue op.
+     */
+    invalidateMessageCache() {
+        this._cachedMessages = null;
+    }
+    updateConfig(config) {
+        this.config = resolveContextOptionsV2({ ...this.config, ...config });
+        this.invalidateMessageCache();
+        this.compaction.updateConfig(config);
+    }
+    /**
+     * Swap the active compaction strategy on a live context. Called from
+     * `ContextManagerV2.getOrCreateContext` on a cache hit when the
+     * incoming `contextManagement` selection (derived from the per-request
+     * LD flag) differs from whatever the cached context was first
+     * constructed with. Without this, the first caller's strategy locks
+     * in for the lifetime of the cache entry and the kill-switch flag
+     * silently no-ops.
+     */
+    setCompactionStrategy(strategy) {
+        if (this.compaction === strategy)
+            return;
+        const previousKind = compactionStrategyKind(this.compaction);
+        this.compaction = strategy;
+        this.compaction.updateConfig(this.config);
+        this.compaction.setCallbacks(this.compactionCallbacks);
+        // Only a change of KIND clears the latch, not any swap.
+        //
+        // `buildCompactionStrategy` returns a fresh instance every time and the
+        // manager calls this on every managed turn, so the reference guard above
+        // never short-circuits in production. Clearing on any swap therefore
+        // cleared the latch on every single prompt, which made it do nothing and
+        // put the per-prompt stall straight back. Kind is the thing that actually
+        // changes the answer: the `ai.server-context-management.options` kill
+        // switch flipping a latched server-side context over to a client-side one
+        // is a genuine second chance, another client instance is not.
+        if (compactionStrategyKind(strategy) !== previousKind) {
+            this.oversizeCompactionExhausted = false;
+        }
+    }
+    setMetricIdentity(identity) {
+        this.metricIdentity = identity;
+    }
+    dispose() {
+        this.isDisposed = true;
+        this.onPersist = undefined;
+    }
+    storeSummary(toolCallId, summary) {
+        this.compaction.storeSummary(toolCallId, summary);
+    }
+    setCompactionCallbacks(callbacks) {
+        this.compactionCallbacks = callbacks;
+        this.compaction.setCallbacks(callbacks);
+    }
+    onServerCompactionStarted() {
+        if (this.serverCompactionCompletedBeforeStart) {
+            this.serverCompactionCompletedBeforeStart = false;
+            return;
+        }
+        if (!this.serverCompactionMessageId) {
+            this.activeServerCompactionStartedAt = performance.now();
+        }
+        this.ensureServerCompactionMessageStarted();
+    }
+    onServerCompactionCancelled() {
+        if (!this.serverCompactionMessageId) {
+            return;
+        }
+        this.recordServerCompactionOutcome("cancelled");
+        this.endedServerCompactionGeneration =
+            this.activeServerCompactionGeneration;
+        this.compactionCallbacks?.onCompactionCancel?.("phase2", this.serverCompactionMessageId);
+        this.serverCompactionMessageId = undefined;
+        this.activeServerCompactionGeneration = undefined;
+        this.activeServerCompactionStartedAt = undefined;
+    }
+    onServerCompactionInterrupted() {
+        if (!this.serverCompactionMessageId) {
+            return;
+        }
+        this.recordServerCompactionOutcome("interrupted");
+        const messageId = this.serverCompactionMessageId;
+        const generation = this.activeServerCompactionGeneration;
+        this.compactionCallbacks?.onCompactionComplete?.("phase2", messageId, SERVER_COMPACTION_INTERRUPTED_SUMMARY);
+        if (generation !== undefined) {
+            this.endedServerCompactionGeneration = generation;
+        }
+        this.serverCompactionMessageId = undefined;
+        this.activeServerCompactionGeneration = undefined;
+        this.activeServerCompactionStartedAt = undefined;
+    }
+    markSkillsNeedReload() {
+        this.skillsNeedReload = true;
+        this.readSystemSkills.clear();
+    }
+    checkAndClearSkillsNeedReload() {
+        if (this.skillsNeedReload) {
+            this.skillsNeedReload = false;
+            return true;
+        }
+        return false;
+    }
+    hasReadSystemSkill(path) {
+        return this.readSystemSkills.has(path);
+    }
+    markSystemSkillRead(path) {
+        this.readSystemSkills.add(path);
+    }
+    setAttachments(attachments) {
+        this.attachments = attachments;
+        void this.persist("attachments");
+    }
+    getAttachments() {
+        return this.attachments;
+    }
+    truncateAfterTimestamp(timestamp) {
+        this.invalidateMessageCache();
+        this.readSystemSkills.clear();
+        void this.queue.enqueue(async () => {
+            const initialCount = this.messages.length;
+            this.messages = this.messages.filter((msg) => !msg._superblocks?.timestamp ||
+                msg._superblocks.timestamp <= timestamp);
+            this.readSystemSkills.clear();
+            this.invalidateMessageCache();
+            const removed = initialCount - this.messages.length;
+            logger.info(`Truncated context after timestamp ${timestamp}. Removed ${removed} messages, ${this.messages.length} remaining.`);
+            await this.persist("truncate");
+        });
+    }
+    static fromRecord(record, options) {
+        const context = new ContextV2(options);
+        context.messages = record.messages;
+        context.attachments = record.attachments;
+        // Live sessions keep media on only the newest screenshot, but event-log
+        // entries are appended before that stripping happens, so a restored
+        // record can resurrect every screenshot's media. Re-stripping here keeps
+        // the restored request bytes identical to what the provider's prompt
+        // cache saw before the restart (APPS-4751) — and avoids re-sending
+        // megabytes of stale base64.
+        context.stripAllButLatestScreenshot();
+        return context;
+    }
+    toRecord() {
+        return {
+            version: 2,
+            messages: this.messages,
+            attachments: this.attachments,
+        };
+    }
+    setSystemPrompt(prompt) {
+        this.systemPrompt = toStoredMessage(prompt);
+        this.invalidateMessageCache();
+    }
+    async addUserMessage(message) {
+        this.serverCompactionCompletedBeforeStart = false;
+        this.endedServerCompactionGeneration = undefined;
+        this.invalidateMessageCache();
+        return this.queue.enqueue(async () => {
+            const storedMessage = toStoredMessage(message);
+            this.messages.push(storedMessage);
+            this.invalidateMessageCache();
+            await this.appendEvent("prompt_sent", storedMessage);
+        });
+    }
+    /**
+     * Replay a full message history into an empty context (cold-pod session
+     * restore). Unlike per-turn `addUserMessage`/`addResponse`, this persists
+     * exactly once at the end: persisting per replayed message serializes the
+     * entire accumulated context each time — O(n²) work that blocks the event
+     * loop for minutes at large history sizes (APPS-4690).
+     *
+     * Must only be called on an empty context. Replaying on top of messages
+     * loaded from storage would silently duplicate the conversation (and, for
+     * persistent contexts, re-append every message to the event log).
+     */
+    async initializeWith(messages) {
+        this.invalidateMessageCache();
+        const tracer = this.tracer ?? LLMObsTracer.instance;
+        return tracer.trace({ kind: "task", name: "context.replay" }, (span) => this.replayMessages(messages, tracer, span));
+    }
+    async replayMessages(messages, tracer, span) {
+        const enqueuedAt = performance.now();
+        let replayMs = 0;
+        await this.queue.enqueue(async () => {
+            const replayStartedAt = performance.now();
+            if (this.messages.length > 0) {
+                logger.warn(`initializeWith called on a non-empty context (${this.messages.length} existing messages); appending — this likely duplicates history`);
+            }
+            for (let i = 0; i < messages.length; i++) {
+                // Without an event store (ephemeral contexts) nothing below awaits
+                // real I/O, so the whole replay runs as one synchronous block; yield
+                // periodically so timers, sockets, and heartbeats can run.
+                if (i > 0 && i % REPLAY_YIELD_INTERVAL === 0) {
+                    await setImmediate();
+                }
+                const message = messages[i];
+                if (!message) {
+                    continue;
+                }
+                if (isUiOnlyToolChatRow(message)) {
+                    logger.warn(`initializeWith: dropped UI-only tool chat row at index ${i}; type=${message.type}; toolCallId=${message.toolCallId}; tool=${message.tool ?? "unknown"}`);
+                    continue;
+                }
+                if (message.role === "system") {
+                    // Last system message wins; an explicit setSystemPrompt() after
+                    // initializeWith() still takes precedence because it runs later.
+                    this.systemPrompt = toStoredMessage(message);
+                    continue;
+                }
+                if (message.role === "user") {
+                    const storedMessage = toStoredMessage(message);
+                    this.messages.push(storedMessage);
+                    await this.appendEvent("prompt_sent", storedMessage);
+                    continue;
+                }
+                const storedResponse = this.ingestResponse(message, ZERO_USAGE, {
+                    stripOlderScreenshots: false,
+                });
+                const eventUsage = message.role === "assistant"
+                    ? extractTokenUsage(ZERO_USAGE)
+                    : undefined;
+                await this.appendEvent("response_received", storedResponse, eventUsage);
+            }
+            this.stripAllButLatestScreenshot();
+            this.invalidateMessageCache();
+            await this.persist("replay");
+            replayMs = Math.round(performance.now() - replayStartedAt);
+        });
+        // queueWaitMs separates queue contention from replay work so a slow
+        // number here points at the right culprit (APPS-4690 diagnosis log).
+        const queueWaitMs = Math.round(performance.now() - enqueuedAt) - replayMs;
+        tracer.annotate(span, {
+            metadata: { messageCount: messages.length, queueWaitMs, replayMs },
+        });
+        logger.info(`initializeWith: replayed ${messages.length} messages in ${replayMs}ms (queueWaitMs=${queueWaitMs})`);
+    }
+    async addResponse(response, usage) {
+        this.invalidateMessageCache();
+        await this.queue.enqueue(async () => {
+            const storedResponse = this.ingestResponse(response, usage, {
+                stripOlderScreenshots: true,
+            });
+            this.invalidateMessageCache();
+            if (response.role === "assistant" || response.role === "tool") {
+                const eventUsage = response.role === "assistant" ? extractTokenUsage(usage) : undefined;
+                await this.appendEvent("response_received", storedResponse, eventUsage);
+            }
+            await this.persist("response");
+        });
+        // After the queued write completes, give the compaction strategy a chance
+        // to react. Server-side is a no-op; client-side may compact this.messages
+        // and flip skillsNeedReload. Must be `await` (not `return`) because the
+        // earlier `await ... .enqueue(...)` already settles before we reach here
+        // — a `return` over the previous line would have made this unreachable.
+        await this.runCompactionIfNeeded(response, usage);
+    }
+    /**
+     * Commit a whole step's responses into the conversation.
+     *
+     * The streaming path (`ContextObserver` → adapter `endStep`) used to call
+     * {@link addResponse} once per response message, and every call rewrote the
+     * entire context file (an O(history) synchronous `JSON.stringify`). On
+     * large-history apps that repeated full-record rewrite blocked the event
+     * loop for seconds *per message* mid-generation — the wedge in APPS-4690.
+     *
+     * This commits the step's messages without a full-record rewrite: each
+     * message is appended to the event log (an O(1) append that carries
+     * per-message durability), and the legacy full-record snapshot is deferred
+     * to {@link endTurn} so the whole generation costs one rewrite instead of
+     * one per message. Screenshot-media stripping is likewise deferred to a
+     * single backward pass (mirroring {@link initializeWith}) instead of an
+     * O(history) scan per message.
+     */
+    async addResponses(responses, usage) {
+        if (responses.length === 0) {
+            return;
+        }
+        this.invalidateMessageCache();
+        await this.queue.enqueue(async () => {
+            for (const response of responses) {
+                const storedResponse = this.ingestResponse(response, usage, {
+                    stripOlderScreenshots: false,
+                });
+                if (response.role === "assistant" || response.role === "tool") {
+                    const eventUsage = response.role === "assistant"
+                        ? extractTokenUsage(usage)
+                        : undefined;
+                    await this.appendEvent("response_received", storedResponse, eventUsage);
+                }
+            }
+            this.stripAllButLatestScreenshot();
+            this.invalidateMessageCache();
+        });
+        // Compaction runs once after the step is committed. It inspects the whole
+        // message array and only acts when no tool calls are pending, so a single
+        // post-batch call preserves the per-message deferral behavior. When it does
+        // compact it persists the (smaller) compacted record itself.
+        const lastResponse = responses[responses.length - 1];
+        if (lastResponse) {
+            await this.runCompactionIfNeeded(lastResponse, usage);
+        }
+    }
+    /**
+     * Begin a user turn. Resets per-turn compaction state (the re-arm latch) so
+     * a fresh turn's first compaction is unguarded. Called by the
+     * adapter's startTurn, once per managed generation (see LLMClient.streamText).
+     */
+    startTurn() {
+        this.compaction.onTurnStart();
+    }
+    /**
+     * Persist the full record once, at the end of a generation.
+     *
+     * Per-step {@link addResponses} no longer rewrites the whole context file
+     * (APPS-4690); this single end-of-turn snapshot keeps the legacy `main.json`
+     * (attachments + the checkpoint/Bucketeer snapshot) reasonably fresh while
+     * per-message durability is carried by the event log. Enqueued so it
+     * serializes behind any in-flight step commit.
+     */
+    async endTurn() {
+        await this.queue.enqueue(async () => {
+            this.completedTurnCount += 1;
+            await this.persist("turn_end");
+        });
+    }
+    recordInterCompactionTurnInterval() {
+        const turnsSince = this.completedTurnCount - this.lastCompactionAtTurnIndex;
+        if (turnsSince > 0) {
+            recordTurnsSinceLastCompaction(turnsSince);
+        }
+        this.lastCompactionAtTurnIndex = this.completedTurnCount;
+    }
+    /** Store a single assistant/tool/other response message and return it. */
+    ingestResponse(response, usage, options) {
+        switch (response.role) {
+            case "assistant": {
+                // Total input tokens = non-cached + cached (prompt caching splits these)
+                const reportedInputTokens = getTotalInputTokens(usage);
+                // Ensure cumulative tokens never decrease - on cache misses, the LLM may
+                // report artificially low input tokens (just new tokens, not the full context).
+                // Use the higher of reported tokens or last known to maintain monotonicity.
+                const lastKnownTokens = this.getLastKnownInputTokens();
+                const cumulativeInputTokens = Math.max(reportedInputTokens, lastKnownTokens);
+                normalizeReasoningProviderOptions(response);
+                const extraMeta = this.compaction.collectAssistantMetadata(response) ?? {};
+                const storedResponse = toStoredMessage(response, {
+                    cumulativeInputTokens,
+                    tokenCount: usage.outputTokens,
+                    ...extraMeta,
+                });
+                this.messages.push(storedResponse);
+                return storedResponse;
+            }
+            case "tool": {
+                const normalized = normalizeToolMessage(stripUndefinedFromToolOutputs(response));
+                // Strip media from older screenshots so at most one is kept in stored
+                // messages. Bulk replay defers this to a single pass at the end.
+                if (options.stripOlderScreenshots && hasScreenshotMedia(normalized)) {
+                    let strippedCount = 0;
+                    for (let i = 0; i < this.messages.length; i++) {
+                        const msg = this.messages[i];
+                        if (msg && hasScreenshotMedia(msg)) {
+                            this.messages[i] = stripScreenshotMediaFromToolMessage(msg);
+                            strippedCount++;
+                        }
+                    }
+                    if (strippedCount > 0) {
+                        logger.info(`Stripped media from ${strippedCount} older screenshot(s)`);
+                    }
+                }
+                const extraMeta = this.compaction.collectToolMetadata(normalized) ?? {};
+                const storedResponse = toStoredMessage(normalized, extraMeta);
+                this.messages.push(storedResponse);
+                return storedResponse;
+            }
+            default: {
+                const storedResponse = toStoredMessage(response);
+                this.messages.push(storedResponse);
+                return storedResponse;
+            }
+        }
+    }
+    /** Single backwards pass keeping media on only the newest screenshot. */
+    stripAllButLatestScreenshot() {
+        let latestKept = false;
+        let strippedCount = 0;
+        for (let i = this.messages.length - 1; i >= 0; i--) {
+            const msg = this.messages[i];
+            if (!msg || !hasScreenshotMedia(msg)) {
+                continue;
+            }
+            if (!latestKept) {
+                latestKept = true;
+                continue;
+            }
+            this.messages[i] = stripScreenshotMediaFromToolMessage(msg);
+            strippedCount++;
+        }
+        if (strippedCount > 0) {
+            logger.info(`Stripped media from ${strippedCount} older screenshot(s)`);
+        }
+    }
+    /**
+     * Runs the configured compaction strategy after the most recent response
+     * has been stored. For the server-side strategy this is a no-op; for the
+     * client-side strategy it may replace `this.messages` with a compacted set
+     * and flip `skillsNeedReload`.
+     *
+     * Defers when `this.messages` ends in an assistant turn whose `tool_use`
+     * blocks haven't been matched by a `tool_result` message yet. Running
+     * compaction at that point would summarize the assistant message away;
+     * when the matching tool result arrives in the next step it would
+     * reference a `toolCallId` that no longer exists, and
+     * `repairOrphanedToolResults` would strip it on the next `getMessages`.
+     * Waiting for the tool result to arrive first means both halves of the
+     * pair are summarized together — no orphan.
+     *
+     * Triggered from both assistant and tool responses (drop the original
+     * assistant-only gate) so the deferred run can fire on the tool_result
+     * that closes out a step's pending tool calls.
+     */
+    async runCompactionIfNeeded(response, usage) {
+        if (this.isDisposed)
+            return;
+        if (response.role !== "assistant" && response.role !== "tool")
+            return;
+        return this.queue.enqueue(async () => {
+            const last = this.messages[this.messages.length - 1];
+            if (!last)
+                return;
+            if (last.role === "assistant" && hasPendingToolCalls(last)) {
+                // Preserve the real measurement we are deferring on: the message that
+                // closes the pending call may arrive through a placeholder-usage path
+                // (the tool-permission flow appends a synthetic assistant/tool_result
+                // pair with zeroed usage), and the deferred check must not go blind at
+                // exactly the safe point the deferral was aiming for (ENG-4792).
+                if (getTotalInputTokens(usage) > 0) {
+                    this.deferredCompactionUsage = usage;
+                }
+                return;
+            }
+            let effectiveUsage = usage;
+            if (getTotalInputTokens(usage) === 0 &&
+                this.deferredCompactionUsage !== undefined) {
+                effectiveUsage = this.deferredCompactionUsage;
+                logger.info("Compaction check reusing usage deferred past pending tool calls", { inputContextTokens: getTotalInputTokens(effectiveUsage) });
+            }
+            // One-shot: the measurement is only valid for the check that closes the
+            // deferral. Clear it regardless of which usage this check ran with, so
+            // a stale value can never leak into unrelated later turns.
+            this.deferredCompactionUsage = undefined;
+            const result = await this.compaction.afterResponse({
+                messages: this.messages,
+                usage: effectiveUsage,
+            });
+            if (result.messages) {
+                this.recordInterCompactionTurnInterval();
+                // Retained assistant messages still carry pre-compaction
+                // `cumulativeInputTokens`. Mark them so the post-compaction floor
+                // resets (see `markPreCompactionBaselines` / `getLastKnownInputTokens`).
+                this.messages = this.markPreCompactionBaselines(result.messages);
+                this.invalidateMessageCache();
+            }
+            if (result.skillsNeedReload) {
+                this.skillsNeedReload = true;
+                this.readSystemSkills.clear();
+            }
+            if (result.eventLogAnchor && result.messages) {
+                // Append the marked messages so the reset survives reload from the
+                // event log (loadMessages), not just the in-memory record.
+                //
+                // Only phase-2 sets `eventLogAnchor` (it produces a new summary window).
+                // Phase-1-only compaction summarizes tool outputs in place and writes
+                // nothing new here, so its baseline flags live only in the persisted
+                // record. That is intentional and safe: phase-1 creates no event-log
+                // anchor, so on reload `loadMessages` replays the FULL unsummarized
+                // history — the prompt is large again, making the retained
+                // `cumulativeInputTokens` accurate (not stale), and the next over-
+                // threshold turn re-runs `markPreCompactionBaselines` to reset the
+                // floor for the new epoch.
+                await this.appendCompactionWindow(this.messages);
+            }
+            if (result.messages) {
+                await this.persist("compaction");
+            }
+        });
+    }
+    /**
+     * Compact this conversation when the request about to be sent is already too
+     * large for the model, BEFORE sending it.
+     *
+     * A long session can grow its persisted history past the model's input limit
+     * without any single live request crossing the compaction threshold: the
+     * per-request prompt stays small while storage keeps accumulating. When a
+     * dev-server restart or warm-pool recycle then restores that history in full,
+     * the first request is rejected by the provider before it reports any usage.
+     * Since `afterResponse` is the only compaction trigger and it needs
+     * provider-reported usage, compaction can never fire again, every retry
+     * replays the same oversized payload, and the app is wedged permanently
+     * (ENG-5282).
+     *
+     * Breaking that cycle needs a check that does not depend on the provider, so
+     * the size is estimated from the payload's own content. The estimate only
+     * gates the decision. The compaction pipeline, thresholds, and phase
+     * selection are the existing ones, so behavior below the threshold is
+     * unchanged.
+     *
+     * Call this from where the request is assembled, after the system prompt is
+     * set and the turn is appended: the estimate then covers the array that is
+     * actually going on the wire, the UI compaction callbacks are already
+     * attached so the user sees the summarization, and a concurrent eviction is
+     * handled by the same `isDisposed` guard as the per-response trigger.
+     *
+     * At most one pass runs at a time, and a pass that ends with the payload
+     * still over the threshold latches the context so no later turn starts
+     * another paid attempt. See `oversizeCompactionExhausted`.
+     *
+     * @param extraInputTokens tokens the request carries that are not in the
+     *   message array, principally the tool-definition schemas. The caller sizes
+     *   them because it is the layer that holds them; this class stays free of
+     *   any dependency on the agent tool types. Measured against the five
+     *   captured production sessions, the estimate reads 0.19x to 1.23x of
+     *   provider-reported usage, and tool schemas are the largest identified
+     *   part of that shortfall. Omitting this is exactly today's behavior.
+     *   Accepts a thunk so the caller's sizing work (schema conversion and
+     *   serialization of every tool) is skipped entirely when the kill switch is
+     *   off or the context is latched; a plain number is evaluated by the caller
+     *   regardless.
+     * @returns `true` only when a pass ran and the payload now fits. `false`
+     *   when it already fit (the common case), when no strategy could act, when
+     *   the pass failed or timed out, or when it ran and reclaimed too little.
+     */
+    async compactIfOversized(extraInputTokens = 0) {
+        if (this.isDisposed ||
+            this.messages.length === 0 ||
+            !this.config.preflightCompactionEnabled) {
+            return false;
+        }
+        if (this.oversizeCompactionExhausted) {
+            // The metric is anonymous by design (identity is never a label), so this
+            // line is what lets oncall find WHICH session is stuck when the `latched`
+            // count rises. One line per prompt on a wedged session is the cost.
+            logger.warn("Skipping oversize compaction: an earlier pass on this context already ended over the threshold", this.metricIdentity);
+            recordPreflightCompaction({
+                outcome: "latched",
+                durationMs: 0,
+                identity: this.metricIdentity,
+            });
+            return false;
+        }
+        const extraTokens = typeof extraInputTokens === "function"
+            ? extraInputTokens()
+            : extraInputTokens;
+        // One pass at a time, and concurrent callers share it rather than stacking
+        // paid summarizations over the same history. A later caller may have sized
+        // a larger tool surface, so the pass decides on the largest figure attached
+        // to it rather than whichever caller happened to start it.
+        if (this.oversizeCompactionInFlight) {
+            this.oversizeCompactionExtraTokens = Math.max(this.oversizeCompactionExtraTokens, extraTokens);
+            return this.oversizeCompactionInFlight;
+        }
+        // An abandoned summarizer from a timed-out pass is still running and still
+        // billing. Refuse to start a second one over the same history.
+        if (this.oversizeCompactionSettled) {
+            logger.warn("Skipping oversize compaction: a previous pass outlived its deadline and is still running", this.metricIdentity);
+            recordPreflightCompaction({
+                outcome: "skipped",
+                durationMs: 0,
+                identity: this.metricIdentity,
+            });
+            return false;
+        }
+        this.oversizeCompactionExtraTokens = extraTokens;
+        const pass = this.queue.enqueue(() => this.runOversizeCompaction(this.oversizeCompactionExtraTokens));
+        this.oversizeCompactionInFlight = pass;
+        void pass
+            .catch(() => undefined)
+            .finally(() => {
+            this.oversizeCompactionInFlight = undefined;
+        });
+        return pass;
+    }
+    async runOversizeCompaction(extraInputTokens) {
+        const startedAt = performance.now();
+        let outcome = "failed";
+        // Set once `this.messages` holds the compacted window. Anything that throws
+        // after that point (the event-log append, persist bookkeeping) happened to
+        // a pass that succeeded, so it must not latch the context.
+        let committed = false;
+        try {
+            // Estimated inside the queued callback, not before it. An earlier queued
+            // pass may already have shrunk the history, and pairing a stale
+            // pre-compaction estimate with the new messages would hand the strategy
+            // an inconsistent (messages, usage) pair and skew its phase selection.
+            //
+            // Sizes the wire payload rather than `this.messages`: `buildMessages`
+            // prepends the system prompt and strips `_superblocks`, so this is what
+            // the provider will actually receive. The estimate can throw on a
+            // malformed message (`JSON.stringify` rejects a BigInt), which the
+            // surrounding catch absorbs: this method promises never to be the reason
+            // a request fails.
+            const payload = await this.buildMessages();
+            // `extraInputTokens` is the rest of the request the provider charges for
+            // and the message array does not carry, principally the tool schemas.
+            // Folded in here rather than compared separately so the synthetic usage
+            // handed to `afterResponse` is the same total this gate decided on;
+            // passing a messages-only figure would make the strategy's own threshold
+            // check disagree with ours and decline the pass we just asked for.
+            const estimatedTokens = estimateMessagesTokens(payload) + extraInputTokens;
+            const threshold = compactionThresholdTokens(this.config);
+            if (estimatedTokens <= threshold) {
+                outcome = "fit";
+                return false;
+            }
+            logger.warn(`Request payload is oversized: ~${estimatedTokens} estimated tokens > ${threshold} threshold ` +
+                `(${this.messages.length} messages); compacting before sending`, this.metricIdentity);
+            // Input-only synthetic usage: `computeContextUsed` measures the input
+            // window, and a non-zero output count would inflate it.
+            //
+            // Bounded, because a summarizer that HANGS rather than throws would
+            // otherwise block this turn forever. `OperationQueue` is a bare promise
+            // chain with no cancellation, so it would also stall every later
+            // operation on this context. The deadline is generous: abandoning a
+            // compaction that would have worked puts us back at the wedge, so waiting
+            // is the cheaper mistake. An abandoned call may still settle in the
+            // background; it can no longer hold up the request.
+            //
+            // `buildMessages()` above primed `_cachedMessages` with the payload this
+            // pass is about to replace. `getMessages` serves that cache without
+            // joining the queue, so a reader that arrives while the summarizer runs
+            // would otherwise be handed the oversized pre-compaction snapshot. Drop
+            // it: the reader then queues behind this pass and gets the result. The
+            // common fit path returned above with the cache intact, so the request
+            // that follows still gets its cache hit.
+            this.invalidateMessageCache();
+            const settled = this.compaction.afterResponse({
+                messages: this.messages,
+                usage: {
+                    inputTokens: estimatedTokens,
+                    outputTokens: 0,
+                    totalTokens: estimatedTokens,
+                },
+                usageIsEstimate: true,
+            });
+            // Tracked separately from the deadline the caller waits on. `compact()`
+            // takes no abort signal, so a pass past its deadline is abandoned rather
+            // than cancelled and keeps running and billing; this marker is what stops
+            // the queue admitting a sibling pass alongside that orphan. It clears
+            // when the SUMMARIZER settles, whether that is before or after the
+            // deadline, so the normal path releases it without the caller waiting.
+            //
+            // The exhausted latch stops a second pass after a timeout on its own, so
+            // this covers the one case that clears the latch mid-orphan, a
+            // `setCompactionStrategy` swap. It narrows the orphan window rather than
+            // closing it; closing it needs an `abortSignal` on `compact()`.
+            this.oversizeCompactionSettled = settled;
+            // An orphan's eventual outcome is otherwise invisible: the metric already
+            // recorded `timed_out` and the request went out without it. These lines
+            // are how oncall tells "settled two minutes late" from "still running an
+            // hour later".
+            let timedOut = false;
+            void settled
+                .then(() => {
+                if (timedOut) {
+                    logger.warn(`Oversize compaction pass settled ${Math.round(performance.now() - startedAt)}ms after it started, past its deadline; its result was discarded`, this.metricIdentity);
+                }
+            }, (err) => {
+                if (timedOut) {
+                    logger.warn(`Oversize compaction pass failed after outliving its deadline: ${err}`, this.metricIdentity);
+                }
+            })
+                .finally(() => {
+                if (this.oversizeCompactionSettled === settled) {
+                    this.oversizeCompactionSettled = undefined;
+                }
+            });
+            let result;
+            try {
+                result = await withDeadline(settled, PREFLIGHT_COMPACTION_TIMEOUT_MS);
+            }
+            catch (err) {
+                if (err instanceof DeadlineExceededError) {
+                    timedOut = true;
+                    outcome = "timed_out";
+                }
+                throw err;
+            }
+            if (!result.messages) {
+                // No strategy could act, or the strategy declined. Either way the
+                // provider is left to reject the request, now labelled
+                // `context_too_large`.
+                this.oversizeCompactionExhausted = true;
+                outcome = "discarded";
+                logger.warn("Oversize compaction produced no changes; payload remains too large to send", this.metricIdentity);
+                return false;
+            }
+            // Measured BEFORE anything is mutated or written, because a compaction is
+            // irreversible once persisted and a pass can come back with the window
+            // essentially unchanged (phase 1 finds nothing prunable and phase 2
+            // declines).
+            //
+            // Three outcomes, not two. The trigger threshold is
+            // `contextLimit - maxOutputTokens - contextBufferTokens`, so 120k on a
+            // 188k model, and tool schemas are irreducible: compaction cannot shrink
+            // them, so `messages_after + extraInputTokens` can sit above the trigger
+            // threshold while being comfortably sendable. Discarding there would
+            // throw away a real shrink and send the original oversized history
+            // instead, which is strictly worse.
+            //
+            // Sendability is measured against `contextLimit - contextBufferTokens`
+            // rather than bare `contextLimit`. `maxOutputTokens` is a generation
+            // reservation, not input the provider charges against the payload, so it
+            // does not belong in a can-this-be-sent bound. The buffer does stay:
+            // against the five captured production sessions this estimator reads
+            // 0.19x to 1.23x of provider-reported usage, so a margin below the hard
+            // limit is doing real work.
+            const candidate = this.markPreCompactionBaselines(result.messages);
+            const remainingTokens = estimateMessagesTokens(await this.buildMessages(candidate)) +
+                extraInputTokens;
+            const sendableLimit = this.config.contextLimit - this.config.contextBufferTokens;
+            if (remainingTokens > sendableLimit) {
+                // Still unsendable. Keep the original history, which at least leaves
+                // the conversation recoverable, and stop paying for the same answer.
+                this.oversizeCompactionExhausted = true;
+                outcome = "discarded";
+                // `compact()` fires onCompactionStart and onCompactionComplete before
+                // it returns, so the user has already been shown "Summarized past
+                // conversation" for work we are about to throw away. Retract it, or the
+                // UI claims a summarization happened while the request goes out with
+                // the original history and gets rejected. Only phase 2 needs this:
+                // `LLMClient.createContext` drops phase-1 callbacks before they render.
+                if (result.phase2MessageId) {
+                    this.compactionCallbacks?.onCompactionCancel?.("phase2", result.phase2MessageId);
+                }
+                logger.warn(`Oversize compaction ran but the payload is still unsendable ` +
+                    `(~${remainingTokens} estimated tokens > ${sendableLimit} sendable limit, ` +
+                    `${estimatedTokens} before); discarding it and leaving the request to the provider`, this.metricIdentity);
+                return false;
+            }
+            // Over the compaction threshold but under the limit, so it will send.
+            // Persist it and do NOT latch: real progress was made, and the normal
+            // usage-driven `afterResponse` can carry on from here with the provider's
+            // own numbers instead of this estimate.
+            const underThreshold = remainingTokens <= threshold;
+            if (!underThreshold) {
+                logger.info(`Oversize compaction reduced the payload to a sendable size but not under the ` +
+                    `compaction threshold (~${remainingTokens} estimated tokens, ${estimatedTokens} before, ` +
+                    `${threshold} threshold, ${sendableLimit} sendable limit)`, this.metricIdentity);
+            }
+            // Re-checked after an await that can last the full deadline. `dispose()`
+            // marks the instance inert so stale generations cannot resurrect cleared
+            // history, and the disk paths already honour it (`runPersist` and
+            // `appendCompactionWindow` both bail on `isDisposed`), but assigning
+            // `this.messages` here would put the pre-dispose conversation back in
+            // memory on a context New Chat or a checkpoint restore just cleared.
+            if (this.isDisposed) {
+                outcome = "discarded";
+                if (result.phase2MessageId) {
+                    this.compactionCallbacks?.onCompactionCancel?.("phase2", result.phase2MessageId);
+                }
+                logger.warn("Discarding an oversize compaction result: the context was disposed while it ran", this.metricIdentity);
+                return false;
+            }
+            this.messages = candidate;
+            committed = true;
+            this.invalidateMessageCache();
+            if (result.skillsNeedReload) {
+                this.skillsNeedReload = true;
+                this.readSystemSkills.clear();
+            }
+            if (result.eventLogAnchor) {
+                await this.appendCompactionWindow(this.messages);
+            }
+            await this.persist("compaction");
+            outcome = underThreshold ? "compacted" : "progressed";
+            return underThreshold;
+        }
+        catch (err) {
+            // Never rethrown, and latched so it is never retried: a summarizer that
+            // threw or blew the deadline would stall every later request for the same
+            // deadline and fail the same way, which is worse than the wedge. Degrade
+            // to letting the provider reject the request, now labelled
+            // `context_too_large`. The estimate itself can also throw here
+            // (`JSON.stringify` rejects a BigInt), and latching that is right too:
+            // a malformed message will still be malformed next turn.
+            //
+            // Not latched once the compacted window is in memory: the pass did its
+            // job and the request goes out with the smaller history. Latching there
+            // would block the next rescue over a bookkeeping failure.
+            if (committed) {
+                logger.error(`Oversize compaction applied but its bookkeeping failed: ${err}`, { ...getErrorMeta(err), ...this.metricIdentity });
+                return false;
+            }
+            this.oversizeCompactionExhausted = true;
+            logger.error(`Failed to compact oversized payload; leaving it to the provider: ${err}`, { ...getErrorMeta(err), ...this.metricIdentity });
+            return false;
+        }
+        finally {
+            // Telemetry only: `outcome` is assigned on every path and nothing here
+            // touches control flow, so a metrics failure cannot change what the
+            // request does.
+            recordPreflightCompaction({
+                outcome,
+                durationMs: performance.now() - startedAt,
+                identity: this.metricIdentity,
+            });
+        }
+    }
+    async getMessages() {
+        // Fast path: return cached result when messages haven't changed.
+        // This avoids re-running 10+ normalization/repair passes and avoids
+        // queue contention on the second call within the same LLM step.
+        if (this._cachedMessages) {
+            logger.debug(`getMessages: cache hit (${this._cachedMessages.length} messages)`);
+            return [...this._cachedMessages];
+        }
+        return this.queue.enqueue(() => this.buildMessages());
+    }
+    /**
+     * Build the wire payload. Split out of `getMessages` so a pass already
+     * running inside the operation queue can size the real payload without
+     * re-entering the queue and deadlocking.
+     */
+    async buildMessages(source) {
+        // A `source` means "size this candidate window", not "this is the context
+        // now": the cache is neither read nor written, so a candidate the caller
+        // ends up discarding cannot leak into the next real request. Same function
+        // either way on purpose, so the before and after measurements are the same
+        // shape and a difference between them means a real difference in payload.
+        const isCandidate = source !== undefined;
+        {
+            // Re-check in case another enqueued op just computed it.
+            if (!isCandidate && this._cachedMessages) {
+                return [...this._cachedMessages];
+            }
+            // Strip system-role messages from the conversation array before
+            // building the wire payload. The `compaction_received` marker
+            // (written by `onCompactionDetected`, surfaced by
+            // `JsonlEventStore.loadMessages` as the anchor StoredMessage, and
+            // inserted in memory by `ServerSideCompactionStrategy`) carries
+            // `role: "system"` and is useful as an in-memory / on-disk
+            // breadcrumb but is not a valid conversation turn — Anthropic
+            // (and most other providers) only accept system messages at the
+            // start of the request, routed through the dedicated `system`
+            // parameter we set from `this.systemPrompt` below. Letting the
+            // marker through would put a second system-role message in the
+            // middle of the `messages` array and 400 the request on the
+            // first post-compaction turn.
+            const conversationMessages = (source ?? this.messages).filter((msg) => msg.role !== "system");
+            const allMessages = this.systemPrompt
+                ? [this.systemPrompt, ...conversationMessages]
+                : [...conversationMessages];
+            // Convert to SDK format (removes _superblocks metadata)
+            const sanitized = toSdkMessages(allMessages);
+            // Normalize malformed tool outputs and repair broken tool calls.
+            const normalized = sanitized.map((msg) => normalizeToolMessage(stripUndefinedFromToolOutputs(msg)));
+            const repaired = normalized
+                .map(repairBrokenToolCalls)
+                .map(repairOrphanedToolResults)
+                .filter((msg) => {
+                // Remove messages left empty after repair (e.g., tool messages with all
+                // results orphaned, or assistant messages with all tool-calls orphaned)
+                if (msg.role !== "user" &&
+                    Array.isArray(msg.content) &&
+                    msg.content.length === 0) {
+                    logger.debug(`Filtered out empty ${msg.role} message after repair`);
+                    return false;
+                }
+                return true;
+            });
+            // Normalize reasoning signatures into both provider namespaces so that
+            // conversations started on one provider (e.g. Vertex/anthropic) can be
+            // replayed on another (e.g. Bedrock) without losing signatures.
+            for (const msg of repaired) {
+                if (msg.role === "assistant") {
+                    normalizeReasoningProviderOptions(msg);
+                }
+            }
+            // Drop reasoning parts that still lack a valid signature after
+            // normalization. These can never be replayed successfully.
+            const signatureSafe = stripUnsignedReasoning(repaired);
+            if (signatureSafe.length < repaired.length) {
+                logger.debug(`Stripped ${repaired.length - signatureSafe.length} message(s) with unsigned reasoning`);
+            }
+            const prefillSafe = stripTrailingAssistantPrefill(signatureSafe);
+            if (prefillSafe.length < signatureSafe.length) {
+                logger.debug(`Stripped ${signatureSafe.length - prefillSafe.length} trailing assistant prefill message(s)`);
+            }
+            // Ensure file part filenames are globally unique across all messages.
+            // Providers like Bedrock reject requests with duplicate document names.
+            const deduped = uniquifyFilePartFilenames(prefillSafe);
+            // Final defense-in-depth: strip any orphan tool_use that survived the
+            // earlier per-message repairs. Anthropic/Bedrock require every tool_use
+            // to be followed IMMEDIATELY by a matching tool_result, and earlier
+            // repairs operate on intermediate arrays whose indices can shift.
+            //
+            // INVARIANT: enforceToolUsePairing must run AFTER repairOrphanedToolResults
+            // (so no orphan tool_results survive into this pass — it only looks forward
+            // and strips tool_use, never tool_result) and BEFORE any step that adds or
+            // removes TOOL-CALL-BEARING messages (or orphans can be reintroduced by
+            // adjacency shifts). stripUnsignedReasoning and stripTrailingAssistantPrefill
+            // also run between the repair passes and this call; they are safe because they
+            // only drop messages with no tool-call parts (pure reasoning / trailing
+            // prefill), so they cannot orphan a tool_use. Cache-breakpoint application
+            // below mutates providerOptions only and is safe.
+            const enforced = enforceToolUsePairing(deduped);
+            // Compaction can persist a lone UTF-16 surrogate (emoji split). Bedrock
+            // then rejects the Converse body as invalid JSON. Repair on the wire
+            // only so already-poisoned chats can send without rewriting history.
+            const jsonSafe = makeJsonSafeValue(enforced);
+            // Apply cache breakpoints (recompute indices after filtering since
+            // the .filter() step may have removed messages, shifting positions)
+            const repairedBreakpoints = findBreakpoints({
+                messages: jsonSafe,
+                hasSystemPrompt: this.systemPrompt !== undefined,
+                config: this.caching,
+            });
+            for (const idx of repairedBreakpoints) {
+                if (jsonSafe[idx]) {
+                    jsonSafe[idx].providerOptions = CACHE_BREAKPOINT_PROVIDER_OPTIONS;
+                }
+            }
+            if (!isCandidate) {
+                this._cachedMessages = jsonSafe;
+            }
+            return [...jsonSafe];
+        }
+    }
+    async onCompactionDetected() {
+        const detectedGeneration = this.activeServerCompactionGeneration ??
+            this.endedServerCompactionGeneration;
+        this.invalidateMessageCache();
+        // Serialize with `addUserMessage` / `addResponse` / `getMessages`: this
+        // method is driven by the stream observer and can otherwise interleave
+        // with a queued write, leading to lost mutations or torn state.
+        await this.queue.enqueue(async () => {
+            const messagesBefore = this.messages.length;
+            const inputTokensBefore = this.getLastKnownInputTokens();
+            const result = this.compaction.onCompactionDetected(this.messages);
+            // Mark retained assistants once and reuse the flagged array for both the
+            // in-memory state and the event-log write below. Capturing it in a local
+            // (rather than re-reading `this.messages`) keeps the event log's
+            // dependency on the marking explicit and refactor-safe — see
+            // `markPreCompactionBaselines` / `getLastKnownInputTokens`.
+            const marked = result.messages
+                ? this.markPreCompactionBaselines(result.messages)
+                : null;
+            if (marked) {
+                this.messages = marked;
+                this.invalidateMessageCache();
+            }
+            if (result.skillsNeedReload) {
+                this.skillsNeedReload = true;
+                this.readSystemSkills.clear();
+            }
+            const marker = result.messages?.[0];
+            const summary = typeof marker?.content === "string"
+                ? marker.content
+                : SERVER_COMPACTION_SUMMARY;
+            const durationMs = this.getActiveServerCompactionDurationMs();
+            const didComplete = this.completeServerCompactionMessage(summary, detectedGeneration);
+            if (didComplete) {
+                this.recordInterCompactionTurnInterval();
+                recordServerCompaction({
+                    ...this.getMetricIdentity(),
+                    durationMs,
+                    inputTokensBefore,
+                    messagesAfter: this.messages.length,
+                    messagesBefore,
+                    status: "completed",
+                });
+            }
+            if (this.isDisposed) {
+                logger.warn(`Skipping server-compaction event append for context '${this.contextId?.name ?? "ephemeral"}': context was disposed (concurrent checkpoint restore or New Chat)`);
+                return;
+            }
+            if (!this.eventStore || !this.contextId) {
+                logger.info("Server-side compaction detected (no event store configured)", {
+                    ...(durationMs !== undefined
+                        ? { durationMs: Math.round(durationMs) }
+                        : {}),
+                    inputTokensBefore,
+                    messagesAfter: this.messages.length,
+                    messagesBefore,
+                    ...this.getMetricIdentity(),
+                });
+                return;
+            }
+            // Replay the marked messages so the baseline reset survives reload from
+            // the event log, not just the in-memory record. `marker` (above) is
+            // `markedMessages[0]` — the summary marker is never an assistant, so
+            // `markPreCompactionBaselines` leaves index 0 untouched.
+            const markedMessages = marked ?? [];
+            const entry = {
+                type: "compaction_received",
+                timestamp: marker?._superblocks?.timestamp ?? Date.now(),
+                role: "system",
+                content: summary,
+            };
+            const retainedMessages = markedMessages.slice(1);
+            try {
+                await this.eventStore.appendEvent(this.contextId, entry, {
+                    shouldAbort: () => this.isDisposed,
+                });
+                for (const message of retainedMessages) {
+                    // Re-check per iteration: the loop awaits between writes, so a
+                    // concurrent New Chat / checkpoint restore can dispose the shared
+                    // instance mid-replay. Stop rather than append the rest into the
+                    // (possibly just-cleared) shared log for every editor.
+                    if (this.isDisposed) {
+                        logger.warn(`Stopping server-compaction replay for context '${this.contextId?.name ?? "ephemeral"}': context disposed mid-write (concurrent checkpoint restore or New Chat)`);
+                        break;
+                    }
+                    await this.eventStore.appendEvent(this.contextId, this.toEventLogEntry(message), { shouldAbort: () => this.isDisposed });
+                }
+            }
+            catch (err) {
+                logger.error(`Failed to append compaction_received event: ${err}`);
+            }
+            logger.info(`Server-side compaction detected, wrote compaction_received event and replayed ${retainedMessages.length} retained message(s)`, {
+                ...(durationMs !== undefined
+                    ? { durationMs: Math.round(durationMs) }
+                    : {}),
+                inputTokensBefore,
+                messagesAfter: this.messages.length,
+                messagesBefore,
+                ...this.getMetricIdentity(),
+            });
+        });
+    }
+    ensureServerCompactionMessageStarted() {
+        if (!this.serverCompactionMessageId) {
+            this.serverCompactionMessageId = `server-compaction-${randomUUID()}`;
+            this.serverCompactionGeneration++;
+            this.activeServerCompactionGeneration = this.serverCompactionGeneration;
+            this.endedServerCompactionGeneration = undefined;
+            this.compactionCallbacks?.onCompactionStart?.("phase2", this.serverCompactionMessageId);
+        }
+        return this.serverCompactionMessageId;
+    }
+    completeServerCompactionMessage(summary, detectedGeneration) {
+        if (detectedGeneration !== undefined &&
+            (this.endedServerCompactionGeneration === detectedGeneration ||
+                this.activeServerCompactionGeneration !== detectedGeneration)) {
+            return false;
+        }
+        const startedBeforeCompletion = this.serverCompactionMessageId !== undefined;
+        const messageId = this.ensureServerCompactionMessageStarted();
+        this.compactionCallbacks?.onCompactionComplete?.("phase2", messageId, summary);
+        this.serverCompactionMessageId = undefined;
+        this.activeServerCompactionGeneration = undefined;
+        this.activeServerCompactionStartedAt = undefined;
+        if (!startedBeforeCompletion) {
+            this.serverCompactionCompletedBeforeStart = true;
+        }
+        return true;
+    }
+    getMetricIdentity() {
+        return {
+            ...(this.contextId?.appId ? { applicationId: this.contextId.appId } : {}),
+            ...(this.contextId?.organizationId
+                ? { organizationId: this.contextId.organizationId }
+                : {}),
+            ...this.metricIdentity,
+        };
+    }
+    getActiveServerCompactionDurationMs() {
+        return this.activeServerCompactionStartedAt === undefined
+            ? undefined
+            : performance.now() - this.activeServerCompactionStartedAt;
+    }
+    recordServerCompactionOutcome(status) {
+        recordServerCompaction({
+            ...this.getMetricIdentity(),
+            durationMs: this.getActiveServerCompactionDurationMs(),
+            status,
+        });
+    }
+    /**
+     * Returns deduplicated tool names from messages marked as protected.
+     * Delegates to the active compaction strategy.
+     */
+    getProtectedToolNames() {
+        return this.compaction.getProtectedToolNames(this.messages);
+    }
+    async appendEvent(type, message, usage) {
+        if (this.isDisposed) {
+            // The event log is the primary load source (manager.loadRecord replays
+            // it before legacy/remote), so a late in-flight append from a disposed
+            // shared instance would resurrect the just-cleared/restored conversation
+            // for every editor. Skip — and log, since it was previously invisible.
+            logger.warn(`Skipping '${type}' event append for context '${this.contextId?.name ?? "ephemeral"}': context was disposed (concurrent checkpoint restore or New Chat)`);
+            return;
+        }
+        if (!this.eventStore || !this.contextId) {
+            return;
+        }
+        const raw = message;
+        const providerMetadata = raw.providerMetadata;
+        const entry = {
+            type,
+            timestamp: message._superblocks?.timestamp ?? Date.now(),
+            role: message.role,
+            content: message.content,
+            ...(message._superblocks != null
+                ? { _superblocks: message._superblocks }
+                : {}),
+            ...(providerMetadata != null ? { providerMetadata } : {}),
+            ...(usage && { usage }),
+        };
+        try {
+            await this.eventStore.appendEvent(this.contextId, entry, {
+                shouldAbort: () => this.isDisposed,
+            });
+        }
+        catch (err) {
+            logger.error(`Failed to append ${type} event: ${err}`);
+        }
+    }
+    async appendCompactionWindow(messages) {
+        if (this.isDisposed) {
+            logger.warn(`Skipping compaction-window event append for context '${this.contextId?.name ?? "ephemeral"}': context was disposed (concurrent checkpoint restore or New Chat)`);
+            return;
+        }
+        if (!this.eventStore || !this.contextId) {
+            return;
+        }
+        // System-role messages are in-memory/on-disk breadcrumbs (e.g. a
+        // restored compaction marker), not conversation turns; rewriting them
+        // into the window would accumulate one marker per compact/restore cycle.
+        const windowMessages = messages.filter((msg) => msg.role !== "system");
+        // Never write an anchor for an empty window: the backward scan in
+        // `loadMessages` would treat it as the replay point and restore an
+        // empty conversation.
+        if (windowMessages.length === 0) {
+            logger.warn("Compaction window is empty after system-role filtering; skipping event log write");
+            return;
+        }
+        // Phase-2 windows begin with an `isSummary` message that
+        // `JsonlEventStore.loadMessages` recognizes as a replay anchor.
+        // Phase-1-only windows carry no such message, so write an explicit
+        // `compaction_received` marker first — without an anchor the next
+        // load would replay the raw pre-compaction events, resurrecting the
+        // uncompacted context and invalidating the provider prompt cache on
+        // every page refresh (APPS-4751).
+        const needsMarker = windowMessages[0]?._superblocks?.isSummary !== true;
+        // The marker + window writes are not atomic: a crash mid-write leaves
+        // a partial window behind the anchor and the next load replays an
+        // incomplete window. That is still preferable to replaying the raw
+        // pre-compaction history; phase-2/server-side windows share the same
+        // exposure.
+        try {
+            if (needsMarker) {
+                await this.eventStore.appendEvent(this.contextId, {
+                    type: "compaction_received",
+                    timestamp: Date.now(),
+                    role: "system",
+                    content: CLIENT_COMPACTION_MARKER,
+                }, { shouldAbort: () => this.isDisposed });
+            }
+            for (const message of windowMessages) {
+                // Re-check per iteration: see onCompactionDetected — a dispose during
+                // the loop's awaits must stop the replay, not keep appending into a
+                // shared log a concurrent New Chat / restore may have just cleared.
+                if (this.isDisposed) {
+                    logger.warn(`Stopping compaction-window replay for context '${this.contextId?.name ?? "ephemeral"}': context disposed mid-write (concurrent checkpoint restore or New Chat)`);
+                    break;
+                }
+                await this.eventStore.appendEvent(this.contextId, this.toEventLogEntry(message), { shouldAbort: () => this.isDisposed });
+            }
+            logger.info(`Wrote ${windowMessages.length} client-side compaction message(s) to event log ` +
+                `(anchor: ${needsMarker ? "phase-1 marker" : "isSummary message"})`);
+        }
+        catch (err) {
+            logger.error(`Failed to append client-side compaction window: ${err}`);
+        }
+    }
+    toEventLogEntry(message) {
+        const raw = message;
+        const providerMetadata = raw.providerMetadata;
+        return {
+            type: message.role === "user" ? "prompt_sent" : "response_received",
+            timestamp: message._superblocks?.timestamp ?? Date.now(),
+            role: message.role,
+            content: message.content,
+            ...(message._superblocks != null
+                ? { _superblocks: message._superblocks }
+                : {}),
+            ...(providerMetadata != null ? { providerMetadata } : {}),
+        };
+    }
+    /**
+     * Returns the last known input token count from the most recent assistant
+     * message in the current (post-compaction) prompt epoch.
+     *
+     * This feeds the monotonic floor in `addResponse` that guards against
+     * providers under-reporting input tokens on cache misses. Messages flagged
+     * `preCompactionInputTokenBaseline` are skipped: their `cumulativeInputTokens`
+     * reflect a larger pre-compaction prompt, so using them as the floor would
+     * pin the cumulative at the stale high-water mark forever (the value would
+     * appear frozen after every compaction).
+     *
+     * NOTE: sessions that compacted before this flag shipped have retained
+     * assistant messages with no `preCompactionInputTokenBaseline`, so they keep
+     * returning the stale pre-compaction peak until their next compaction re-marks
+     * them. No migration is applied — accepted for a telemetry-only fix.
+     */
+    getLastKnownInputTokens() {
+        for (let i = this.messages.length - 1; i >= 0; i--) {
+            const meta = this.messages[i]?._superblocks;
+            if (meta?.cumulativeInputTokens !== undefined &&
+                meta.preCompactionInputTokenBaseline !== true) {
+                return meta.cumulativeInputTokens;
+            }
+        }
+        return 0;
+    }
+    /**
+     * After compaction shrinks the prompt, the retained assistant messages still
+     * carry `cumulativeInputTokens` from the pre-compaction epoch. Flag each one
+     * so `getLastKnownInputTokens` stops treating those values as the monotonic
+     * floor — otherwise the high-water mark survives compaction and pins
+     * `cumulativeInputTokens` at the pre-compaction peak forever.
+     *
+     * The values themselves are preserved for historical per-turn delta
+     * accounting (see `turns.ts`). Marking is idempotent (already-flagged
+     * messages are returned untouched), so repeated compactions in a single
+     * session each reset the floor for the new epoch without churn.
+     *
+     * Phase-1-only client compaction returns the full message list, so every
+     * assistant in history is flagged and the floor drops to the post-compaction
+     * prompt size even though only tool outputs were pruned in place.
+     */
+    markPreCompactionBaselines(messages) {
+        return messages.map((msg) => {
+            if (msg.role !== "assistant" ||
+                msg._superblocks?.cumulativeInputTokens === undefined ||
+                msg._superblocks.preCompactionInputTokenBaseline === true) {
+                return msg;
+            }
+            return {
+                ...msg,
+                _superblocks: {
+                    ...msg._superblocks,
+                    preCompactionInputTokenBaseline: true,
+                },
+            };
+        });
+    }
+    /**
+     * Await every persist that is currently mid-flight, then resolve.
+     *
+     * A persist that has already passed the {@link persist} dispose guard is
+     * committed to writing the snapshot; `dispose()` cannot recall it. A caller
+     * about to overwrite that snapshot with rolled-back state (checkpoint restore
+     * heals the snapshot to match the truncated event log) must drain first, or
+     * the late write lands after the heal and clobbers the rollback — and
+     * re-emits `contextPersisted`, flushing the poisoned state remotely. Drains
+     * until stable in case a persist enqueues while we await, though after
+     * `dispose()` none should start.
+     */
+    async drainPersists() {
+        while (this.inFlightPersists.size > 0) {
+            await Promise.allSettled([...this.inFlightPersists]);
+        }
+    }
+    /**
+     * Persist failures are swallowed (logged + recorded on the span) — a
+     * storage error must never fail the conversation turn that triggered it.
+     *
+     * Tracks the returned promise in {@link inFlightPersists} so a concurrent
+     * {@link drainPersists} can await a write that has already begun.
+     */
+    persist(trigger) {
+        const run = this.runPersist(trigger);
+        this.inFlightPersists.add(run);
+        // `runPersist` swallows the storage error itself (logs + records on the
+        // span), so `run` only rejects for a failure OUTSIDE that try — the tracer
+        // or persist-accounting path. Log it here rather than an empty catch: this
+        // is the sole place a fire-and-forget persist's out-of-band failure is
+        // observable, and `drainPersists` deliberately discards settled results.
+        void run
+            .catch((err) => logger.error(`Persist tracking failed for context '${this.contextId?.name ?? "ephemeral"}': ${err}`))
+            .finally(() => this.inFlightPersists.delete(run));
+        return run;
+    }
+    async runPersist(trigger) {
+        if (this.isDisposed) {
+            // A concurrent checkpoint restore or New Chat disposes the shared
+            // ContextV2 instance (all editors of an app share one, keyed
+            // appId::name). An in-flight turn can still reach here; persisting now
+            // would silently clobber the just-restored/cleared context, so skip —
+            // and log it, since the collision was previously invisible.
+            logger.warn(`Skipping '${trigger}' persist for context '${this.contextId?.name ?? "ephemeral"}': context was disposed (concurrent checkpoint restore or New Chat)`);
+            return;
+        }
+        if (!this.onPersist) {
+            return;
+        }
+        const onPersist = this.onPersist;
+        const tracer = this.tracer ?? LLMObsTracer.instance;
+        await tracer.trace({ kind: "task", name: "context.persist" }, async (span) => {
+            // Re-check after the tracer's async boundary: dispose() may have run
+            // between the guard above and here. No await sits between this check
+            // and the onPersist call below, so this closes the clobber window.
+            if (this.isDisposed) {
+                logger.warn(`Skipping '${trigger}' persist for context '${this.contextId?.name ?? "ephemeral"}': context disposed mid-persist (concurrent checkpoint restore or New Chat)`);
+                return;
+            }
+            const startedAt = performance.now();
+            // Capture CPU time and event-loop activity across the await so a slow
+            // persist can be classified after the fact. The persist
+            // body is a tiny mkdir + JSON.stringify + writeFile, yet wall-clock
+            // occasionally runs to minutes uncorrelated with size, which means the
+            // single dev-server event loop was frozen during the await, not the
+            // file write. cpuMs near zero while wall-clock is large means the
+            // process got no CPU (k8s CFS throttle / deschedule); cpuMs tracking
+            // wall-clock means a synchronous CPU-bound block (or GC) held the
+            // loop. loopUtilization gives corroborating context: low means the
+            // loop was idle/waiting, high means it was spinning on callbacks.
+            // gVisor-sandboxed pods export no cgroup CPU/throttle metrics, so this
+            // in-process signal has to ride the log line below, which does export
+            // from prod.
+            const cpuStart = process.cpuUsage();
+            const eluStart = performance.eventLoopUtilization();
+            let persistError;
+            try {
+                await onPersist(this.toRecord());
+            }
+            catch (err) {
+                persistError = err;
+                logger.error(`Failed to persist context: ${err}`);
+            }
+            const elapsedMs = performance.now() - startedAt;
+            const cpu = process.cpuUsage(cpuStart);
+            const cpuMs = Math.round((cpu.user + cpu.system) / 1000);
+            const loopUtilization = Math.round(performance.eventLoopUtilization(eluStart).utilization * 100) / 100;
+            tracer.annotate(span, {
+                tags: { trigger },
+                metadata: {
+                    durationMs: Math.round(elapsedMs),
+                    messageCount: this.messages.length,
+                    cpuMs,
+                    loopUtilization,
+                },
+                ...(persistError !== undefined ? { error: persistError } : {}),
+            });
+            recordContextPersist({
+                trigger,
+                durationMs: elapsedMs,
+                identity: this.getMetricIdentity(),
+            });
+            if (elapsedMs > SLOW_PERSIST_WARN_MS) {
+                logger.warn(`slow persist: ${Math.round(elapsedMs)}ms (messages=${this.messages.length}, cpuMs=${cpuMs}, loopUtilization=${loopUtilization})`);
+            }
+        });
+    }
+}
+//# sourceMappingURL=context.js.map