@trigger.dev/sdk 0.0.0-prerelease-20260908122921 → 0.0.0-prerelease-streamfix-20260909094302

package/skills/trigger-chat-agent-advanced/SKILL.md

@@ -143,12 +143,6 @@ await waitUntilComplete();
 5s timeout, before `onTurnComplete`). `chat.inject(messages)` queues `ModelMessage[]` that drain at
 the next turn start or `prepareStep` boundary.
 
-Two lanes, decided by role. A `role: "system"` message goes to the model's instructions, where it is
-trusted like the system prompt, and applies to the next turn only. Any other role joins the
-conversation and is untrusted by construction, so put checkable facts there and directives in the
-system lane. The instructions lane reaches the model only through the managed `streamText` (or a
-`chat.toStreamTextOptions()` spread), since that is where the SDK can set instructions.
-
 ```ts
 export const myChat = chat.agent({
   id: "my-chat",
@@ -160,9 +154,8 @@ export const myChat = chat.agent({
       })()
     );
   },
-  registry,
-  run: async ({ messages, signal, streamText }) =>
-    streamText({ messages, abortSignal: signal, stopWhen: stepCountIs(15) }),
+  run: async ({ messages, signal }) =>
+    streamText({ ...chat.toStreamTextOptions({ registry }), messages, abortSignal: signal, stopWhen: stepCountIs(15) }),
 });
 ```
 
@@ -170,9 +163,8 @@ export const myChat = chat.agent({
 
 `compaction.shouldCompact` decides when, `summarize` produces the summary that replaces the model
 messages. UI messages are preserved by default (customize via `compactUIMessages`). The `prepareStep`
-that performs inner-loop compaction rides the managed `streamText`, which composes a `prepareStep`
-you pass after it. Spreading `chat.toStreamTextOptions()` and then passing your own replaces it,
-switching compaction off.
+that performs inner-loop compaction is auto-injected by `chat.toStreamTextOptions()`; a `prepareStep`
+you pass after the spread wins.
 
 ```ts
 compaction: {
@@ -190,14 +182,7 @@ compaction: {
 `actionSchema` validates; `onAction` mutates via `chat.history` (`slice`, `replace`, `rollbackTo`,
 `remove`, `getPendingToolCalls`, `extractNewToolResults`). Actions fire `hydrateMessages` and
 `onAction` only, never `run()` or the turn hooks. Return a `StreamTextResult`, string, or `UIMessage`
-to also emit a model response, built with the `streamText` from `onAction`'s own argument so it
-carries the agent's prompt and tools like any other turn.
-
-Persistence splits by model. Without `hydrateMessages` the runtime snapshots the conversation after
-an action that changed it, so a rollback or a returned response survives the run ending. With
-`hydrateMessages` your store is the source of truth and the runtime does not write, so mirror every
-mutation yourself: a regenerate is a delete and an insert, and `chat.pipeAndCapture` hands back the
-same assistant message the runtime would have captured.
+to also emit a model response.
 
 ```ts
 export const myChat = chat.agent({
@@ -210,8 +195,7 @@ export const myChat = chat.agent({
     if (action.type === "undo") chat.history.slice(0, -2);
     if (action.type === "rollback") chat.history.rollbackTo(action.targetMessageId);
   },
-  run: async ({ messages, signal, streamText }) =>
-    streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal }),
+  run: async ({ messages, signal }) => streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal }),
 });
 ```
 
@@ -226,19 +210,18 @@ must be **schema-only** (a module importing `ai` + `zod` only); heavy executes s
 
 ```ts
 import { chat } from "@trigger.dev/sdk/chat-server";
+import { streamText, stepCountIs } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 import { headStartTools } from "@/lib/chat-tools/schemas";
 
 export const chatHandler = chat.headStart({
   agentId: "my-chat",
-  // `streamText` from the run argument owns `messages`, `prompt`, `stopWhen`
-  // and `abortSignal`: the handover needs `stopWhen: stepCountIs(1)` so the agent,
-  // not this handler, runs step 2 onward. Passing any of them is a type error.
-  run: async ({ streamText }) =>
+  run: async ({ chat: helper }) =>
     streamText({
+      ...helper.toStreamTextOptions({ tools: headStartTools }),
       model: anthropic("claude-sonnet-4-6"),
       system: "You are helpful.",
-      tools: headStartTools,
+      stopWhen: stepCountIs(15),
     }),
 });
 // Next.js: export const POST = chatHandler;  Transport: headStart: "/api/chat"
