fix(webapp,sdk): keep chat.agent snapshots on one object store

When a webapp is configured with both a default object store
(`OBJECT_STORE_BASE_URL`) and a named protocol provider
(`OBJECT_STORE_DEFAULT_PROTOCOL=s3`), chat.agent session snapshot writes
landed in the named provider but reads fell through to the default — so
the recovery boot couldn't find the snapshot it had just written.

After a mid-stream cancel, the missing snapshot triggered a fallback
replay path that dropped the user's follow-up message, leaving the chat
stuck in `submitted` indefinitely.

Fix:
- New `/api/v1/sessions/:id/snapshot-url` route handles PUT + GET
  symmetrically — both prefix unprefixed keys with
  `OBJECT_STORE_DEFAULT_PROTOCOL` so they always round-trip through the
  same store.
- `Session.chatSnapshotStoragePath` persists the resolved URI on first
  write so future protocol changes don't strand existing snapshots.
  Reads prefer the stored URI and fall back to the computed default for
  pre-column sessions.
- SDK calls `createChatSnapshotUploadUrl` / `getChatSnapshotUrl`; the
  generic v1/v2 packets endpoints are unchanged.

Author: ericallam

.server-changes/chat-snapshot-default-protocol.md

@@ -0,0 +1,8 @@
+---
+area: webapp
+type: fix
+---
+
+Pin chat.agent session snapshots to a single object store so writes and reads
+always round-trip through the same provider when `OBJECT_STORE_DEFAULT_PROTOCOL`
+is set.

apps/webapp/app/routes/api.v1.sessions.$sessionId.snapshot-url.ts

@@ -0,0 +1,99 @@
+import type { ActionFunctionArgs } from "@remix-run/server-runtime";
+import { json } from "@remix-run/server-runtime";
+import { z } from "zod";
+import { $replica, prisma } from "~/db.server";
+import { env } from "~/env.server";
+import { authenticateApiRequest } from "~/services/apiAuth.server";
+import { resolveSessionByIdOrExternalId } from "~/services/realtime/sessions.server";
+import { createLoaderApiRoute } from "~/services/routeBuilders/apiBuilder.server";
+import { generatePresignedUrl } from "~/v3/objectStore.server";
+
+const ParamsSchema = z.object({
+  sessionId: z.string(),
+});
+
+// Canonical key for new sessions, prefixed with the default protocol so
+// PUT/GET resolve to the same store on multi-provider deployments.
+function defaultSnapshotKey(sessionId: string): string {
+  const path = `sessions/${sessionId}/snapshot.json`;
+  const protocol = env.OBJECT_STORE_DEFAULT_PROTOCOL;
+  return protocol ? `${protocol}://${path}` : path;
+}
+
+export async function action({ request, params }: ActionFunctionArgs) {
+  if (request.method.toUpperCase() !== "PUT") {
+    return { status: 405, body: "Method Not Allowed" };
+  }
+
+  const auth = await authenticateApiRequest(request);
+  if (!auth) {
+    return json({ error: "Invalid or Missing API key" }, { status: 401 });
+  }
+
+  const parsed = ParamsSchema.parse(params);
+  const session = await resolveSessionByIdOrExternalId(
+    $replica,
+    auth.environment.id,
+    parsed.sessionId
+  );
+  if (!session) {
+    return json({ error: "Session not found" }, { status: 404 });
+  }
+
+  // Reuse the stored path on subsequent writes; persist on first write so
+  // future default-protocol changes don't strand existing snapshots.
+  const key = session.chatSnapshotStoragePath ?? defaultSnapshotKey(parsed.sessionId);
+
+  const signed = await generatePresignedUrl(
+    auth.environment.project.externalRef,
+    auth.environment.slug,
+    key,
+    "PUT"
+  );
+  if (!signed.success) {
+    return json({ error: `Failed to generate presigned URL: ${signed.error}` }, { status: 500 });
+  }
+
+  if (session.chatSnapshotStoragePath === null) {
+    await prisma.session
+      .updateMany({
+        where: { id: session.id, chatSnapshotStoragePath: null },
+        data: { chatSnapshotStoragePath: key },
+      })
+      .catch(() => {
+        // Best-effort; concurrent writers may have already set it.
+      });
+  }
+
+  return json({ presignedUrl: signed.url });
+}
+
+export const loader = createLoaderApiRoute(
+  {
+    params: ParamsSchema,
+    allowJWT: true,
+    corsStrategy: "all",
+    findResource: async (params, auth) =>
+      resolveSessionByIdOrExternalId($replica, auth.environment.id, params.sessionId),
+  },
+  async ({ params, authentication, resource: session }) => {
+    if (!session) {
+      return json({ error: "Session not found" }, { status: 404 });
+    }
+
+    // Stored path wins; fall back to computed default for pre-column sessions.
+    const key = session.chatSnapshotStoragePath ?? defaultSnapshotKey(params.sessionId);
+
+    const signed = await generatePresignedUrl(
+      authentication.environment.project.externalRef,
+      authentication.environment.slug,
+      key,
+      "GET"
+    );
+    if (!signed.success) {
+      return json({ error: `Failed to generate presigned URL: ${signed.error}` }, { status: 500 });
+    }
+
+    return json({ presignedUrl: signed.url });
+  }
+);

