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

package/docs/realtime/backend/subscribe.mdx

@@ -0,0 +1,225 @@
+---
+title: "Run updates (backend)"
+sidebarTitle: "Run updates"
+description: "Subscribe to run status changes, metadata updates, and tag changes from your backend code using async iterators."
+---
+
+**Subscribe to runs from your backend and get updates whenever status, metadata, or tags change.** Each function returns an async iterator that yields the run object on every change.
+
+## runs.subscribeToRun
+
+Subscribes to all changes to a specific run.
+
+```ts Example
+import { runs } from "@trigger.dev/sdk";
+
+for await (const run of runs.subscribeToRun("run_1234")) {
+  console.log(run);
+}
+```
+
+This function subscribes to all changes to a run. It returns an async iterator that yields the run object whenever the run is updated. The iterator will complete when the run is finished.
+
+**Authentication**: This function supports both server-side and client-side authentication. For server-side authentication, use your API key. For client-side authentication, you must generate a public access token with read access to the specific run. See our [authentication guide](/realtime/auth) for details.
+
+**Response**: The AsyncIterator yields the [run object](/realtime/run-object).
+
+## runs.subscribeToRunsWithTag
+
+Subscribes to all changes to runs with a specific tag.
+
+```ts Example
+import { runs } from "@trigger.dev/sdk";
+
+for await (const run of runs.subscribeToRunsWithTag("user:1234")) {
+  console.log(run);
+}
+```
+
+This function subscribes to all changes to runs with a specific tag. It returns an async iterator that yields the run object whenever a run with the specified tag is updated. This iterator will never complete, so you must manually break out of the loop when you no longer want to receive updates.
+
+**Authentication**: This function supports both server-side and client-side authentication. For server-side authentication, use your API key. For client-side authentication, you must generate a public access token with read access to the specific tag. See our [authentication guide](/realtime/auth) for details.
+
+**Response**: The AsyncIterator yields the [run object](/realtime/run-object).
+
+## runs.subscribeToBatch
+
+Subscribes to all changes for runs in a batch.
+
+```ts Example
+import { runs } from "@trigger.dev/sdk";
+
+for await (const run of runs.subscribeToBatch("batch_1234")) {
+  console.log(run);
+}
+```
+
+This function subscribes to all changes for runs in a batch. It returns an async iterator that yields a run object whenever a run in the batch is updated. The iterator does not complete on its own, you must manually `break` the loop when you want to stop listening for updates.
+
+**Authentication**: This function supports both server-side and client-side authentication. For server-side authentication, use your API key. For client-side authentication, you must generate a public access token with read access to the specific batch. See our [authentication guide](/realtime/auth) for details.
+
+**Response**: The AsyncIterator yields the [run object](/realtime/run-object).
+
+## Type safety
+
+You can infer the types of the run's payload and output by passing the type of the task to the subscribe functions:
+
+```ts
+import { runs, tasks } from "@trigger.dev/sdk";
+import type { myTask } from "./trigger/my-task";
+
+async function myBackend() {
+  const handle = await tasks.trigger("my-task", { some: "data" });
+
+  for await (const run of runs.subscribeToRun<typeof myTask>(handle.id)) {
+    // run.payload and run.output are now typed
+    console.log(run.payload.some);
+
+    if (run.output) {
+      console.log(run.output.some);
+    }
+  }
+}
+```
+
+When using `subscribeToRunsWithTag`, you can pass a union of task types:
+
+```ts
+import { runs } from "@trigger.dev/sdk";
+import type { myTask, myOtherTask } from "./trigger/my-task";
+
+for await (const run of runs.subscribeToRunsWithTag<typeof myTask | typeof myOtherTask>("my-tag")) {
+  // Narrow down the type based on the taskIdentifier
+  switch (run.taskIdentifier) {
+    case "my-task": {
+      console.log("Run output:", run.output.foo); // Type-safe
+      break;
+    }
+    case "my-other-task": {
+      console.log("Run output:", run.output.bar); // Type-safe
+      break;
+    }
+  }
+}
+```
+
+## Subscribe to metadata updates from your tasks
+
+The metadata API allows you to update custom metadata on runs and receive real-time updates when metadata changes. This is useful for tracking progress, storing intermediate results, or adding custom status information that can be monitored in real-time.
+
+<Note>
+  For frontend applications using React, see our [React hooks metadata
+  documentation](/realtime/react-hooks/subscribe#using-metadata-to-show-progress-in-your-ui) for
+  consuming metadata updates in your UI.
+</Note>
+
+When you update metadata from within a task using `metadata.set()`, `metadata.append()`, or other metadata methods, all subscribers to that run will automatically receive the updated run object containing the new metadata.
+
+This makes metadata perfect for:
+
+- Progress tracking
+- Status updates
+- Intermediate results
+- Custom notifications
+
+Use the metadata API within your task to update metadata in real-time. In this basic example task, we're updating the progress of a task as it processes items.
+
+### How to subscribe to metadata updates
+
+This example task updates the progress of a task as it processes items.
+
+```ts
+// Your task code
+import { task, metadata } from "@trigger.dev/sdk";
+
+export const progressTask = task({
+  id: "progress-task",
+  run: async (payload: { items: string[] }) => {
+    const total = payload.items.length;
+
+    for (let i = 0; i < payload.items.length; i++) {
+      // Update progress metadata
+      metadata.set("progress", {
+        current: i + 1,
+        total: total,
+        percentage: Math.round(((i + 1) / total) * 100),
+        currentItem: payload.items[i],
+      });
+
+      // Process the item
+      await processItem(payload.items[i]);
+    }
+
+    metadata.set("status", "completed");
+    return { processed: total };
+  },
+});
+
+async function processItem(item: string) {
+  // Simulate work
+  await new Promise((resolve) => setTimeout(resolve, 1000));
+}
+```
+
+We can now subscribe to the runs and receive real-time metadata updates.
+
+```ts
+// Somewhere in your backend code
+import { runs } from "@trigger.dev/sdk";
+import type { progressTask } from "./trigger/progress-task";
+
+async function monitorProgress(runId: string) {
+  for await (const run of runs.subscribeToRun<typeof progressTask>(runId)) {
+    console.log(`Run ${run.id} status: ${run.status}`);
+
+    if (run.metadata?.progress) {
+      const progress = run.metadata.progress as {
+        current: number;
+        total: number;
+        percentage: number;
+        currentItem: string;
+      };
+
+      console.log(`Progress: ${progress.current}/${progress.total} (${progress.percentage}%)`);
+      console.log(`Processing: ${progress.currentItem}`);
+    }
+
+    if (run.metadata?.status === "completed") {
+      console.log("Task completed!");
+      break;
+    }
+  }
+}
+```
+
+For more information on how to write tasks that use the metadata API, as well as more examples, see our [run metadata docs](/runs/metadata#more-metadata-task-examples).
+
+### Type safety
+
+You can get type safety for your metadata by defining types:
+
+```ts
+import { runs } from "@trigger.dev/sdk";
+import type { progressTask } from "./trigger/progress-task";
+
+interface ProgressMetadata {
+  progress?: {
+    current: number;
+    total: number;
+    percentage: number;
+    currentItem: string;
+  };
+  status?: "running" | "completed" | "failed";
+}
+
+async function monitorTypedProgress(runId: string) {
+  for await (const run of runs.subscribeToRun<typeof progressTask>(runId)) {
+    const metadata = run.metadata as ProgressMetadata;
+
+    if (metadata?.progress) {
+      // Now you have full type safety
+      console.log(`Progress: ${metadata.progress.percentage}%`);
+    }
+  }
+}
+```

package/docs/realtime/how-it-works.mdx

@@ -0,0 +1,94 @@
+---
+title: "How Realtime works"
+sidebarTitle: "How it works"
+description: "Technical architecture behind Trigger.dev's real-time run updates, built on Electric SQL and PostgreSQL syncing."
+---
+
+This page covers the infrastructure behind **run updates** (status, metadata, tags). [Streaming](/tasks/streams) uses a separate transport.
+
+## Architecture
+
+The run updates system is built on top of [Electric SQL](https://electric-sql.com/), an open-source PostgreSQL syncing engine. The Trigger.dev API wraps Electric SQL and provides a simple API to subscribe to [runs](/runs) and get updates as they happen.
+
+## Run changes
+
+You will receive updates whenever a run changes for the following reasons:
+
+- The run moves to a new state. See our [run lifecycle docs](/runs#the-run-lifecycle) for more information.
+- [Run tags](/tags) are added or removed.
+- [Run metadata](/runs/metadata) is updated.
+
+## Run object
+
+The run object returned by Realtime subscriptions is optimized for streaming updates and differs from the management API's run object. See [the run object](/realtime/run-object) page for the complete schema and field descriptions.
+
+## Basic usage
+
+After you trigger a task, you can subscribe to the run using the `runs.subscribeToRun` function. This function returns an async iterator that you can use to get updates on the run status.
+
+```ts
+import { runs, tasks } from "@trigger.dev/sdk";
+
+// Somewhere in your backend code
+async function myBackend() {
+  const handle = await tasks.trigger("my-task", { some: "data" });
+
+  for await (const run of runs.subscribeToRun(handle.id)) {
+    // This will log the run every time it changes
+    console.log(run);
+  }
+}
+```
+
+Every time the run changes, the async iterator will yield the updated run. You can use this to update your UI, log the run status, or take any other action.
+
+Alternatively, you can subscribe to changes to any run that includes a specific tag (or tags) using the `runs.subscribeToRunsWithTag` function.
+
+```ts
+import { runs } from "@trigger.dev/sdk";
+
+// Somewhere in your backend code
+for await (const run of runs.subscribeToRunsWithTag("user:1234")) {
+  // This will log the run every time it changes, for all runs with the tag "user:1234"
+  console.log(run);
+}
+```
+
+If you've used `batchTrigger` to trigger multiple runs, you can also subscribe to changes to all the runs triggered in the batch using the `runs.subscribeToBatch` function.
+
+```ts
+import { runs } from "@trigger.dev/sdk";
+
+// Somewhere in your backend code
+for await (const run of runs.subscribeToBatch("batch-id")) {
+  // This will log the run every time it changes, for all runs in the batch with the ID "batch-id"
+  console.log(run);
+}
+```
+
+## Run metadata
+
+The run metadata API gives you the ability to add or update custom metadata on a run, which will cause the run to be updated. This allows you to extend the Realtime API with custom data attached to a run that can be used for various purposes. Some common use cases include:
+
+- Adding a link to a related resource
+- Adding a reference to a user or organization
+- Adding a custom status with progress information
+
+See our [run metadata docs](/runs/metadata) for more on how to write tasks that use the metadata API.
+
+### Using metadata with Realtime & React hooks
+
+You can combine run metadata with the Realtime API to bridge the gap between your trigger.dev tasks and your applications in two ways:
+
+1. Using our [React hooks](/realtime/react-hooks/subscribe#using-metadata-to-show-progress-in-your-ui) to subscribe to metadata updates and update your UI in real-time.
+2. Using our [backend functions](/realtime/backend) to subscribe to metadata updates in your backend.
+
+## Limits
+
+The Realtime API in the Trigger.dev Cloud limits the number of concurrent subscriptions, depending on your plan. If you exceed the limit, you will receive an error when trying to subscribe to a run. For more information, see our [pricing page](https://trigger.dev/pricing).
+
+## Learn more
+
+- Read our Realtime blog post ["How we built a real-time service that handles 20,000 updates per second](https://trigger.dev/blog/how-we-built-realtime)
+- Using Realtime: [React Hooks (frontend)](/realtime/react-hooks)
+- Using [Backend (server-side)](/realtime/backend)

package/docs/realtime/overview.mdx

@@ -0,0 +1,63 @@
+---
+title: Realtime overview
+sidebarTitle: Overview
+description: "Get live run updates and stream data from background tasks to your frontend or backend. No polling."
+---
+
+**Realtime is the umbrella for everything live in Trigger.dev.** It covers two things: getting notified when a run's state changes, and streaming continuous data (like AI tokens) from a running task to your app.
+
+Both use the same `@trigger.dev/react-hooks` package and the same authentication system. The difference is what they give you.
+
+## Run updates vs Streaming
+
+| | Run updates | Streaming |
+|---|---|---|
+| **What you get** | Run state: status, metadata, tags | Continuous data you define (AI tokens, file chunks, progress) |
+| **When it fires** | On state changes | While the task runs, as data is produced |
+| **Use case** | Progress bars, status badges, dashboards | AI chat output, live logs, file processing |
+| **React hook** | [`useRealtimeRun`](/realtime/react-hooks/subscribe) | [`useRealtimeStream`](/realtime/react-hooks/streams) |
+| **Setup in task code?** | No, automatic | Yes, using `streams.define()` |
+| **Infrastructure** | [Electric SQL](/realtime/how-it-works) (PostgreSQL sync) | Streams transport |
+
+You can use both at the same time. Subscribe to a run's status (to show a progress bar) while also streaming AI output (to display tokens as they arrive).
+
+## Run updates
+
+Subscribe to a run and your code gets called whenever its status, [metadata](/runs/metadata), or [tags](/tags) change. No setup needed in your task code.
+
+You can subscribe to:
+
+- **Specific runs** by run ID
+- **Runs with specific tags** (e.g., all runs tagged with `user:123`)
+- **Batch runs** within a specific batch
+- **Trigger + subscribe combos** that trigger a task and immediately subscribe (frontend only)
+
+→ [React hooks](/realtime/react-hooks/subscribe) | [Backend](/realtime/backend/subscribe)
+
+## Streaming
+
+Define typed streams in your task, pipe data to them, and read that data from your frontend or backend as it's produced. You need to set up streams in your task code using `streams.define()`.
+
+→ [How to emit streams from tasks](/tasks/streams) | [React hooks](/realtime/react-hooks/streams) | [Backend](/realtime/backend/streams)
+
+## Authentication
+
+All Realtime hooks and functions require authentication. See the [authentication guide](/realtime/auth) for setup.
+
+## Frequently asked questions
+
+### How do I show a progress bar for a background task?
+
+Use [run metadata](/runs/metadata) to store progress data (like a percentage), then subscribe to the run with [`useRealtimeRun`](/realtime/react-hooks/subscribe). Your component re-renders on every metadata update.
+
+### How do I stream AI/LLM responses from a background task?
+
+Define a stream in your task with `streams.define()`, pipe your AI SDK response to it, then consume it in React with [`useRealtimeStream`](/realtime/react-hooks/streams). See [Streaming data from tasks](/tasks/streams) for the full guide.
+
+### Do I need WebSockets or polling?
+
+No. Run updates are powered by [Electric SQL](/realtime/how-it-works) (HTTP-based PostgreSQL syncing). Streams use their own transport. The hooks handle connections automatically.
+
+### Can I use both run updates and streaming together?
+
+Yes. A common pattern: subscribe to run status with `useRealtimeRun` (progress indicator) while streaming AI output with `useRealtimeStream` (token-by-token display).

package/docs/realtime/react-hooks/overview.mdx

@@ -0,0 +1,73 @@
+---
+title: "React hooks for real-time task updates"
+sidebarTitle: Overview
+description: "Subscribe to background task progress, stream AI responses, and trigger tasks from React components using @trigger.dev/react-hooks."
+---
+
+import RealtimeExamplesCards from "/snippets/realtime-examples-cards.mdx";
+
+**`@trigger.dev/react-hooks` gives your React components live access to background tasks.** Subscribe to run progress, stream AI output as it generates, or trigger tasks directly from the browser.
+
+## Installation
+
+Install the `@trigger.dev/react-hooks` package in your project:
+
+<CodeGroup>
+
+```bash npm
+npm add @trigger.dev/react-hooks
+```
+
+```bash pnpm
+pnpm add @trigger.dev/react-hooks
+```
+
+```bash yarn
+yarn add @trigger.dev/react-hooks
+```
+
+</CodeGroup>
+
+## Authentication
+
+All hooks require authentication with a Public Access Token. Pass the token via the `accessToken` option:
+
+```tsx
+import { useRealtimeRun } from "@trigger.dev/react-hooks";
+
+export function MyComponent({
+  runId,
+  publicAccessToken,
+}: {
+  runId: string;
+  publicAccessToken: string;
+}) {
+  const { run, error } = useRealtimeRun(runId, {
+    accessToken: publicAccessToken,
+    baseURL: "https://your-trigger-dev-instance.com", // optional, only needed if you are self-hosting Trigger.dev
+  });
+
+  // ...
+}
+```
+
+Learn more about [generating and managing tokens in our authentication guide](/realtime/auth).
+
+## Available hooks
+
+| Hook category | What it does | Guide |
+|---|---|---|
+| **Trigger hooks** | Trigger tasks from the browser | [Triggering](/realtime/react-hooks/triggering) |
+| **Run updates** | Subscribe to run status, metadata, and tags | [Run updates](/realtime/react-hooks/subscribe) |
+| **Streaming** | Consume AI output, file chunks, or any continuous data | [Streaming](/realtime/react-hooks/streams) |
+| **SWR hooks** | One-time fetch with caching (not recommended for most cases) | [SWR](/realtime/react-hooks/swr) |
+
+## SWR vs Realtime hooks
+
+We offer two "styles" of hooks: SWR and Realtime. SWR hooks use the [swr](https://swr.vercel.app/) library to fetch data once and cache it. Realtime hooks use [Trigger.dev Realtime](/realtime) to subscribe to updates as they happen.
+
+<Note>
+  It can be a little confusing which one to use because [swr](https://swr.vercel.app/) can also be
+  configured to poll for updates. But because of rate-limits and the way the Trigger.dev API works,
+  we recommend using the Realtime hooks for most use cases.
+</Note>

package/docs/realtime/react-hooks/session-stream.mdx

@@ -0,0 +1,126 @@
+---
+title: "Read a session channel in React"
+sidebarTitle: "Session streams"
+description: "Subscribe to a session's output or input channel from React with useSessionStream: accumulate records, resume from a cursor, and read only the latest."
+---
+
+**`useSessionStream` subscribes to one channel of a [session](/ai-chat/sessions) and updates a `records` array as new records arrive.** It reads the `out` channel by default (the agent's output) or `in` (the input channel). It is read-only; `useSession` is reserved for two-way (read and write) communication.
+
+<Note>
+  Requires a Public Access Token with the `read:sessions:{id}` scope. See [Realtime
+  auth](/realtime/auth) for generating one.
+</Note>
+
+## Basic usage
+
+Pass the session id (or external id) and an `accessToken`. The hook returns the `records` received so far, the last control record, the cursor of the last record seen, and any error:
+
+```tsx
+"use client";
+
+import { useSessionStream } from "@trigger.dev/react-hooks";
+
+export function SessionViewer({
+  sessionId,
+  accessToken,
+}: {
+  sessionId: string;
+  accessToken: string;
+}) {
+  const { records, error } = useSessionStream<string>(sessionId, { accessToken });
+
+  if (error) return <div>Error: {error.message}</div>;
+
+  return <div>{records.join("")}</div>;
+}
+```
+
+## Options
+
+```tsx
+const { records, lastEventId, lastControl, error, stop } = useSessionStream(sessionId, {
+  accessToken: "pk_...", // Required: public access token with read:sessions:{id}
+  io: "out", // Optional: "out" (default) or "in"
+  from: "beginning", // Optional: "beginning" (default) or "latest"
+  maxRecords: 100, // Optional: keep only the most recent N records (default: unbounded)
+  lastEventId: undefined, // Optional: resume cursor
+  timeoutInSeconds: 60, // Optional: close after this long with no new data (default: 60)
+  throttleInMs: 16, // Optional: throttle record updates (default: 16ms)
+  onRecords: (batch) => {}, // Optional: callback per throttled batch, each with its event id
+  onControl: (event) => {}, // Optional: callback for control records (e.g. turn-complete)
+});
+```
+
+The return value:
+
+- **`records`**: every data record received so far, in arrival order. Control records are delivered to `onControl` instead.
+- **`lastEventId`**: the cursor of the last record seen. Persist it and pass it back as the `lastEventId` option to resume.
+- **`lastControl`**: the last control record (for example `turn-complete`).
+- **`stop`**: abort the subscription, keeping the records received so far.
+
+## Start from the latest record
+
+By default the hook replays the channel history, then live-tails. Pass `from: "latest"` to start at the current tail (the latest record, then live updates) instead of replaying, and `maxRecords` to bound memory:
+
+```tsx
+const { records } = useSessionStream<{ url: string }>(sessionId, {
+  accessToken,
+  io: "out",
+  from: "latest", // start at the latest record, then live updates
+  maxRecords: 1, // keep just the most recent record
+});
+```
+
+<Note>
+  `from: "latest"` requires a server that supports it. Against an older server a client that passes
+  it degrades safely to a full replay.
+</Note>
+
+## Resume from a cursor
+
+The hook resumes automatically across a component remount. A full page reload clears in-memory state, so to resume there, persist the returned `lastEventId` and pass it back on the next load. The channel then continues after that record with no replay and no gap:
+
+```tsx
+const cursorKey = `session-cursor:${sessionId}:out`; // scope the key to this session and channel
+const saved = localStorage.getItem(cursorKey) ?? undefined;
+
+const { records, lastEventId } = useSessionStream<string>(sessionId, {
+  accessToken,
+  lastEventId: saved,
+  onRecords: (batch) => localStorage.setItem(cursorKey, batch.at(-1)!.id),
+});
+```
+
+## React to control records
+
+Control records (such as `turn-complete`) never enter `records`. Handle them with `onControl`, or read the latest from `lastControl`:
+
+```tsx
+const { records, lastControl } = useSessionStream<string>(sessionId, {
+  accessToken,
+  onControl: (event) => {
+    if (event.subtype === "turn-complete") {
+      console.log("The turn is complete");
+    }
+  },
+});
+```
+
+For an expiring token on a long-lived subscription, pass `refreshAccessToken` (see [Realtime auth](/realtime/auth)). To read a session channel outside React, use [`session.out.read()`](/ai-chat/sessions).
+
+## Named side channels
+
+`useSessionStream` reads a session's reserved channel. To read a [named side channel](/ai-chat/side-channels) — a durable, cross-run stream separate from the chat transcript — use `useSessionStreamChannel`. It takes the channel name as its first argument and has the same options and return shape, plus a channel-definition type argument that types `records`:
+
+```tsx
+import { useSessionStreamChannel } from "@trigger.dev/react-hooks";
+import type { screenshots } from "../trigger/channels";
+
+const { records } = useSessionStreamChannel<typeof screenshots>("screenshots", {
+  sessionId,
+  accessToken,
+  io: "out",
+  from: "latest",
+  maxRecords: 1,
+});
+```