@@ -265,10 +248,8 @@ export const myChat = chat.agent({
 ### 8. Pending messages (mid-stream user input)
 
 A message sent while a turn is streaming should NOT cancel the stream. Configure
-`pendingMessages` (`shouldInject`, `prepare`, `onReceived`, `onInjected`) on the agent so the managed
-`streamText`'s `prepareStep` folds them in at the next boundary. An injected steering message is part
-of the conversation your hooks see, so it arrives in `uiMessages` and `newUIMessages` at
-`onTurnComplete` and an app persisting from there stores it without extra work. On the frontend, `usePendingMessages`
+`pendingMessages` (`shouldInject`, `prepare`, `onReceived`, `onInjected`) on the agent so the SDK's
+auto-injected `prepareStep` folds them in at the next boundary. On the frontend, `usePendingMessages`
 returns `pending`, `steer(text)`, `queue(text)`, and `promoteToSteering(id)`; send via
 `transport.sendPendingMessage(chatId, uiMessage, metadata?)`.
 

package/dist/commonjs/v3/chatVersionSkew.d.ts

@@ -1,12 +0,0 @@
-export type ChatVersionSkewPolicy = "follow" | "hold";
-export type SessionVersionPin = {
-    externalDeploymentId?: string | null;
-    lockToVersion?: string;
-};
-export type ResolvePinToFollowOptions = {
-    policy: ChatVersionSkewPolicy | undefined;
-    deployedExternalId: string | undefined;
-    upgradeAlreadyRequested: boolean;
-    readPin: () => Promise<SessionVersionPin | undefined>;
-};
-export declare function resolvePinToFollow(options: ResolvePinToFollowOptions): Promise<string | undefined>;

package/dist/commonjs/v3/chatVersionSkew.js

@@ -1,30 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolvePinToFollow = resolvePinToFollow;
-const v3_1 = require("@trigger.dev/core/v3");
-async function resolvePinToFollow(options) {
-    if (options.policy === "hold") {
-        return undefined;
-    }
-    if (options.upgradeAlreadyRequested) {
-        return undefined;
-    }
-    if (!options.deployedExternalId) {
-        return undefined;
-    }
-    const [error, pin] = await (0, v3_1.tryCatch)(options.readPin());
-    if (error || !pin) {
-        return undefined;
-    }
-    if (!pin.externalDeploymentId) {
-        return undefined;
-    }
-    if (pin.lockToVersion) {
-        return undefined;
-    }
-    if (pin.externalDeploymentId === options.deployedExternalId) {
-        return undefined;
-    }
-    return pin.externalDeploymentId;
-}
-//# sourceMappingURL=chatVersionSkew.js.map

package/dist/commonjs/v3/chatVersionSkew.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"chatVersionSkew.js","sourceRoot":"","sources":["../../../src/v3/chatVersionSkew.ts"],"names":[],"mappings":";;;AAAA,6CAAgD;AAgBzC,KAAK,6BACV,OAAkC;IAElC,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QAC9B,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,OAAO,CAAC,uBAAuB,EAAE,CAAC;QACpC,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE,CAAC;QAChC,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,GAAG,MAAM,IAAA,aAAQ,EAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAEvD,IAAI,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC;QAClB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,CAAC,GAAG,CAAC,oBAAoB,EAAE,CAAC;QAC9B,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,GAAG,CAAC,aAAa,EAAE,CAAC;QACtB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,GAAG,CAAC,oBAAoB,KAAK,OAAO,CAAC,kBAAkB,EAAE,CAAC;QAC5D,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO,GAAG,CAAC,oBAAoB,CAAC;AAClC,CAAC"}

package/dist/commonjs/v3/externalDeploymentId.d.ts

@@ -1,23 +0,0 @@
-import { type SessionTriggerConfig } from "@trigger.dev/core/v3";
-/** Reads an env var unless the scope opted out of ambient context (`inheritContext: false`). */
-export declare function scopedEnvVar(name: string): string | undefined;
-/**
- * Precedence: an explicit value, the client config, `TRIGGER_EXTERNAL_DEPLOYMENT_ID`, then
- * platform/CI commit vars when automatic skew protection is on. `null` is an explicit opt-out.
- */
-export declare function resolveTriggerExternalDeploymentId(explicit?: string | null): string | undefined;
-/** A session trigger config as callers write it: the pin is optional, and `null` opts out. */
-type TriggerConfigInput = Omit<SessionTriggerConfig, "externalDeploymentId"> & {
-    externalDeploymentId?: string | null;
-};
-/**
- * Fill in `triggerConfig.externalDeploymentId` on an outgoing session-create body, at each point
- * one leaves the SDK. Discovery has to happen here rather than server-side: the commit SHA lives
- * in the calling application's runtime, so the caller's build is what selects the agent version.
- */
-export declare function withResolvedExternalDeploymentId<TBody extends {
-    triggerConfig: TriggerConfigInput;
-}>(body: TBody): TBody & {
-    triggerConfig: SessionTriggerConfig;
-};
-export {};

package/dist/commonjs/v3/externalDeploymentId.js

@@ -1,43 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.scopedEnvVar = scopedEnvVar;
-exports.resolveTriggerExternalDeploymentId = resolveTriggerExternalDeploymentId;
-exports.withResolvedExternalDeploymentId = withResolvedExternalDeploymentId;
-const v3_1 = require("@trigger.dev/core/v3");
-/** Reads an env var unless the scope opted out of ambient context (`inheritContext: false`). */
-function scopedEnvVar(name) {
-    const scope = v3_1.sdkScope.getStore();
-    if (scope && !scope.inheritContext)
-        return undefined;
-    return (0, v3_1.getEnvVar)(name);
-}
-/**
- * Precedence: an explicit value, the client config, `TRIGGER_EXTERNAL_DEPLOYMENT_ID`, then
- * platform/CI commit vars when automatic skew protection is on. `null` is an explicit opt-out.
- */
-function resolveTriggerExternalDeploymentId(explicit) {
-    if (explicit === null)
-        return undefined;
-    return (0, v3_1.resolveExternalDeploymentId)({
-        explicit,
-        clientConfig: v3_1.apiClientManager.externalDeploymentId,
-        read: scopedEnvVar,
-    });
-}
-/**
- * Fill in `triggerConfig.externalDeploymentId` on an outgoing session-create body, at each point
- * one leaves the SDK. Discovery has to happen here rather than server-side: the commit SHA lives
- * in the calling application's runtime, so the caller's build is what selects the agent version.
- */
-function withResolvedExternalDeploymentId(body) {
-    const resolved = resolveTriggerExternalDeploymentId(body.triggerConfig.externalDeploymentId);
-    const { externalDeploymentId: _omit, ...rest } = body.triggerConfig;
-    return {
-        ...body,
-        triggerConfig: {
-            ...rest,
-            ...(resolved ? { externalDeploymentId: resolved } : {}),
-        },
-    };
-}
-//# sourceMappingURL=externalDeploymentId.js.map

package/dist/commonjs/v3/externalDeploymentId.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"externalDeploymentId.js","sourceRoot":"","sources":["../../../src/v3/externalDeploymentId.ts"],"names":[],"mappings":";;;;;AAAA,6CAM8B;AAE9B,gGAAgG;AAChG,sBAA6B,IAAY;IACvC,MAAM,KAAK,GAAG,aAAQ,CAAC,QAAQ,EAAE,CAAC;IAClC,IAAI,KAAK,IAAI,CAAC,KAAK,CAAC,cAAc;QAAE,OAAO,SAAS,CAAC;IACrD,OAAO,IAAA,cAAS,EAAC,IAAI,CAAC,CAAC;AACzB,CAAC;AAED;;;GAGG;AACH,4CAAmD,QAAwB;IACzE,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAExC,OAAO,IAAA,gCAA2B,EAAC;QACjC,QAAQ;QACR,YAAY,EAAE,qBAAgB,CAAC,oBAAoB;QACnD,IAAI,EAAE,YAAY;KACnB,CAAC,CAAC;AACL,CAAC;AAOD;;;;GAIG;AACH,0CAEE,IAAW;IACX,MAAM,QAAQ,GAAG,kCAAkC,CAAC,IAAI,CAAC,aAAa,CAAC,oBAAoB,CAAC,CAAC;IAC7F,MAAM,EAAE,oBAAoB,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC,aAAa,CAAC;IAEpE,OAAO;QACL,GAAG,IAAI;QACP,aAAa,EAAE;YACb,GAAG,IAAI;YACP,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,oBAAoB,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACxD;KACF,CAAC;AACJ,CAAC"}

