@trigger.dev/sdk 0.0.0-python-preview-20250226140121 → 0.0.0-rc-4-8-0-20261021151928

package/docs/idempotency.mdx

@@ -0,0 +1,542 @@
+---
+title: "Idempotency"
+description: "An API call or operation is idempotent if it has the same result when called more than once."
+---
+
+**Idempotency keys deduplicate task triggers.** If you trigger a task with the same `idempotencyKey` twice, the second request does not create a new run. It returns the original run's handle, so you can track the existing run's progress.
+
+The key applies to the trigger call and nothing else. It deduplicates `trigger()`, `triggerAndWait()`, and `batchTrigger()`; it does not make the code inside a task's `run()` function idempotent. See [Side effects inside `run()`](#side-effects-inside-run) for what that means when a task calls an external API.
+
+## Why use idempotency keys?
+
+The most common use case is **preventing duplicate child tasks when a parent task retries**. Without idempotency keys, each retry of the parent would trigger a new child task run:
+
+```mermaid
+sequenceDiagram
+    participant Parent as Parent Task
+    participant SDK as Trigger.dev
+    participant Child as Child Task
+
+    Note over Parent: Attempt 1
+    Parent->>SDK: trigger(childTask, {idempotencyKey})
+    SDK->>Child: Creates child run
+    Child-->>SDK: Running...
+    Parent->>Parent: Fails, will retry
+
+    Note over Parent: Attempt 2 (retry)
+    Parent->>SDK: trigger(childTask, {idempotencyKey})
+    Note over SDK: Same key, returns existing run
+    SDK-->>Parent: Returns original child run
+    
+    Note over Child: Child task only runs once
+```
+
+Other common use cases include:
+
+- **Preventing duplicate emails** - Trigger the email task once, even if the parent task retries
+- **Avoiding double-charging customers** - Trigger the payment task once, even if the parent task retries. The payment API call itself still needs the provider's own idempotency key, see [Side effects inside `run()`](#side-effects-inside-run)
+- **One-time setup tasks** - Trigger initialization or migration tasks once
+- **Deduplicating webhook processing** - Trigger the handler task once per webhook event, even if the event is delivered multiple times
+
+## Side effects inside `run()`
+
+An idempotency key stops a task from being *triggered* twice. It does not stop the code inside that task from *running* twice. When a run retries, `run()` executes again from the top, and every API call, database write, or email inside it happens again unless that operation is itself idempotent.
+
+This matters most for payments. A refund issued directly inside a retryable task is issued again on every retry, even when the retry is caused by an unrelated failure later in the same function. Moving the refund into a child task and triggering it with an idempotency key does not close the gap either: the child is triggered once, but its own `run()` can retry after the provider has accepted the request. Only the provider can deduplicate its own API call.
+
+Pass the provider's idempotency key on every call that must happen at most once. Derive it from a value that stays the same across every attempt of the run. The run ID, `ctx.run.id`, always qualifies: retries are attempts of the same run, so the ID does not change between them. This is the same value the default `run` scope mixes into a Trigger.dev idempotency key.
+
+```ts /trigger/refund-order.ts
+import { idempotencyKeys, task } from "@trigger.dev/sdk";
+import Stripe from "stripe";
+import { sendRefundEmail } from "./send-refund-email";
+
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
+
+export const refundOrder = task({
+  id: "refund-order",
+  retry: { maxAttempts: 3 },
+  run: async (payload: { orderId: string; paymentIntentId: string; amount: number }, { ctx }) => {
+    // The run ID is stable across retries, so Stripe returns the original refund instead of creating a second one
+    await stripe.refunds.create(
+      { payment_intent: payload.paymentIntentId, amount: payload.amount },
+      { idempotencyKey: `refund-${ctx.run.id}` }
+    );
+
+    // The Trigger.dev key is run-scoped by default, so a retry does not create a second email run
+    const idempotencyKey = await idempotencyKeys.create("refund-email");
+    await sendRefundEmail.trigger({ orderId: payload.orderId }, { idempotencyKey });
+  },
+});
+```
+
+The run ID protects against retries of one run. If the same task can be triggered more than once for the same order, either trigger it with a Trigger.dev idempotency key so repeated triggers resolve to the same run and the same run ID, or key the provider call on a business ID from your payload instead, such as `refund-${payload.orderId}`, which deduplicates across separate runs too.
+
+Use a Trigger.dev idempotency key to stop a retry triggering a task twice, and the provider's idempotency key to stop a retry calling the provider twice. For a side effect with no idempotency support, record that you performed it in your own database and check that record before performing it again.
+
+## `idempotencyKey` option
+
+You can provide an `idempotencyKey` when triggering a task:
+
+```ts
+import { idempotencyKeys, task } from "@trigger.dev/sdk";
+
+export const myTask = task({
+  id: "my-task",
+  retry: {
+    maxAttempts: 4,
+  },
+  run: async (payload: any) => {
+    // This idempotency key will be unique to this task run, meaning the childTask will only be triggered once across all retries
+    const idempotencyKey = await idempotencyKeys.create("my-task-key");
+
+    // childTask will only be triggered once with the same idempotency key
+    await childTask.trigger({ foo: "bar" }, { idempotencyKey });
+
+    // Do something else, that may throw an error and cause the task to be retried
+    throw new Error("Something went wrong");
+  },
+});
+```
+
+You can use the `idempotencyKeys.create` SDK function to create an idempotency key before passing it to the `options` object.
+
+We automatically inject the run ID when generating the idempotency key when running inside a task by default. You can turn it off by passing the `scope` option to `idempotencyKeys.create`:
+
+```ts
+import { idempotencyKeys, task } from "@trigger.dev/sdk";
+
+export const myTask = task({
+  id: "my-task",
+  retry: {
+    maxAttempts: 4,
+  },
+  run: async (payload: any) => {
+    // This idempotency key will be globally unique, meaning only a single task run will be triggered with this key
+    const idempotencyKey = await idempotencyKeys.create("my-task-key", { scope: "global" });
+
+    // childTask will only be triggered once with the same idempotency key
+    await childTask.trigger({ foo: "bar" }, { idempotencyKey });
+  },
+});
+```
+
+If you are triggering a task from your backend code, you can use the `idempotencyKeys.create` SDK function to create an idempotency key.
+
+```ts
+import { idempotencyKeys, tasks } from "@trigger.dev/sdk";
+
+// You can also pass an array of strings to create a idempotency key
+const idempotencyKey = await idempotencyKeys.create([myUser.id, "my-task"]);
+await tasks.trigger("my-task", { some: "data" }, { idempotencyKey });
+```
+
+You can also pass a string to the `idempotencyKey` option, without first creating it with `idempotencyKeys.create`.
+
+```ts
+import { myTask } from "./trigger/myTasks";
+
+// You can also pass an array of strings to create a idempotency key
+await myTask.trigger({ some: "data" }, { idempotencyKey: myUser.id });
+```
+
+<Note>
+When you pass a raw string, it defaults to `"run"` scope (scoped to the parent run). See [Default behavior](#default-behavior) for details on how scopes work and how to use global scope instead.
+</Note>
+
+<Note>Make sure you provide sufficiently unique keys to avoid collisions.</Note>
+
+<Note>
+Idempotency keys are limited to 2048 characters. Keys produced by `idempotencyKeys.create()` are 64-character hashes and always fit; this limit only matters if you pass a long raw string. Requests above the limit return `400`.
+</Note>
+
+You can pass the `idempotencyKey` when calling `batchTrigger` as well:
+
+```ts
+import { tasks } from "@trigger.dev/sdk";
+
+await tasks.batchTrigger("my-task", [
+  {
+    payload: { some: "data" },
+    options: { idempotencyKey: await idempotencyKeys.create(myUser.id) },
+  },
+]);
+```
+
+## Understanding scopes
+
+The `scope` option determines how your idempotency key is processed. When you provide a key, it gets hashed together with additional context based on the scope. This means the same key string can produce different idempotency behaviors depending on the scope you choose.
+
+### Available scopes
+
+| Scope | What gets hashed | Description | Use case |
+| --- | --- | --- | --- |
+| `"run"` | `key + parentRunId` | Key is combined with the parent run ID | Prevent duplicates within a single parent run (default) |
+| `"attempt"` | `key + parentRunId + attemptNumber` | Key is combined with the parent run ID and attempt number | Allow child tasks to re-run on each retry of the parent |
+| `"global"` | `key` | Key is used as-is, no context added | Ensure a task only runs once ever, regardless of parent |
+
+### `run` scope (default)
+
+The `run` scope makes the idempotency key unique to the current parent task run. This is the default behavior for both raw strings and `idempotencyKeys.create()`.
+
+```ts
+import { idempotencyKeys, task } from "@trigger.dev/sdk";
+
+export const processOrder = task({
+  id: "process-order",
+  retry: { maxAttempts: 3 },
+  run: async (payload: { orderId: string; email: string }) => {
+    // This key is scoped to this specific run of processOrder
+    // If processOrder retries, the same key still refers to the same child run
+    const idempotencyKey = await idempotencyKeys.create(`send-confirmation-${payload.orderId}`);
+
+    // sendEmail will only be triggered once, even if processOrder retries multiple times
+    await sendEmail.trigger(
+      { to: payload.email, subject: "Order confirmed" },
+      { idempotencyKey }
+    );
+
+    // ... more processing that might fail and cause a retry
+  },
+});
+```
+
+With `run` scope, if you trigger `processOrder` twice with different run IDs, both will send emails because the idempotency keys are different (they include different parent run IDs).
+
+### `attempt` scope
+
+The `attempt` scope makes the idempotency key unique to each attempt of the parent task. Use this when you want child tasks to re-execute on each retry.
+
+```ts
+import { idempotencyKeys, task } from "@trigger.dev/sdk";
+
+export const syncData = task({
+  id: "sync-data",
+  retry: { maxAttempts: 3 },
+  run: async (payload: { userId: string }) => {
+    // This key changes on each retry attempt
+    const idempotencyKey = await idempotencyKeys.create(`fetch-${payload.userId}`, {
+      scope: "attempt",
+    });
+
+    // fetchLatestData will run again on each retry, getting fresh data
+    const result = await fetchLatestData.triggerAndWait(
+      { userId: payload.userId },
+      { idempotencyKey }
+    );
+
+    // Process the fresh data...
+  },
+});
+```
+
+### `global` scope
+
+The `global` scope makes the idempotency key truly global across all runs. Use this when you want to ensure a task only runs once ever (until the TTL expires), regardless of which parent task triggered it.
+
+```ts
+import { idempotencyKeys, task } from "@trigger.dev/sdk";
+
+export const onboardUser = task({
+  id: "onboard-user",
+  run: async (payload: { userId: string; email: string }) => {
+    // This key is global - the welcome email will only be sent once per user,
+    // even if onboardUser is triggered multiple times from different places
+    const idempotencyKey = await idempotencyKeys.create(`welcome-email-${payload.userId}`, {
+      scope: "global",
+    });
+
+    await sendWelcomeEmail.trigger(
+      { to: payload.email },
+      { idempotencyKey, idempotencyKeyTTL: "7d" }
+    );
+  },
+});
+```
+
+<Note>
+Even with `global` scope, idempotency keys are still isolated to the specific task and environment. Using the same key to trigger *different* tasks will not deduplicate - both tasks will run. See [Environment and task scoping](#environment-and-task-scoping) for more details.
+</Note>
+
+## Default behavior
+
+Understanding the default behavior is important to avoid unexpected results:
+
+### Passing a raw string
+
+When you pass a raw string directly to the `idempotencyKey` option, it is automatically processed with `run` scope:
+
+```ts
+// These two are equivalent when called inside a task:
+await childTask.trigger(payload, { idempotencyKey: "my-key" });
+await childTask.trigger(payload, { idempotencyKey: await idempotencyKeys.create("my-key") });
+```
+
+<Warning>
+**Breaking change in v4.3.1:** In v4.3.0 and earlier, raw strings defaulted to `global` scope. Starting in v4.3.1, raw strings now default to `run` scope. If you're upgrading and relied on the previous global behavior, you must now explicitly use `idempotencyKeys.create("key", { scope: "global" })`.
+</Warning>
+
+This means raw strings are scoped to the parent run by default. If you want global behavior, you must explicitly create the key with `scope: "global"`:
+
+```ts
+// For global idempotency, you must use idempotencyKeys.create with scope: "global"
+const idempotencyKey = await idempotencyKeys.create("my-key", { scope: "global" });
+await childTask.trigger(payload, { idempotencyKey });
+```
+
+### Triggering from backend code
+
+When triggering tasks from your backend code (outside of a task), there is no parent run context. In this case, `run` and `attempt` scopes behave the same as `global` since there's no run ID or attempt number to inject:
+
+```ts
+// In your backend code (e.g., an API route)
+import { idempotencyKeys, tasks } from "@trigger.dev/sdk";
+
+// All three of these behave the same when called outside a task:
+await tasks.trigger("my-task", payload, { idempotencyKey: "my-key" });
+await tasks.trigger("my-task", payload, {
+  idempotencyKey: await idempotencyKeys.create("my-key", { scope: "run" }),
+});
+await tasks.trigger("my-task", payload, {
+  idempotencyKey: await idempotencyKeys.create("my-key", { scope: "global" }),
+});
+```
+
+<Note>
+When triggering from backend code, the scope doesn't matter since there's no task context. All scopes effectively behave as global.
+</Note>
+
+## `idempotencyKeyTTL` option
+
+The `idempotencyKeyTTL` option defines a time window during which a task with the same idempotency key will only run once. Here's how it works:
+
+1. When you trigger a task with an idempotency key and set `idempotencyKeyTTL: "5m"`, it creates a 5-minute window.
+2. During this window, any subsequent triggers with the same idempotency key will return the original task run instead of creating a new one.
+3. Once the TTL window expires, the next trigger with that idempotency key will create a new task run and start a new time window.
+
+![idempotency-key-ttl](/images/idempotency-key-ttl.png)
+
+By default idempotency keys are stored for 30 days. You can change this by passing the `idempotencyKeyTTL` option when triggering a task:
+
+```ts
+import { idempotencyKeys, task, wait } from "@trigger.dev/sdk";
+
+export const myTask = task({
+  id: "my-task",
+  retry: {
+    maxAttempts: 4,
+  },
+  run: async (payload: any) => {
+    const idempotencyKey = await idempotencyKeys.create("my-task-key");
+
+    // The idempotency key will expire after 60 seconds
+    await childTask.trigger({ foo: "bar" }, { idempotencyKey, idempotencyKeyTTL: "60s" });
+
+    await wait.for({ seconds: 61 });
+
+    // The idempotency key will have expired, so the childTask will be triggered again
+    await childTask.trigger({ foo: "bar" }, { idempotencyKey });
+
+    // Do something else, that may throw an error and cause the task to be retried
+    throw new Error("Something went wrong");
+  },
+});
+```
+
+You can use the following units for the `idempotencyKeyTTL` option:
+
+- `s` for seconds (e.g. `60s`)
+- `m` for minutes (e.g. `5m`)
+- `h` for hours (e.g. `2h`)
+- `d` for days (e.g. `3d`)
+
+## Failed runs and idempotency
+
+When a run with an idempotency key **fails**, the key is automatically cleared. This means triggering the same task with the same idempotency key will create a new run. However, **successful** and **canceled** runs keep their idempotency key. If you need to re-trigger after a successful or canceled run, you can:
+
+1. **Reset the idempotency key** using `idempotencyKeys.reset()`:
+
+```ts
+import { idempotencyKeys } from "@trigger.dev/sdk";
+
+// Clear the idempotency key to allow re-triggering
+await idempotencyKeys.reset("my-task", "my-idempotency-key");
+
+// Now you can trigger the task again
+await myTask.trigger(payload, { idempotencyKey: "my-idempotency-key" });
+```
+
+2. **Use a shorter TTL** so the key expires automatically:
+
+```ts
+// Key expires after 5 minutes
+await myTask.trigger(payload, { 
+  idempotencyKey: "my-key", 
+  idempotencyKeyTTL: "5m" 
+});
+```
+
+## Payload-based idempotency
+
+We don't currently support payload-based idempotency, but you can implement it yourself by hashing the payload and using the hash as the idempotency key.
+
+```ts
+import { idempotencyKeys, task } from "@trigger.dev/sdk";
+import { createHash } from "node:crypto";
+
+// Somewhere in your code
+const idempotencyKey = await idempotencyKeys.create(hash(childPayload));
+// childTask will only be triggered once with the same idempotency key
+await tasks.trigger("child-task", { some: "payload" }, { idempotencyKey });
+
+// Create a hash of the payload using Node.js crypto
+// Ideally, you'd do a stable serialization of the payload before hashing, to ensure the same payload always results in the same hash
+function hash(payload: any): string {
+  const hash = createHash("sha256");
+  hash.update(JSON.stringify(payload));
+  return hash.digest("hex");
+}
+```
+
+## Resetting idempotency keys
+
+You can reset an idempotency key to clear it from all associated runs. This is useful if you need to allow a task to be triggered again with the same idempotency key.
+
+When you reset an idempotency key, it will be cleared for all runs that match both the task identifier and the idempotency key in the current environment. This allows you to trigger the task again with the same key.
+
+### API signature
+
+```ts
+idempotencyKeys.reset(
+  taskIdentifier: string,
+  idempotencyKey: string,
+  requestOptions?: ZodFetchOptions
+): Promise<{ id: string }>
+```
+
+| Parameter | Description |
+| --- | --- |
+| `taskIdentifier` | The identifier of the task (e.g., `"my-task"`) |
+| `idempotencyKey` | The idempotency key hash to reset (the 64-character hash string) |
+| `requestOptions` | Optional fetch options for the API request |
+
+### Resetting keys created with `idempotencyKeys.create()`
+
+When you pass an `IdempotencyKey` created with `idempotencyKeys.create()`, the scope and original key are automatically extracted, making it easy to reset:
+
+```ts
+import { idempotencyKeys, task } from "@trigger.dev/sdk";
+
+export const parentTask = task({
+  id: "parent-task",
+  run: async (payload) => {
+    const key = await idempotencyKeys.create("my-key", { scope: "global" });
+    await childTask.trigger(payload, { idempotencyKey: key });
+
+    // Later in the same task, reset it - options extracted automatically
+    await idempotencyKeys.reset("child-task", key);
+  },
+});
+```
+
+### Resetting global keys
+
+Global keys are the simplest to reset since they don't require any run context:
+
+```ts
+import { idempotencyKeys } from "@trigger.dev/sdk";
+
+// From anywhere - inside a task or from your backend code
+await idempotencyKeys.reset("my-task", "my-key", { scope: "global" });
+```
+
+### Resetting run-scoped keys
+
+Keys created with `"run"` scope (the default) include the parent run ID in the hash. When resetting from inside the same task, the run ID is automatically available:
+
+```ts
+import { idempotencyKeys, task } from "@trigger.dev/sdk";
+
+export const parentTask = task({
+  id: "parent-task",
+  run: async (payload) => {
+    // Create a run-scoped key (default)
+    const key = await idempotencyKeys.create("my-key");
+    await childTask.trigger(payload, { idempotencyKey: key });
+
+    // Reset works automatically inside the task - run ID is available from context
+    await idempotencyKeys.reset("child-task", key);
+  },
+});
+```
+
+When resetting from outside a task, you must provide the `parentRunId` if the key was created within a task context:
+
+```ts
+import { idempotencyKeys } from "@trigger.dev/sdk";
+
+// If the key was created within a task, you need the parent run ID
+await idempotencyKeys.reset("my-task", "my-key", {
+  scope: "run",
+  parentRunId: "run_abc123"
+});
+```
+
+<Note>
+If you triggered the task from backend code, all scopes behave as global (see [Triggering from backend code](#triggering-from-backend-code)). Use `scope: "global"` when resetting.
+</Note>
+
+### Resetting attempt-scoped keys
+
+Keys created with `"attempt"` scope include both the parent run ID and attempt number. When resetting from outside a task, you must provide both:
+
+```ts
+import { idempotencyKeys } from "@trigger.dev/sdk";
+
+// From your backend code
+await idempotencyKeys.reset("my-task", "my-key", {
+  scope: "attempt",
+  parentRunId: "run_abc123",
+  attemptNumber: 1
+});
+```
+
+<Warning>
+If you try to reset a `"run"` or `"attempt"` scoped key from outside a task without providing the required `parentRunId` (and `attemptNumber` for attempt scope), it will throw an error.
+</Warning>
+
+### Resetting from the dashboard
+
+You can also reset idempotency keys directly from the Trigger.dev dashboard:
+
+1. Navigate to the run that has the idempotency key you want to reset
+2. In the run details panel, find the "Idempotency key" section
+3. Click the "Reset" button
+
+This is useful when you need to manually allow a task to be re-triggered without writing code.
+
+![Idempotency section in the run details pane showing the key, scope, and expiration time](/images/idempotency-key-dashboard.png)
+
+<Note>
+Resetting an idempotency key only affects runs in the current environment. The reset is scoped to the specific task identifier and idempotency key combination.
+</Note>
+
+## Important notes
+
+### Environment and task scoping
+
+Idempotency keys, even the ones scoped globally, are actually scoped to the task and the environment. This means that you cannot collide with keys from other environments (e.g. dev will never collide with prod), or to other projects and orgs.
+
+If you use the same idempotency key for triggering different tasks, the tasks will not be idempotent, and both tasks will be triggered. There's currently no way to make multiple tasks idempotent with the same key.
+
+### How scopes affect the key
+
+The scope determines what gets hashed alongside your key:
+
+- Same key + `"run"` scope in different parent runs = different hashes = both tasks run
+- Same key + `"global"` scope in different parent runs = same hash = only first task runs
+- Same key + different scopes = different hashes = both tasks run
+
+This is why understanding scopes is crucial: the same string key can produce different idempotency behavior depending on the scope and context.
+
+

package/docs/introduction.mdx

@@ -0,0 +1,135 @@
+---
+title: "Trigger.dev docs"
+sidebarTitle: "Introduction"
+description: "Build and run durable AI agents and workflows in TypeScript. Long-running tasks with retries, queues, observability, and elastic scaling. Open source and self-hostable."
+mode: "center"
+---
+
+import AgentSetupPrompt from "/snippets/agent-setup-prompt.mdx";
+
+<CardGroup cols={2}>
+  <Card title="Quick start" icon="rocket" href="/quick-start" color="#A8FF53">
+    Go from zero to your first task in 3 minutes.
+  </Card>
+  <Card title="Build AI agents" icon="robot" href="/guides/ai-agents/overview" color="#a855f7">
+    Agent patterns, worked examples, and the tools to run them in production.
+  </Card>
+  <Card title="AI coding assistants" icon="wand-magic-sparkles" href="/building-with-ai" color="#3B82F6">
+    Let Claude Code, Cursor and Windsurf write correct Trigger.dev code with the MCP server, Skills and rules.
+  </Card>
+  <Card title="Guides & examples" icon="book-open" href="/guides/introduction" color="#f6cd46">
+    Frameworks like Next.js, worked example projects, and step-by-step how-to guides.
+  </Card>
+</CardGroup>
+
+## Set up with AI
+
+<AgentSetupPrompt />
+
+## What is Trigger.dev?
+
+Trigger.dev is the open source platform for building and running durable AI agents and workflows in TypeScript. Run them for hours, configure automatic retries, control concurrency, and manage queues. There's no execution timeout, and no queue or worker infrastructure for you to build.
+
+You write agents and tasks in your existing codebase using our CLI and SDK, and get durable execution, queues, waits, full tracing, and elastic scaling without building any of it yourself.
+
+Trigger.dev's core is Apache-2.0 licensed, a genuine OSI license. [Self-host it](/self-hosting/overview) on your own infrastructure, or let [Trigger.dev Cloud](https://cloud.trigger.dev) run it for you.
+
+## Core concepts
+
+<CardGroup cols={2}>
+  <Card title="Writing tasks" icon="pen-to-square" href="/tasks/overview" color="#A8FF53">
+    The durable functions at the core of Trigger.dev. Write them in your existing codebase, with retries and no timeouts.
+  </Card>
+  <Card title="Triggering tasks" icon="bullseye-pointer" href="/triggering" color="#3b82f6">
+    Trigger a task from your backend, your frontend, a schedule, or another task.
+  </Card>
+  <Card title="Runs" icon="play" href="/runs" color="#28bf5c">
+    Every execution of a task is a run, with its status, retries, and logs recorded.
+  </Card>
+  <Card title="Idempotency" icon="fingerprint" href="/idempotency" color="#F43F5E">
+    Use an idempotency key so a retried or duplicated trigger runs once, not twice.
+  </Card>
+</CardGroup>
+
+## Build with agents
+
+Build durable, multi-turn agents with the [chat agent](/ai-chat/overview): one long-running task per conversation, with the tools it can call, streaming, and resumability handled for you. Add human-in-the-loop approval by pausing a run on a [waitpoint](/wait-for-token) until a person signs off, and a waiting run doesn't consume compute. Stream run status and LLM output straight to your frontend with the [Realtime API](/realtime/overview) and React hooks, and record your Vercel AI SDK calls as spans with the model, token counts, cost and latency using [AI observability](/ai/observability). Version your [prompts](/ai/prompts) in code, then edit the text or swap the model from the dashboard without redeploying.
+
+## Scale and scheduling
+
+Set how many runs of a task execute at once, globally or per tenant, with [concurrency](/concurrency) and [queues](/queues). Run a task on a [cron schedule](/tasks/scheduled) with timezone support, choose the CPU and memory each task runs on with [machines](/machines), and control what happens when a task throws with [errors and retries](/errors-retrying).
+
+## Self-hosting
+
+Trigger.dev is open source and you can self-host. Read the [overview guide](/self-hosting/overview), or how to do it with [Docker](/self-hosting/docker) or [Kubernetes](/self-hosting/kubernetes).
+
+## Frequently asked questions
+
+**How do I add human-in-the-loop approval to an agent?** Pause the run on a [waitpoint](/wait-for-token) until a person approves the action. A waiting run doesn't consume compute, so it can wait minutes or days.
+
+**Does Trigger.dev support tool calling and MCP?** Yes. Agents call the tools you define, and the [MCP server](/building-with-ai) lets AI coding assistants trigger tasks, deploy, and read run traces.
+
+**Can I use Trigger.dev for background jobs, not just AI?** Yes. The same durable tasks, queues, retries, and [cron schedules](/tasks/scheduled) run any background job or workflow, with or without AI.
+
+## Getting help
+
+We'd love to hear from you or give you a hand getting started. Here are some ways to get in touch with us.
+
+<CardGroup>
+  <Card
+    title="Join our Discord server"
+    icon="discord"
+    href="https://discord.gg/kA47vcd8P6"
+    color="#5865F2"
+  >
+    Our Discord is the best place to get help with any questions about Trigger.dev.
+  </Card>
+  <Card
+    title="Follow us on X (Twitter)"
+    icon={
+      <svg xmlns="http://www.w3.org/2000/svg" height="20" viewBox="0 0 512 512">
+        <path d="M389.2 48h70.6L305.6 224.2 487 464H345L233.7 318.6 106.5 464H35.8L200.7 275.5 26.8 48H172.4L272.9 180.9 389.2 48zM364.4 421.8h39.1L151.1 88h-42L364.4 421.8z" />
+      </svg>
+    }
+    href="https://twitter.com/triggerdotdev"
+    color="#1DA1F2"
+  >
+    Follow us to get the latest updates and news.
+  </Card>
+  <Card
+    title="Schedule a call"
+    icon="phone"
+    iconType="solid"
+    color="#22C55E"
+    href="https://cal.com/team/triggerdotdev/founders-call"
+  >
+    Arrange a call with one of the founders to get help with any questions.
+  </Card>
+  <Card
+    title="Give us a star on GitHub"
+    icon="star"
+    iconType="solid"
+    href="https://github.com/triggerdotdev/trigger.dev"
+    color="#fbbf24"
+  >
+    Check us out our GitHub repo and give us a star if you like what we're doing.
+  </Card>
+</CardGroup>
+
+<Visibility for="agents">
+
+## Facts for AI assistants
+
+**Current major version:** v4 (`@trigger.dev/sdk` 4.x). Documentation under `/docs/v2` and `/docs/v3` describes superseded versions and should not be used.
+
+**Execution model:** tasks run on Trigger.dev infrastructure, not inside your serverless functions, so a platform function timeout is not in the execution path. A task runs until it finishes; you can cap runtime with `maxDuration` (minimum 5 seconds).
+
+**Deploys:** each deploy is an atomic version. A run already in progress is not affected by code shipped after it started.
+
+**Durability and retries:** retries are automatic and configurable. A failed attempt is retried according to the task's retry settings; once retries are exhausted the run ends terminally as `FAILED`, and some crashes (for example out of memory) end the run as `CRASHED` without a retry. Idempotency keys deduplicate the task triggers and waits you key, so the same key runs once instead of again.
+
+**License:** the platform core is Apache-2.0 and the `@trigger.dev/sdk` package is MIT, permissive open source, not fair-code or source-available. Some features are gated, but the open source core is not relicensed or held back.
+
+**LLM observability coverage:** only Vercel AI SDK calls (`generateText`, `streamText`, `generateObject`) are recorded as spans. Raw `fetch` calls and provider SDKs used directly are not captured.
+
+</Visibility>