@ixo/oracle-runtime-workers 0.37.1 → 0.38.0

package/src/llm/provider-error.ts

@@ -268,10 +268,13 @@ export function markPlatformFallbackFailure(error: unknown): void {
   if (error && typeof error === 'object') PLATFORM_FALLBACK_FAILURES.add(error);
 }
 
-/** The error, or one it wraps (`cause`, as LangChain's MiddlewareError does). */
+/**
+ * The error, or one it wraps (`cause`, as LangChain's MiddlewareError does,
+ * once per middleware layer).
+ */
 function isPlatformFallbackFailure(error: unknown): boolean {
   let current: unknown = error;
-  for (let depth = 0; depth < 8; depth += 1) {
+  for (let depth = 0; depth < 32; depth += 1) {
     if (!current || typeof current !== 'object') return false;
     if (PLATFORM_FALLBACK_FAILURES.has(current)) return true;
     current = 'cause' in current ? current.cause : undefined;

package/src/llm/stream-liveness.ts

@@ -83,11 +83,12 @@ export class ProviderStallError extends Error {
 /**
  * The `ProviderStallError` in `error` or its `cause` chain — the OpenAI SDK
  * wraps a failed `fetch` in `APIConnectionError` with the original as
- * `cause`, LangChain's middleware errors wrap again.
+ * `cause`, LangChain's middleware errors wrap again, once per middleware
+ * layer (a dozen on the main agent), so the walk goes deep.
  */
 export function findProviderStall(error: unknown): ProviderStallError | null {
   let current: unknown = error;
-  for (let depth = 0; depth < 8; depth += 1) {
+  for (let depth = 0; depth < 32; depth += 1) {
     if (current instanceof ProviderStallError) return current;
     if (!current || typeof current !== 'object' || !('cause' in current))
       return null;

package/src/matrix/gateway-do.ts

@@ -24,9 +24,11 @@ import {
   listPendingSends,
   MatrixBotDO,
   optionsFromEnv,
+  parseEncryptedFileInfo,
   Semaphore,
   withRateLimitRetry,
   type BotMessage,
+  type EncryptedFileInfo,
   type BotTimelineEvent,
   type MatrixBotOptions,
   type StartResult,
@@ -37,6 +39,7 @@ import {
   userOracleRoomAlias,
   type BotCredentials,
   type CreateRoomOptions,
+  type EventMediaInfo,
   type GatewayStatus,
   type GroupRoomInfo,
   type JsonString,
@@ -99,11 +102,7 @@ import {
 } from './user-homeserver';
 import { replyPartTxnId, roomReplyMessages } from './reply-parts';
 import { VerifiedRoomAliases } from './room-alias';
-import {
-  boundedSignal,
-  raceSignal,
-  streamWithDeadline,
-} from './media-deadline';
+import { boundedSignal, raceSignal } from './media-deadline';
 
 const TYPING_REFRESH_MS = 20_000;
 const TYPING_TIMEOUT_MS = 30_000;
@@ -122,11 +121,19 @@ const MEMO_MAX_ENTRIES = 5_000;
  */
 const STATUS_CACHE_MS = 5_000;
 /**
- * Upper bound on one media download (response and body), unless the caller
- * asks for less. A stalled homeserver stream must not hold the reader — and
- * with it the user's turn — open indefinitely.
+ * Upper bound on one media event lookup (`eventMediaInfo`), unless the caller
+ * asks for less. A stalled homeserver must not hold the user's turn open
+ * indefinitely.
  */
 export const MEDIA_DOWNLOAD_TIMEOUT_MS = 60_000;
+/**
+ * `sendEvent` calls with `priority: 'background'` (channel text mirrors and
+ * file events) in the SDK's send path at once. The SDK 0.7.0 `sendEvent`
+ * dispatches every event `interactive`, so this lane is what keeps a burst
+ * of them from queueing ahead of replies in the rate-limited sender: at most
+ * this many sit there, the rest wait here.
+ */
+export const BACKGROUND_SEND_CONCURRENCY = 2;
 /**
  * A live message whose sender's homeserver could not be looked up stays in
  * the inbox and is replayed on its own after this delay (each replay is
@@ -184,6 +191,90 @@ interface OracleGatewayConfig {
   oracleRoomDid: string;
 }
 
+/** A JSON object's own property, or undefined. */
+function prop(value: unknown, name: string): unknown {
+  return typeof value === 'object' && value !== null && name in value
+    ? Reflect.get(value, name)
+    : undefined;
+}
+
+/** Whether event content (JSON) carries an attachment key (`file.key`, `EncryptedFile`). */
+function carriesAttachmentKey(content: JsonString): boolean {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    // The SDK refuses content that is not a JSON object.
+    return false;
+  }
+  return prop(prop(parsed, 'file'), 'key') !== undefined;
+}
+
+/**
+ * The `EncryptedFile` fields of an event's `file`, validated
+ * (`parseEncryptedFileInfo` throws on a malformed one) and rebuilt from the
+ * checked values, without `url`, `mimetype` and `size`.
+ */
+function encryptedFileOf(file: unknown): EncryptedFileInfo {
+  parseEncryptedFileInfo(file);
+  const key = prop(file, 'key');
+  const k = prop(key, 'k');
+  const iv = prop(file, 'iv');
+  const sha256 = prop(prop(file, 'hashes'), 'sha256');
+  if (
+    typeof k !== 'string' ||
+    typeof iv !== 'string' ||
+    typeof sha256 !== 'string'
+  )
+    throw new Error('encrypted attachment: malformed EncryptedFile');
+  const ops = prop(key, 'key_ops');
+  return {
+    v: 'v2',
+    key: {
+      kty: 'oct',
+      key_ops: Array.isArray(ops)
+        ? ops.filter((op): op is string => typeof op === 'string')
+        : ['encrypt', 'decrypt'],
+      alg: 'A256CTR',
+      k,
+      ext: true,
+    },
+    iv,
+    hashes: { sha256 },
+  };
+}
+
+/**
+ * Where a decrypted media event's file lives (`eventMediaInfo`): null for a
+ * redaction, a redacted (empty) event or one without an `mxc://` URL.
+ */
+export function mediaInfoOfEvent(
+  event: unknown,
+  eventId: string,
+): EventMediaInfo | null {
+  if (prop(event, 'type') === 'm.room.redaction') return null;
+  const content = prop(event, 'content');
+  if (typeof content !== 'object' || content === null) return null;
+  if (Object.keys(content).length === 0) return null;
+  const file = prop(content, 'file');
+  const mxc = file !== undefined ? prop(file, 'url') : prop(content, 'url');
+  if (typeof mxc !== 'string' || !mxc.startsWith('mxc://'))
+    throw new Error(
+      `MatrixGatewayDO: media event ${eventId} carries no mxc url`,
+    );
+  const info = prop(content, 'info');
+  const mimetype = prop(info, 'mimetype');
+  const size = prop(info, 'size');
+  const filename = prop(content, 'filename') ?? prop(content, 'body');
+  return {
+    mxc,
+    ...(file !== undefined ? { file: encryptedFileOf(file) } : {}),
+    ...(typeof mimetype === 'string' ? { mimetype } : {}),
+    ...(typeof filename === 'string' ? { filename } : {}),
+    ...(typeof size === 'number' ? { size } : {}),
+  };
+}
+
 /** The plugins' device credentials as stored (`identity:bot-client`). */
 interface StoredDevice {
   userId: string;
@@ -197,9 +288,9 @@ interface AliasCacheEntry {
   at: number;
 }
 
-/** A media download's bound. `signal` only works for a caller in this isolate: an `AbortSignal` cannot cross an RPC boundary. */
+/** A media event lookup's bound. `signal` only works for a caller in this isolate: an `AbortSignal` cannot cross an RPC boundary. */
 export interface MediaDownloadOptions {
-  /** Upper bound on the whole transfer (default `MEDIA_DOWNLOAD_TIMEOUT_MS`). */
+  /** Upper bound on the whole lookup (default `MEDIA_DOWNLOAD_TIMEOUT_MS`). */
   timeoutMs?: number;
   signal?: AbortSignal;
 }
@@ -371,6 +462,9 @@ export class MatrixGatewayDO
     gateSizeFromEnv(this.env.MATRIX_TURN_CONCURRENCY, DEFAULT_TURN_CONCURRENCY),
   );
   private pluginDevice: BotCredentials | null = null;
+  /** The plugin device lookup in flight: concurrent first callers share one `whoami` / login. */
+  private pluginDeviceLoad: Promise<BotCredentials> | null = null;
+  private readonly backgroundSends = new Semaphore(BACKGROUND_SEND_CONCURRENCY);
   /** Memoised `getOracleSecretsKey` result (private JWK JSON). */
   private oracleSecretsKeyJson: string | null = null;
   private oracleSigningMnemonic: string | null = null;
@@ -1535,7 +1629,7 @@ export class MatrixGatewayDO
   }
 
   // -------------------------------------------------------------------------
-  // User snapshots (SQLite files as room media) and media downloads
+  // User snapshots (SQLite files as room media) and media event lookups
   // -------------------------------------------------------------------------
 
   async uploadUserSnapshotStream(
@@ -1648,105 +1742,28 @@ export class MatrixGatewayDO
   }
 
   /**
-   * A media message (`m.image` / `m.file` / …) for the attachments pipeline,
-   * as stored (see `mediaStream`). Null when the event is unknown or redacted.
+   * See `MatrixGatewayObject.eventMediaInfo`: the media event fetched and
+   * decrypted here, its file left on the homeserver for the caller to read.
    */
-  async downloadEventMediaStream(
+  async eventMediaInfo(
     roomId: string,
     eventId: string,
     opts: MediaDownloadOptions = {},
-  ): Promise<MediaStream | null> {
+  ): Promise<EventMediaInfo | null> {
     const bound = boundedSignal(
       opts.timeoutMs ?? MEDIA_DOWNLOAD_TIMEOUT_MS,
       opts.signal,
     );
-    let media: MediaStream | null;
     try {
-      // The SDK opens the download without a signal: race it, and release a
-      // stream that arrives after the bound.
-      media = await raceSignal(
-        this.mediaStream(roomId, eventId),
+      const raw = await raceSignal(
+        this.getEvent(roomId, eventId),
         bound.signal,
-        (late) => void late?.stream.cancel().catch(() => undefined),
+        () => undefined,
       );
-    } catch (err) {
-      bound.clear();
-      throw err;
-    }
-    if (!media) {
-      bound.clear();
-      return null;
-    }
-    return { ...media, stream: streamWithDeadline(media.stream, bound) };
-  }
-
-  /**
-   * Authenticated download of an `mxc://` URI as a stream
-   * (`/_matrix/client/v1/media/download`, legacy fallback on 404), bounded
-   * by `opts.timeoutMs` (default `MEDIA_DOWNLOAD_TIMEOUT_MS`) from the
-   * request to the last byte.
-   */
-  async downloadMxcMediaStream(
-    mxc: string,
-    opts: MediaDownloadOptions = {},
-  ): Promise<ReadableStream<Uint8Array>> {
-    const bound = boundedSignal(
-      opts.timeoutMs ?? MEDIA_DOWNLOAD_TIMEOUT_MS,
-      opts.signal,
-    );
-    try {
-      const body = await this.fetchMxc(mxc, bound.signal);
-      return streamWithDeadline(body, bound);
-    } catch (err) {
+      return raw ? mediaInfoOfEvent(JSON.parse(raw), eventId) : null;
+    } finally {
       bound.clear();
-      throw err;
-    }
-  }
-
-  private async fetchMxc(
-    mxc: string,
-    signal: AbortSignal,
-  ): Promise<ReadableStream<Uint8Array>> {
-    const client = await this.startedClient();
-    const token = client.getAccessToken();
-    const headers: Record<string, string> = token
-      ? { Authorization: `Bearer ${token}` }
-      : {};
-    const authed = client.mxcUrlToHttp(
-      mxc,
-      undefined,
-      undefined,
-      undefined,
-      false,
-      true,
-      true,
-    );
-    if (!authed) throw new Error(`MatrixGatewayDO: invalid mxc url ${mxc}`);
-    let res = await fetch(authed, { headers, signal });
-    if (res.status === 404) {
-      const legacy = client.mxcUrlToHttp(
-        mxc,
-        undefined,
-        undefined,
-        undefined,
-        false,
-        true,
-        false,
-      );
-      if (legacy) {
-        await res.body?.cancel().catch(() => undefined);
-        res = await fetch(legacy, { headers, signal });
-      }
-    }
-    if (!res.ok) {
-      await res.body?.cancel().catch(() => undefined);
-      throw new Error(
-        `MatrixGatewayDO: media download failed: ${res.status} ${res.statusText}`,
-      );
     }
-    if (!res.body)
-      throw new Error('MatrixGatewayDO: media download has no body');
-    return res.body;
   }
 
   // -------------------------------------------------------------------------
@@ -1801,13 +1818,31 @@ export class MatrixGatewayDO
   /**
    * See `MatrixGatewayObject.botCredentials`: a second password device with
    * NO crypto store, for plugins that drive a raw matrix-js-sdk client
-   * (editor, flows) — it must never be the gateway's own E2EE device, whose
-   * one-time keys and store are the SDK's. Its id is pinned in storage so a
-   * re-login (token rejected) keeps the same device. Cached per instance
-   * after one `whoami`.
+   * (editor, flows) and the user objects' media transfers — it must never
+   * be the gateway's own E2EE device, whose one-time keys and store are the
+   * SDK's. Its id is pinned in storage so a re-login keeps the same device.
+   * Cached per instance after one `whoami`; concurrent callers share one
+   * lookup (a login rotates the token, so a herd would invalidate each
+   * other's). `rejected` drops the cache only when it is the cached token.
    */
-  async botCredentials(): Promise<BotCredentials> {
+  async botCredentials(
+    opts: { rejected?: string } = {},
+  ): Promise<BotCredentials> {
+    if (opts.rejected && this.pluginDevice?.accessToken === opts.rejected) {
+      this.log(
+        'warn',
+        'plugin device token rejected by a caller; re-validating',
+      );
+      this.pluginDevice = null;
+    }
     if (this.pluginDevice) return this.pluginDevice;
+    this.pluginDeviceLoad ??= this.loadPluginDevice().finally(() => {
+      this.pluginDeviceLoad = null;
+    });
+    return this.pluginDeviceLoad;
+  }
+
+  private async loadPluginDevice(): Promise<BotCredentials> {
     const cfg = this.cfg();
     const stored = await this.ctx.storage.get<StoredDevice>(
       BOT_CLIENT_IDENTITY_KEY,
@@ -1841,6 +1876,33 @@ export class MatrixGatewayDO
     return this.pluginDevice;
   }
 
+  /**
+   * See `MatrixGatewayObject.sendEvent`: the SDK's send, behind the
+   * background lane for `priority: 'background'`, and never an attachment
+   * key into a room this gateway does not see as end-to-end encrypted.
+   */
+  override async sendEvent(
+    roomId: string,
+    type: string,
+    content: JsonString,
+    opts: { txnId?: string; priority?: 'interactive' | 'background' } = {},
+  ): Promise<string> {
+    if (carriesAttachmentKey(content) && !(await this.isRoomEncrypted(roomId)))
+      throw new Error(
+        `MatrixGatewayDO: refusing to send an encrypted attachment's key into ${roomId}, which is not end-to-end encrypted`,
+      );
+    const send = (): Promise<string> =>
+      super.sendEvent(
+        roomId,
+        type,
+        content,
+        opts.txnId ? { txnId: opts.txnId } : {},
+      );
+    return opts.priority === 'background'
+      ? this.backgroundSends.run(send)
+      : send();
+  }
+
   // -------------------------------------------------------------------------
   // Operator surface
   // -------------------------------------------------------------------------

package/src/matrix/ingest.ts

@@ -85,9 +85,10 @@ export interface IngestDeps {
    */
   userServerName(userDid: string): string | null;
   /**
-   * The bot's Matrix user id. Its first occurrence in a message is rewritten
-   * to `(USER MENTIONED YOU @AI_AGENT)` before the agent sees it, as the Node
-   * bridge does; omit to leave messages as sent.
+   * The bot's Matrix user id. Its own messages are dropped (`'own'`), and its
+   * first occurrence in a message is rewritten to `(USER MENTIONED YOU
+   * @AI_AGENT)` before the agent sees it, as the Node bridge does; omit to
+   * leave messages as sent.
    */
   botUserId?: string;
   debounceMs?: number;
@@ -210,6 +211,7 @@ export type OfferOutcome =
   | 'queued'
   | 'unverified'
   | 'empty'
+  | 'own'
   | 'unmapped'
   | 'foreign';
 
@@ -229,6 +231,13 @@ export class IngestPipeline {
    * for none); omitted, `canonicalAlias` is asked.
    */
   offer(msg: InboundMessage, alias?: string | null): OfferOutcome {
+    // The oracle's own events — its room mirrors and the channel files it
+    // posts in a session thread — are never a turn. The bot SDK already
+    // drops them before `onMessage`; this holds on every path that offers a
+    // message here (inbox replays included), and keeps a DID-shaped bot
+    // account from being attributed to itself.
+    if (this.deps.botUserId !== undefined && msg.sender === this.deps.botUserId)
+      return 'own';
     if (!msg.body.trim() && !msg.attachment) return 'empty';
     const attribution = attributeUser({
       alias: alias === undefined ? this.deps.canonicalAlias(msg.roomId) : alias,

package/src/matrix/media-deadline.ts

@@ -1,12 +1,9 @@
 /**
- * Deadlines for the gateway's media downloads. A homeserver that stops
- * sending mid-body would otherwise keep the reading side — a user object
- * assembling an attachment for a turn — waiting for as long as the
- * connection stays open.
- *
- * The bound covers the whole transfer: opening the download and every byte
- * of the body. When it passes (or the caller's own signal aborts), the
- * source is cancelled and the stream handed out errors with the reason.
+ * Deadlines for the gateway's media event lookups (`eventMediaInfo`). A
+ * homeserver that never answers would otherwise keep the asking side — a
+ * user object assembling an attachment for a turn — waiting for as long as
+ * the connection stays open. When the bound passes (or the caller's own
+ * signal aborts), the lookup rejects with the reason.
  */
 
 export interface BoundedSignal {
@@ -89,42 +86,3 @@ export function raceSignal<T>(
     );
   });
 }
-
-/**
- * `source` behind the deadline: the returned stream carries the same bytes,
- * and errors with the signal's reason (the source cancelled) when the bound
- * passes before the last byte. The timer is cleared once the transfer ends
- * either way, including when the reader cancels.
- */
-export function streamWithDeadline(
-  source: ReadableStream<Uint8Array>,
-  bound: BoundedSignal,
-): ReadableStream<Uint8Array> {
-  const { readable, writable } = new TransformStream<Uint8Array, Uint8Array>();
-  const writer = writable.getWriter();
-  const reader = source.getReader();
-  const stop = (reason: unknown): void => {
-    void writer.abort(reason).catch(() => undefined);
-    void reader.cancel(reason).catch(() => undefined);
-  };
-  const onAbort = (): void => stop(bound.signal.reason);
-  if (bound.signal.aborted) onAbort();
-  else bound.signal.addEventListener('abort', onAbort, { once: true });
-  void (async () => {
-    try {
-      for (;;) {
-        const { done, value } = await reader.read();
-        if (done || bound.signal.aborted) break;
-        await writer.write(value);
-      }
-      if (!bound.signal.aborted) await writer.close();
-    } catch (err) {
-      // The reader went away (cancelled) or the source failed: end both.
-      stop(err);
-    } finally {
-      bound.signal.removeEventListener('abort', onAbort);
-      bound.clear();
-    }
-  })();
-  return readable;
-}

package/src/plugins/attachments/attachments.plugin.ts

@@ -1,7 +1,7 @@
 /**
- * Attachments plugin — the agent-facing half of attachment payload
- * retention (`src/attachments/retention.ts`), Workers-only: the Node runtime
- * keeps every attachment inline for the life of a session.
+ * Attachments plugin — the agent-facing half of keeping attachment bytes
+ * out of storage (`src/attachments/retention.ts`), Workers-only: the Node
+ * runtime keeps every attachment inline for the life of a session.
  *
  * Contributes one request-time tool, `view_attachment`, and only on turns
  * whose session already has an offloaded payload (the host surface says so),

package/src/plugins/attachments/view-attachment-tool.ts

@@ -1,6 +1,7 @@
 /**
- * `view_attachment` — fetch an attachment of this session again after its
- * inline payload was offloaded (see `src/attachments/retention.ts`).
+ * `view_attachment` — fetch an attachment of this session again: its bytes
+ * are not stored with the conversation, the stored message holds a
+ * placeholder instead (see `src/attachments/retention.ts`).
  *
  * Two result shapes, decided by the host surface with the same routing as
  * the turn pipeline:
@@ -11,8 +12,9 @@
  *    OpenAI-compatible wire, so the tool returns a LangGraph `Command` that
  *    appends its tool message AND a human message holding the block — the
  *    same proven shape a fresh attachment turn uses. That message is tagged
- *    `lc_source: attachment_view`: transcripts hide it, retention treats it
- *    as part of the current user turn and offloads it again later.
+ *    `lc_source: attachment_view`: transcripts hide it, the checkpointer
+ *    stores it with the placeholder like any other, and the image recall
+ *    counts it with the user turn before it.
  */
 import { HumanMessage, ToolMessage } from '@langchain/core/messages';
 import { Command } from '@langchain/langgraph';

package/src/sqlite/inline-payloads.ts

@@ -0,0 +1,121 @@
+/**
+ * The checkpointer's storage form of a value: every human message that
+ * carries inline attachment bytes (base64 content blocks, see
+ * `src/attachments/retention.ts`) is replaced by its placeholder copy
+ * (`offloadInlinePayloads`), wherever it sits in the value.
+ *
+ * Every byte the saver writes passes through here: message rows
+ * (`encodeMessageRow`, which `put` and `appendTurnMessages` use), the
+ * checkpoint blob's other channel values and every pending write
+ * (`putWrites` — a node's output and LangGraph's `Send` packets, which
+ * carry a copy of the whole state, messages included). The graph's
+ * in-memory state keeps the real blocks: nothing here mutates its input,
+ * and a container is copied only when something inside it was replaced,
+ * so a value without inline payloads comes back as the same object.
+ *
+ * Only human messages are replaced: a tool or AI message that carries
+ * base64 (an MCP screenshot) is stored as it is, since nothing could bring
+ * its bytes back. The saver scans what it serializes for the payload text
+ * (`containsInlinePayload`) and logs a write that still holds one, so a
+ * shape this walk misses is visible.
+ */
+import { isBaseMessage } from '@langchain/core/messages';
+import { offloadInlinePayloads } from '../attachments/retention';
+
+/**
+ * How deep a value is searched. A `Send` packet holds the state, the state
+ * holds the message list, the list holds the message: four levels; the
+ * margin covers state channels that nest a little deeper.
+ */
+const MAX_DEPTH = 12;
+
+function isPlainObject(value: object): value is Record<string, unknown> {
+  const proto: unknown = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+/**
+ * A LangGraph `Send` packet (`lg_name: 'Send'`), the shape the serializer
+ * recognises (`serialization.ts` `_default`, `JsonPlusSerializer`).
+ */
+function isSendPacket(
+  value: object,
+): value is { lg_name: 'Send'; node: unknown; args: unknown } {
+  return Reflect.get(value, 'lg_name') === 'Send';
+}
+
+function strip(value: unknown, depth: number): unknown {
+  if (typeof value !== 'object' || value === null || depth > MAX_DEPTH)
+    return value;
+  if (isBaseMessage(value)) return offloadInlinePayloads(value) ?? value;
+  if (Array.isArray(value)) {
+    let out: unknown[] | undefined;
+    for (let i = 0; i < value.length; i++) {
+      const item: unknown = value[i];
+      const stripped = strip(item, depth + 1);
+      if (stripped === item) continue;
+      out ??= value.slice();
+      out[i] = stripped;
+    }
+    return out ?? value;
+  }
+  if (isSendPacket(value)) {
+    const args = strip(value.args, depth + 1);
+    if (args === value.args) return value;
+    // Serialized exactly like the `Send` it replaces: both serializers
+    // write `{ node, args }` (plus `timeout` when set) for this shape.
+    const timeout: unknown = Reflect.get(value, 'timeout');
+    return {
+      lg_name: 'Send',
+      node: value.node,
+      args,
+      ...(timeout !== undefined ? { timeout } : {}),
+    };
+  }
+  if (!isPlainObject(value)) return value;
+  let out: Record<string, unknown> | undefined;
+  for (const [key, item] of Object.entries(value)) {
+    const stripped = strip(item, depth + 1);
+    if (stripped === item) continue;
+    out ??= { ...value };
+    out[key] = stripped;
+  }
+  return out ?? value;
+}
+
+/**
+ * `value` as the checkpointer stores it: inline attachment payloads
+ * replaced by their placeholder (see the module comment). The same object
+ * when there is nothing to replace.
+ */
+export function withoutInlinePayloads(value: unknown): unknown {
+  return strip(value, 0);
+}
+
+/**
+ * The text every serialized inline payload block contains (`JSON.stringify`
+ * writes no spaces): what the stored-form checks and the one-time sweep of
+ * old rows look for. User text quoting it matches too, harmlessly.
+ */
+export const INLINE_PAYLOAD_NEEDLE = '"source_type":"base64"';
+
+const NEEDLE_BYTES = new TextEncoder().encode(INLINE_PAYLOAD_NEEDLE);
+
+/**
+ * Whether serialized bytes still contain an inline payload block: a shape
+ * `withoutInlinePayloads` does not reach (a plain `{ role, content }`
+ * object, a `Map` or class instance, a value nested deeper than
+ * `MAX_DEPTH`) or a non-human message carrying base64 (tool output, never
+ * stripped). One linear scan, no decoding.
+ */
+export function containsInlinePayload(bytes: Uint8Array): boolean {
+  const first = NEEDLE_BYTES[0]!;
+  const last = bytes.length - NEEDLE_BYTES.length;
+  for (let i = bytes.indexOf(first); i !== -1 && i <= last; ) {
+    let j = 1;
+    while (j < NEEDLE_BYTES.length && bytes[i + j] === NEEDLE_BYTES[j]) j++;
+    if (j === NEEDLE_BYTES.length) return true;
+    i = bytes.indexOf(first, i + 1);
+  }
+  return false;
+}