package/dist/esm/v3/chatVersionSkew.d.ts

@@ -1,12 +0,0 @@
-export type ChatVersionSkewPolicy = "follow" | "hold";
-export type SessionVersionPin = {
-    externalDeploymentId?: string | null;
-    lockToVersion?: string;
-};
-export type ResolvePinToFollowOptions = {
-    policy: ChatVersionSkewPolicy | undefined;
-    deployedExternalId: string | undefined;
-    upgradeAlreadyRequested: boolean;
-    readPin: () => Promise<SessionVersionPin | undefined>;
-};
-export declare function resolvePinToFollow(options: ResolvePinToFollowOptions): Promise<string | undefined>;

package/dist/esm/v3/chatVersionSkew.js

@@ -1,27 +0,0 @@
-import { tryCatch } from "@trigger.dev/core/v3";
-export async function resolvePinToFollow(options) {
-    if (options.policy === "hold") {
-        return undefined;
-    }
-    if (options.upgradeAlreadyRequested) {
-        return undefined;
-    }
-    if (!options.deployedExternalId) {
-        return undefined;
-    }
-    const [error, pin] = await tryCatch(options.readPin());
-    if (error || !pin) {
-        return undefined;
-    }
-    if (!pin.externalDeploymentId) {
-        return undefined;
-    }
-    if (pin.lockToVersion) {
-        return undefined;
-    }
-    if (pin.externalDeploymentId === options.deployedExternalId) {
-        return undefined;
-    }
-    return pin.externalDeploymentId;
-}
-//# sourceMappingURL=chatVersionSkew.js.map

