@maudecode/talaria-web 1.18.0 → 1.19.0

package/dist/sessions/merge.js

@@ -4,11 +4,13 @@
  * `_extract_tool_calls_from_messages`, `_build_partial_message`).
  */
 import { buildActiveTurnToken, completedToolIndex } from '../redact.js';
-import { RunJournal } from './journal.js';
+import { selectAuthoritativeTerminalEvent } from './journal.js';
 import { str } from '../util.js';
+import { stateDbMessageKey, stateDbMessageFingerprint, stateDbRowId, stateDbIdentityKeys, stateDbMessageRepresented } from './state-db-identity.js';
 import { stripAttachedFilesMarker, stripWorkspacePrefix } from './session.js';
 export { WORKSPACE_PREFIX_RE, stripWorkspacePrefix } from './session.js';
 import { decidedEditDiff, toolEditDiff, toolName } from './tool-display.js';
+import { sourceKind } from './source-kind.js';
 const TOOL_RESULT_SNIPPET_MAX = 4000;
 // Python `_TOOL_ARG_CONTENT_KEYS`: file bodies, commands, and patch text keep up to the content cap; incidental args cut at 120.
 export const TOOL_ARG_CONTENT_KEYS = new Set(['command', 'cmd', 'script', 'code', 'patch', 'diff', 'old_string', 'new_string', 'content', 'path', 'file_path']);
@@ -46,11 +48,33 @@ export function messageText(content) {
     }
     return str(content);
 }
