feat(core,sdk,webapp): a pinned chat session follows its pin

Deciding when to call chat.requestUpgrade() was entirely hand-written: thread a
build id through clientData, stash it with chat.local in onBoot, compare it in
onTurnStart. Both documented recipes were that dance, and the docs implied version
skew protection already covered it. It did not — re-pinning a session only
affected the NEXT run, so a live agent kept answering on the old build until it
happened to end.

A pinned session now hands over at the next turn boundary when its stored
externalDeploymentId stops naming the deployment the run is on. The comparison is
self-clearing: the successor runs under that id, so it never re-fires. Opt one
agent out with versionSkew: 'hold'.

Two cases never fire, and the second is load-bearing rather than defensive: an
unpinned session has nothing to compare, and a session using lockToVersion would
hand over, land on the same locked version and repeat forever, because
lockToVersion outranks the external id and requestUpgrade cannot escape it.

A handoff onto a deployment that has not landed parks the successor, which used to
leave the chat silent — swapSessionRun computed pendingVersion and the
end-and-continue route discarded it. The run now writes a pending-version control
record before exiting, and the transport surfaces it as the existing
run-pending-version event with source 'upgrade', so the handler the docs already
prescribe covers this case with no new client code. Manual requestUpgrade gets the
same signal.

Also corrects two docs claims: that skew protection made the upgrade recipe
unnecessary, and that a continuation starts on the latest version regardless of
the session's pin.

Author: 0ski

.changeset/chat-agent-follows-its-pin.md

@@ -0,0 +1,6 @@
+---
+"@trigger.dev/core": patch
+"@trigger.dev/sdk": patch
+---
+
+A pinned chat session now follows its pin on its own: when your app redeploys and re-pins the session, the agent hands the conversation over at the next turn boundary instead of the new pin only applying to the next run. This replaces writing that yourself with `clientData` and `chat.requestUpgrade()`. Set `versionSkew: "hold"` on an agent that should stay put. If a handoff lands on a deployment that hasn't finished building, the transport emits `run-pending-version` with `source: "upgrade"`.

apps/webapp/app/routes/api.v1.sessions.$session.end-and-continue.ts