package/dist/esm/v3/chatVersionSkew.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"chatVersionSkew.js","sourceRoot":"","sources":["../../../src/v3/chatVersionSkew.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAgBhD,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAAkC;IAElC,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QAC9B,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,OAAO,CAAC,uBAAuB,EAAE,CAAC;QACpC,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE,CAAC;QAChC,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAEvD,IAAI,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC;QAClB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,CAAC,GAAG,CAAC,oBAAoB,EAAE,CAAC;QAC9B,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,GAAG,CAAC,aAAa,EAAE,CAAC;QACtB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,GAAG,CAAC,oBAAoB,KAAK,OAAO,CAAC,kBAAkB,EAAE,CAAC;QAC5D,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO,GAAG,CAAC,oBAAoB,CAAC;AAClC,CAAC"}

package/dist/esm/v3/externalDeploymentId.d.ts

@@ -1,23 +0,0 @@
-import { type SessionTriggerConfig } from "@trigger.dev/core/v3";
-/** Reads an env var unless the scope opted out of ambient context (`inheritContext: false`). */
-export declare function scopedEnvVar(name: string): string | undefined;
-/**
- * Precedence: an explicit value, the client config, `TRIGGER_EXTERNAL_DEPLOYMENT_ID`, then
- * platform/CI commit vars when automatic skew protection is on. `null` is an explicit opt-out.
- */
-export declare function resolveTriggerExternalDeploymentId(explicit?: string | null): string | undefined;
-/** A session trigger config as callers write it: the pin is optional, and `null` opts out. */
-type TriggerConfigInput = Omit<SessionTriggerConfig, "externalDeploymentId"> & {
-    externalDeploymentId?: string | null;
-};
-/**
- * Fill in `triggerConfig.externalDeploymentId` on an outgoing session-create body, at each point
- * one leaves the SDK. Discovery has to happen here rather than server-side: the commit SHA lives
- * in the calling application's runtime, so the caller's build is what selects the agent version.
- */
-export declare function withResolvedExternalDeploymentId<TBody extends {
-    triggerConfig: TriggerConfigInput;
-}>(body: TBody): TBody & {
-    triggerConfig: SessionTriggerConfig;
-};
-export {};

package/dist/esm/v3/externalDeploymentId.js

