@vellumai/assistant 0.11.7 → 0.11.8-staging.1

package/src/daemon/conversation-messaging.ts

@@ -37,6 +37,7 @@ import {
   attachmentExists,
   AttachmentUploadError,
   createInlineAttachment,
+  deleteOrphanAttachments,
   getAttachmentContent,
   getFilePathForAttachment,
   linkAttachmentToMessage,
@@ -59,7 +60,12 @@ import {
   syncMessageToDisk,
   updateMetaFile,
 } from "../persistence/conversation-disk-view.js";
-import type { ContentBlock, Message } from "../providers/types.js";
+import { SIGHT_FRAME_ATTACHMENT_IDS_KEY } from "../persistence/conversation-types.js";
+import {
+  attachmentIdFragment,
+  type ContentBlock,
+  type Message,
+} from "../providers/types.js";
 import type { AuthContext } from "../runtime/auth/types.js";
 import { getLogger } from "../util/logger.js";
 import { withSqliteRetry } from "../util/sqlite-retry.js";
@@ -430,37 +436,232 @@ async function prepareUserAttachmentReferences(
   attachments: MessageAttachmentInput[],
 ): Promise<PreparedUserAttachment[]> {
   const prepared: PreparedUserAttachment[] = [];
-  for (let i = 0; i < attachments.length; i++) {
-    const a = attachments[i];
-    const outcome = await materializeUserAttachment(
-      conversationId,
-      conversationCreatedAt,
-      a,
+  // Rows this call brought into being, tracked as they are made rather than
+  // read back off `prepared`: building a reference block is awaited between
+  // creating the row and recording it, so a throw there leaves a row nothing
+  // else knows about. The caller only ever sees a returned array, so a throw
+  // out of here makes this the one place that can still give them up.
+  const created: string[] = [];
+  try {
+    for (let i = 0; i < attachments.length; i++) {
+      const a = attachments[i];
+      const outcome = await materializeUserAttachment(
+        conversationId,
+        conversationCreatedAt,
+        a,
+      );
+      if (outcome.kind === "stored") {
+        if (outcome.stored.id !== a.id) {
+          created.push(outcome.stored.id);
+        }
+        prepared.push({
+          position: i,
+          block: await referenceBlockForAttachment(a, outcome.stored),
+          link: { attachmentId: outcome.stored.id },
+        });
+        continue;
+      }
+      if (outcome.kind === "rejected") {
+        continue;
+      }
+      // transient: keep the upload by inlining its bytes (dropped only when the
+      // recoverable failure left us with no bytes to inline).
+      const inline = await inlineBlockForAttachment(a);
+      if (inline) {
+        prepared.push({ position: i, block: inline });
+      } else {
+        log.warn(
+          { filename: a.filename },
+          "Dropping user attachment: store write failed and no inline bytes",
+        );
+      }
+    }
+  } catch (err) {
+    discardAttemptAttachments(created);
+    throw err;
+  }
+  return prepared;
+}
+
+/**
+ * Give up attachment rows a failed persist attempt created for itself.
+ *
+ * Conversation scoping CLONES an attachment already linked to another
+ * conversation, and an inline upload creates a fresh row under an id of its
+ * own. Either way the row is an artifact of this attempt that nothing else can
+ * reach: no message names it, and the caller still holds the id it sent or the
+ * bytes behind it. An attempt that dies before its message row exists has to
+ * take those with it, or the row and its copied file stay for good.
+ *
+ * Never the id the caller handed in. When materialization stored the
+ * attachment under that same id, the row IS the caller's upload, and deleting
+ * it would break the retry they are about to make.
+ *
+ * Routed through {@link deleteOrphanAttachments} so link-awareness stays the
+ * backstop, and swallowed on failure: cleaning up must never mask the error
+ * that caused it.
+ */
+function discardAttemptAttachments(attachmentIds: string[]): void {
+  if (attachmentIds.length === 0) {
+    return;
+  }
+  try {
+    deleteOrphanAttachments(attachmentIds);
+  } catch (err) {
+    log.warn(
+      { err, attachmentIds },
+      "Could not discard the attachments of a failed persist attempt",
     );
-    if (outcome.kind === "stored") {
-      prepared.push({
-        position: i,
-        block: await referenceBlockForAttachment(a, outcome.stored),
-        link: { attachmentId: outcome.stored.id },
-      });
+  }
+}
+
+/**
+ * Materialized ids that differ from the id their input arrived with, which is
+ * what separates a row this attempt made from the caller's own upload.
+ */
+function attemptCreatedAttachmentIds(
+  attachmentInputs: MessageAttachmentInput[],
+  prepared: PreparedUserAttachment[],
+): string[] {
+  const created: string[] = [];
+  for (const p of prepared) {
+    if (!p.link) {
       continue;
     }
-    if (outcome.kind === "rejected") {
-      continue;
+    if (p.link.attachmentId !== attachmentInputs[p.position]?.id) {
+      created.push(p.link.attachmentId);
     }
-    // transient: keep the upload by inlining its bytes (dropped only when the
-    // recoverable failure left us with no bytes to inline).
-    const inline = await inlineBlockForAttachment(a);
-    if (inline) {
-      prepared.push({ position: i, block: inline });
-    } else {
-      log.warn(
-        { filename: a.filename },
-        "Dropping user attachment: store write failed and no inline bytes",
-      );
+  }
+  return created;
+}
+
+/** One requested camera frame: the id the caller held, and what was stored. */
+interface SightFrameEntry {
+  inputId: string;
+  storedId: string;
+}
+
+/**
+ * Pair each requested ambient camera frame with the id its persisted block is
+ * attributable by, walking every materialized attachment back to the input it
+ * came from.
+ *
+ * Which id that is depends on how the attachment landed. A stored one is named
+ * by its linked row, which is also what its `workspace_ref` block carries. One
+ * that fell back to inline base64 has no row, and its block carries the
+ * caller's own id on `_attachmentId`, so that is the id to name: retention
+ * reads both shapes through `mediaBlockAttachmentId`, and an inline frame is
+ * the heaviest thing in every later request precisely because its bytes are in
+ * the row.
+ */
+function requestedSightFrameEntries(
+  requestedIds: readonly string[] | undefined,
+  attachmentInputs: MessageAttachmentInput[],
+  prepared: PreparedUserAttachment[],
+): SightFrameEntry[] {
+  if (!requestedIds || requestedIds.length === 0) {
+    return [];
+  }
+  const requested = new Set(requestedIds);
+  const entries: SightFrameEntry[] = [];
+  for (const p of prepared) {
+    const inputId = attachmentInputs[p.position]?.id;
+    if (inputId === undefined || !requested.has(inputId)) {
+      continue;
     }
+    entries.push({
+      inputId,
+      storedId: p.link ? p.link.attachmentId : inputId,
+    });
   }
-  return prepared;
+  return entries;
+}
+
+/**
+ * The ids to tag the row with.
+ *
+ * Exactly one id per frame, never both. A stored attachment's pre-clone id
+ * belongs to a DIFFERENT conversation's row, so naming it as well would mark
+ * that attachment as an ambient frame if it ever entered this lineage and stub
+ * an image someone deliberately attached. That is what separates this from a
+ * fork's widened tag (`widenForkSightFrameTags`), where the two ids are two
+ * names for the same image.
+ */
+function sightFrameTagIds(entries: SightFrameEntry[]): string[] {
+  return [...new Set(entries.map((entry) => entry.storedId))];
+}
+
+/**
+ * Frames whose stored id differs from the one the caller handed in, by the
+ * caller's id. Empty unless conversation scoping cloned a row.
+ */
+function sightFrameBlockRenames(
+  entries: SightFrameEntry[],
+): Map<string, string> {
+  return new Map(
+    entries
+      .filter((entry) => entry.storedId !== entry.inputId)
+      .map((entry) => [entry.inputId, entry.storedId]),
+  );
+}
+
+/**
+ * Point an inline media block at the id its attachment was stored under.
+ *
+ * Only the inline shape is restamped. A `workspace_ref` names its row inside
+ * `source`, which materialization already filled with the stored id, so there
+ * is nothing to correct and rewriting `_attachmentId` alone would leave the two
+ * halves disagreeing.
+ */
+function restampInlineAttachmentId(
+  block: ContentBlock,
+  renames: ReadonlyMap<string, string>,
+): ContentBlock {
+  if (block.type !== "image" && block.type !== "file") {
+    return block;
+  }
+  if (block.source.type === "workspace_ref") {
+    return block;
+  }
+  const renamed =
+    block._attachmentId === undefined
+      ? undefined
+      : renames.get(block._attachmentId);
+  if (renamed === undefined) {
+    return block;
+  }
+  return { ...block, ...attachmentIdFragment(renamed) };
+}
+
+/**
+ * Rewrite the live message's camera-frame blocks to the ids their rows were
+ * stored under.
+ *
+ * The in-memory message is built from the attachments the caller handed in, so
+ * its blocks name the ids the caller held while the tag names what
+ * materialization stored. Those differ whenever conversation scoping cloned a
+ * row, and retention walking the live history would then find no frame to age:
+ * the tag matches nothing until a reload rebuilds the blocks from the persisted
+ * content. Restamping is what makes the array a turn actually sends agree with
+ * the tag, so a cloned frame is bounded on the turn that created it rather than
+ * only after a restart.
+ *
+ * Matched by id, never by position: `attachmentsToContentBlocks` emits nothing
+ * for an attachment it cannot turn into a block, so positions do not line up.
+ */
+function restampInlineAttachmentIds(
+  message: Message,
+  renames: ReadonlyMap<string, string>,
+): Message {
+  if (renames.size === 0) {
+    return message;
+  }
+  return {
+    ...message,
+    content: message.content.map((block) =>
+      restampInlineAttachmentId(block, renames),
+    ),
+  };
 }
 
 function extractTurnChannelContext(
@@ -736,6 +937,30 @@ export interface PersistMessageOptions {
    * what a consumer that must not misattribute a turn to a surface needs.
    */
   requestClientOs?: string;
+  /**
+   * Which of `attachments`, by the id the caller holds, arrived as ambient
+   * camera frames rather than files the user picked. Stamps
+   * `SIGHT_FRAME_ATTACHMENT_IDS_KEY` on the persisted row, which is what the
+   * retention pass reads to decide which images a later turn still sends in
+   * full and which become timestamped stubs.
+   *
+   * Named through this option rather than written into `metadata` by the
+   * caller because only the persist knows the id the row ends up linked to.
+   * A pre-uploaded attachment already linked to another conversation is
+   * CLONED into this one under a fresh id, and both the persisted content
+   * block and the `message_attachments` row carry the clone. A tag composed
+   * ahead of that names a row the retention pass can never match, and the
+   * frame then rides every later request forever.
+   *
+   * The tag names whatever id the persisted block is attributable by: the
+   * linked row's id for a materialized attachment, and the caller's own id
+   * for one a recoverable store failure left as inline base64, which is the
+   * id `attachmentsToContentBlocks` stamps on that block. The inline case is
+   * the one that matters most, because such a block carries its full bytes in
+   * `messages.content`, so the frame heaviest in every later request is
+   * exactly the one retention has to be able to stub.
+   */
+  sightFrameAttachmentIds?: readonly string[];
 }
 
 // ── persistUserMessage ───────────────────────────────────────────────
@@ -857,6 +1082,13 @@ export async function persistQueuedMessageBody(
     }),
   );
   let pushedToHistory = false;
+  // Hoisted so the failure path can tell which rows this attempt made, and
+  // whether its message ever landed. From the insert onward the persisted
+  // content references those rows while no link yet protects them, which is
+  // exactly the shape a link-aware delete reads as collectible, so the cleanup
+  // must stop at the insert.
+  let preparedAttachments: PreparedUserAttachment[] = [];
+  let messageInserted = false;
 
   try {
     const turnCtx =
@@ -1009,7 +1241,7 @@ export async function persistQueuedMessageBody(
     // once the message id exists.
     const conversationCreatedAt =
       getConversation(ctx.conversationId)?.createdAt ?? Date.now();
-    const preparedAttachments = await prepareUserAttachmentReferences(
+    preparedAttachments = await prepareUserAttachmentReferences(
       ctx.conversationId,
       conversationCreatedAt,
       attachmentInputs,
@@ -1021,7 +1253,18 @@ export async function persistQueuedMessageBody(
     const sentAttachments = preparedAttachments.map(
       (p) => attachmentInputs[p.position],
     );
-    const cleanMessage = await createUserMessage(content, sentAttachments);
+    const sightFrameEntries = requestedSightFrameEntries(
+      options.sightFrameAttachmentIds,
+      attachmentInputs,
+      preparedAttachments,
+    );
+    const sightFrameRenames = sightFrameBlockRenames(sightFrameEntries);
+    // The blocks are built from the ids the caller held, so a cloned frame is
+    // pointed at its stored row before the message reaches the live history.
+    const cleanMessage = restampInlineAttachmentIds(
+      await createUserMessage(content, sentAttachments),
+      sightFrameRenames,
+    );
 
     // When displayContent is provided (e.g. original text before recording
     // intent stripping), persist that to DB so users see the full message
@@ -1032,17 +1275,26 @@ export async function persistQueuedMessageBody(
       displayContent,
       preparedAttachments.map((p) => p.block),
     );
+    // Composed here rather than with the rest of the metadata above, because
+    // materialization is what decides the id each frame is stored under.
+    const sightFrameIds = sightFrameTagIds(sightFrameEntries);
+    const metadataToPersist =
+      sightFrameIds.length > 0
+        ? { ...mergedMetadata, [SIGHT_FRAME_ATTACHMENT_IDS_KEY]: sightFrameIds }
+        : mergedMetadata;
+
     const persistedUserMessage = await addMessage(
       ctx.conversationId,
       "user",
       contentToPersist,
       {
-        metadata: mergedMetadata,
+        metadata: metadataToPersist,
         clientMessageId,
         id: requestId,
         ...(skipIndexing ? { skipIndexing: true } : {}),
       },
     );
+    messageInserted = true;
 
     if (persistedUserMessage.deduplicated) {
       return { id: persistedUserMessage.id, deduplicated: true };
@@ -1106,7 +1358,13 @@ export async function persistQueuedMessageBody(
         );
         if (inline) {
           repairedBlocks ??= preparedAttachments.map((pp) => pp.block);
-          repairedBlocks[idx] = inline;
+          // Rebuilt from the caller's attachment, so it names the id the
+          // caller held while the tag written above names the stored row.
+          // Restamping keeps a repaired frame matchable by retention.
+          repairedBlocks[idx] = restampInlineAttachmentId(
+            inline,
+            sightFrameRenames,
+          );
         }
       }
     }
@@ -1169,6 +1427,11 @@ export async function persistQueuedMessageBody(
     if (pushedToHistory) {
       ctx.messages.pop();
     }
+    if (!messageInserted) {
+      discardAttemptAttachments(
+        attemptCreatedAttachmentIds(attachmentInputs, preparedAttachments),
+      );
+    }
     throw err;
   }
 }

package/src/daemon/conversation-runtime-assembly.ts

@@ -48,6 +48,7 @@ import { isGuardianCardRow } from "../notifications/approval-card-data.js";
 import {
   getMessages as defaultGetMessages,
   type MessageRow,
+  selectSightFrameCaptureTimes,
 } from "../persistence/conversation-crud.js";
 import { isBackgroundConversationType } from "../persistence/conversation-types.js";
 import { createContextSummaryMessage } from "../plugins/defaults/compaction/window-manager.js";
@@ -76,8 +77,14 @@ import { resolveCapabilities } from "../runtime/capabilities.js";
 import type { SubagentState } from "../subagent/types.js";
 import { TERMINAL_STATUSES } from "../subagent/types.js";
 import { canonicalizeInboundIdentity } from "../util/canonicalize-identity.js";
+import { getLogger } from "../util/logger.js";
 import { channelSupportsInlineOptions } from "./channel-ui-capability.js";
 import { findConversationOrSubagent } from "./conversation-registry.js";
+import {
+  hasAttributableImages,
+  resolveSightKeepLatestFrames,
+  stripAgedSightFrames,
+} from "./conversation-sight-frames.js";
 import type { SurfaceShowPair } from "./conversation-surfaces.js";
 import { canonicalizeTimeZone, formatTurnTimestamp } from "./date-context.js";
 import type {} from "./message-protocol.js";
@@ -89,6 +96,8 @@ import { timeLatencySubSpan } from "./turn-latency-sub-spans.js";
 // loop can own it; re-exported here for this module's existing consumers.
 export { stripInjectionsForCompaction } from "../context/strip-injections.js";
 
+const log = getLogger("conversation-runtime-assembly");
+
 /**
  * Describes the capabilities of the channel through which the user is
  * interacting.  Used to gate UI-specific references and permission asks.
@@ -737,6 +746,64 @@ export function stripNowScratchpad(messages: Message[]): Message[] {
   return stripUserTextBlocksByPrefix(messages, NOW_SCRATCHPAD_STRIP_PREFIXES);
 }
 
+// ---------------------------------------------------------------------------
+// Camera-frame retention
+// ---------------------------------------------------------------------------
+
+/**
+ * Trim the conversation's ambient camera frames down to the newest
+ * `sight.keepLatestFrames`, replacing the rest with text stubs.
+ *
+ * A camera call samples a frame every few seconds, and history resends
+ * every inline image on every later request, so an hour-long call otherwise
+ * grows its own context until the provider rejects it. Trimming here, on the
+ * assembled copy the turn is about to send, keeps the stored transcript and its
+ * attachments intact.
+ *
+ * The tag that names the frames is per-row metadata, and the assembled
+ * `Message[]` omits row metadata, so the ids are read back from the rows and
+ * matched against the attachment id each image block carries: `workspace_ref`
+ * on a reloaded block, `_attachmentId` on the live copy a turn pushed. One
+ * uninterrupted call and a reloaded conversation therefore trim from the same
+ * pool. A conversation with no tagged rows returns the input array unchanged.
+ *
+ * Called twice over a turn that compacts: once before the run, and again on the
+ * rebuilt history the agent loop installs, since compaction reads the stored
+ * rows and can retain frames this pass had already stubbed.
+ *
+ * Best-effort: this trims cost, it does not decide what the turn means, so a
+ * failed read degrades to the untrimmed history rather than failing the turn.
+ */
+export function applySightFrameRetention(
+  messages: Message[],
+  conversationId: string,
+): Message[] {
+  // A frame always traces back to an attachment row, so a history holding no
+  // attributable image can be answered without reading any rows. That is the
+  // overwhelming majority of turns, and this pass sits on the per-turn critical
+  // path.
+  if (!hasAttributableImages(messages)) {
+    return messages;
+  }
+  try {
+    const captureTimes = selectSightFrameCaptureTimes(conversationId);
+    if (captureTimes.size === 0) {
+      return messages;
+    }
+    return stripAgedSightFrames(
+      messages,
+      captureTimes,
+      resolveSightKeepLatestFrames(),
+    ).messages;
+  } catch (err) {
+    log.warn(
+      { conversationId, err },
+      "Camera-frame retention failed (non-fatal)",
+    );
+    return messages;
+  }
+}
+
 /**
  * Build the `<channel_capabilities>` block text for the given capabilities, or
  * `null` on the happy path (desktop, full capabilities, no special context)

package/src/daemon/conversation-sight-frames.ts

@@ -0,0 +1,187 @@
+/**
+ * Retention for ambient camera frames, the images a call samples on its own
+ * while the camera is up.
+ *
+ * Frames arrive every few seconds for as long as the camera is up, and history
+ * resends every inline image on every later request, so a long call grows its
+ * own context until the provider rejects it. {@link stripAgedSightFrames} keeps
+ * only the newest `sight.keepLatestFrames` as real images and replaces the rest
+ * with text stubs, on the copy of the history a turn is about to send.
+ *
+ * This is the proactive counterpart to `stripMediaPayloadsForRetry`
+ * (`conversation-media-retry.ts`), which fires only after a provider has
+ * already rejected a request and which governs every kind of media. The two
+ * live apart because that module reaches the compaction layer for its
+ * summary-message predicate and this one must stay a leaf the assembly path can
+ * import. They agree on the shape of what they leave behind: a `text` block
+ * naming the media that was dropped, so a frame stubbed here is plain text by
+ * the time the retry path walks the history and is neither counted as media nor
+ * stubbed a second time. Both describe that media through
+ * `mediaSourceDescriptor`, which is what holds the two wordings together
+ * without either module importing the other.
+ */
+
+import { getConfig } from "../config/loader.js";
+import {
+  KEEP_LATEST_SIGHT_FRAMES,
+  MAX_SIGHT_KEEP_LATEST_FRAMES,
+  MIN_SIGHT_KEEP_LATEST_FRAMES,
+} from "../config/schemas/sight.js";
+import { mediaSourceDescriptor } from "../providers/media-resolve.js";
+import {
+  type ContentBlock,
+  mediaBlockAttachmentId,
+  type Message,
+} from "../providers/types.js";
+
+/**
+ * The workspace's `sight.keepLatestFrames`, clamped to
+ * [{@link MIN_SIGHT_KEEP_LATEST_FRAMES}, {@link MAX_SIGHT_KEEP_LATEST_FRAMES}].
+ *
+ * Clamped at read rather than rejected by the schema because an out-of-range
+ * value states an intent the guardrail can honor part of the way: capping it
+ * shows the most frames the budget allows, while failing validation would fall
+ * back to the default and show a number neither the config nor the guardrail
+ * asked for.
+ */
+export function resolveSightKeepLatestFrames(): number {
+  const configured = getConfig().sight.keepLatestFrames;
+  if (!Number.isFinite(configured)) {
+    return KEEP_LATEST_SIGHT_FRAMES;
+  }
+  return Math.min(
+    MAX_SIGHT_KEEP_LATEST_FRAMES,
+    Math.max(MIN_SIGHT_KEEP_LATEST_FRAMES, Math.trunc(configured)),
+  );
+}
+
+/**
+ * True when any image in the history can be traced back to an attachment row.
+ *
+ * The retention pass reads rows to learn which attachments were camera frames;
+ * a history holding no attributable image has nothing those rows could match,
+ * so callers use this to skip the read entirely. Shares
+ * {@link mediaBlockAttachmentId} with the matcher so the two cannot disagree
+ * about what is skippable.
+ */
+export function hasAttributableImages(messages: Message[]): boolean {
+  return messages.some((message) =>
+    message.content.some(
+      (block) =>
+        block.type === "image" && mediaBlockAttachmentId(block) !== undefined,
+    ),
+  );
+}
+
+/**
+ * Replace every camera frame in `messages` except the newest
+ * `keepLatestFrames` with a text stub.
+ *
+ * `keepLatestFrames` defaults to {@link KEEP_LATEST_SIGHT_FRAMES}, the config
+ * default. The assembly path passes {@link resolveSightKeepLatestFrames}
+ * instead, so what a turn sends follows the workspace's own setting.
+ *
+ * `frameCaptureTimes` maps an attachment id the conversation tagged as a camera
+ * frame to when the row carrying it was written; an image block counts as a
+ * frame only when {@link mediaBlockAttachmentId} resolves it to one of those
+ * ids. Every other attachment (picked files, pasted images, shutter photos) is
+ * left alone here.
+ *
+ * Frames are ranked by capture time, not by where they sit in the history:
+ * compaction rebuilds the frames it keeps into one synthetic message in the
+ * order the model listed them, so position stops tracking recency the moment a
+ * conversation has been compacted. The times come from the rows themselves
+ * (`createdAt`, which `monotonicNow` keeps strictly increasing), so they order
+ * frames the way they were captured and no client-supplied timestamp can perturb
+ * that. Frames sharing a row share a time and fall back to history order, which
+ * is the order they were attached. Returns the input array itself when nothing
+ * is replaced.
+ */
+export function stripAgedSightFrames(
+  messages: Message[],
+  frameCaptureTimes: ReadonlyMap<string, number>,
+  keepLatestFrames: number = KEEP_LATEST_SIGHT_FRAMES,
+): { messages: Message[]; modified: boolean; replacedBlocks: number } {
+  if (frameCaptureTimes.size === 0) {
+    return { messages, modified: false, replacedBlocks: 0 };
+  }
+
+  const frames: Array<{
+    messageIndex: number;
+    blockIndex: number;
+    capturedAt: number;
+  }> = [];
+  for (const [messageIndex, message] of messages.entries()) {
+    for (const [blockIndex, block] of message.content.entries()) {
+      if (block.type !== "image") {
+        continue;
+      }
+      const attachmentId = mediaBlockAttachmentId(block);
+      if (attachmentId === undefined) {
+        continue;
+      }
+      const capturedAt = frameCaptureTimes.get(attachmentId);
+      if (capturedAt === undefined) {
+        continue;
+      }
+      frames.push({ messageIndex, blockIndex, capturedAt });
+    }
+  }
+  if (frames.length <= keepLatestFrames) {
+    return { messages, modified: false, replacedBlocks: 0 };
+  }
+
+  // Oldest first by capture time, so dropping the tail keeps the newest. The
+  // sort is stable and `frames` was collected in history order, which is what
+  // separates frames that share a row's timestamp.
+  const byCaptureTime = [...frames].sort((a, b) => a.capturedAt - b.capturedAt);
+  const aged = new Map<number, Map<number, number>>();
+  for (const frame of byCaptureTime.slice(
+    0,
+    byCaptureTime.length - keepLatestFrames,
+  )) {
+    const blocks = aged.get(frame.messageIndex) ?? new Map<number, number>();
+    blocks.set(frame.blockIndex, frame.capturedAt);
+    aged.set(frame.messageIndex, blocks);
+  }
+
+  let replacedBlocks = 0;
+  const nextMessages = messages.map((message, messageIndex) => {
+    const blocks = aged.get(messageIndex);
+    if (!blocks) {
+      return message;
+    }
+    return {
+      ...message,
+      content: message.content.map((block, blockIndex) => {
+        const capturedAt = blocks.get(blockIndex);
+        if (capturedAt === undefined || block.type !== "image") {
+          return block;
+        }
+        replacedBlocks += 1;
+        return sightFrameBlockToStub(block, capturedAt);
+      }),
+    };
+  });
+
+  return { messages: nextMessages, modified: true, replacedBlocks };
+}
+
+/**
+ * Stub for a frame that has aged out of the context. Describes the dropped
+ * media through `mediaSourceDescriptor`, the same way the retry path's stubs
+ * do, and adds the capture time, which is the only thing telling one ambient
+ * frame from another once the pixels are gone. A frame is always an image, so
+ * the extracted-text folding the retry path does for file blocks has nothing to
+ * act on here.
+ */
+function sightFrameBlockToStub(
+  block: Extract<ContentBlock, { type: "image" }>,
+  capturedAt: number,
+): Extract<ContentBlock, { type: "text" }> {
+  const capturedAtIso = new Date(capturedAt).toISOString();
+  return {
+    type: "text",
+    text: `[Camera frame omitted from context: captured ${capturedAtIso}, ${mediaSourceDescriptor(block.source)}]`,
+  };
+}