fix(think): preserve attachment fetchMetadata through messenger serialization (#1833) (#1839)

serializableMessengerEvent stripped everything except id/mediaType/name/
size/text/url from attachments before handing events to sub-agent DOs,
discarding fetch, raw, and the platform identifier. For adapters like
@chat-adapter/telegram the file id lives only in fetchMetadata.fileId and
the top-level id is never set, so attachments were irretrievable inside a
sub-agent.

Add a serialization-safe fetchMetadata field to MessengerAttachment,
preserve it through serializableMessengerEvent, and carry it through
toMessengerAttachment while backfilling the top-level id from a known
metadata key (id/fileId/mediaId/fileUniqueId).

Co-authored-by: Sunil Pai <18808+threepointone@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: threepointone

.changeset/think-messenger-attachment-fetchmetadata.md

@@ -0,0 +1,11 @@
+---
+"@cloudflare/think": patch
+---
+
+Preserve attachment `fetchMetadata` through messenger event serialization so sub-agents can re-fetch files.
+
+When a conversation resolver routes a thread to a sub-agent Durable Object, the messenger event is run through `serializableMessengerEvent()` before crossing the DO boundary. That serialization previously dropped everything except `id`, `mediaType`, `name`, `size`, `text`, and `url` from each attachment — discarding `fetch`, `raw`, and (for adapters that store their platform identifier there) the only remaining handle on the file.
+
+For adapters like `@chat-adapter/telegram`, the file identifier lives exclusively in `fetchMetadata.fileId` and the top-level `id` is never populated, so photos became irretrievable inside a sub-agent (`attachment.id` and `attachment.fetch` were both missing).
+
+`MessengerAttachment` now carries a serialization-safe `fetchMetadata?: Record<string, string>` field that survives the sub-agent hop. `toMessengerAttachment()` copies `fetchMetadata` from the underlying Chat SDK attachment and backfills the top-level `id` from a known metadata key (`id`, `fileId`, `mediaId`, `fileUniqueId`) when the adapter doesn't set one. A downstream agent can use `fetchMetadata` together with the adapter's `rehydrateAttachment()` to reconstruct the download closure.

packages/think/src/messengers/chat-sdk.ts

@@ -740,6 +740,7 @@ export function toMessengerAuthor(author: ChatAuthor): MessengerAuthor {
 export function toMessengerAttachment(
   attachment: ChatAttachment
 ): MessengerAttachment {
+  const fetchMetadata = attachment.fetchMetadata;
   return {
     fetch: attachment.fetchData
       ? async () => {
@@ -754,6 +755,8 @@ export function toMessengerAttachment(
           return copy instanceof ArrayBuffer ? copy : new ArrayBuffer(0);
         }
       : undefined,
+    fetchMetadata: fetchMetadata ? { ...fetchMetadata } : undefined,
+    id: identifierFromFetchMetadata(fetchMetadata),
     mediaType: attachment.mimeType,
     name: attachment.name,
     raw: attachment,
@@ -762,6 +765,29 @@ export function toMessengerAttachment(
   };
 }
 
+const FETCH_METADATA_ID_KEYS = ["id", "fileId", "mediaId", "fileUniqueId"];
+
+/**
+ * Best-effort top-level id for an attachment whose adapter only records its
+ * identifier in `fetchMetadata` (e.g. Telegram `fileId`). This keeps id-based
+ * consumers working without per-adapter knowledge, while the full
+ * `fetchMetadata` is preserved verbatim for precise re-fetching.
+ */
+function identifierFromFetchMetadata(
+  fetchMetadata: Record<string, string> | undefined
+): string | undefined {
+  if (!fetchMetadata) {
+    return undefined;
+  }
+  for (const key of FETCH_METADATA_ID_KEYS) {
+    const value = fetchMetadata[key];
+    if (typeof value === "string" && value.length > 0) {
+      return value;
+    }
+  }
+  return undefined;
+}
+
 function stableNamePart(value: string): string {
   const safe = value.replace(/[^a-zA-Z0-9:_-]/g, "_");
   if (safe.length <= 80) {

packages/think/src/messengers/events.ts

@@ -18,6 +18,14 @@ export interface MessengerAuthor {
 export interface MessengerAttachment {
   data?: ArrayBuffer;
   fetch?: () => Promise<ArrayBuffer>;
+  /**
+   * Platform-specific metadata needed to re-fetch the attachment after the
+   * event has been serialized (e.g. across a sub-agent Durable Object hop).
+   * Adapters store identifiers here — Telegram `fileId`, WhatsApp `mediaId`,
+   * etc. — that survive serialization even when `fetch`, `data`, and `raw`
+   * cannot, so a downstream agent can reconstruct the download closure.
+   */
+  fetchMetadata?: Record<string, string>;
   id?: string;
   mediaType?: string;
   name?: string;
@@ -114,6 +122,9 @@ export function serializableMessengerEvent(
     message: event.message
       ? {
           attachments: event.message.attachments.map((attachment) => ({
+            fetchMetadata: attachment.fetchMetadata
+              ? { ...attachment.fetchMetadata }
+              : undefined,
             id: attachment.id,
             mediaType: attachment.mediaType,
             name: attachment.name,

packages/think/src/tests/messengers.test.ts

@@ -26,6 +26,7 @@ import {
   TextStreamCallback,
   textDeltaFromStreamChunk,
   ThinkMessengerRuntime,
+  toMessengerAttachment,
   toMessengerUserMessage,
   type MessengerEvent,
   type MessengerThinkHost
@@ -349,6 +350,7 @@ describe("think messengers core", () => {
           {
             data: new ArrayBuffer(1),
             fetch: () => Promise.resolve(new ArrayBuffer(1)),
+            fetchMetadata: { fileId: "AgACAgIfileid" },
             mediaType: "text/plain",
             name: "notes.txt",
             raw: { providerFile: true },
@@ -372,9 +374,41 @@ describe("think messengers core", () => {
     expect(cloned.event.message.attachments[0].raw).toBeUndefined();
     expect(cloned.event.message.attachments[0].data).toBeUndefined();
     expect(cloned.event.message.attachments[0].fetch).toBeUndefined();
+    expect(cloned.event.message.attachments[0].fetchMetadata).toEqual({
+      fileId: "AgACAgIfileid"
+    });
     expect(cloned.thread._type).toBe("chat:Thread");
   });
 
+  it("preserves attachment fetchMetadata and backfills id when converting", () => {
+    const attachment = toMessengerAttachment({
+      fetchData: () => Promise.resolve(Buffer.from("hello")),
+      fetchMetadata: { fileId: "AgACAgItelegram" },
+      mimeType: "image/jpeg",
+      name: "photo.jpg",
+      size: 1024,
+      type: "image",
+      url: "https://example.com/photo.jpg"
+    });
+
+    expect(attachment.fetchMetadata).toEqual({ fileId: "AgACAgItelegram" });
+    expect(attachment.id).toBe("AgACAgItelegram");
+    expect(attachment.raw).toBeDefined();
+  });
+
+  it("leaves attachment id undefined when fetchMetadata has no known id key", () => {
+    const attachment = toMessengerAttachment({
+      fetchMetadata: { region: "us-east" },
+      mimeType: "image/jpeg",
+      name: "photo.jpg",
+      type: "image",
+      url: "https://example.com/photo.jpg"
+    });
+
+    expect(attachment.fetchMetadata).toEqual({ region: "us-east" });
+    expect(attachment.id).toBeUndefined();
+  });
+
   it("parses and classifies messenger recovery snapshots", () => {
     const accepted = messengerReplySnapshot("accepted", baseEvent, {
       _type: "chat:Thread",