@trigger.dev/sdk 4.8.4 → 4.8.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (187) hide show
  1. package/dist/commonjs/v3/ai.d.ts +29 -5
  2. package/dist/commonjs/v3/ai.js +160 -114
  3. package/dist/commonjs/v3/ai.js.map +1 -1
  4. package/dist/commonjs/v3/auth.d.ts +4 -4
  5. package/dist/commonjs/v3/auth.js +21 -75
  6. package/dist/commonjs/v3/auth.js.map +1 -1
  7. package/dist/commonjs/v3/chat-client.d.ts +1 -1
  8. package/dist/commonjs/v3/chat.d.ts +1 -1
  9. package/dist/commonjs/v3/prompt.js +6 -8
  10. package/dist/commonjs/v3/prompt.js.map +1 -1
  11. package/dist/commonjs/v3/runs.d.ts +5 -1
  12. package/dist/commonjs/v3/runs.js.map +1 -1
  13. package/dist/commonjs/v3/sessions.js +10 -7
  14. package/dist/commonjs/v3/sessions.js.map +1 -1
  15. package/dist/commonjs/v3/shared.d.ts +2 -2
  16. package/dist/commonjs/v3/shared.js +16 -15
  17. package/dist/commonjs/v3/shared.js.map +1 -1
  18. package/dist/commonjs/v3/steeringContext.d.ts +35 -10
  19. package/dist/commonjs/v3/steeringContext.js +35 -12
  20. package/dist/commonjs/v3/steeringContext.js.map +1 -1
  21. package/dist/commonjs/v3/streams.js +10 -8
  22. package/dist/commonjs/v3/streams.js.map +1 -1
  23. package/dist/commonjs/v3/tasks.d.ts +2 -2
  24. package/dist/commonjs/v3/tasks.js.map +1 -1
  25. package/dist/commonjs/v3/test/mock-chat-agent.js +24 -13
  26. package/dist/commonjs/v3/test/mock-chat-agent.js.map +1 -1
  27. package/dist/commonjs/v3/webhooks.d.ts +8 -2
  28. package/dist/commonjs/v3/webhooks.js +20 -11
  29. package/dist/commonjs/v3/webhooks.js.map +1 -1
  30. package/dist/commonjs/version.js +1 -1
  31. package/dist/esm/v3/ai.d.ts +29 -5
  32. package/dist/esm/v3/ai.js +162 -117
  33. package/dist/esm/v3/ai.js.map +1 -1
  34. package/dist/esm/v3/auth.d.ts +4 -4
  35. package/dist/esm/v3/auth.js +22 -76
  36. package/dist/esm/v3/auth.js.map +1 -1
  37. package/dist/esm/v3/chat-client.d.ts +1 -1
  38. package/dist/esm/v3/chat.d.ts +1 -1
  39. package/dist/esm/v3/prompt.js +6 -8
  40. package/dist/esm/v3/prompt.js.map +1 -1
  41. package/dist/esm/v3/runs.d.ts +5 -1
  42. package/dist/esm/v3/runs.js.map +1 -1
  43. package/dist/esm/v3/sessions.js +10 -7
  44. package/dist/esm/v3/sessions.js.map +1 -1
  45. package/dist/esm/v3/shared.d.ts +2 -2
  46. package/dist/esm/v3/shared.js +16 -15
  47. package/dist/esm/v3/shared.js.map +1 -1
  48. package/dist/esm/v3/steeringContext.d.ts +35 -10
  49. package/dist/esm/v3/steeringContext.js +34 -12
  50. package/dist/esm/v3/steeringContext.js.map +1 -1
  51. package/dist/esm/v3/streams.js +10 -8
  52. package/dist/esm/v3/streams.js.map +1 -1
  53. package/dist/esm/v3/tasks.d.ts +2 -2
  54. package/dist/esm/v3/tasks.js.map +1 -1
  55. package/dist/esm/v3/test/mock-chat-agent.js +25 -14
  56. package/dist/esm/v3/test/mock-chat-agent.js.map +1 -1
  57. package/dist/esm/v3/webhooks.d.ts +8 -2
  58. package/dist/esm/v3/webhooks.js +20 -11
  59. package/dist/esm/v3/webhooks.js.map +1 -1
  60. package/dist/esm/version.js +1 -1
  61. package/docs/ai/observability.mdx +25 -19
  62. package/docs/ai/prompts.mdx +25 -19
  63. package/docs/ai-chat/actions.mdx +1 -1
  64. package/docs/ai-chat/anatomy.mdx +1 -1
  65. package/docs/ai-chat/backend.mdx +24 -24
  66. package/docs/ai-chat/background-injection.mdx +5 -5
  67. package/docs/ai-chat/chat-local.mdx +2 -2
  68. package/docs/ai-chat/compaction.mdx +38 -15
  69. package/docs/ai-chat/custom-agents.mdx +4 -4
  70. package/docs/ai-chat/error-handling.mdx +4 -4
  71. package/docs/ai-chat/fast-starts.mdx +8 -7
  72. package/docs/ai-chat/frontend.mdx +6 -2
  73. package/docs/ai-chat/lifecycle-hooks.mdx +11 -11
  74. package/docs/ai-chat/migrating-from-a-route-handler.mdx +4 -4
  75. package/docs/ai-chat/migrating-from-hydrate-messages.mdx +1 -1
  76. package/docs/ai-chat/overview.mdx +1 -1
  77. package/docs/ai-chat/patterns/branching-conversations.mdx +1 -1
  78. package/docs/ai-chat/patterns/database-persistence.mdx +2 -2
  79. package/docs/ai-chat/patterns/human-in-the-loop.mdx +1 -1
  80. package/docs/ai-chat/patterns/native-compaction.mdx +29 -9
  81. package/docs/ai-chat/patterns/persistence-and-replay.mdx +1 -1
  82. package/docs/ai-chat/patterns/redacting-telemetry.mdx +2 -2
  83. package/docs/ai-chat/patterns/skills.mdx +2 -2
  84. package/docs/ai-chat/patterns/sub-agents.mdx +1 -1
  85. package/docs/ai-chat/patterns/tool-result-auditing.mdx +1 -1
  86. package/docs/ai-chat/patterns/trusted-edge-signals.mdx +2 -2
  87. package/docs/ai-chat/patterns/version-upgrades.mdx +2 -2
  88. package/docs/ai-chat/pending-messages.mdx +5 -5
  89. package/docs/ai-chat/prompt-caching.mdx +7 -7
  90. package/docs/ai-chat/quick-start.mdx +2 -2
  91. package/docs/ai-chat/testing.mdx +9 -9
  92. package/docs/ai-chat/tools.mdx +9 -5
  93. package/docs/ai-chat/transcript-storage.mdx +2 -2
  94. package/docs/ai-chat/types.mdx +10 -3
  95. package/docs/apikeys.mdx +2 -1
  96. package/docs/cli-login-commands.mdx +12 -0
  97. package/docs/concurrency.mdx +40 -0
  98. package/docs/database-connections.mdx +1 -1
  99. package/docs/deploy-environment-variables.mdx +84 -2
  100. package/docs/deployment/trusted-publishing.mdx +4 -0
  101. package/docs/errors-retrying.mdx +25 -18
  102. package/docs/github-actions.mdx +1 -1
  103. package/docs/github-integration.mdx +21 -0
  104. package/docs/how-it-works.mdx +4 -2
  105. package/docs/introduction.mdx +1 -1
  106. package/docs/mcp-introduction.mdx +7 -1
  107. package/docs/mcp-remote.mdx +90 -0
  108. package/docs/oidc/azure.mdx +81 -0
  109. package/docs/oidc/databricks.mdx +99 -0
  110. package/docs/oidc/doppler.mdx +60 -0
  111. package/docs/oidc/gcp.mdx +109 -0
  112. package/docs/oidc/hugging-face.mdx +90 -0
  113. package/docs/oidc/openrouter.mdx +91 -0
  114. package/docs/oidc/snowflake.mdx +91 -0
  115. package/docs/oidc/vault.mdx +71 -0
  116. package/docs/oidc.mdx +2 -0
  117. package/docs/runs/metadata.mdx +1 -1
  118. package/docs/self-hosting/docker.mdx +2 -0
  119. package/docs/self-hosting/env/webapp.mdx +4 -1
  120. package/docs/self-hosting/kubernetes.mdx +2 -0
  121. package/docs/tasks/schemaTask.mdx +26 -13
  122. package/docs/tasks/streams.mdx +2 -2
  123. package/docs/troubleshooting.mdx +7 -0
  124. package/docs/webhooks/channels.mdx +6 -6
  125. package/docs/webhooks/connect.mdx +9 -75
  126. package/docs/webhooks/custom-providers.mdx +87 -0
  127. package/docs/webhooks/deliveries.mdx +7 -7
  128. package/docs/webhooks/filters.mdx +2 -2
  129. package/docs/webhooks/how-it-works.mdx +58 -0
  130. package/docs/webhooks/human-in-the-loop.mdx +3 -3
  131. package/docs/webhooks/linear.mdx +5 -3
  132. package/docs/webhooks/overview.mdx +20 -71
  133. package/docs/webhooks/own-handler.mdx +62 -0
  134. package/docs/webhooks/pricing-and-limits.mdx +13 -0
  135. package/docs/webhooks/providers/attio.mdx +38 -0
  136. package/docs/webhooks/providers/autumn.mdx +40 -0
  137. package/docs/webhooks/providers/cal-com.mdx +41 -0
  138. package/docs/webhooks/providers/calendly.mdx +41 -0
  139. package/docs/webhooks/providers/clerk.mdx +40 -0
  140. package/docs/webhooks/providers/discord.mdx +45 -0
  141. package/docs/webhooks/providers/docusign.mdx +41 -0
  142. package/docs/webhooks/providers/elevenlabs.mdx +41 -0
  143. package/docs/webhooks/providers/firecrawl.mdx +54 -0
  144. package/docs/webhooks/providers/github.mdx +46 -0
  145. package/docs/webhooks/providers/gitlab.mdx +41 -0
  146. package/docs/webhooks/providers/granola.mdx +44 -0
  147. package/docs/webhooks/providers/hookdeck.mdx +98 -0
  148. package/docs/webhooks/providers/infisical.mdx +41 -0
  149. package/docs/webhooks/providers/jira.mdx +41 -0
  150. package/docs/webhooks/providers/langfuse.mdx +40 -0
  151. package/docs/webhooks/providers/linear.mdx +45 -0
  152. package/docs/webhooks/providers/loops.mdx +40 -0
  153. package/docs/webhooks/providers/metronome.mdx +42 -0
  154. package/docs/webhooks/providers/mux.mdx +40 -0
  155. package/docs/webhooks/providers/openai.mdx +40 -0
  156. package/docs/webhooks/providers/pagerduty.mdx +40 -0
  157. package/docs/webhooks/providers/plain.mdx +41 -0
  158. package/docs/webhooks/providers/planetscale.mdx +40 -0
  159. package/docs/webhooks/providers/recall-ai.mdx +54 -0
  160. package/docs/webhooks/providers/replicate.mdx +41 -0
  161. package/docs/webhooks/providers/resend.mdx +44 -0
  162. package/docs/webhooks/providers/retell.mdx +41 -0
  163. package/docs/webhooks/providers/sentry.mdx +41 -0
  164. package/docs/webhooks/providers/shopify.mdx +49 -0
  165. package/docs/webhooks/providers/slack.mdx +48 -0
  166. package/docs/webhooks/providers/square.mdx +40 -0
  167. package/docs/webhooks/providers/stripe.mdx +86 -0
  168. package/docs/webhooks/providers/supabase.mdx +41 -0
  169. package/docs/webhooks/providers/tailscale.mdx +43 -0
  170. package/docs/webhooks/providers/typeform.mdx +42 -0
  171. package/docs/webhooks/providers/vapi.mdx +47 -0
  172. package/docs/webhooks/providers/vercel.mdx +40 -0
  173. package/docs/webhooks/providers/whatsapp.mdx +45 -0
  174. package/docs/webhooks/providers/workos.mdx +41 -0
  175. package/docs/webhooks/providers/zendesk.mdx +41 -0
  176. package/docs/webhooks/providers.mdx +53 -0
  177. package/docs/webhooks/quick-start.mdx +131 -0
  178. package/docs/webhooks/session-routing.mdx +6 -6
  179. package/docs/webhooks/signing-secrets.mdx +80 -0
  180. package/docs/webhooks/slack.mdx +11 -2
  181. package/docs/webhooks/verification.mdx +139 -0
  182. package/docs/webhooks/waiters.mdx +2 -2
  183. package/docs/webhooks/webhook-tasks.mdx +46 -0
  184. package/package.json +4 -5
  185. package/docs/migrating-from-v3.mdx +0 -332
  186. package/docs/webhooks/public-beta.mdx +0 -70
  187. package/docs/webhooks/sources.mdx +0 -252