apps/webapp/app/services/apiRateLimit.server.ts

@@ -70,6 +70,7 @@ export const apiRateLimiter = authorizationRateLimitMiddleware({
     // customer-facing surface so customer rate limits shouldn't apply.
     /^\/api\/v1\/packets\//,
     /^\/api\/v2\/packets\//,
+    /^\/api\/v1\/sessions\/[^\/]+\/snapshot-url$/,
   ],
   log: {
     rejections: env.API_RATE_LIMIT_REJECTION_LOGS_ENABLED === "1",

internal-packages/database/prisma/migrations/20260520170000_add_session_chat_snapshot_storage_path/migration.sql

@@ -0,0 +1 @@
+ALTER TABLE "Session" ADD COLUMN IF NOT EXISTS "chatSnapshotStoragePath" TEXT;

internal-packages/database/prisma/schema.prisma

@@ -830,6 +830,11 @@ model Session {
   /// (OSS, or pre-backfill); reads fall back to the global basin.
   streamBasinName String?
 
+  /// Storage URI (with protocol prefix) for this session's chat.agent
+  /// snapshot blob. Set on first snapshot write. Null = pre-column session,
+  /// fall back to computed default path.
+  chatSnapshotStoragePath String?
+
   runs SessionRun[]
 
   /// Idempotency: `(env, externalId)` uniquely identifies a session.

packages/core/src/v3/apiClient/index.ts

@@ -602,6 +602,32 @@ export class ApiClient {
     );
   }
 
+  /** Presigned PUT URL for a `chat.agent` session snapshot. */
+  createChatSnapshotUploadUrl(sessionId: string, requestOptions?: ZodFetchOptions) {
+    return zodfetch(
+      CreateUploadPayloadUrlResponseBody,
+      `${this.baseUrl}/api/v1/sessions/${encodeURIComponent(sessionId)}/snapshot-url`,
+      {
+        method: "PUT",
+        headers: this.#getHeaders(false),
+      },
+      mergeRequestOptions(this.defaultRequestOptions, requestOptions)
+    );
+  }
+
+  /** Presigned GET URL for a `chat.agent` session snapshot. */
+  getChatSnapshotUrl(sessionId: string, requestOptions?: ZodFetchOptions) {
+    return zodfetch(
+      CreateUploadPayloadUrlResponseBody,
+      `${this.baseUrl}/api/v1/sessions/${encodeURIComponent(sessionId)}/snapshot-url`,
+      {
+        method: "GET",
+        headers: this.#getHeaders(false),
+      },
+      mergeRequestOptions(this.defaultRequestOptions, requestOptions)
+    );
+  }
+
   retrieveRun(runId: string, requestOptions?: ZodFetchOptions) {
     return zodfetch(
       RetrieveRunResponse,

packages/trigger-sdk/src/v3/ai.ts

@@ -219,20 +219,6 @@ async function findLatestSessionInCursor(
  */
 export type { ChatSnapshotV1 } from "@trigger.dev/core/v3";
 
-/**
- * S3 key suffix for a session's snapshot blob. The webapp's presigned-URL
- * routes prefix this with `packets/{projectRef}/{envSlug}/` server-side, so
- * the final S3 key lands at
- * `packets/{projectRef}/{envSlug}/sessions/{sessionId}/snapshot.json`.
- *
- * Stable per session: the friendlyId persists across `chat.requestUpgrade`
- * continuations and idle-suspend restarts.
- * @internal
- */
-function snapshotFilename(sessionId: string): string {
-  return `sessions/${sessionId}/snapshot.json`;
-}
-
 /**
  * Test-only override hook — `mockChatAgent` installs a fake to return
  * synthetic snapshots without hitting S3. Mirrors the `__set*ImplForTests`
@@ -285,7 +271,7 @@ async function readChatSnapshot<TUIMessage extends UIMessage>(
   const apiClient = apiClientManager.clientOrThrow();
   let presignedUrl: string;
   try {
-    const resp = await apiClient.getPayloadUrl(snapshotFilename(sessionId));
+    const resp = await apiClient.getChatSnapshotUrl(sessionId);
     presignedUrl = resp.presignedUrl;
   } catch (error) {
     logger.warn("chat.agent: snapshot presign (read) failed; continuing without snapshot", {
@@ -360,7 +346,7 @@ async function writeChatSnapshot<TUIMessage extends UIMessage>(
   const apiClient = apiClientManager.clientOrThrow();
   let presignedUrl: string;
   try {
-    const resp = await apiClient.createUploadPayloadUrl(snapshotFilename(sessionId));
+    const resp = await apiClient.createChatSnapshotUploadUrl(sessionId);
     presignedUrl = resp.presignedUrl;
   } catch (error) {
     logger.warn("chat.agent: snapshot presign (write) failed; next run will replay further", {

packages/trigger-sdk/test/chat-snapshot.test.ts

@@ -34,28 +34,27 @@ function buildSnapshot(count = 1): ChatSnapshotV1 {
 
 /**
  * Stub `apiClientManager.clientOrThrow()` so the helpers see a fake API
- * client whose `getPayloadUrl` / `createUploadPayloadUrl` resolve with the
- * presigned URLs the test wants. Returns spies for assertion.
+ * client whose `getChatSnapshotUrl` / `createChatSnapshotUploadUrl` resolve
+ * with the presigned URLs the test wants. Returns spies for assertion.
  */
 function stubApiClient(opts: {
-  getPayloadUrl?: (filename: string) => Promise<{ presignedUrl: string }>;
-  createUploadPayloadUrl?: (filename: string) => Promise<{ presignedUrl: string }>;
+  getChatSnapshotUrl?: (sessionId: string) => Promise<{ presignedUrl: string }>;
+  createChatSnapshotUploadUrl?: (sessionId: string) => Promise<{ presignedUrl: string }>;
 }) {
-  const getPayloadUrl = vi.fn(
-    opts.getPayloadUrl ?? (async (_filename: string) => ({ presignedUrl: "https://example.invalid/get" }))
+  const getChatSnapshotUrl = vi.fn(
+    opts.getChatSnapshotUrl ??
+      (async (_sessionId: string) => ({ presignedUrl: "https://example.invalid/get" }))
   );
-  const createUploadPayloadUrl = vi.fn(
-    opts.createUploadPayloadUrl ??
-      (async (_filename: string) => ({ presignedUrl: "https://example.invalid/put" }))
+  const createChatSnapshotUploadUrl = vi.fn(
+    opts.createChatSnapshotUploadUrl ??
+      (async (_sessionId: string) => ({ presignedUrl: "https://example.invalid/put" }))
   );
   const fakeClient = {
-    getPayloadUrl,
-    createUploadPayloadUrl,
+    getChatSnapshotUrl,
+    createChatSnapshotUploadUrl,
   };
-  vi.spyOn(apiClientManager, "clientOrThrow").mockReturnValue(
-    fakeClient as never
-  );
-  return { getPayloadUrl, createUploadPayloadUrl };
+  vi.spyOn(apiClientManager, "clientOrThrow").mockReturnValue(fakeClient as never);
+  return { getChatSnapshotUrl, createChatSnapshotUploadUrl };
 }
 
 /**
@@ -87,7 +86,7 @@ describe("chat snapshot helpers", () => {
 
   describe("readChatSnapshot", () => {
     it("returns the snapshot on a successful GET", async () => {
-      const { getPayloadUrl } = stubApiClient({});
+      const { getChatSnapshotUrl } = stubApiClient({});
       const snapshot = buildSnapshot(2);
       stubFetch(async () =>
         new Response(JSON.stringify(snapshot), {
@@ -97,7 +96,7 @@ describe("chat snapshot helpers", () => {
       );
 
       const result = await readChatSnapshot("session-1");
-      expect(getPayloadUrl).toHaveBeenCalledWith("sessions/session-1/snapshot.json");
+      expect(getChatSnapshotUrl).toHaveBeenCalledWith("session-1");
       expect(result).toMatchObject({
         version: 1,
         messages: snapshot.messages,
@@ -177,7 +176,7 @@ describe("chat snapshot helpers", () => {
 
     it("returns undefined when presign call fails", async () => {
       stubApiClient({
-        getPayloadUrl: async () => {
+        getChatSnapshotUrl: async () => {
           throw new Error("presign denied");
         },
       });
@@ -202,13 +201,13 @@ describe("chat snapshot helpers", () => {
 
   describe("writeChatSnapshot", () => {
     it("PUTs the snapshot JSON to the presigned URL", async () => {
-      const { createUploadPayloadUrl } = stubApiClient({});
+      const { createChatSnapshotUploadUrl } = stubApiClient({});
       const fetchSpy = stubFetch(async () => new Response(null, { status: 200 }));
 
       const snapshot = buildSnapshot(3);
       await writeChatSnapshot("session-2", snapshot);
 
-      expect(createUploadPayloadUrl).toHaveBeenCalledWith("sessions/session-2/snapshot.json");
+      expect(createChatSnapshotUploadUrl).toHaveBeenCalledWith("session-2");
       expect(fetchSpy).toHaveBeenCalledOnce();
       const [url, init] = fetchSpy.mock.calls[0]!;
       expect(url).toBe("https://example.invalid/put");
@@ -239,7 +238,7 @@ describe("chat snapshot helpers", () => {
 
     it("returns without throwing when presign fails (warns)", async () => {
       stubApiClient({
-        createUploadPayloadUrl: async () => {
+        createChatSnapshotUploadUrl: async () => {
           throw new Error("presign denied");
         },
       });
@@ -250,29 +249,28 @@ describe("chat snapshot helpers", () => {
       expect(fetchSpy).not.toHaveBeenCalled();
     });
 
-    it("uses the same `snapshotFilename(sessionId)` convention as the read path", async () => {
-      // Round-trip check: read and write target the same key for a given
-      // sessionId. The runtime relies on this to make read-after-write
-      // coherent on subsequent boots.
-      const { getPayloadUrl } = stubApiClient({
-        getPayloadUrl: async () => ({ presignedUrl: "https://example.invalid/get" }),
+    it("addresses reads and writes by the same sessionId", async () => {
+      // Round-trip check: both presign methods receive the same sessionId.
+      // The canonical key (`sessions/{id}/snapshot.json`) lives server-side
+      // now, so the SDK has no key string to compare — sessionId equality
+      // is the SDK-visible invariant.
+      const { getChatSnapshotUrl } = stubApiClient({
+        getChatSnapshotUrl: async () => ({ presignedUrl: "https://example.invalid/get" }),
       });
       stubFetch(async () => new Response(null, { status: 404 }));
 
-      // Trigger a read.
       await readChatSnapshot("round-trip-session");
-      const [readKey] = getPayloadUrl.mock.calls[0]!;
+      const [readArg] = getChatSnapshotUrl.mock.calls[0]!;
 
-      // Trigger a write to the same session.
-      const { createUploadPayloadUrl } = stubApiClient({
-        createUploadPayloadUrl: async () => ({ presignedUrl: "https://example.invalid/put" }),
+      const { createChatSnapshotUploadUrl } = stubApiClient({
+        createChatSnapshotUploadUrl: async () => ({ presignedUrl: "https://example.invalid/put" }),
       });
       stubFetch(async () => new Response(null, { status: 200 }));
       await writeChatSnapshot("round-trip-session", buildSnapshot());
-      const [writeKey] = createUploadPayloadUrl.mock.calls[0]!;
+      const [writeArg] = createChatSnapshotUploadUrl.mock.calls[0]!;
 
-      expect(readKey).toBe(writeKey);
-      expect(readKey).toBe("sessions/round-trip-session/snapshot.json");
+      expect(readArg).toBe(writeArg);
+      expect(readArg).toBe("round-trip-session");
     });
   });
 });