@@ -1,38 +0,0 @@
-import { apiClientManager, getEnvVar, resolveExternalDeploymentId, sdkScope, } from "@trigger.dev/core/v3";
-/** Reads an env var unless the scope opted out of ambient context (`inheritContext: false`). */
-export function scopedEnvVar(name) {
-    const scope = sdkScope.getStore();
-    if (scope && !scope.inheritContext)
-        return undefined;
-    return getEnvVar(name);
-}
-/**
- * Precedence: an explicit value, the client config, `TRIGGER_EXTERNAL_DEPLOYMENT_ID`, then
- * platform/CI commit vars when automatic skew protection is on. `null` is an explicit opt-out.
- */
-export function resolveTriggerExternalDeploymentId(explicit) {
-    if (explicit === null)
-        return undefined;
-    return resolveExternalDeploymentId({
-        explicit,
-        clientConfig: apiClientManager.externalDeploymentId,
-        read: scopedEnvVar,
-    });
-}
-/**
- * Fill in `triggerConfig.externalDeploymentId` on an outgoing session-create body, at each point
- * one leaves the SDK. Discovery has to happen here rather than server-side: the commit SHA lives
- * in the calling application's runtime, so the caller's build is what selects the agent version.
- */
-export function withResolvedExternalDeploymentId(body) {
-    const resolved = resolveTriggerExternalDeploymentId(body.triggerConfig.externalDeploymentId);
-    const { externalDeploymentId: _omit, ...rest } = body.triggerConfig;
-    return {
-        ...body,
-        triggerConfig: {
-            ...rest,
-            ...(resolved ? { externalDeploymentId: resolved } : {}),
-        },
-    };
-}
-//# sourceMappingURL=externalDeploymentId.js.map

package/dist/esm/v3/externalDeploymentId.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"externalDeploymentId.js","sourceRoot":"","sources":["../../../src/v3/externalDeploymentId.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,SAAS,EACT,2BAA2B,EAC3B,QAAQ,GAET,MAAM,sBAAsB,CAAC;AAE9B,gGAAgG;AAChG,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,EAAE,CAAC;IAClC,IAAI,KAAK,IAAI,CAAC,KAAK,CAAC,cAAc;QAAE,OAAO,SAAS,CAAC;IACrD,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kCAAkC,CAAC,QAAwB;IACzE,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAExC,OAAO,2BAA2B,CAAC;QACjC,QAAQ;QACR,YAAY,EAAE,gBAAgB,CAAC,oBAAoB;QACnD,IAAI,EAAE,YAAY;KACnB,CAAC,CAAC;AACL,CAAC;AAOD;;;;GAIG;AACH,MAAM,UAAU,gCAAgC,CAE9C,IAAW;IACX,MAAM,QAAQ,GAAG,kCAAkC,CAAC,IAAI,CAAC,aAAa,CAAC,oBAAoB,CAAC,CAAC;IAC7F,MAAM,EAAE,oBAAoB,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC,aAAa,CAAC;IAEpE,OAAO;QACL,GAAG,IAAI;QACP,aAAa,EAAE;YACb,GAAG,IAAI;YACP,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,oBAAoB,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACxD;KACF,CAAC;AACJ,CAAC"}

package/docs/ai-chat/patterns/native-compaction.mdx