@@ -92,7 +92,7 @@ export const myChatAgent = chat
92
92
  id: "my-chat",
93
93
  run: async ({ messages, clientData, signal, streamText }) => {
94
94
  return streamText({
95
- model: clientData?.model ?? "openai/gpt-4o-mini",
95
+ model: clientData?.model ?? "openai/gpt-6-luna",
96
96
  messages,
97
97
  abortSignal: signal,
98
98
  stopWhen: stepCountIs(15),
@@ -161,7 +161,7 @@ export const agent = chat
161
161
  id: "agent",
162
162
  run: async ({ messages, clientData, signal, streamText }) => {
163
163
  return streamText({
164
- model: clientData?.model ?? anthropic("claude-haiku-4-5"),
164
+ model: clientData?.model ?? anthropic("claude-haiku-5-5"),
165
165
  messages,
166
166
  abortSignal: signal,
167
167
  stopWhen: stepCountIs(15),
@@ -177,9 +177,13 @@ const harness = mockChatAgent(agent, {
177
177
  });
178
178
  ```
179
179
 
180
+ `clientData` reaches `run()` and the callbacks an agent can call a model from: `prepareMessages`, `onValidateMessages`, `onAction`, `onTurnComplete`, `onCompacted`, the compaction `shouldCompact` and `summarize` callbacks (between steps and between turns, also through `chat.MessageAccumulator` and `chat.createSession` turns), and the `pendingMessages` `onReceived` and `onInjected` callbacks. Read the mock model from `clientData` in each of them and those calls stay offline.
181
+
182
+ In a hand-rolled `chat.customAgent` loop that doesn't use `chat.createSession`, the SDK has no turn to read from. `conversation.prepareStep()` then calls the inner `summarize` without `chatId`, `turn` or `clientData`, so close over `clientData` when you build the `summarize` config. Pass `{ chatId, turn, clientData }` to `conversation.compactIfNeeded()` for the outer compaction.
183
+
180
184
  ## Driving turns
181
185
 
182
- The harness exposes one method per chat trigger. Each waits for the next `trigger:turn-complete` chunk before resolving.
186
+ The harness exposes one method per chat trigger. Each waits for the next `trigger:turn-complete` chunk, and for the turn's post-turn hooks (`onTurnComplete` and the transcript save) to finish, before resolving. You can assert on what those hooks recorded right after the `await`.
183
187
 
184
188
  ### sendMessage
185
189
 
@@ -283,9 +287,6 @@ const agent = chat.agent({
283
287
  const harness = mockChatAgent(agent, { chatId: "t" });
284
288
  await harness.sendMessage(userMessage("hi"));
285
289
 
286
- // onTurnComplete fires after the turn-complete chunk is written —
287
- // give it a tick before asserting.
288
- await new Promise((r) => setTimeout(r, 20));
289
290
  expect(events).toEqual([
290
291
  "onChatStart",
291
292
  "onTurnStart",
@@ -413,7 +414,6 @@ try {
413
414
  role: "user",
414
415
  parts: [{ type: "text", text: "where were we?" }],
415
416
  });
416
- await new Promise((r) => setTimeout(r, 20));
417
417
 
418
418
  expect(onChatStart).not.toHaveBeenCalled();
419
419
  expect(onTurnStart).toHaveBeenCalledTimes(1);
@@ -534,7 +534,7 @@ export const agent = chat.agent({
534
534
  });
535
535
  },
536
536
  run: async ({ messages, signal }) => {
537
- return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
537
+ return streamText({ model: anthropic("claude-sonnet-5-5"), messages, abortSignal: signal });
538
538
  },
539
539
  });
540
540
  ```
@@ -675,7 +675,7 @@ await runInMockTaskContext(
675
675
 
676
676
  - **No network.** The mock task context replaces realtime streams, run metadata, lifecycle managers, and the runtime. Anything that bypasses these (raw `fetch`, direct DB clients) runs against the real network.
677
677
  - **Single agent per process.** The resource catalog is process-global; tests within a file are sequential by default. If you parallelize across files, vitest runs each file in its own worker, which avoids registry collisions.
678
- - **Time-sensitive hooks.** `onTurnComplete` runs *after* the `turn-complete` chunk is written, so `sendMessage()` resolves before that hook finishes. Add a brief `await new Promise((r) => setTimeout(r, 20))` if you need to assert on hook side-effects.
678
+ - **Deferred work.** Turn methods wait for `onTurnComplete`, but not for work you start with `chat.defer()`. That work runs alongside the idle wait, as it does in production, so await your own promise before asserting on it.
679
679
  - **No real LLM.** The harness does not call providers — you must inject `MockLanguageModelV3` (or another mock) yourself.
680
680
 
681
681
  ## Check the deployed behavior
@@ -26,7 +26,7 @@ export const myChat = chat.agent({
26
26
  run: async ({ messages, tools, signal, streamText }) =>
27
27
  streamText({
28
28
  tools,
29
- model: anthropic("claude-sonnet-4-5"),
29
+ model: anthropic("claude-sonnet-5-5"),
30
30
  messages,
31
31
  abortSignal: signal,
32
32
  stopWhen: stepCountIs(15),
@@ -88,7 +88,7 @@ export const chartChat = chat.agent({
88
88
  run: async ({ messages, tools, signal, streamText }) =>
89
89
  streamText({
90
90
  tools,
91
- model: anthropic("claude-sonnet-4-5"),
91
+ model: anthropic("claude-sonnet-5-5"),
92
92
  messages,
93
93
  abortSignal: signal,
94
94
  stopWhen: stepCountIs(15),
@@ -112,7 +112,7 @@ export const myChat = chat
112
112
  run: async ({ messages, tools, signal, streamText }) =>
113
113
  streamText({
114
114
  tools,
115
- model: anthropic("claude-sonnet-4-5"),
115
+ model: anthropic("claude-sonnet-5-5"),
116
116
  messages,
117
117
  abortSignal: signal,
118
118
  stopWhen: stepCountIs(15),
@@ -120,6 +120,10 @@ export const myChat = chat
120
120
  });
121
121
  ```
122
122
 
123
+ <Note>
124
+ Claude 5.5 models bind each thinking block to the tool set it was produced with. Adding or removing a tool partway through a chat can make Anthropic reject the earlier thinking blocks with a 400, so keep a chat's tool set stable once it starts (for example, decide `plan`-based tools on the first turn).
125
+ </Note>
126
+
123
127
  The function receives a `ResolveToolsEvent` and runs once per turn (after `clientData` is parsed):
124
128
 
125
129
  | Field | Type | Description |
@@ -140,7 +144,7 @@ run: async ({ messages, tools, signal, streamText }) => {
140
144
  // `tools` is typed as your tool set, not a broad `ToolSet`
141
145
  return streamText({
142
146
  tools,
143
- model: anthropic("claude-sonnet-4-5"),
147
+ model: anthropic("claude-sonnet-5-5"),
144
148
  messages,
145
149
  abortSignal: signal,
146
150
  });
@@ -181,7 +185,7 @@ const messages = await convertToModelMessages(uiMessages, {
181
185
  ignoreIncompleteToolCalls: true,
182
186
  });
183
187
 
184
- return streamText({ model: anthropic("claude-sonnet-4-5"), messages, tools });
188
+ return streamText({ model: anthropic("claude-sonnet-5-5"), messages, tools });
185
189
  ```
186
190
 
187
191
  ## Learn more
@@ -36,7 +36,7 @@ import { anthropic } from "@ai-sdk/anthropic";
36
36
  export const myChat = chat.agent({
37
37
  id: "my-chat",
38
38
  run: async ({ messages, signal, streamText }) =>
39
- streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal }),
39
+ streamText({ model: anthropic("claude-sonnet-5-5"), messages, abortSignal: signal }),
40
40
  });
41
41
  ```
42
42
 
@@ -55,7 +55,7 @@ export const myChat = chat.agent({
55
55
  id: "my-chat",
56
56
  storage: myTranscriptStorage,
57
57
  run: async ({ messages, signal, streamText }) =>
58
- streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal }),
58
+ streamText({ model: anthropic("claude-sonnet-5-5"), messages, abortSignal: signal }),
59
59
  });
60
60
  ```
61
61
 
@@ -93,10 +93,12 @@ export const myChat = chat
93
93
  run: async ({ messages, tools, signal, streamText }) => {
94
94
  // `tools` is myTools, typed, handed back on the payload
95
95
  return streamText({
96
- model: anthropic("claude-sonnet-4-5"),
96
+ model: anthropic("claude-sonnet-5-5"),
97
97
  messages,
98
98
  tools,
99
99
  abortSignal: signal,
100
+ // Claude 5.5 models omit thinking text unless you ask for a summary
101
+ providerOptions: { anthropic: { thinking: { type: "adaptive", display: "summarized" } } },
100
102
  stopWhen: stepCountIs(15),
101
103
  });
102
104
  },
@@ -194,7 +196,12 @@ export const myChat = chat
194
196
  .agent({
195
197
  id: "my-chat",
196
198
  run: async ({ messages, signal, streamText }) => {
197
- return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
199
+ return streamText({
200
+ model: anthropic("claude-sonnet-5-5"),
201
+ messages,
202
+ abortSignal: signal,
203
+ providerOptions: { anthropic: { thinking: { type: "adaptive", display: "summarized" } } },
204
+ });
198
205
  },
199
206
  });
200
207
  ```
@@ -219,7 +226,7 @@ chat
219
226
  await createChatRecord(event.chatId);
220
227
  },
221
228
  run: async ({ messages, signal, streamText }) => {
222
- return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
229
+ return streamText({ model: anthropic("claude-sonnet-5-5"), messages, abortSignal: signal });
223
230
  },
224
231
  });
225
232
  ```
package/docs/apikeys.mdx CHANGED
@@ -123,11 +123,12 @@ The key must belong to the target environment. Use a Production key with `--env
123
123
 
124
124
  Give a key a list of allowed IP addresses to limit where it can be used. Requests using the key from any other address are rejected, so a leaked key is useless outside your network. They get the same `Invalid API key` error as a key that doesn't exist, so the response never confirms the key is real. If a working key suddenly returns that error, check its allowed IP addresses.
125
125
 
126
- - Enter one IPv4 or IPv6 address or CIDR range per line, for example `203.0.113.9` or `203.0.113.0/24`. A key can have up to 50 ranges.
126
+ - Add IPv4 or IPv6 addresses or CIDR ranges, for example `203.0.113.9` or `203.0.113.0/24`. Press Enter, comma or space after each one, or paste a list. A key can have up to 50 ranges.
127
127
  - Leave the list empty to allow any IP address.
128
128
  - Private and reserved ranges, such as `10.0.0.0/8` or `192.168.0.0/16`, are not accepted. Use the public addresses your requests come from.
129
129
  - Set the list when you create the key, or change it later with **Edit allowed IPs** in the key's menu. Changes take effect immediately.
130
130
  - The API keys page shows the IP address each key was last used from, so you can check it before saving a list.
131
+ - **Test an IP**, beside the list, checks whether an address would be allowed before you save.
131
132
  - [Public Access Tokens](/realtime/auth) created with the key are not IP-restricted, since they are meant for browsers. Creating one still requires an allowed IP address.
132
133
 
133
134
  <Tip>
@@ -26,6 +26,18 @@ yarn dlx trigger.dev@latest login
26
26
 
27
27
  When the CLI opens your browser, approving the login sends you back to the CLI automatically. If the browser is on another machine, for example when you're connected over SSH, use `--no-browser`: after you approve, the page shows a code to paste into the terminal.
28
28
 
29
+ ## Login expiry
30
+
31
+ A login stops working after 7 days without use. The 7 days count from the last command that used it, or from when you logged in if you never used it. Running a command that uses your login, such as `dev` or `deploy`, at least once a week keeps you logged in.
32
+
33
+ When a login has expired, commands that log you in, such as `login`, `dev` and `deploy`, start a new login. You don't need to log out first. The [MCP server](/mcp-introduction#authentication) does the same on its next tool call.
34
+
35
+ - **In CI**, the CLI can't complete a login, so it fails and tells you to run `npx trigger.dev@latest login`. To deploy from CI, use an environment API key in `TRIGGER_ACCESS_TOKEN` instead of a copied CLI login. See [CI / GitHub Actions](/github-actions).
36
+ - **CLI versions before 4.8.4** show the server's error but can't start a new login over an expired one. Run `trigger.dev logout`, then `trigger.dev login`.
37
+ - **Logins made before login expiry was introduced** (in 4.8.4 for self-hosted instances) don't expire.
38
+
39
+ If you self-host, `CLI_LOGIN_IDLE_TIMEOUT_DAYS` sets the window (default `7`), and `0` turns idle expiry off for new logins. Each login keeps the setting it was created with. See the [webapp environment variables](/self-hosting/env/webapp).
40
+
29
41
  ## Options
30
42
 
31
43
  <ParamField body="No browser" type="--no-browser">
@@ -201,6 +201,46 @@ export const processWebhook = task({
201
201
  await processWebhook.trigger(payload, { concurrencyKey: tenantId });
202
202
  ```
203
203
 
204
+ ## A different key for each limit
205
+
206
+ A string `concurrencyKey` keys every `perKey` bound the run holds. When two limits need different keys, for example a cap per session and a cap per organization on the same run, pass an object. `default` is the run's own key, and every other entry is a named limit and the key to use for it:
207
+
208
+ ```ts /trigger/subagent.ts
209
+ import { concurrencyLimit, task } from "@trigger.dev/sdk";
210
+
211
+ // each organization runs at most 20 sub-agents at once
212
+ export const orgLimit = concurrencyLimit({ name: "org-subagents", perKey: 20 });
213
+
214
+ export const subagent = task({
215
+ id: "subagent",
216
+ // 3 per session, 200 in total, plus the organization limit
217
+ concurrency: [{ perKey: 3, total: 200 }, orgLimit],
218
+ run: async (payload) => {
219
+ //...
220
+ },
221
+ });
222
+ ```
223
+
224
+ ```ts app/api/subagent/route.ts
225
+ import { orgLimit, subagent } from "~/trigger/subagent";
226
+
227
+ await subagent.trigger(payload, {
228
+ concurrencyKey: {
229
+ default: sessionId,
230
+ [orgLimit.name]: orgId,
231
+ },
232
+ });
233
+ ```
234
+
235
+ The run starts only when the session has fewer than 3 running, the organization has fewer than 20, and fewer than 200 are running in total.
236
+
237
+ - **A limit uses its own entry if it has one, otherwise `default`.** A string is shorthand for `{ default: "..." }`.
238
+ - **`default` is required.** Runs are queued and scheduled fairly per default key, so pick the key you want fairness across.
239
+ - **A limit's own key is 1-128 characters.**
240
+ - **An entry for a limit the task doesn't declare adds that limit to the run.** If the limit is declared in the same environment, by another task or by a deploy that is still rolling out, the run counts towards it, so triggers keep working during the deploy.
241
+ - **A name that matches no declared limit caps nothing**, and the limit you meant falls back to `default`. Use `[limit.name]` rather than a string literal.
242
+ - **`default` always means the default key**, so a limit that is itself named `default` can't be given its own key.
243
+
204
244
  ## A global cap for a shared resource
205
245
 
206
246
  To cap something global, like total traffic to an external API, across many tasks and all tenants: declare a limit with only a `total` and share it. It counts every run holding it, whether or not the run has a `concurrencyKey`:
@@ -186,7 +186,7 @@ export const myChat = chat.agent({
186
186
  const user = await prisma.user.findUnique({ where: { id: clientData.userId } });
187
187
  // The connection is back in the pool before the model stream starts.
188
188
  return streamText({
189
- model: openai("gpt-4o"),
189
+ model: openai("gpt-6-luna"),
190
190
  system: `Helping ${user?.name ?? "the user"}.`,
191
191
  messages,
192
192
  abortSignal: signal,
@@ -79,12 +79,94 @@ You can edit an environment variable's values. You cannot edit the key name, you
79
79
  </Step>
80
80
 
81
81
  <Step title="Press delete">
82
- This will immediately delete the variable. ![Environment variables
82
+ Confirm in the dialog to delete the variable's value from that environment. This can't be
83
+ undone. ![Environment variables
83
84
  page](/images/environment-variables-delete-popover.png)
84
85
  </Step>
85
86
 
86
87
  </Steps>
87
88
 
89
+ #### Deleting several values at once
90
+
91
+ Each row on the Environment Variables page is one value: a key in one environment or preview branch. You can select up to 100 values and delete them in one step.
92
+
93
+ <Steps>
94
+
95
+ <Step title="Tick the values to delete">
96
+ Tick the checkbox on each row, or tick the checkbox in the table header to select the values on
97
+ the current page. Shift-click selects a range. A bar at the bottom of the list shows how many
98
+ values are selected.
99
+ </Step>
100
+
101
+ <Step title="Press Delete in the bar">
102
+ The confirmation lists every selected value and counts them per environment.
103
+ </Step>
104
+
105
+ <Step title="Type the confirmation words and press Delete">
106
+ The selected values are deleted together. If any of them can't be deleted, none are.
107
+ </Step>
108
+
109
+ </Steps>
110
+
111
+ The selection applies to the current view of the list, so it clears when you change the filter, search, sort or page. A row has no checkbox when you don't have permission to delete its value. Deleting a preview branch's override makes that branch use the Preview value again.
112
+
113
+ ### Comparing two environments
114
+
115
+ The compare view lists the keys that differ between two environments, so you don't have to read both lists side by side. Press **Compare** on the Environment Variables page to open it with the current environment on the left. Each side can be your Dev environment, Staging, Prod, Preview or one preview branch: pick them in the column headers. The two sides are in the URL, so you can share a comparison.
116
+
117
+ The filters narrow the list:
118
+
119
+ | Filter | Lists the keys that |
120
+ | --- | --- |
121
+ | All | differ in any way (every key except the ones that are the same) |
122
+ | Different | are set on both sides with different values |
123
+ | Missing | are set on one side only (one filter for each side) |
124
+ | Empty | are empty on one side only |
125
+ | Same | have the same value on both sides |
126
+
127
+ Secrets are compared on the server: the view says whether two secrets are the same or different, and never shows either value. A secret is never compared with a plain value, because the plain value on the page would reveal the secret; such keys are listed under All and say they weren't compared. A side you don't have permission to read shows "Permission denied" and is never compared.
128
+
129
+ Comparing a preview branch with Preview lists the branch's own overrides. To compare only some keys, tick them on the Environment Variables page and press **Compare** in the bar. Up to 1,000 keys can be compared at once; above that, search to narrow them down or compare ticked keys.
130
+
131
+ #### Copying values across
132
+
133
+ You can copy values from one side of the comparison to the other, in either direction.
134
+
135
+ <Steps>
136
+
137
+ <Step title="Choose the values">
138
+ Hover a row and press **Copy to** with the target environment's name, or tick up to 100 rows and
139
+ press **Copy to** in the bar at the bottom of the list.
140
+ </Step>
141
+
142
+ <Step title="Confirm">
143
+ The dialog says which keys are added to the target and which existing values are replaced, and
144
+ which ticked keys are skipped (not set or not readable on the source side, already the same, or
145
+ empty when your organization doesn't allow empty values). Copying several values asks you to type
146
+ two words to confirm.
147
+ </Step>
148
+
149
+ </Steps>
150
+
151
+ The values are copied together: if any of them can't be copied, none are. A copied secret stays a secret, and a value copied onto a secret stays a secret. You need permission to read the source environment and to change the target. Copying replaces values in the target environment, so runs that start afterwards use the new values.
152
+
153
+ ### Values that need attention
154
+
155
+ The Needs attention page lists the keys in one environment that are probably wrong or worth a second look. Press **Needs attention** on the Environment Variables page to open it; the button shows how many keys need attention in the current environment, leaving out empty values. Pick the environment (your Dev environment, Staging, Prod or Preview) in the value column's header.
156
+
157
+ | Tab | Lists the keys that |
158
+ | --- | --- |
159
+ | All | need attention for any reason, grouped by the most pressing one |
160
+ | Missing here | are set in another of Dev, Staging and Prod but not in this environment |
161
+ | Empty | are set to an empty string, secrets included |
162
+ | Replace with OIDC | hold credentials that [OIDC](/oidc) could replace, in deployed environments when your organization has OIDC |
163
+ | Changed recently | were saved in the last 24 hours, newest first |
164
+ | Ignored | have a reason your team ignored |
165
+
166
+ A Missing here row offers **Copy from** to copy the value from an environment where it's set, through the same confirmation as [copying values across](#copying-values-across), or **Set** to enter a new one.
167
+
168
+ Ignore a reason when it's expected, such as a key that is only meant to exist in Prod. An ignore applies to one key, in one environment, for one reason, and is shared with everyone on the project, who see who ignored it and when. Ignored reasons move to the Ignored tab until someone presses **Stop ignoring**. An ignored empty value stops being ignored the next time the value is saved. Changed recently can't be ignored: a key leaves that tab a day after it was saved.
169
+
88
170
  ## Local development
89
171
 
90
172
  When running `npx trigger.dev dev`, the CLI automatically loads environment variables from these files in order (later files override any duplicate keys from earlier ones):
@@ -221,7 +303,7 @@ If your secrets live in [Infisical](https://infisical.com), sync them natively,
221
303
 
222
304
  Set it up in Infisical in two steps:
223
305
 
224
- 1. Add a **Trigger.dev App Connection** using a Trigger.dev Personal Access Token from your account settings. Self-hosted instances are supported.
306
+ 1. Add a **Trigger.dev App Connection** using a Trigger.dev Personal Access Token from your account settings. Self-hosted instances are supported. The token [expires](/management/authentication#pat-expiry) on the date you choose, so replace it in the App Connection before then to keep the sync running.
225
307
  2. Create a **Secret Sync**: choose the connection, pick the target organization, project and environment (Production, Staging, Development, or Preview), and set the secret path to sync.
226
308
 
227
309
  Follow the [Trigger.dev Secret Sync guide](https://infisical.com/docs/integrations/secret-syncs/trigger-dev) in the Infisical docs for the full walkthrough.
@@ -5,6 +5,10 @@ description: "Deploy from GitHub Actions without storing a Trigger.dev API key."
5
5
 
6
6
  Trusted publishing uses GitHub Actions OIDC tokens to authorize deployments. No Personal Access Token or environment API key is needed in GitHub secrets. Builds run entirely on Trigger.dev's build server.
7
7
 
8
+ ## Prerequisites
9
+
10
+ - Use the Trigger.dev CLI (`trigger.dev`) **4.8.4 or later**, including the CLI used in CI.
11
+
8
12
  ## Configure trust
9
13
 
10
14
  1. Select **Staging**, **Preview**, or **Production**, then open [**Trusted publishing**](https://cloud.trigger.dev/_/trusted-publishing) under **Security**.
@@ -216,7 +216,7 @@ export const openaiTask = task({
216
216
  run: async (payload: { prompt: string }) => {
217
217
  const chatCompletion = await openai.chat.completions.create({
218
218
  messages: [{ role: "user", content: payload.prompt }],
219
- model: "gpt-3.5-turbo",
219
+ model: "gpt-6-luna",
220
220
  });
221
221
 
222
222
  return chatCompletion.choices[0].message.content;
@@ -319,7 +319,7 @@ export const openaiTask = task({
319
319
  //if this fails, it will throw an error and stop retrying
320
320
  const chatCompletion = await openai.chat.completions.create({
321
321
  messages: [{ role: "user", content: payload.prompt }],
322
- model: "gpt-3.5-turbo",
322
+ model: "gpt-6-luna",
323
323
  });
324
324
 
325
325
  if (chatCompletion.choices[0]?.message.content === undefined) {
@@ -334,10 +334,15 @@ export const openaiTask = task({
334
334
 
335
335
  ### Using try/catch
336
336
 
337
- Sometimes you want to catch an error and don't want to retry the task. You can use try/catch as you normally would. In this example we fallback to using Replicate if OpenAI fails.
337
+ Sometimes you want to catch an error and don't want to retry the task. You can use try/catch as you normally would. In this example we fall back to using Anthropic if OpenAI fails.
338
338
 
339
339
  ```ts /trigger/myTasks.ts
340
340
  import { task } from "@trigger.dev/sdk";
341
+ import Anthropic from "@anthropic-ai/sdk";
342
+ import OpenAI from "openai";
343
+
344
+ const openai = new OpenAI();
345
+ const anthropic = new Anthropic();
341
346
 
342
347
  export const openaiTask = task({
343
348
  id: "openai-task",
@@ -346,7 +351,7 @@ export const openaiTask = task({
346
351
  //if this fails, it will throw an error and retry
347
352
  const chatCompletion = await openai.chat.completions.create({
348
353
  messages: [{ role: "user", content: payload.prompt }],
349
- model: "gpt-3.5-turbo",
354
+ model: "gpt-6-luna",
350
355
  });
351
356
 
352
357
  if (chatCompletion.choices[0]?.message.content === undefined) {
@@ -356,23 +361,25 @@ export const openaiTask = task({
356
361
 
357
362
  return chatCompletion.choices[0].message.content;
358
363
  } catch (error) {
359
- //use Replicate if OpenAI fails
360
- const prediction = await replicate.run(
361
- "meta/llama-2-70b-chat:02e509c789964a7ea8736978a43525956ef40397be9033abf9fd2badfe68c9e3",
362
- {
363
- input: {
364
- prompt: payload.prompt,
365
- max_new_tokens: 250,
366
- },
367
- }
368
- );
364
+ //use Anthropic if OpenAI fails
365
+ const message = await anthropic.messages.create({
366
+ model: "claude-haiku-5-5",
367
+ max_tokens: 16000,
368
+ messages: [{ role: "user", content: payload.prompt }],
369
+ });
370
+
371
+ //the response can include thinking blocks, so only read the text blocks
372
+ const text = message.content
373
+ .filter((block) => block.type === "text")
374
+ .map((block) => block.text)
375
+ .join("");
369
376
 
370
- if (prediction.output === undefined) {
371
- //retry if Replicate fails
372
- throw new Error("Replicate call failed");
377
+ if (!text) {
378
+ //retry if Anthropic fails
379
+ throw new Error("Anthropic call failed");
373
380
  }
374
381
 
375
- return prediction.output;
382
+ return text;
376
383
  }
377
384
  },
378
385
  });
@@ -3,7 +3,7 @@ title: "CI / GitHub Actions"
3
3
  description: "Deploy your tasks from CI using trusted deploys or an environment API key."
4
4
  ---
5
5
 
6
- For GitHub Actions without stored credentials, use [Trusted publishing](/deployment/trusted-publishing) with OIDC. The API-key instructions below also apply to other CI systems. Use an environment API key rather than a Personal Access Token so deployments are not tied to an individual team member's account or permissions.
6
+ For GitHub Actions without stored credentials, use [Trusted publishing](/deployment/trusted-publishing) with OIDC. The API-key instructions below also apply to other CI systems. Use an environment API key rather than a Personal Access Token so deployments are not tied to an individual team member's account or permissions. A Personal Access Token also [expires](/management/authentication#pat-expiry) on the date chosen when it was created, and a copied CLI login [expires after 7 days without use](/cli-login-commands#login-expiry).
7
7
 
8
8
  <Tip>
9
9
  Check out our new [GitHub integration](/github-integration) for automatic deployments, without adding any GitHub Actions workflows.
@@ -72,6 +72,27 @@ The name of the preview branch matches the branch name of the pull request.
72
72
  Preview branch deployments require the preview environment to be enabled on your project. Learn more about [preview branches](/deployment/preview-branches).
73
73
  </Note>
74
74
 
75
+ ## Ignored branches
76
+
77
+ Ignored branches stop pull requests from matching branches from getting a preview deployment, for example Dependabot updates.
78
+
79
+ Open **Integrations** in your project settings and add the patterns in the git settings panel, one per line. Use **Test a branch** to check which pattern, if any, matches a branch.
80
+
81
+ ```text
82
+ dependabot/**
83
+ skip-preview/**
84
+ ```
85
+
86
+ - Patterns match the whole branch name. `*` stays within one part of the name and `**` also crosses `/`, so `skip-preview/**` matches `skip-preview/login` and `skip-preview` itself.
87
+ - Negation (`!`), braces (`{a,b}`) and extglob groups like `@(a|b)` aren't supported. A pattern can use `**` at most twice and `*` at most twice more, and you can add up to 100 patterns of up to 256 characters each.
88
+ - Only previews are affected: pushes to your production and staging branches always deploy, and a preview deployed before you added a pattern is archived as usual.
89
+
90
+ When a preview is skipped, the pull request's Trigger.dev check is marked as skipped with the matching pattern. Re-run that check from GitHub to deploy the preview anyway.
91
+
92
+ <Warning>
93
+ If your project is connected to Vercel, ignore the same branches in both places. A Vercel preview of a branch that Trigger.dev ignores has no task deployment for its commit, so with [version skew protection](/vercel-integration#version-skew-protection) its runs wait for one and [expire after an hour](/deployment/atomic-deployment#waiting-and-expiry).
94
+ </Warning>
95
+
75
96
  ## Ignored paths
76
97
 
77
98
  Skip builds for pushes that only touch files your tasks do not depend on, such as docs or another app in a monorepo.
@@ -1,12 +1,14 @@
1
1
  ---
2
2
  title: "How Trigger.dev works"
3
3
  sidebarTitle: "How it works"
4
- description: "Understand how Trigger.dev works and how it can help you."
4
+ description: "Understand how Trigger.dev runs durable AI agents and workflows."
5
5
  ---
6
6
 
7
7
  ## Introduction
8
8
 
9
- Trigger.dev allows you to integrate long-running async tasks into your application and run them in the background. This allows you to offload tasks that take a long time to complete, such as sending multi-day email campaigns, processing videos, or running long chains of AI tasks.
9
+ Trigger.dev is the open source platform for building and running durable AI agents and workflows in TypeScript. You write tasks and agents in your existing codebase, and they run on Trigger.dev with retries, queues, waits, full tracing, and elastic scaling. There's no execution timeout, so you can offload work that takes a long time to complete, such as AI agents with human-in-the-loop approvals, processing videos, or sending multi-day email campaigns.
10
+
11
+ To build durable chat agents, see [AI Agents](/ai-chat/overview).
10
12
 
11
13
  For example, the below task processes a video with `ffmpeg` and sends the results to an s3 bucket, then updates a database with the results and sends an email to the user.
12
14
 
@@ -44,7 +44,7 @@ export const supportAgent = chat.agent({
44
44
  id: "support-agent",
45
45
  run: async ({ messages, signal, streamText }) =>
46
46
  streamText({
47
- model: anthropic("claude-sonnet-4-5"),
47
+ model: anthropic("claude-sonnet-5-5"),
48
48
  messages,
49
49
  abortSignal: signal,
50
50
  }),
@@ -16,6 +16,10 @@ The Trigger.dev MCP (Model Context Protocol) Server enables AI assistants to int
16
16
  - Monitor run details and list runs with filtering options
17
17
  - Query your data with TRQL and run built-in dashboard metrics
18
18
 
19
+ <Note>
20
+ This page covers the CLI MCP server, which runs locally and can deploy and run your dev server. To connect over HTTP without installing anything, use the [remote MCP server](/mcp-remote).
21
+ </Note>
22
+
19
23
  ## Installation
20
24
 
21
25
  The quickest way to get set up is the interactive installer:
@@ -299,7 +303,9 @@ After adding the config, restart your client. You should see a server named **tr
299
303
 
300
304
  ## Authentication
301
305
 
302
- The `search_docs` tool works without authentication, and so do the local-only tools `list_profiles`, `dev_server_status` and `stop_dev_server`. All other tools require you to be logged in via the [Trigger.dev CLI](/cli-login-commands). The first time you use an authenticated tool, your MCP client will prompt you to log in.
306
+ The `search_docs` tool works without authentication, and so do the local-only tools `list_profiles`, `dev_server_status` and `stop_dev_server`. All other tools require you to be logged in via the [Trigger.dev CLI](/cli-login-commands). The first time you use an authenticated tool, your MCP client prompts you to log in.
307
+
308
+ A login stops working after 7 days without use. The next authenticated tool call starts the login flow again. If your client supports confirmation prompts, it asks first. Then the browser opens, and the call continues once you approve. See [CLI login expiry](/cli-login-commands#login-expiry).
303
309
 
304
310
  <Accordion title="CLI Options">
305
311