+/** Agent-injected memory is model context, never typed user text. Match the Agent's fence, including an unclosed tail. */
+function withoutMemoryContext(text) {
+    const stripped = text.replace(/(?:\r?\n)?<memory-context>[\s\S]*?(?:<\/memory-context>|$)/gi, '');
+    // Remove the fence's line separator, not the prompt's indentation or trailing whitespace.
+    return stripped !== text && !stripped.trim() ? '' : stripped;
+}
+/** Display-only user projection shared by transcript hydration and turn identity; model history stays untouched. */
+export function normalizeUserDisplay(message) {
+    if (!isDict(message) || message.role !== 'user')
+        return message;
+    const content = message.content;
+    if (typeof content === 'string')
+        return { ...message, content: withoutMemoryContext(content) };
+    if (!Array.isArray(content))
+        return message;
+    return { ...message, content: content.flatMap((part) => {
+            if (!isDict(part) || part.type !== 'text' || typeof part.text !== 'string')
+                return [part];
+            const text = withoutMemoryContext(part.text);
+            return text === part.text ? [part] : text ? [{ ...part, text }] : [];
+        }) };
+}
 export function messageIdentity(msg, textLimit = 500) {
     if (!isDict(msg))
         return null;
     const role = str(msg.role);
-    let text = messageText(msg.content);
+    let text = messageText(normalizeUserDisplay(msg).content);
     if (role === 'user') {
         const typed = userPromptText(text);
         // An attachment-only prompt has no typed text; its whole attached-files line (never truncated) tells one such turn
@@ -110,15 +134,77 @@ export function markerKind(msg) {
 export function isContextCompressionMarker(msg) {
     return markerKind(msg) === 'context_compaction';
 }
+// The Agent's failed-turn boundary copy (`agent/turn_failure_copy.py`): an older row carries it without its kind.
+const FAILED_TURN_NOTICES = new Set([
+    'Your request was not processed. Send it again if you still want me to carry it out.',
+    'This turn did not complete. Some actions may already have run; verify their effects before resending.',
+]);
+/**
+ * TAL-815: rows the Agent writes outside the conversation, by its `display_kind` and its own read-side rules.
+ * `failed_turn`: the assistant boundary closing a turn that failed, never the model's reply. `hidden`: a row the Agent
+ * never renders, such as the empty interrupt placeholder or an untyped `[System:` scaffold notice in a user row.
+ */
+export function agentRowKind(msg) {
+    if (!isDict(msg))
+        return null;
+    if (msg.display_kind === 'hidden')
+        return 'hidden';
+    if (msg.role === 'assistant' && (msg.display_kind === 'failed_turn' || (!msg.display_kind && typeof msg.content === 'string' && FAILED_TURN_NOTICES.has(msg.content.trim()))))
+        return 'failed_turn';
+    return msg.role === 'user' && !msg.display_kind && typeof msg.content === 'string' && msg.content.trimStart().startsWith('[System:') ? 'hidden' : null;
+}
+const DELIVERY_PREFIXES = [['webhook', '[Webhook delivery: '], ['cron', '[Cron delivery: ']];
+/**
+ * TAL-816: the user row the Agent's gateway mirrors into a chat's transcript after a webhook or cron delivery
+ * (`gateway/mirror.py` callers): exactly `[Webhook delivery: <route>]` or `[Cron delivery: <job>]`, a newline, then the
+ * delivered text. Only meaningful in a messaging session; anyone can type the same prefix elsewhere.
+ */
+export function deliveryNotice(msg) {
+    if (!isDict(msg) || msg.role !== 'user' || typeof msg.content !== 'string')
+        return null;
+    const newline = msg.content.indexOf('\n');
+    const label = newline < 0 ? '' : msg.content.slice(0, newline);
+    const match = DELIVERY_PREFIXES.find(([, prefix]) => label.startsWith(prefix));
+    if (!match || !label.endsWith(']') || label.length <= match[1].length + 1)
+        return null;
+    return { kind: match[0], name: label.slice(match[1].length, -1), body: msg.content.slice(newline + 1) };
+}
+/**
+ * TAL-816: `session`'s rows for a copy that is no longer a messaging session (duplicate, branch), each mirrored delivery
+ * marked with the Agent's own mirror metadata (`mirror_source`, which it drops at the SQLite boundary) so the copy still
+ * shows it as a delivery. Returns copies; stored rows are untouched.
+ */
+export function withMirrorSources(messages, session) {
+    if (sourceKind(session) !== 'messaging')
+        return messages;
+    return messages.map((m) => {
+        const delivery = deliveryNotice(m);
+        return delivery ? { ...m, mirror_source: delivery.kind } : m;
+    });
+}
 /**
  * TAL-305: stamps `_marker_kind` on marker rows, and `_marker_body` (the list without its marker line) on a preserved
- * task list, so clients render a marker card instead of a message. Returns copies; stored rows are untouched.
+ * task list, so clients render a marker card instead of a message. TAL-815: a failed turn's boundary gets
+ * `_notice_kind`, unless the turn (`_turn_id`) already carries Web's own error row; that copy and every other row the
+ * Agent hides leave as `display_kind: 'hidden'`. TAL-816: a mirrored delivery in a messaging `session`, or one a copy
+ * marked with its `mirror_source`, gets `_delivery`. Returns copies; stored rows are untouched.
  */
-export function withMarkerKinds(messages) {
+export function withMarkerKinds(messages, session) {
+    const erroredTurns = new Set(messages.flatMap((m) => (isDict(m) && m._error ? [str(m._turn_id)] : [])));
+    const messaging = sourceKind(session) === 'messaging';
     return messages.map((m) => {
-        const kind = markerKind(m);
-        if (!kind || !isDict(m))
+        if (!isDict(m))
             return m;
+        const delivery = deliveryNotice(m);
+        if (delivery && (messaging || m.mirror_source === delivery.kind))
+            return { ...m, _delivery: delivery };
+        const kind = markerKind(m);
+        if (!kind) {
+            const agentKind = agentRowKind(m);
+            if (!agentKind)
+                return m;
+            return agentKind === 'failed_turn' && !erroredTurns.has(str(m._turn_id)) ? { ...m, _notice_kind: agentKind } : { ...m, display_kind: 'hidden' };
+        }
         if (kind === 'context_compaction')
             return { ...m, _marker_kind: kind };
         const body = messageText(m.content).trim().slice(PRESERVED_TASK_LIST_PREFIX.length).trim();
@@ -132,7 +218,7 @@ export function looksLikeCurrentUserTurn(msg, msgText) {
     // A persisted steer is display-only: it is never the prompt that opened a turn.
     if (!isDict(msg) || str(msg.role) !== 'user' || isDict(msg._steer))
         return false;
-    const candidate = normalizeUserText(messageText(msg.content));
+    const candidate = normalizeUserText(messageText(normalizeUserDisplay(msg).content));
     const target = normalizeUserText(msgText);
     // An attachment-only prompt (TAL-276) has no text: the Agent's row for it carries none either.
     if (!target)
@@ -169,7 +255,8 @@ export function findCurrentUserTurn(messages, msgText) {
 /** Python `_merge_display_messages_after_agent_result` (append-only display merge). */
 /** Python `_assistant_message_has_final_visible_text`: a non-error assistant row carrying visible answer text. */
 function assistantHasFinalVisibleText(msg) {
-    if (msg.role !== 'assistant' || msg._error)
+    // The Agent's failed-turn boundary is no answer (TAL-815).
+    if (msg.role !== 'assistant' || msg._error || agentRowKind(msg))
         return false;
     return messageText(msg.content).trim().length > 0;
 }
@@ -603,7 +690,7 @@ export function extractToolCallsFromMessages(messages, liveToolCalls = [], recor
  * (recorded live, else `null`), `result` (the result snippet, else `null`) and `result_view` (its display sections, TAL-315,
  * else `null`). Returns copies; stored rows are untouched.
  */
-export function withToolCallOutcomes(messages, sessionToolCalls, activeTurnId) {
+export function withToolCallOutcomes(messages, sessionToolCalls, activeTurnId, baseIndex = 0) {
     // Every identifier a stored call may carry (`ToolCallSchema`).
     const callId = (tc) => (isDict(tc) ? toolCallId(tc) || str(tc.tool_call_id) : '');
     // Providers may reuse an id (`call_1` in every response), so a reply answers the latest earlier assistant row that
@@ -620,7 +707,7 @@ export function withToolCallOutcomes(messages, sessionToolCalls, activeTurnId) {
         if (!isDict(m))
             return;
         if (m.role === 'tool')
-            answer(str(m.tool_call_id) || str(m.tool_use_id), { content: m.content, is_error: false });
+            answer(str(m.tool_call_id) || str(m.tool_use_id), { content: m.content, is_error: false, display_metadata: m.display_metadata });
         else if (m.role === 'user' && Array.isArray(m.content)) {
             // Anthropic-style results: `tool_result` blocks in a user row, each naming its call.
             for (const part of m.content)
@@ -657,7 +744,7 @@ export function withToolCallOutcomes(messages, sessionToolCalls, activeTurnId) {
         // Calls known only from a record: the session-level list's, and the live calls a failed or cancelled turn's partial
         // snapshot kept (`_partial_tool_calls`).
         const records = [];
-        const rowRecords = recordedByRow.get(index) ?? [];
+        const rowRecords = recordedByRow.get(baseIndex + index) ?? [];
         const recorded = new Map(rowRecords.filter((tc) => str(tc.tid)).map((tc) => [str(tc.tid), tc]));
         for (const tc of [...rowRecords, ...(Array.isArray(m._partial_tool_calls) ? m._partial_tool_calls : [])]) {
             if (!isDict(tc))
@@ -676,7 +763,7 @@ export function withToolCallOutcomes(messages, sessionToolCalls, activeTurnId) {
             const reply = id ? replies.get(key(index, id)) : undefined;
             const outcome = reply ? { ...toolOutcome(reply.content), flagged: reply.is_error } : null;
             // TAL-448: a file edit's change, from its full reply, else the one its live record decided.
-            const editDiff = reply ? toolEditDiff(name, reply.content) : decidedEditDiff(rec?.edit_diff);
+            const editDiff = reply ? toolEditDiff(name, reply.content, reply.display_metadata) : decidedEditDiff(rec?.edit_diff);
             return {
                 ...(editDiff ? { edit_diff: editDiff } : {}),
                 done: Boolean(reply) || answered || !running, is_error: outcome ? outcome.flagged || outcome.is_error : rec?.is_error === true,
@@ -800,7 +887,7 @@ export function journalOutputRows(events, turnId) {
         at = e.created_at || at;
     }
     flush();
-    const done = RunJournal.selectAuthoritativeTerminalEvent(events);
+    const done = selectAuthoritativeTerminalEvent(events);
     if (done?.event !== 'done')
         return { rows, answered: false };
     // The last row answers only with visible prose and no calls after it (a reasoning-only segment is no answer).
@@ -945,8 +1032,7 @@ export function normalizeAssistantDisplay(message) {
  * TAL-493: once a boundary or settled turn recorded the highest state.db id it read (`stateDbSeenId`) and the rows carry
  * ids, identity replaces the timestamp rules: rows up to that id are covered, and every newer row not already in the
  * sidecar is appended, even one a writer stamped before the newest local row or the watermark but committed later.
- * ponytail: the Python identity memo (api_content sidecars, message ids, workspace-prefix normalisation) is not ported;
- * add it if a mixed WebUI/CLI transcript shows duplicated turns.
+ * Direct and absorbed durable identities cover merged Agent prompts even when their text and timestamp changed.
  */
 export function mergeSessionMessagesAppendOnly(sidecar, state, opts = {}) {
     const watermark = Number(opts.truncationWatermark);
@@ -954,32 +1040,43 @@ export function mergeSessionMessagesAppendOnly(sidecar, state, opts = {}) {
     if (!state.length)
         return sidecar;
     const ts = (m) => { const n = Number(m.timestamp); return Number.isFinite(n) ? n : null; };
-    const key = (m) => `${String(m.role)}\0${String(ts(m) ?? '')}\0${typeof m.content === 'string' ? m.content : JSON.stringify(m.content ?? null)}`;
+    const key = stateDbMessageKey;
     const seenId = opts.stateDbSeenId;
+    const generation = opts.stateDbGeneration ?? null;
+    const includeUids = state.some((m) => stateDbIdentityKeys(m).some((id) => id.startsWith('uid:')));
+    const identities = (m) => stateDbIdentityKeys(m, includeUids, generation);
+    const representedIds = new Set(sidecar.flatMap((m) => identities(m)));
+    const isRepresented = (m) => stateDbMessageRepresented(m, representedIds, includeUids, generation);
+    const rememberIds = (m) => { for (const id of identities(m))
+        representedIds.add(id); };
     if (typeof seenId === 'number' && Number.isFinite(seenId) && state.some((m) => stateDbRowId(m) !== null)) {
-        // Each local row stands for at most one new state.db row: a persisted copy by its id, any other by its key.
-        const localIds = new Set(sidecar.map(stateDbRowId));
         const localKeys = new Map();
         for (const m of sidecar)
-            if (stateDbRowId(m) === null)
+            if (!identities(m).length)
                 localKeys.set(key(m), (localKeys.get(key(m)) ?? 0) + 1);
-        const merged = [...sidecar];
-        for (const m of state) {
-            const id = stateDbRowId(m);
-            if (id !== null && localIds.has(id))
-                continue;
-            // In state.db order, so a covered row matches its own local copy before a newer duplicate can.
-            const left = localKeys.get(key(m)) ?? 0;
-            if (left > 0) {
-                localKeys.set(key(m), left - 1);
-                continue;
-            }
-            if (id === null || id <= seenId)
-                continue;
-            merged.push(m);
-        }
-        return merged;
+        return [...sidecar, ...appendStateDbIdentityRows(state, seenId, representedIds, localKeys, generation, includeUids)];
     }
+    // Legacy sidecars may have no seen marker or row IDs. A verified copy can still match its archived
+    // source's exact role/timestamp/content key. This only removes represented copies; the timestamp
+    // and truncate/compress gates below continue to decide which remaining rows may be appended.
+    const represented = new Set();
+    const remember = (message) => {
+        represented.add(stateDbMessageFingerprint(message));
+        if (typeof message._state_db_source_key === 'string')
+            represented.add(message._state_db_source_key);
+    };
+    for (const message of sidecar)
+        remember(message);
+    state = state.filter((message) => {
+        if (isRepresented(message))
+            return false;
+        const sourceKey = message._state_db_source_key;
+        if (typeof sourceKey === 'string' && represented.has(sourceKey))
+            return false;
+        remember(message);
+        rememberIds(message);
+        return true;
+    });
     if (!sidecar.length) {
         if (!hasWatermark) {
             const seen = new Set();
@@ -1014,10 +1111,28 @@ export function mergeSessionMessagesAppendOnly(sidecar, state, opts = {}) {
     }
     return merged;
 }
-/** The state.db row id a row was read with (a compaction copy reads as the row it copies; TAL-709), or null for a database without the column. */
-function stateDbRowId(m) {
-    const id = m._state_db_row_id;
-    return typeof id === 'number' && Number.isFinite(id) ? id : null;
+/** Shared identity-mode append step; an indexed prefix supplies the same witnesses without visiting its rows. */
+export function appendStateDbIdentityRows(state, seenId, represented, localKeys, generation, includeUids) {
+    const added = new Set();
+    const consumed = new Map();
+    const witnesses = { has: (id) => represented.has(id) || added.has(id) };
+    const appended = [];
+    for (const m of state) {
+        if (stateDbMessageRepresented(m, witnesses, includeUids, generation))
+            continue;
+        const id = stateDbRowId(m), key = stateDbMessageKey(m);
+        const used = consumed.get(key) ?? 0;
+        const left = (localKeys.get(key) ?? 0) - used;
+        if (left > 0 && (m._state_db_authored_change !== true || id === null || id <= seenId))
+            consumed.set(key, used + 1);
+        else if (id !== null && id > seenId)
+            appended.push(m);
+        else
+            continue;
+        for (const identity of stateDbIdentityKeys(m, includeUids, generation))
+            added.add(identity);
+    }
+    return appended;
 }
 /** TAL-493: the `state_db_seen_id` after reading `rows`: their highest id, or null when they carry none. */
 export function stateDbSeenId(rows) {
@@ -1103,6 +1218,44 @@ export function withDisplayMedia(messages, project) {
         return out;
     });
 }
+/** Anthropic-style tool calls: `tool_use` blocks in the content array, interleaved with the text around them. */
+export function hasToolUseBlocks(message) {
+    return Array.isArray(message.content) && message.content.some((part) => isDict(part) && part.type === 'tool_use');
+}
+/**
+ * The final answer rule: the turn's last assistant row, with visible content, no tool calls, not interim or partial.
+ * A Stop row is no answer: its outcome is the status (TAL-364; older rows still carry English copy).
+ */
+export function finalAnswerOf(last) {
+    if ((Array.isArray(last.tool_calls) && last.tool_calls.length > 0) || hasToolUseBlocks(last) || last._interim === true || last._partial === true)
+        return '';
+    if (last._error === true && (last._terminal_state === 'cancelled' || last.provider_details_label === 'Cancellation details'))
+        return '';
+    return splitDisplayText(messageText(last.content))[0];
+}
+/** Conversation classification shared by the indexed selector and the hydrated projection. */
+export function isConversationalAssistant(message) {
+    return isDict(message) && message.role === 'assistant' && !agentRowKind(message) && !markerKind(message)
+        && !message._marker_kind && !message._notice_kind && !message._background_silent && !message._background_update && !message._delivery;
+}
+/** Absolute coordinate of the newest settled visible answer; running and answerless turns never displace it. */
+export function newestSettledReply(messages, activeTurnId, offset = 0) {
+    const visited = new Set();
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const m = messages[i];
+        if (!isConversationalAssistant(m))
+            continue;
+        const turn = typeof m._turn_id === 'string' ? m._turn_id : `row:${offset + i}`;
+        if (turn === activeTurnId || visited.has(turn))
+            continue;
+        visited.add(turn);
+        const scene = m._anchor_activity_scene;
+        const answer = isDict(scene) ? str(scene.final_answer) : finalAnswerOf(m);
+        if (!m._error && !m._partial && !m._interim && splitDisplayText(answer)[0].trim())
+            return offset + i;
+    }
+    return null;
+}
 /** TAL-456: a settled user or assistant body longer than this ships a collapsed excerpt for clients to render. */
 export const BODY_EXCERPT_LIMIT = 3000;
 const graphemes = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
@@ -1124,20 +1277,28 @@ function bodyExcerpt(text) {
 /**
  * TAL-456: stamps `_display_excerpt` and `_display_truncated` on settled user and assistant rows whose display text is longer than
  * `BODY_EXCERPT_LIMIT`, and `final_answer_excerpt` on a settled scene whose final answer is, so clients render a bounded
- * excerpt instead of laying out the whole body. Full text stays for copy and edit; the running turn's rows are left alone.
+ * excerpt instead of laying out the whole body. The newest settled answer and running turn stay full; copy and edit retain full text.
  * Runs after scene hydration. Returns copies; stored rows are untouched.
  */
-export function withBodyExcerpts(messages, activeTurnId) {
-    return messages.map((m) => {
+export function withBodyExcerpts(messages, activeTurnId, newestReplyIndex = newestSettledReply(messages, activeTurnId), offset = 0) {
+    return messages.map((m, index) => {
         if (!isDict(m) || (m.role !== 'user' && m.role !== 'assistant'))
             return m;
-        if (activeTurnId && m._turn_id === activeTurnId)
-            return m;
-        let out = m;
-        const text = typeof m._display_content === 'string' ? m._display_content : messageText(m.content);
+        let out = { ...m };
+        delete out._display_excerpt;
+        delete out._display_truncated;
+        if (isDict(out._anchor_activity_scene)) {
+            const scene = { ...out._anchor_activity_scene };
+            delete scene.final_answer_excerpt;
+            out._anchor_activity_scene = scene;
+        }
+        if ((activeTurnId && m._turn_id === activeTurnId) || index + offset === newestReplyIndex)
+            return out;
+        // A delivery shows its body under its own label (TAL-816), so the excerpt is the body's.
+        const text = isDict(m._delivery) ? str(m._delivery.body) : typeof m._display_content === 'string' ? m._display_content : messageText(m.content);
         if (text.length > BODY_EXCERPT_LIMIT)
             out = { ...out, _display_excerpt: bodyExcerpt(text), _display_truncated: true };
-        const scene = m._anchor_activity_scene;
+        const scene = out._anchor_activity_scene;
         const finalAnswer = isDict(scene) ? (typeof scene.final_answer_display === 'string' ? scene.final_answer_display : scene.final_answer) : null;
         if (isDict(scene) && typeof finalAnswer === 'string' && finalAnswer.length > BODY_EXCERPT_LIMIT) {
             out = { ...out, _anchor_activity_scene: { ...scene, final_answer_excerpt: bodyExcerpt(finalAnswer) } };
@@ -1232,6 +1393,11 @@ function toolCallId(tc) {
     return str(tc.id) || str(tc.call_id);
 }
 const API_SAFE_MSG_KEYS = new Set(['role', 'content', 'tool_calls', 'tool_call_id', 'tool_use_id', 'name', 'refusal', 'reasoning_content']);
+// TAL-927: the Agent's reload projection (`_rows_to_conversation`) restores these on assistant rows so prior reasoning
+// replays and keeps its signatures; turn history keeps them too. Persistence-only: the Agent strips them per route.
+const AGENT_ASSISTANT_REPLAY_KEYS = new Set(['reasoning', 'reasoning_details', 'codex_reasoning_items', 'codex_message_items', 'finish_reason']);
+// The opaque ones are bound to the provider that issued them.
+const PROVIDER_ISSUED_REASONING_KEYS = new Set(['reasoning_details', 'codex_reasoning_items', 'codex_message_items']);
 const OOB_USER_MESSAGE_BLOCK_RE = /\[OUT-OF-BAND\s+USER\s+MESSAGE(?:\s*(?:—|-)\s*[\s\S]*?)?\]\s*?[\s\S]*?\[\/OUT-OF-BAND\s+USER\s+MESSAGE\]/gi;
 const OOB_DELIVERY_RE = /^\s*\[OUT-OF-BAND\s+USER\s+MESSAGE[^\]]*\]\s*([\s\S]*?)\s*\[\/OUT-OF-BAND\s+USER\s+MESSAGE\]\s*$/i;
 /** The Agent's own record of a steer it delivered (`display_kind: 'steer'`, an out-of-band block): its text, else null. */
@@ -1273,9 +1439,11 @@ function stripOobBlocks(content) {
  * out-of-band blocks, and keeps a cancelled (`_recovered`) user prompt only where it separates two assistant turns —
  * otherwise the neighbours fuse cleanly or the prompt is stale, and replaying it would answer it again.
  * `preserveApiContent` (Python `_sanitize_messages_for_agent`) keeps the Agent's `api_content` replay sidecar on
- * user/assistant rows and every row's `timestamp` for turn history; compression and other projections strip both.
+ * user/assistant rows, every row's `timestamp`, and the assistant reasoning carriers the Agent replays (TAL-927) for
+ * turn history; compression and other projections strip them all. Provider-issued carriers stay only on rows stamped at
+ * or after `issuedReasoningSince`, the turn provider's start; without one they stay home too.
  */
-export function sanitizeMessagesForApi(messages, { preserveApiContent = false } = {}) {
+export function sanitizeMessagesForApi(messages, { preserveApiContent = false, issuedReasoningSince = null, maxMessages = Infinity } = {}) {
     // Calls are OpenAI `tool_calls` or Anthropic-style `tool_use` content blocks; results name them by `tool_call_id`,
     // `tool_use_id`, or a user row's `tool_result` blocks.
     const toolUseIds = (msg) => (Array.isArray(msg.content) ? msg.content.flatMap((part) => (isDict(part) && part.type === 'tool_use' && str(part.id) ? [str(part.id)] : [])) : []);
@@ -1300,7 +1468,7 @@ export function sanitizeMessagesForApi(messages, { preserveApiContent = false }
         if (isReasoningOnlyAssistant(msg) && !replay)
             continue;
         // The Agent already received a steer mid-turn; its persisted row is display-only.
-        if (msg._error || isDict(msg._steer))
+        if (msg._error || isDict(msg._steer) || msg._notice_kind === 'session_finalize')
             continue;
         if (msg._partial && !messageText(msg.content).trim())
             continue;
@@ -1310,7 +1478,10 @@ export function sanitizeMessagesForApi(messages, { preserveApiContent = false }
             if (!tid || !validToolCallIds.has(tid))
                 continue;
         }
-        const sanitized = Object.fromEntries(Object.entries(msg).filter(([k]) => API_SAFE_MSG_KEYS.has(k)));
+        const replayCarriers = preserveApiContent && msg.role === 'assistant';
+        const issuedHere = issuedReasoningSince !== null && Number(msg.timestamp) >= issuedReasoningSince;
+        const replayKey = (k) => replayCarriers && AGENT_ASSISTANT_REPLAY_KEYS.has(k) && (issuedHere || !PROVIDER_ISSUED_REASONING_KEYS.has(k));
+        const sanitized = Object.fromEntries(Object.entries(msg).filter(([k]) => API_SAFE_MSG_KEYS.has(k) || replayKey(k)));
         if (Array.isArray(sanitized.tool_calls) && !sanitized.tool_calls.length)
             Reflect.deleteProperty(sanitized, 'tool_calls');
         if (replay)
@@ -1367,9 +1538,46 @@ export function sanitizeMessagesForApi(messages, { preserveApiContent = false }
             msg = Object.fromEntries(Object.entries(msg).filter(([k]) => k !== '_recovered'));
         }
         final.push(msg);
+        if (final.length >= maxMessages)
+            break;
     }
     return final;
 }
+/** A revision's compression threshold, using the sanitizer itself and stopping once four retained rows prove it. */
+export class ApiMessageSummary {
+    excludeTurn;
+    displayHistory;
+    rows = [];
+    unidentified = [new Map(), new Map()];
+    enough = false;
+    marker = false;
+    nextCheck = 4;
+    constructor(excludeTurn = null, displayHistory = true) {
+        this.excludeTurn = excludeTurn;
+        this.displayHistory = displayHistory;
+    }
+    add(row) {
+        if (this.enough)
+            return;
+        if (this.displayHistory && (row._error || row._partial))
+            return;
+        this.marker ||= isContextCompressionMarker(row);
+        if (this.enough || (this.excludeTurn && row._turn_id === this.excludeTurn))
+            return;
+        this.rows.push(row);
+        for (const [mode, includeUids] of [false, true].entries())
+            if (!stateDbIdentityKeys(row, includeUids).length) {
+                const key = stateDbMessageKey(row);
+                this.unidentified[mode].set(key, (this.unidentified[mode].get(key) ?? 0) + 1);
+            }
+        if (this.rows.length >= this.nextCheck) {
+            this.finish();
+            this.nextCheck *= 2;
+        }
+    }
+    finish() { if (!this.enough)
+        this.enough = sanitizeMessagesForApi(this.rows, { maxMessages: 4 }).length >= 4; }
+}
 const isNativeImagePart = (part) => isDict(part) && (part.type === 'image_url' || 'image_url' in part);
 /** True when any row's content carries a native `image_url` part. */
 export function hasNativeImages(messages) {