fix(sdk): recover chat transport when a restored session no longer exists (#3816)

## Summary

When a chat's restored session state points at a session that no longer
exists in the current environment — for example a `sessions` entry that
was persisted against a different trigger environment —
`useTriggerChatTransport` assumed the session was live and never created
a real one. The next message then failed with a 404 and the chat
couldn't send.

## Fix

`callWithAuthRetry` now treats a 404 from a session-PAT-authed call as
"this session doesn't exist here". After the existing 401/403 token
refresh, a 404 recreates the session via `startSession`, drops the stale
`lastEventId` resume cursor (it pointed at another environment's
stream), and retries the send once. When `startSession` isn't configured
the transport throws a clear message instead of a bare 404.

Author: ericallam

.changeset/chat-transport-recreate-missing-session.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/sdk": patch
+---
+
+`useTriggerChatTransport` now recovers when restored session state points at a session that no longer exists in the current environment

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

@@ -85,6 +85,19 @@ function isAuthError(error: unknown): boolean {
   return e.name === "TriggerApiError" && (e.status === 401 || e.status === 403);
 }
 
+/**
+ * Detect a 404 from a session-PAT-authed call — i.e. the session doesn't
+ * exist in the current environment. Happens when hydrated session state
+ * (the `sessions` option / a customer's persisted record) was created in a
+ * different trigger environment, or predates the upgrade to the sessions
+ * model, so there's no real Session row behind the cached PAT.
+ */
+function isSessionNotFoundError(error: unknown): boolean {
+  if (error === null || typeof error !== "object") return false;
+  const e = error as { name?: string; status?: number };
+  return e.name === "TriggerApiError" && e.status === 404;
+}
+
 /**
  * Parses an SSE byte/text stream of `data: <UIMessageChunk JSON>\n\n`
  * frames back into `UIMessageChunk` objects. Used by the handover
@@ -1099,17 +1112,66 @@ export class TriggerChatTransport implements ChatTransport<UIMessage> {
     state: ChatSessionState,
     op: (token: string) => Promise<void>
   ): Promise<void> {
+    // 1) Try with the current PAT.
     try {
       await op(state.publicAccessToken);
       return;
     } catch (err) {
+      if (isSessionNotFoundError(err)) {
+        // The cached PAT authenticated but the session doesn't exist here —
+        // recreate it and retry.
+        await this.recreateSession(chatId, state);
+        await op(state.publicAccessToken);
+        return;
+      }
       if (!isAuthError(err)) throw err;
     }
 
+    // 2) Auth error — refresh the PAT and retry. (A cross-environment cached
+    //    PAT fails auth here because it was signed by another env's keys.)
     const fresh = await this.resolveAccessToken({ chatId });
     state.publicAccessToken = fresh;
     this.notifySessionChange(chatId, state);
-    await op(fresh);
+    try {
+      await op(fresh);
+      return;
+    } catch (err) {
+      if (!isSessionNotFoundError(err)) throw err;
+    }
+
+    // 3) PAT is now valid but the session still 404s — the hydrated session
+    //    state is stale (created in a different environment, or before the
+    //    sessions upgrade). Recreate the session and retry once.
+    await this.recreateSession(chatId, state);
+    await op(state.publicAccessToken);
+  }
+
+  /**
+   * Repair a stale/phantom hydrated session. The cached state pointed at a
+   * session that doesn't exist in the current environment (404) — typically
+   * because it was persisted against a different trigger environment, or
+   * predates the upgrade to the sessions model. Recreate the session via
+   * `startSession` and overwrite the cached state **in place** so callers
+   * holding a reference (e.g. `sendMessages` before it opens the SSE) pick
+   * up the new PAT. The stale `lastEventId` resume cursor is dropped — it
+   * pointed at a different environment's stream.
+   */
+  private async recreateSession(chatId: string, state: ChatSessionState): Promise<void> {
+    if (!this.resolveStartSession) {
+      throw new Error(
+        "TriggerChatTransport: session not found and no `startSession` configured to recreate it. The stored session state for this chat may be stale (e.g. created in a different environment) — provide `startSession` or clear the stored session so a fresh one can be created."
+      );
+    }
+    const { publicAccessToken } = await this.resolveStartSession({
+      taskId: this.taskId,
+      chatId,
+      clientData: (this.defaultMetadata ?? {}) as Record<string, unknown>,
+    });
+    state.publicAccessToken = publicAccessToken;
+    state.lastEventId = undefined;
+    state.isStreaming = false;
+    this.sessions.set(chatId, state);
+    this.notifySessionChange(chatId, state);
   }
 
   /**