@@ -1,310 +0,0 @@
----
-title: "Native compaction & provider fallback"
-sidebarTitle: "Native compaction"
-description: "Persist provider-native compaction (Anthropic context editing, OpenAI stored responses) across chat.agent turns so history is never re-sent, and fall back between providers without losing the conversation."
----
-
-Providers compact a conversation within a single request. Anthropic's [context editing](https://docs.anthropic.com/en/docs/build-with-claude/context-editing) clears old tool-use blocks server-side, and OpenAI's [stored responses](https://platform.openai.com/docs/guides/conversation-state) keep the thread server-side so you only send the delta. Neither changes what your agent has accumulated, so on its own the next turn re-sends the whole transcript again and the token saving is lost.
-
-This is the gap this page closes. After each turn, mirror what the provider compacted into the agent's stored history with [`chat.history.set()`](/ai-chat/reference#chat-namespace), so the next turn is derived from the already-reduced conversation. And because a native handle is provider-specific, this page also shows how a provider-agnostic [Trigger.dev compaction](/ai-chat/compaction) summary lets you fall back between providers without re-expanding the context.
-
-<Note>
-  The full runnable example is [`triggerdotdev/resilient-chat-example`](https://github.com/triggerdotdev/resilient-chat-example). See `native-persist.ts` for the Anthropic persistence flow and `resilient-chat.ts` for OpenAI stored responses plus provider fallback.
-</Note>
-
-## Two kinds of compaction
-
-They are not competing; they compose. Native compaction is the per-turn optimization, and Trigger.dev compaction is the durable, portable checkpoint.
-
-| | Native (provider) | Trigger.dev `compaction` |
-| --- | --- | --- |
-| Runs | Inside one provider request | Between steps / turns, in your run |
-| Scope | Provider-specific (Anthropic edits, OpenAI stored thread) | Provider-agnostic |
-| Portable across a provider switch | No, the handle is a cache miss on the other provider | Yes, `summarize` returns a plain string |
-| Persisted by default | No, you mirror it in `onTurnComplete` | Yes, replaces model messages and keeps UI messages |
-
-## Persist Anthropic native context editing
-
-Anthropic's `contextManagement` clears old tool-use/tool-result blocks server-side per request, and reports how many it cleared in `providerMetadata.anthropic.contextManagement.appliedEdits` (`clearedToolUses`, `clearedInputTokens`). It does not touch your accumulated history, so on its own the next turn still re-sends everything.
-
-The fix: read the `appliedEdits` counts as they stream in `onStepFinish`, then after the turn mirror that clearing into stored history with `chat.history.set()`. No custom summarizer is involved, since the provider's native editing drives what gets persisted.
-
-```ts /trigger/native-persist.ts
-import { chat } from "@trigger.dev/sdk/ai";
-import { streamText, stepCountIs, tool, type UIMessage } from "ai";
-import { anthropic } from "@ai-sdk/anthropic";
-import { z } from "zod";
-
-const fetchRecord = tool({
-  description: "Fetch the full text of a record by its numeric id.",
-  inputSchema: z.object({ id: z.number() }),
-  execute: async ({ id }) => ({ id, text: `RECORD ${id}: ...` }),
-});
-
-// How many tool-uses Anthropic cleared this turn, per chat. Captured in run(),
-// applied in onTurnComplete. An in-memory Map is enough because the run stays
-// alive across turns (idleTimeoutInSeconds).
-const clearedByChat = new Map<string, number>();
-
-const isToolPart = (p: { type?: string }) =>
-  typeof p?.type === "string" && (p.type.startsWith("tool-") || p.type === "dynamic-tool");
-
-// Drop the oldest n tool parts, mirroring what the provider cleared. A tool call
-// and its result live in one part, so pairing stays intact.
-function pruneOldestToolParts(messages: UIMessage[], n: number): UIMessage[] {
-  let toRemove = n;
-  const out: UIMessage[] = [];
-  for (const m of messages) {
-    if (toRemove <= 0 || m.role !== "assistant" || !m.parts) {
-      out.push(m);
-      continue;
-    }
-    const kept = m.parts.filter((p) => {
-      if (toRemove > 0 && isToolPart(p)) {
-        toRemove--;
-        return false;
-      }
-      return true;
-    });
-    if (kept.length > 0) out.push({ ...m, parts: kept });
-  }
-  return out;
-}
-
-export const nativePersist = chat.agent({
-  id: "native-persist",
-  idleTimeoutInSeconds: 120,
-  tools: { fetchRecord },
-  run: async ({ messages, chatId, tools, signal }) => {
-    return streamText({
-      model: anthropic("claude-sonnet-4-5"),
-      messages,
-      tools,
-      abortSignal: signal,
-      stopWhen: stepCountIs(12),
-      providerOptions: {
-        anthropic: {
-          contextManagement: {
-            edits: [
-              {
-                type: "clear_tool_uses_20250919",
-                trigger: { type: "tool_uses", value: 2 },
-                keep: { type: "tool_uses", value: 1 },
-                clearToolInputs: true,
-              },
-            ],
-          },
-        },
-      },
-      onStepFinish: ({ providerMetadata }) => {
-        const cm = providerMetadata?.anthropic?.contextManagement as
-          | { appliedEdits?: Array<{ type?: string; clearedToolUses?: number }> }
-          | undefined;
-        let stepCleared = 0;
-        for (const e of cm?.appliedEdits ?? []) {
-          if (e.type === "clear_tool_uses_20250919") stepCleared += e.clearedToolUses ?? 0;
-        }
-        if (stepCleared > 0) {
-          clearedByChat.set(chatId, (clearedByChat.get(chatId) ?? 0) + stepCleared);
-        }
-      },
-    });
-  },
-  // After the turn, mirror the server-side clearing into stored history.
-  onTurnComplete: async ({ chatId, uiMessages }) => {
-    const cleared = clearedByChat.get(chatId) ?? 0;
-    if (cleared <= 0) return;
-    chat.history.set(pruneOldestToolParts(uiMessages, cleared));
-    clearedByChat.set(chatId, 0);
-  },
-});
-```
-
-Turn 1 sends the user message and accumulates six tool results. Anthropic clears four of them server-side. `onTurnComplete` prunes those four from stored history, so turn 2 re-sends the smaller conversation (one tool result, not six) instead of the full transcript.
-
-<Note>
-  `onTurnComplete` is where persistence happens. Action turns fire `onAction` only, and a `chat.history.set()` inside `run()` is overwritten by the accumulator at turn end. See [Persistence and replay](/ai-chat/patterns/persistence-and-replay#action-turns-no-snapshot-write).
-</Note>
-
-## Persist OpenAI stored responses
-
-OpenAI's `store: true` keeps the thread server-side and returns a `responseId`. Pass that back as `previousResponseId` on the next turn and send only the messages since the last assistant reply; everything before it lives on OpenAI's side.
-
-```ts /trigger/openai-store.ts
-import { chat } from "@trigger.dev/sdk/ai";
-import { streamText, stepCountIs, type ModelMessage } from "ai";
-import { openai } from "@ai-sdk/openai";
-
-// Persist the stored-response handle between turns. Replace with your database.
-const nativeStore = new Map<string, { previousResponseId: string }>();
-
-// When OpenAI already holds the thread, send only what is new since the last
-// assistant reply. Everything before that lives server-side.
-function messagesSinceLastAssistant(messages: ModelMessage[]): ModelMessage[] {
-  let last = -1;
-  for (let i = 0; i < messages.length; i++) {
-    if (messages[i]!.role === "assistant") last = i;
-  }
-  return last === -1 ? messages : messages.slice(last + 1);
-}
-
-export const openaiStore = chat.agent({
-  id: "openai-store",
-  idleTimeoutInSeconds: 120,
-  run: async ({ messages, chatId, signal }) => {
-    const native = nativeStore.get(chatId);
-    const outbound = native ? messagesSinceLastAssistant(messages) : messages;
-
-    const result = streamText({
-      model: openai("gpt-4o"),
-      messages: outbound,
-      abortSignal: signal,
-      stopWhen: stepCountIs(5),
-      providerOptions: {
-        openai: native ? { store: true, previousResponseId: native.previousResponseId } : { store: true },
-      },
-    });
-
-    // Capture the response id off the metadata for the next turn.
-    void result.providerMetadata.then((meta) => {
-      const rid = typeof meta?.openai?.responseId === "string" ? meta.openai.responseId : undefined;
-      if (rid) nativeStore.set(chatId, { previousResponseId: rid });
-    });
-
-    return result;
-  },
-});
-```
-
-Turn 1 stores the thread and sends all three messages. Turn 2 sends only the new user message (`1/3`), because OpenAI already has the rest.
-
-## Fall back between providers without losing history
-
-A native handle is a per-provider cache. An OpenAI `previousResponseId` means nothing to Anthropic, and Anthropic's server-side edits don't exist on OpenAI. So when a provider is down and you fall back to another, the native optimization is a cache miss, and a naive fallback re-sends the entire raw transcript to the new provider.
-
-[Trigger.dev's `compaction`](/ai-chat/compaction) is the portable checkpoint that closes this gap. `summarize` returns a plain string and `compactModelMessages` returns neutral `ModelMessage[]`, so the summary survives any provider switch. Tag each native handle with the provider that produced it. On a switch it's a cache miss, and you rebuild from the summary instead of re-expanding the context.
-
-```ts /trigger/resilient-chat.ts
-import { chat } from "@trigger.dev/sdk/ai";
-import { streamText, generateText, stepCountIs, generateId, type ModelMessage } from "ai";
-import { anthropic } from "@ai-sdk/anthropic";
-import { openai } from "@ai-sdk/openai";
-
-type Provider = "anthropic" | "openai";
-const FALLBACK_ORDER: Provider[] = ["anthropic", "openai"];
-
-// Native handle, tagged with the provider that produced it. Replace with your DB.
-type NativeState = { provider: "openai"; previousResponseId: string };
-const nativeStore = new Map<string, NativeState>();
-
-// Provider-agnostic summary: a plain string, portable across any provider.
-async function summarizeConversation(messages: ModelMessage[]): Promise<string> {
-  const { text } = await generateText({
-    model: openai("gpt-4o-mini"),
-    messages: [
-      ...messages,
-      {
-        role: "user",
-        content:
-          "Summarize this conversation so it can continue with ANY model. " +
-          "Preserve decisions made, facts established, open questions, and the user's intent.",
-      },
-    ],
-  });
-  return text;
-}
-
-export const resilientChat = chat.agent({
-  id: "resilient-chat",
-  idleTimeoutInSeconds: 120,
-
-  compaction: {
-    shouldCompact: ({ totalTokens }) => (totalTokens ?? 0) > 80_000,
-    summarize: ({ messages }) => summarizeConversation(messages),
-    compactModelMessages: ({ modelMessages, summary }) => [
-      { role: "user", content: `Summary of the conversation so far:\n\n${summary}` },
-      ...modelMessages.slice(-2),
-    ],
-    compactUIMessages: ({ uiMessages, summary }) => [
-      {
-        id: generateId(),
-        role: "assistant",
-        parts: [{ type: "text", text: `[Conversation summary]\n\n${summary}` }],
-      },
-      ...uiMessages.slice(-2),
-    ],
-  },
-
-  // A Trigger.dev compaction is the reset point: the provider's server-side thread
-  // no longer matches the compacted baseline, so invalidate the native handle.
-  onCompacted: async ({ chatId }) => {
-    if (chatId) nativeStore.delete(chatId);
-  },
-
-  run: async ({ messages, chatId, signal }) => {
-    let lastError: unknown;
-    for (const providerId of FALLBACK_ORDER) {
-      const native = nativeStore.get(chatId);
-      try {
-        if (providerId === "openai") {
-          // On a switch to OpenAI with no matching handle, `messages` is already the
-          // compacted baseline (summary + recent), so raw history is not re-sent.
-          const useHandle = native?.provider === "openai";
-          const result = streamText({
-            model: openai("gpt-4o"),
-            messages,
-            abortSignal: signal,
-            stopWhen: stepCountIs(5),
-            providerOptions: {
-              openai: useHandle
-                ? { store: true, previousResponseId: native!.previousResponseId }
-                : { store: true },
-            },
-          });
-          void result.providerMetadata.then((meta) => {
-            const rid = typeof meta?.openai?.responseId === "string" ? meta.openai.responseId : undefined;
-            if (rid) nativeStore.set(chatId, { provider: "openai", previousResponseId: rid });
-          });
-          return result;
-        }
-
-        return streamText({
-          model: anthropic("claude-sonnet-4-5"),
-          messages,
-          abortSignal: signal,
-          stopWhen: stepCountIs(5),
-          providerOptions: {
-            anthropic: {
-              contextManagement: {
-                edits: [{ type: "clear_tool_uses_20250919", trigger: { type: "input_tokens", value: 80_000 }, keep: { type: "tool_uses", value: 3 } }],
-              },
-            },
-          },
-        });
-      } catch (error) {
-        lastError = error; // Provider failed, try the next one in the order.
-      }
-    }
-    throw lastError;
-  },
-});
-```
-
-When Anthropic is down, the loop falls through to OpenAI. Because `compaction` has already reduced `messages` to a summary plus the last couple of exchanges, the switch sends the portable baseline, not megabytes of raw transcript.
-
-<Warning>
-  Fallback here retries a turn that hasn't started streaming yet. Once a response is streaming to the client, a mid-stream provider failure can't be swapped transparently. Surface the error and let the frontend regenerate the turn. See [Error handling](/ai-chat/error-handling).
-</Warning>
-
-## Production notes
-
-- **Persist the handles.** The `Map`s above (`nativeStore`, `clearedByChat`) work in the example because the run stays alive across turns, but they don't survive a run boundary. Store native handles and summaries in your database keyed by `chatId`, alongside your [message persistence](/ai-chat/patterns/database-persistence).
-- **No cross-provider translation.** Native compaction from one provider never transfers to another. The Trigger.dev `compaction` summary is the only portable baseline across a switch.
-- **Native compaction is opt-in per turn.** It applies only for the provider whose `providerOptions` you set on that turn's `streamText` call.
-
-## See also
-
-- [Compaction](/ai-chat/compaction): the provider-agnostic `compaction` option, `onCompacted`, and manual `chat.compact()`.
-- [Prompt caching](/ai-chat/prompt-caching): the other per-turn token optimization, and how it interacts with a growing history.
-- [Database persistence](/ai-chat/patterns/database-persistence): where to store native handles and summaries for real.
-- [Lifecycle hooks](/ai-chat/lifecycle-hooks): `onTurnComplete` and `onCompacted` in the broader hook taxonomy.