feat(sdk): route chat.agent transcript persistence through a TranscriptStorage seam

Introduces the TranscriptStorage interface (load/save over id-addressed changes: put, remove, truncateAfter, state) and makes the built-in snapshot writer its default implementation. The runtime keeps a shadow of the transcript it last saved and hands the storage the diff after every turn, failed turn and history-changing action, together with the stream cursors the next boot resumes from. The default storage reduces each changeset onto an in-memory copy and rewrites the blob as version 2, so a turn still costs one PUT and no GET, and the boot read goes through load.

The snapshot read/write helpers move to their own module so the storage can import them without a cycle; the test seams keep their import path. The mock chat agent harness now reports version 2 snapshots and accepts either version as a seed.

Author: ericallam

apps/webapp/test/chat-snapshot-integration.test.ts

@@ -1,27 +1,8 @@
-// Plan F.3: integration test that round-trips a `ChatSnapshotV1` blob
-// through the SDK's snapshot helpers + a real MinIO backing store. Mirrors
-// the testcontainer pattern from `objectStore.test.ts`.
-//
-// What this verifies end-to-end:
-//   - SDK's `writeChatSnapshot` calls `apiClient.createUploadPayloadUrl`
-//     to mint a presigned PUT, then PUTs JSON to it.
-//   - SDK's `readChatSnapshot` calls `apiClient.getPayloadUrl` to mint a
-//     presigned GET, then fetches and parses.
-//   - The webapp's `generatePresignedUrl` produces URLs MinIO accepts.
-//   - The blob round-trips with `version: 1` shape preserved.
-//   - 404 (no snapshot for a fresh session) returns `undefined`, not an
-//     error.
-//
-// This is the integration safety net behind the unit tests in
-// `packages/trigger-sdk/test/chat-snapshot.test.ts` — those tests mock
-// `fetch`; this one drives a real S3-compatible backend.
-
 import { postgresAndMinioTest } from "@internal/testcontainers";
-import { apiClientManager } from "@trigger.dev/core/v3";
+import { apiClientManager, type TranscriptSnapshotV2 } from "@trigger.dev/core/v3";
 import {
   __readChatSnapshotProductionPathForTests as readChatSnapshot,
   __writeChatSnapshotProductionPathForTests as writeChatSnapshot,
-  type ChatSnapshotV1,
 } from "@trigger.dev/sdk/ai";
 import type { UIMessage } from "ai";
 import { afterEach, describe, expect, vi } from "vitest";
@@ -35,22 +16,24 @@ vi.setConfig({ testTimeout: 60_000 });
 
 function makeSnapshot(
   opts: { messages?: UIMessage[]; lastOutEventId?: string } = {}
-): ChatSnapshotV1 {
+): TranscriptSnapshotV2 {
+  const messages = opts.messages ?? [
+    {
+      id: "u-1",
+      role: "user",
+      parts: [{ type: "text", text: "hello" }],
+    },
+    {
+      id: "a-1",
+      role: "assistant",
+      parts: [{ type: "text", text: "world" }],
+    },
+  ];
   return {
-    version: 1,
+    version: 2,
     savedAt: 1_700_000_000_000,
-    messages: opts.messages ?? [
-      {
-        id: "u-1",
-        role: "user",
-        parts: [{ type: "text", text: "hello" }],
-      },
-      {
-        id: "a-1",
-        role: "assistant",
-        parts: [{ type: "text", text: "world" }],
-      },
-    ],
+    messages: messages.map((message) => ({ id: message.id, final: true, message })),
+    state: null,
     lastOutEventId: opts.lastOutEventId ?? "evt-42",
   };
 }

apps/webapp/test/replay-after-crash.test.ts

@@ -24,11 +24,10 @@
 // through it), even though the replay path itself doesn't read from S3.
 
 import { postgresAndMinioTest } from "@internal/testcontainers";
-import { apiClientManager } from "@trigger.dev/core/v3";
+import { apiClientManager, type TranscriptSnapshotV2 } from "@trigger.dev/core/v3";
 import {
   __readChatSnapshotProductionPathForTests as readChatSnapshot,
   __replaySessionOutTailProductionPathForTests as replaySessionOutTail,
-  type ChatSnapshotV1,
 } from "@trigger.dev/sdk/ai";
 import type { UIMessageChunk } from "ai";
 import { afterEach, describe, expect, vi } from "vitest";
@@ -265,13 +264,26 @@ describe("replay after crash (MinIO + SDK helpers)", () => {
 
       // Pre-write a snapshot to MinIO via real apiClient stub.
       const sessionId = "sess_merge_round_trip";
-      const snapshot: ChatSnapshotV1 = {
-        version: 1,
+      const snapshot: TranscriptSnapshotV2 = {
+        version: 2,
         savedAt: 1_700_000_000_000,
         messages: [
-          { id: "u-1", role: "user", parts: [{ type: "text", text: "hi" }] },
-          { id: "a-1", role: "assistant", parts: [{ type: "text", text: "stale-assistant" }] },
+          {
+            id: "u-1",
+            final: true,
+            message: { id: "u-1", role: "user", parts: [{ type: "text", text: "hi" }] },
+          },
+          {
+            id: "a-1",
+            final: true,
+            message: {
+              id: "a-1",
+              role: "assistant",
+              parts: [{ type: "text", text: "stale-assistant" }],
+            },
+          },
         ],
+        state: null,
         lastOutEventId: "evt-prev",
       };