@@ -134,6 +134,7 @@ const { action, loader } = createActionApiRoute(
       const responseBody: EndAndContinueSessionResponseBody = {
         runId: run?.friendlyId ?? result.runId,
         swapped: result.swapped,
+        pendingVersion: result.pendingVersion,
       };
       return json<EndAndContinueSessionResponseBody>(responseBody);
     } catch (error) {

apps/webapp/test/sessionRunManagerExternalDeploymentId.test.ts

@@ -263,6 +263,50 @@ describe("session runs — external deployment id", () => {
     }
   );
 
+  postgresTest(
+    "a changed pin does not disturb a live run — the SDK moves it, not the server",
+    async ({ prisma }) => {
+      const suffix = `pin_live_${seq++}`;
+      const { seed, writerStore } = await setup(prisma as unknown as PrismaClient, suffix);
+
+      const liveRunId = cuidRunId(`l${seq}`);
+      await writerStore.createRun(
+        buildCreateRunInput({
+          runId: liveRunId,
+          friendlyId: `run_${suffix}_live`,
+          organizationId: seed.organization.id,
+          projectId: seed.project.id,
+          runtimeEnvironmentId: seed.environment.id,
+          status: "EXECUTING",
+        })
+      );
+
+      const session = await prisma.session.create({
+        data: {
+          friendlyId: `session_${suffix}`,
+          type: "chat.agent",
+          projectId: seed.project.id,
+          runtimeEnvironmentId: seed.environment.id,
+          environmentType: "PRODUCTION",
+          organizationId: seed.organization.id,
+          taskIdentifier: "my-chat",
+          triggerConfig: { basePayload: {}, externalDeploymentId: "commit-new" },
+          currentRunId: liveRunId,
+          currentRunVersion: 0,
+        },
+      });
+
+      const result = await ensureRunForSession({
+        session,
+        environment: environmentFor(seed),
+        reason: "continuation",
+      });
+
+      expect(result.triggered).toBe(false);
+      expect(result.runId).toBe(liveRunId);
+    }
+  );
+
   postgresTest("reports pendingVersion when the triggered run parks", async ({ prisma }) => {
     const suffix = `pin_parked_${seq++}`;
     const { seed } = await setup(prisma as unknown as PrismaClient, suffix);

docs/ai-chat/patterns/version-upgrades.mdx

@@ -9,11 +9,14 @@ Chat agent runs are pinned to the worker version they started on. When you deplo
 `chat.requestUpgrade()` is the managed upgrade signal for `chat.agent()` and the `chat.createSession()` iterator. Fully hand-rolled custom agents use `chat.endAndContinue()` between turns to immediately hand the Session to a new run.
 
 <Note>
-  If you use [version skew protection](/deployment/version-skew-protection#chat-sessions), most of
-  this page is done for you: sessions pin to the deployment matching the app build that started
-  them, so the agent and the frontend move together without a hand-maintained version. Read this
-  page for the cases skew protection doesn't cover — an agent that wants to leave its pin
-  mid-conversation, or a session that was never pinned.
+  If your sessions are pinned by [version skew
+  protection](/deployment/version-skew-protection#chat-sessions), you do not need this page to move a
+  conversation onto a new deployment. A pinned session follows its pin on its own: when the stored
+  `externalDeploymentId` stops naming the deployment a run is on, the agent hands over at the next
+  turn boundary. Set [`versionSkew: "hold"`](#staying-put) to turn that off for one agent.
+
+  Read on for the cases that are still yours to decide — leaving a pin for a version nobody named,
+  a session that was never pinned, and hand-rolled custom agents.
 </Note>
 
 ## How it works
@@ -130,6 +133,13 @@ This pattern is useful when:
 
 ## Auto-detect from build ID (Next.js / Vercel)
 
+<Warning>
+  You probably don't need this any more. If your sessions are pinned, following the pin is the
+  built-in behaviour and it needs no `clientData` and no `chat.local`. Reach for the recipe below
+  only when you want to upgrade on a signal the pin doesn't carry — a frontend build id that moves
+  independently of the deployment your app names.
+</Warning>
+
 For automatic upgrade on every deploy, pass your platform's build ID via `clientData` instead of a manual version. The agent stores the ID from the first message and upgrades when it changes:
 
 ```tsx title="app/components/Chat.tsx"
@@ -178,11 +188,37 @@ export const myChat = chat
 
 This upgrades on **every** deploy, not just breaking changes. Good for fast-moving projects where you always want the latest code.
 
-<Tip>
-  With [version skew protection](/deployment/version-skew-protection#chat-sessions) on, you don't
-  need this recipe: the session is already pinned to the deployment that matches the app build that
-  started it, and a client on a new build re-pins the session when it starts.
-</Tip>
+## Staying put
+
+A pinned session follows its pin by default. To keep one agent where it is — a long tool chain you
+don't want interrupted, or a conversation you'd rather move on your own terms — set `versionSkew`:
+
+```ts
+export const myChat = chat.agent({
+  id: "my-chat",
+  versionSkew: "hold",
+  run: async ({ messages, signal }) => { ... },
+});
+```
+
+`"hold"` only stops the automatic handoff. `chat.requestUpgrade()` still works, so you can keep the
+decision and still get the seamless swap.
+
+Two cases never hand over automatically, whatever `versionSkew` says:
+
+- **A session with no pin.** There is nothing to compare against, and an unpinned session already
+  lands on the current version every time it starts a run.
+- **A session using `lockToVersion`.** That pin outranks the external deployment id and
+  `chat.requestUpgrade()` cannot escape it, so handing over would land on the same version and
+  repeat.
+
+<Note>
+  Following the pin costs one session read per turn on pinned chats, and the handoff happens at a
+  turn boundary — never mid-turn. If the pin names a deployment that hasn't landed yet, the successor
+  parks: your messages stay durable, and the transport emits `run-pending-version` with
+  `source: "upgrade"` so you can say so in the UI. See [parked
+  chats](/deployment/version-skew-protection#chat-sessions).
+</Note>
 
 ## Custom agents
 
@@ -199,7 +235,7 @@ await chat.endAndContinue();
 return;
 ```
 
-The continuation uses the same durable Session and receives `.in` records that the old run has not consumed. It starts on the latest deployed task version unless the Session's trigger configuration sets `lockToVersion`.
+The continuation uses the same durable Session and receives `.in` records that the old run has not consumed. It starts on the latest deployed task version only if the Session is unpinned — a Session carrying `lockToVersion` or an `externalDeploymentId` re-applies that pin, so the continuation lands where the Session says rather than on the newest build.
 
 If input has been dispatched to the old run but should be processed by the continuation, detach the old listeners and skip the final `chat.writeTurnComplete()`. A turn-complete boundary acknowledges the latest input dispatched to the old run, so writing one after that dispatch would cause the continuation to resume past the input.
 

docs/deployment/version-skew-protection.mdx

@@ -296,7 +296,7 @@ export const startChatSession = chat.createStartSessionAction<typeof myChat>("my
 
 Three things follow from the pin living on the session:
 
-- **Starting the session again refreshes it.** `sessions.start()` is idempotent on `chatId` and rewrites the stored config, so when your transport calls `startSession` after a redeploy, the *next* run picks up the new id. The turn already in flight finishes on the code it started on.
+- **Starting the session again refreshes it, and the conversation follows.** `sessions.start()` is idempotent on `chatId` and rewrites the stored config, so when your transport calls `startSession` after a redeploy, the session re-pins. The agent then hands the conversation over at the next turn boundary, so the next message is answered by the deployment you just named — not several turns later when the old run happens to end. The turn already in flight finishes on the code it started on. Set [`versionSkew: "hold"`](/ai-chat/patterns/version-upgrades#staying-put) on an agent that should stay put instead.
 - **There is one pin per `chatId`.** If the same conversation is open in two tabs on two different releases of your app, whichever called `startSession` most recently sets the pin for both.
 - **A parked chat is waiting, not broken.** A run pinned to a deployment that hasn't landed parks, and every message sent meanwhile is stored durably and delivered once the deployment arrives. Nothing is lost — but nothing answers either, so tell the user. Pass `pendingVersion` through your `startSession` callback and the transport emits a `run-pending-version` event:
 
@@ -312,7 +312,7 @@ const transport = useTriggerChatTransport({
 });
 ```
 
-The event repeats on every message sent while the chat is parked, so a notice driven off it stays accurate.
+The event repeats on every message sent while the chat is parked, so a notice driven off it stays accurate. Its `source` says where the park was learned: `start` from creating the session, `send` from an append, `head-start` from the route's response header, and `upgrade` when a session followed its pin onto a deployment that hasn't landed yet — that last one arrives as soon as the handoff happens, without waiting for another message.
 
 [Head Start](/ai-chat/fast-starts#head-start) softens this considerably: turn 1 runs in your own warm process, so a parked deployment costs nothing until step 2. The handover signal is durable, so the agent picks the turn up where it left off once the deployment lands. The transport emits `run-pending-version` with `source: "head-start"` for that case, and `chat.startHeadStart` returns `pendingVersion` for the detached flow.
 
@@ -336,7 +336,7 @@ Use this for a conversation that should always run on the current version — a
 chat.requestUpgrade({ externalDeploymentId: clientData.commitSha });
 ```
 
-Either way the change is persisted on the session, so the next continuation doesn't fall back to the id the agent just rejected. `lockToVersion` is a separate, explicit pin and is never cleared — `requestUpgrade()` cannot escape it.
+Either way the change is persisted on the session, so the next continuation doesn't fall back to the id the agent just rejected. `lockToVersion` is a separate, explicit pin and is never cleared — `requestUpgrade()` cannot escape it, which is also why a session using it never follows its external deployment id automatically.
 
 ## Waiting and expiry
 

packages/core/src/v3/schemas/api.ts

@@ -1993,6 +1993,12 @@ export const EndAndContinueSessionResponseBody = z.object({
    * to drive the next run.
    */
   swapped: z.boolean(),
+  /**
+   * The run that took over is parked waiting for its deployment. Surface this so a
+   * handoff onto a version that has not landed reads as a deploy in progress rather
+   * than a chat that went quiet.
+   */
+  pendingVersion: z.boolean().optional(),
 });
 export type EndAndContinueSessionResponseBody = z.infer<typeof EndAndContinueSessionResponseBody>;
 

packages/core/src/v3/sessionStreams/wireProtocol.ts

@@ -55,6 +55,7 @@ export const SESSION_IN_CONSUMED_ID_HEADER = "session-in-consumed-id" as const;
 export const TRIGGER_CONTROL_SUBTYPE = {
   TURN_COMPLETE: "turn-complete",
   UPGRADE_REQUIRED: "upgrade-required",
+  PENDING_VERSION: "pending-version",
 } as const;
 
 export type TriggerControlSubtype =

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

@@ -36,6 +36,7 @@ import {
   type TaskSchema,
   type TaskWithSchema,
   TRIGGER_CONTROL_SUBTYPE,
+  tryCatch,
   type StreamWriteResult,
   type RouterCheckpoint,
   type SessionRouteTable,
@@ -109,6 +110,7 @@ type ToolCallOptions = {
 import { readFileInSkill, runBashInSkill } from "./agentSkillsRuntime.js";
 import { ensureAiSdkTelemetry } from "./aiAutoTelemetry.js";
 import { withResolvedExternalDeploymentId } from "./externalDeploymentId.js";
+import { type ChatVersionSkewPolicy, resolvePinToFollow } from "./chatVersionSkew.js";
 import {
   type SessionChannelHandleFor,
   type SessionHandle,
@@ -5515,6 +5517,18 @@ export type ChatAgentOptions<
    */
   oomMachine?: MachinePresetName;
 
+  /**
+   * What to do when the session's `externalDeploymentId` no longer names the deployment
+   * this run is on — after a redeploy re-pins the session, say.
+   *
+   * - `"follow"` (default) hands the conversation to the pinned deployment at the next
+   *   turn boundary, so no `chat.requestUpgrade()` of your own is needed.
+   * - `"hold"` stays put until you ask to move. Manual `chat.requestUpgrade()` works either way.
+   *
+   * Ignored for sessions with no pin, and for sessions using `lockToVersion`.
+   */
+  versionSkew?: ChatVersionSkewPolicy;
+
   /**
    * Schema for validating `clientData` from the frontend.
    * Accepts Zod, ArkType, Valibot, or any supported schema library.
@@ -6394,6 +6408,7 @@ function chatAgent<
     onChatResume,
     exitAfterPreloadIdle = false,
     oomMachine,
+    versionSkew,
     ...restOptions
   } = options;
 
@@ -8010,6 +8025,8 @@ function chatAgent<
                     );
                   }
 
+                  await followSessionPin(currentWirePayload.chatId, versionSkew);
+
                   // chat.requestUpgrade() called in onTurnStart (or onValidateMessages) —
                   // skip run() and signal the transport to re-trigger the same message
                   // on the new version.
@@ -9677,6 +9694,30 @@ function requestUpgrade(options?: { externalDeploymentId?: string }): void {
   if (target) locals.set(chatUpgradeExternalDeploymentIdKey, target);
 }
 
+/** @internal Requests a handoff when the session's pin no longer names this deployment. */
+async function followSessionPin(
+  chatId: string | undefined,
+  policy: ChatVersionSkewPolicy | undefined
+): Promise<void> {
+  if (!chatId) {
+    return;
+  }
+
+  const target = await resolvePinToFollow({
+    policy,
+    deployedExternalId: locals.get(chatAgentRunContextKey)?.deployment?.externalId,
+    upgradeAlreadyRequested: locals.get(chatUpgradeRequestedKey) === true,
+    readPin: async () => (await sessions.retrieve(chatId)).triggerConfig,
+  });
+
+  if (!target) {
+    return;
+  }
+
+  logger.info("chat.versionSkew: following the session pin", { chatId, target });
+  requestUpgrade({ externalDeploymentId: target });
+}
+
 /**
  * Hand off the current custom agent Session to a fresh run.
  *
@@ -9733,11 +9774,25 @@ async function performEndAndContinue(options?: { externalDeploymentId?: string }
 
   const externalDeploymentId = options?.externalDeploymentId;
   const apiClient = apiClientManager.clientOrThrow();
-  await apiClient.endAndContinueSession(chatId, {
+  const result = await apiClient.endAndContinueSession(chatId, {
     callingRunId,
     reason: "upgrade",
     ...(externalDeploymentId ? { externalDeploymentId } : {}),
   });
+
+  if (result?.pendingVersion !== true) {
+    return;
+  }
+
+  // The successor parked. Say so on `.out` while this run still can — the transport's
+  // subscription survives the swap, so the client learns without waiting for its next send.
+  const [error] = await tryCatch(
+    getChatSession().out.writeControl(TRIGGER_CONTROL_SUBTYPE.PENDING_VERSION)
+  );
+
+  if (error) {
+    logger.warn("could not signal a parked handoff", { chatId, error });
+  }
 }
 
 /**
@@ -10494,6 +10549,11 @@ export type ChatSessionOptions = {
   timeout?: string;
   /** Max turns before ending. @default 100 */
   maxTurns?: number;
+  /**
+   * What to do when the session's `externalDeploymentId` no longer names this deployment.
+   * `"follow"` (default) hands over at the next turn boundary; `"hold"` stays put.
+   */
+  versionSkew?: ChatVersionSkewPolicy;
   /** Automatic context compaction — same options as `chat.agent({ compaction })`. */
   compaction?: ChatAgentCompactionOptions;
   /** Configure mid-execution message injection — same options as `chat.agent({ pendingMessages })`. */
@@ -10710,6 +10770,7 @@ function createChatSession<TClientData = unknown>(
     maxTurns = 100,
     compaction: sessionCompaction,
     pendingMessages: sessionPendingMessages,
+    versionSkew: sessionVersionSkew,
   } = options;
 
   const idleTimeoutInSeconds = sessionIdleTimeoutOpt ?? 30;
@@ -10934,6 +10995,8 @@ function createChatSession<TClientData = unknown>(
             accumulator.applyHandover(pendingHandoverSignal);
           }
 
+          await followSessionPin(currentPayload.chatId, sessionVersionSkew);
+
           // chat.requestUpgrade() called before this turn — signal transport and exit
           if (locals.get(chatUpgradeRequestedKey)) {
             await writeUpgradeRequiredChunk();

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

@@ -835,6 +835,10 @@ export class AgentChat<TAgent = unknown> {
                 continue;
               }
 
+              if (controlValue === TRIGGER_CONTROL_SUBTYPE.PENDING_VERSION) {
+                continue;
+              }
+
               if (controlValue === TRIGGER_CONTROL_SUBTYPE.TURN_COMPLETE) {
                 // Customer's callback may be async (e.g. persisting
                 // lastEventId to a DB). Wrap so a rejected Promise