Merge branch 'main' into fix/tri-6732-hover-vertical-timeline-does-not-update-on-task-runs

## Summary
- **Fix Docker publish automation**: The `v.docker.*` tags pushed by the
release workflow using `GITHUB_TOKEN` don't trigger the publish workflow
(GitHub Actions limitation to prevent infinite loops). Added a
`workflow_call` to `publish.yml` directly from the release job so Docker
images are built automatically after npm publish. Tags are still pushed
for reference.
- **Fix worker Containerfiles**: The coordinator, docker-provider, and
kubernetes-provider builds have been failing since the superjson
vendoring change in `@trigger.dev/core` (#2949). The Containerfiles now
run `bundle-vendor` before `build:bundle` to generate the vendor files
that esbuild needs.

### Context
- Docker images on GHCR have been stuck at v4.3.0 — v4.3.1, v4.3.2,
v4.3.3 tags existed on GitHub but never triggered publish runs
- The worker builds (publish-worker) have been failing on every push to
main since Jan 30

## Test plan
- [x] Verified kubernetes-provider Containerfile builds locally with the
fix
- [x] Manually dispatched publish workflow for v4.3.1 — all jobs
succeeded
<!-- devin-review-badge-begin -->

---

<a
href="https://app.devin.ai/review/triggerdotdev/trigger.dev/pull/3013"
target="_blank">
  <picture>
<source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-open-in-devin-review-dark.svg?v=1">
<img
src="https://static.devin.ai/assets/gh-open-in-devin-review-light.svg?v=1"
alt="Open with Devin">
  </picture>
</a>
<!-- devin-review-badge-end -->

.changeset/add-debounce-maxdelay.md

@@ -0,0 +1,16 @@
+---
+"@trigger.dev/core": patch
+"@trigger.dev/sdk": patch
+---
+
+Add `maxDelay` option to debounce feature. This allows setting a maximum time limit for how long a debounced run can be delayed, ensuring execution happens within a specified window even with continuous triggers.
+
+```typescript
+await myTask.trigger(payload, {
+  debounce: {
+    key: "my-key",
+    delay: "5s",
+    maxDelay: "30m", // Execute within 30 minutes regardless of continuous triggers
+  },
+});
+```

.changeset/beige-horses-juggle.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Added experimental_devProcessCwdInBuildDir config option to opt-in to new process.cwd behavior when executing tasks in the dev CLI. Currently process.cwd maps to the "root" of your trigger.dev project (the directory that contains your trigger.config.ts file). Setting experimental_devProcessCwdInBuildDir to true changes process.cwd to instead be the temporary build directory inside of the .trigger directory.

.changeset/big-carrots-fail.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Fix dev runs

.changeset/big-garlics-own.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/sdk": patch
----
-
-fix: importing from runEngine/index.js breaks non-node runtimes

.changeset/blue-eyes-tickle.md

@@ -1,6 +0,0 @@
----
-"trigger.dev": patch
-"@trigger.dev/core": patch
----
-
-The dev command will now use the platform-provided engine URL

.changeset/breezy-turtles-talk.md

@@ -1,10 +0,0 @@
----
-"@trigger.dev/react-hooks": patch
-"@trigger.dev/sdk": patch
-"trigger.dev": patch
-"@trigger.dev/build": patch
-"@trigger.dev/core": patch
-"@trigger.dev/rsc": patch
----
-
-Run Engine 2.0 (alpha)

.changeset/calm-hooks-wait.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/react-hooks": patch
+---
+
+Fix `onComplete` callback firing prematurely when the realtime stream disconnects before the run finishes.

.changeset/chatty-snakes-hope.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/sdk": patch
----
-
-fix: Logging large objects is now much more performant and uses less memory

.changeset/chilled-weeks-switch.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Fix update command version mismatch detection

.changeset/clean-beans-compete.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/sdk": patch
----
-
-New internal idempotency implementation for trigger and batch trigger to prevent request retries from duplicating work

.changeset/consistent-stream-targets.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/sdk": patch
+---
+
+Aligned the SDK's `getRunIdForOptions` logic with the Core package to handle semantic targets (`root`, `parent`) in root tasks.

.changeset/cuddly-boats-press.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Add external log exporters and fix missing external trace exporters in deployed tasks

.changeset/curvy-dogs-share.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/sdk": patch
----
-
-When you create a Waitpoint token using `wait.createToken()` you get a URL back that can be used to complete it by making an HTTP POST request.

.changeset/cyan-news-design.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Allow any runs to finish after SIGTERM but disable warm starts

.changeset/early-points-jam.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Gracefully shutdown task run processes using SIGTERM followed by SIGKILL after a 1s timeout. This also prevents cancelled or completed runs from leaving orphaned Ttask run processes behind

.changeset/eight-ligers-help.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Enhance deploy command output to better distinguish between local and remote builds

.changeset/eighty-rings-divide.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/core": patch
----
-
-Configurable queue consumer count in supervisor session

.changeset/empty-dolls-judge.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Switch to profile after successful login

.changeset/export-start-attempt-hook-type.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/sdk": patch
+---
+
+Export `AnyOnStartAttemptHookFunction` type to allow defining `onStartAttempt` hooks for individual tasks.

.changeset/fifty-beers-bake.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Fixes a bug that would allow processes that had OOM errors to be incorrectly reused when experimental_processKeepAlive was enabled

.changeset/five-nails-whisper.md

@@ -1,92 +0,0 @@
----
-"@trigger.dev/sdk": patch
----
-
-External Trace Correlation & OpenTelemetry Package Updates.
-
-| Package | Previous Version | New Version | Change Type |
-|---------|------------------|-------------|-------------|
-| `@opentelemetry/api` | 1.9.0 | 1.9.0 | No change (stable API) |
-| `@opentelemetry/api-logs` | 0.52.1 | 0.203.0 | Major update |
-| `@opentelemetry/core` | - | 2.0.1 | New dependency |
-| `@opentelemetry/exporter-logs-otlp-http` | 0.52.1 | 0.203.0 | Major update |
-| `@opentelemetry/exporter-trace-otlp-http` | 0.52.1 | 0.203.0 | Major update |
-| `@opentelemetry/instrumentation` | 0.52.1 | 0.203.0 | Major update |
-| `@opentelemetry/instrumentation-fetch` | 0.52.1 | 0.203.0 | Major update |
-| `@opentelemetry/resources` | 1.25.1 | 2.0.1 | Major update |
-| `@opentelemetry/sdk-logs` | 0.52.1 | 0.203.0 | Major update |
-| `@opentelemetry/sdk-node` | 0.52.1 | - | Removed (functionality consolidated) |
-| `@opentelemetry/sdk-trace-base` | 1.25.1 | 2.0.1 | Major update |
-| `@opentelemetry/sdk-trace-node` | 1.25.1 | 2.0.1 | Major update |
-| `@opentelemetry/semantic-conventions` | 1.25.1 | 1.36.0 | Minor update |
-
-### External trace correlation and propagation
-
-We will now correlate your external traces with trigger.dev traces and logs when using our external exporters:
-
-```ts
-import { defineConfig } from "@trigger.dev/sdk";
-import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
-import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
-
-export default defineConfig({
-  project: process.env.TRIGGER_PROJECT_REF,
-  dirs: ["./src/trigger"],
-  telemetry: {
-    logExporters: [
-      new OTLPLogExporter({
-        url: "https://api.axiom.co/v1/logs",
-        headers: {
-          Authorization: `Bearer ${process.env.AXIOM_TOKEN}`,
-          "X-Axiom-Dataset": "test",
-        },
-      }),
-    ],
-    exporters: [
-      new OTLPTraceExporter({
-        url: "https://api.axiom.co/v1/traces",
-        headers: {
-          Authorization: `Bearer ${process.env.AXIOM_TOKEN}`,
-          "X-Axiom-Dataset": "test",
-        },
-      }),
-    ],
-  },
-  maxDuration: 3600,
-});
-```
-
-You can also now propagate your external trace context when calling back into your own backend infra from inside a trigger.dev task:
-
-```ts
-import { otel, task } from "@trigger.dev/sdk";
-import { context, propagation } from "@opentelemetry/api";
-
-async function callNextjsApp() {
-  return await otel.withExternalTrace(async () => {
-    const headersObject = {};
-
-    // Now context.active() refers to your external trace context
-    propagation.inject(context.active(), headersObject);
-
-    const result = await fetch("http://localhost:3000/api/demo-call-from-trigger", {
-      headers: new Headers(headersObject),
-      method: "POST",
-      body: JSON.stringify({
-        message: "Hello from Trigger.dev",
-      }),
-    });
-
-    return result.json();
-  });
-}
-
-export const myTask = task({
-  id: "my-task",
-  run: async (payload: any) => {
-    await callNextjsApp()
-  }
-})
-```
-
-

.changeset/fix-dead-process-execute-hang.md

@@ -0,0 +1,5 @@
+---
+"trigger.dev": patch
+---
+
+Fix runner getting stuck indefinitely when `execute()` is called on a dead child process.

.changeset/flat-pianos-live.md

@@ -1,6 +0,0 @@
----
-"trigger.dev": patch
-"@trigger.dev/core": patch
----
-
-Runtime agnostic SDK config via env vars

.changeset/fluffy-mirrors-live.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/sdk": patch
----
-
-Add jsonSchema support when indexing tasks

.changeset/four-needles-add.md

@@ -1,12 +0,0 @@
----
-"@trigger.dev/redis-worker": major
-"@trigger.dev/react-hooks": major
-"@trigger.dev/sdk": major
-"trigger.dev": major
-"@trigger.dev/python": major
-"@trigger.dev/build": major
-"@trigger.dev/core": major
-"@trigger.dev/rsc": major
----
-
-Trigger.dev v4 release. Please see our upgrade to v4 docs to view the full changelog: https://trigger.dev/docs/upgrade-to-v4

.changeset/fuzzy-snakes-beg.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/core": patch
----
-
-Add supervisor http client option to disable debug logs

.changeset/gentle-waves-suffer.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/sdk": patch
----
-
-Fixed an issue with realtime streams that timeout and resume streaming dropping chunks

.changeset/giant-plums-smash.md

@@ -1,18 +0,0 @@
----
-"@trigger.dev/sdk": patch
----
-
-Added and cleaned up the run ctx param:
-
-- New optional properties `ctx.run.parentTaskRunId` and `ctx.run.rootTaskRunId` reference the current run's root/parent ID.
-- Removed deprecated properties from `ctx`
-- Added a new `ctx.deployment` object that contains information about the deployment associated with the run.
-
-We also update `metadata.root` and `metadata.parent` to work even when the run is a "root" run (meaning it doesn't have a parent or a root associated run). This now works:
-
-```ts
-metadata.root.set("foo", "bar");
-metadata.parent.set("baz", 1);
-metadata.current().foo // "bar"
-metadata.current().baz // 1
-```

.changeset/giant-rivers-tease.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-improve contrast for chalkWorker in light mode

.changeset/gold-insects-invite.md

@@ -1,6 +0,0 @@
----
-"trigger.dev": patch
-"@trigger.dev/core": patch
----
-
-Expose esbuild `keepNames` option (experimental)

.changeset/green-lions-relate.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/sdk": patch
----
-
-The envvars.list() and retrieve() functions receive isSecret for each value. Secret values are always redacted.

.changeset/grumpy-wasps-fold.md

@@ -1,6 +0,0 @@
----
-"trigger.dev": patch
-"@trigger.dev/core": patch
----
-
-Add `experimental_autoDetectExternal` trigger config option

.changeset/healthy-apricots-drop.md

@@ -1,6 +0,0 @@
----
-"trigger.dev": patch
-"@trigger.dev/core": patch
----
-
-Add project details to the whoami command

.changeset/hip-cups-wave.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/sdk": patch
----
-
-Fix issue where realtime streams would cut off after 5 minutes

.changeset/honest-files-decide.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/sdk": patch
----
-
-Deprecate toolTask and replace with `ai.tool(mySchemaTask)`

.changeset/itchy-frogs-care.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Log images sizes for self-hosted deploys

.changeset/itchy-games-sort.md

@@ -1,6 +0,0 @@
----
-"@trigger.dev/sdk": patch
-"trigger.dev": patch
----
-
-Display clickable links in Cursor terminal

.changeset/late-chairs-ring.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Fix init.ts in custom trigger dirs

.changeset/late-dancers-smile.md

@@ -1,6 +0,0 @@
----
-"trigger.dev": patch
-"@trigger.dev/core": patch
----
-
-Add import timings and bundle size analysis, the dev command will now warn about slow imports

.changeset/lazy-panthers-shop.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/core": patch
----
-
-Improve structured logs

.changeset/lazy-plums-fetch.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/build": patch
----
-
-syncVercelEnvVars() fix for syncing the wrong preview branch env vars

.changeset/light-peas-melt.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Fix update command version range handling

.changeset/little-birds-appear.md

@@ -1,45 +0,0 @@
----
-"@trigger.dev/sdk": patch
----
-
-Removes the `releaseConcurrencyOnWaitpoint` option on queues and the `releaseConcurrency` option on various wait functions. Replaced with the following default behavior:
-
-- Concurrency is never released when a run is first blocked via a waitpoint, at either the env or queue level.
-- Concurrency is always released when a run is checkpointed and shutdown, at both the env and queue level.
-
-Additionally, environment concurrency limits now have a new "Burst Factor", defaulting to 2.0x. The "Burst Factor" allows the environment-wide concurrency limit to be higher than any individual queue's concurrency limit. For example, if you have an environment concurrency limit of 100, and a Burst Factor of 2.0x, then you can execute up to 200 runs concurrently, but any one task/queue can still only execute 100 runs concurrently.
-
-We've done some work cleaning up the run statuses. The new statuses are:
-
-- `PENDING_VERSION`: Task is waiting for a version update because it cannot execute without additional information (task, queue, etc.)
-- `QUEUED`: Task is waiting to be executed by a worker
-- `DEQUEUED`: Task has been dequeued and is being sent to a worker to start executing.
-- `EXECUTING`: Task is currently being executed by a worker
-- `WAITING`: Task has been paused by the system, and will be resumed by the system
-- `COMPLETED`: Task has been completed successfully
-- `CANCELED`: Task has been canceled by the user
-- `FAILED`: Task has failed to complete, due to an error in the system
-- `CRASHED`: Task has crashed and won't be retried, most likely the worker ran out of resources, e.g. memory or storage
-- `SYSTEM_FAILURE`: Task has failed to complete, due to an error in the system
-- `DELAYED`: Task has been scheduled to run at a specific time
-- `EXPIRED`: Task has expired and won't be executed
-- `TIMED_OUT`: Task has reached it's maxDuration and has been stopped
-
-We've removed the following statuses:
-
-- `WAITING_FOR_DEPLOY`: This is no longer used, and is replaced by `PENDING_VERSION`
-- `FROZEN`: This is no longer used, and is replaced by `WAITING`
-- `INTERRUPTED`: This is no longer used
-- `REATTEMPTING`: This is no longer used, and is replaced by `EXECUTING`
-
-We've also added "boolean" helpers to runs returned via the API and from Realtime:
-
-- `isQueued`: Returns true when the status is `QUEUED`, `PENDING_VERSION`, or `DELAYED`
-- `isExecuting`: Returns true when the status is `EXECUTING`, `DEQUEUED`. These count against your concurrency limits.
-- `isWaiting`: Returns true when the status is `WAITING`. These do not count against your concurrency limits.
-- `isCompleted`: Returns true when the status is any of the completed statuses.
-- `isCanceled`: Returns true when the status is `CANCELED`
-- `isFailed`: Returns true when the status is any of the failed statuses.
-- `isSuccess`: Returns true when the status is `COMPLETED`
-
-This change adds the ability to easily detect which runs are being counted against your concurrency limit by filtering for both `EXECUTING` or `DEQUEUED`.

.changeset/little-lemons-grab.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-All experimental flags have been promoted to non-experimental, but the experimental ones still work (for now). keepNames and autoDetectExternal now default to true.

.changeset/moody-squids-count.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Init command will now correctly install v4-beta packages

.changeset/nasty-cobras-wonder.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Fix metadata collapsing correctness

.changeset/nice-colts-boil.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Improve warm start times by eagerly creating the child TaskRunProcess when a previous run as completed

.changeset/ninety-games-grow.md

@@ -1,11 +0,0 @@
----
-"trigger.dev": patch
-"@trigger.dev/core": patch
----
-
-- Resolve issue where CLI could get stuck during deploy finalization
-- Unify local and remote build logic, with multi-platform build support
-- Improve switch command; now accepts profile name as an argument
-- Registry configuration is now fully managed by the webapp
-- The deploy `--self-hosted` flag is no longer required
-- Enhance deployment error reporting and image digest retrieval

.changeset/orange-pens-smile.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/redis-worker": patch
----
-
-Now each worker gets it's own pLimit concurrency limiter, and we will only ever dequeue items where there is concurrency capacity, preventing incorrectly retried jobs due to visibility timeout expiry

.changeset/orange-rocks-grow.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Fix init.ts detection when using the sentry esbuild plugin

.changeset/plenty-dolphins-act.md

@@ -1,8 +0,0 @@
----
-"trigger.dev": patch
-"@trigger.dev/core": patch
----
-
-- Correctly resolve waitpoints that come in early
-- Ensure correct state before requesting suspension
-- Fix race conditions in snapshot processing

.changeset/polite-badgers-suffer.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-experimental processKeepAlive

.changeset/polite-impalas-care.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Fixes runLimiter check on #dequeueRuns

.changeset/polite-lies-fix.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Update nypm package to support test-based bun.lock files

.changeset/pre.json

@@ -1,113 +0,0 @@
-{
-  "mode": "pre",
-  "tag": "v4-beta",
-  "initialVersions": {
-    "coordinator": "0.0.1",
-    "docker-provider": "0.0.1",
-    "kubernetes-provider": "0.0.1",
-    "supervisor": "0.0.1",
-    "webapp": "1.0.0",
-    "@trigger.dev/build": "3.3.17",
-    "trigger.dev": "3.3.17",
-    "@trigger.dev/core": "3.3.17",
-    "@trigger.dev/python": "3.3.17",
-    "@trigger.dev/react-hooks": "3.3.17",
-    "@trigger.dev/redis-worker": "3.3.17",
-    "@trigger.dev/rsc": "3.3.17",
-    "@trigger.dev/sdk": "3.3.17",
-    "@trigger.dev/schema-to-json": "4.0.0-v4-beta.26"
-  },
-  "changesets": [
-    "beige-horses-juggle",
-    "big-carrots-fail",
-    "big-garlics-own",
-    "blue-eyes-tickle",
-    "breezy-turtles-talk",
-    "chatty-snakes-hope",
-    "chilled-weeks-switch",
-    "clean-beans-compete",
-    "cuddly-boats-press",
-    "curvy-dogs-share",
-    "cyan-news-design",
-    "early-points-jam",
-    "eight-ligers-help",
-    "eighty-rings-divide",
-    "empty-dolls-judge",
-    "fifty-beers-bake",
-    "five-nails-whisper",
-    "flat-pianos-live",
-    "fluffy-mirrors-live",
-    "four-needles-add",
-    "fuzzy-snakes-beg",
-    "gentle-waves-suffer",
-    "giant-plums-smash",
-    "giant-rivers-tease",
-    "gold-insects-invite",
-    "green-lions-relate",
-    "grumpy-wasps-fold",
-    "healthy-apricots-drop",
-    "hip-cups-wave",
-    "honest-files-decide",
-    "itchy-frogs-care",
-    "itchy-games-sort",
-    "late-chairs-ring",
-    "late-dancers-smile",
-    "lazy-panthers-shop",
-    "lazy-plums-fetch",
-    "light-peas-melt",
-    "little-birds-appear",
-    "little-lemons-grab",
-    "moody-squids-count",
-    "nasty-cobras-wonder",
-    "nice-colts-boil",
-    "ninety-games-grow",
-    "orange-pens-smile",
-    "orange-rocks-grow",
-    "plenty-dolphins-act",
-    "polite-badgers-suffer",
-    "polite-impalas-care",
-    "polite-lies-fix",
-    "rare-beds-accept",
-    "rare-mails-fail",
-    "real-rats-drop",
-    "red-chairs-begin",
-    "red-rings-marry",
-    "red-wasps-cover",
-    "shiny-kiwis-beam",
-    "silent-lobsters-march",
-    "silly-cows-serve",
-    "silly-timers-repair",
-    "sixty-beers-share",
-    "slow-games-drum",
-    "small-birds-arrive",
-    "small-dancers-smell",
-    "smart-coins-hammer",
-    "smooth-planets-flow",
-    "soft-candles-do",
-    "sour-mirrors-accept",
-    "spotty-ducks-punch",
-    "spotty-pants-wink",
-    "strong-pianos-provide",
-    "sweet-dolphins-invent",
-    "swift-vans-dress",
-    "tender-jobs-collect",
-    "thick-bikes-laugh",
-    "thick-poets-yawn",
-    "tidy-books-smell",
-    "tiny-buckets-teach",
-    "tricky-houses-invite",
-    "twelve-actors-hide",
-    "two-eagles-report",
-    "two-tigers-dream",
-    "weak-jobs-hide",
-    "weak-parents-sip",
-    "wet-deers-think",
-    "wet-dragons-boil",
-    "wet-steaks-reflect",
-    "wicked-ads-walk",
-    "wild-mirrors-return",
-    "witty-cherries-tan",
-    "witty-donkeys-unite",
-    "yellow-cars-tell"
-  ]
-}

.changeset/rare-beds-accept.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/core": patch
----
-
-Add verbose structured log level

.changeset/rare-mails-fail.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/build": patch
----
-
-Add Lightpanda extension

.changeset/real-rats-drop.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/sdk": patch
----
-
-Add onCancel lifecycle hook

.changeset/red-chairs-begin.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Added AI assistance link when you have build errors

.changeset/red-rings-marry.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/sdk": patch
----
-
-Provide realtime skipColumns option via untamperable public access tokens

.changeset/red-wasps-cover.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/core": patch
----
-
-Suppress external instrumentation for fetch calls from ApiClient

.changeset/shiny-kiwis-beam.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Handle flush errors gracefully in dev

.changeset/silent-lobsters-march.md

@@ -1,7 +0,0 @@
----
-"trigger.dev": patch
-"@trigger.dev/build": patch
----
-
-- Improve playwright non-headless chrome installation
-- Prevent spinner message duplication in narrow terminals

.changeset/silly-cows-serve.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Added support for Preview branches in v4 projects

.changeset/silly-timers-repair.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Can now set project ref using the TRIGGER_PROJECT_REF env var

.changeset/sixty-beers-share.md

@@ -1,6 +0,0 @@
----
-"trigger.dev": patch
-"@trigger.dev/core": patch
----
-
-Add runtime version detection for display in the dashboard

.changeset/slow-games-drum.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/sdk": patch
----
-
-Removed triggerAndPoll. It was never recommended so it's been removed.

.changeset/small-birds-arrive.md

@@ -1,16 +0,0 @@
----
-"@trigger.dev/react-hooks": patch
----
-
-Added the ability to specify a "createdAt" filter when subscribing to tags in our useRealtime hooks:
-
-```tsx
-// Only subscribe to runs created in the last 10 hours
-useRealtimeRunWithTags("my-tag", { createdAt: "10h" })
-```
-
-You can also now choose to skip subscribing to specific columns by specifying the `skipColumns` option:
-
-```tsx
-useRealtimeRun(run.id, { skipColumns: ["usageDurationMs"] });
-```

.changeset/small-dancers-smell.md

@@ -1,6 +0,0 @@
----
-"@trigger.dev/sdk": patch
-"@trigger.dev/core": patch
----
-
-Improve metadata flushing efficiency by collapsing operations

.changeset/smart-coins-hammer.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/core": patch
----
-
-fix: Realtime streams: prevent enqueuing into closed ReadableStream

.changeset/smooth-planets-flow.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Update profile switcher

.changeset/soft-candles-do.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Update base images to latest compatible versions. The `node-22` runtime now uses v22.16.0 and `bun` uses the latest v1.2.18 release. The default `node` runtime is unchanged and points at v21.7.3.

.changeset/sour-mirrors-accept.md

@@ -1,6 +0,0 @@
----
-"trigger.dev": patch
-"@trigger.dev/core": patch
----
-
-Improve usage flushing

.changeset/spotty-ducks-punch.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-fix: default machine config indexing now works

.changeset/spotty-pants-wink.md

@@ -1,6 +0,0 @@
----
-"trigger.dev": patch
-"@trigger.dev/core": patch
----
-
-Prevent large outputs from overwriting each other

.changeset/strong-pianos-provide.md

@@ -1,6 +0,0 @@
----
-"trigger.dev": patch
-"@trigger.dev/core": patch
----
-
-Fail fast in CI when running deploy with missing `TRIGGER_ACCESS_TOKEN` and add useful error message with link to docs

.changeset/sweet-dolphins-invent.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Always print full deploy logs in CI

.changeset/swift-vans-dress.md

@@ -1,7 +0,0 @@
----
-"@trigger.dev/sdk": patch
-"trigger.dev": patch
-"@trigger.dev/core": patch
----
-
-Upgrade to zod 3.25.76

.changeset/tender-jobs-collect.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-TriggerApiError 4xx errors will no longer cause tasks to be retried

.changeset/thick-bikes-laugh.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/build": patch
----
-
-Add ffmpeg v7 support to existing extension: `ffmpeg({ version: "7" })`

.changeset/thick-poets-yawn.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/sdk": patch
----
-
-Specify a region override when triggering a run

.changeset/tidy-books-smell.md

@@ -1,8 +0,0 @@
----
-"trigger.dev": patch
-"@trigger.dev/core": patch
----
-
-- Fix polling interval reset bug that could create duplicate intervals
-- Protect against unexpected attempt number changes
-- Prevent run execution zombies after warm starts

.changeset/tiny-buckets-teach.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Fix stalled run detection

.changeset/tricky-houses-invite.md

@@ -1,6 +0,0 @@
----
-"trigger.dev": patch
-"@trigger.dev/core": patch
----
-
-Managed run controller performance and reliability improvements

.changeset/twelve-actors-hide.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Fix init.ts auto-import for deployed workers

.changeset/two-eagles-report.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/sdk": patch
----
-
-Added runs.list filtering for queue and machine

.changeset/two-tigers-dream.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/sdk": patch
----
-
-maintain proper context in metadata.root and parent getters

.changeset/vendor-superjson-esm-fix.md

@@ -0,0 +1,7 @@
+---
+"@trigger.dev/core": patch
+---
+
+fix: vendor superjson to fix ESM/CJS compatibility
+
+Bundle superjson during build to avoid `ERR_REQUIRE_ESM` errors on Node.js versions that don't support `require(ESM)` by default (< 22.12.0) and AWS Lambda which intentionally disables it.

.changeset/weak-jobs-hide.md

@@ -1,7 +0,0 @@
----
-"@trigger.dev/sdk": patch
-"trigger.dev": patch
-"@trigger.dev/core": patch
----
-
-v4: New lifecycle hooks

.changeset/weak-parents-sip.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Output esbuild metafile, can be inspected after `deploy --dry run`

.changeset/wet-deers-think.md

@@ -1,6 +0,0 @@
----
-"trigger.dev": patch
-"@trigger.dev/core": patch
----
-
-Fix QUEUED status snapshot handler

.changeset/wet-dragons-boil.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Serialize metadata to prevent invalid metadata from breaking run completions

.changeset/wet-steaks-reflect.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-If you pass a directory when calling deploy we validate it exists and give helpful hints

.changeset/wicked-ads-walk.md

@@ -1,6 +0,0 @@
----
-"@trigger.dev/react-hooks": patch
-"@trigger.dev/core": patch
----
-
-Fixes an issue with realtime when re-subscribing to a run, that would temporarily display stale data and the changes. Now when re-subscribing to a run only the latest changes will be vended

.changeset/wild-mirrors-return.md

@@ -1,6 +0,0 @@
----
-"trigger.dev": patch
-"@trigger.dev/core": patch
----
-
-Expose esbuild `minify` option (experimental)

.changeset/witty-cherries-tan.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Fix `syncEnvVars` for non-preview deployments

.changeset/witty-donkeys-unite.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/build": patch
----
-
-Add playwright extension

.changeset/yellow-cars-tell.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/core": patch
----
-
-Fix Bun runtime path resolution fallback

.claude/skills/trigger-dev-tasks/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: trigger-dev-tasks
+description: Use this skill when writing, designing, or optimizing Trigger.dev background tasks and workflows. This includes creating reliable async tasks, implementing AI workflows, setting up scheduled jobs, structuring complex task hierarchies with subtasks, configuring build extensions for tools like ffmpeg or Puppeteer/Playwright, and handling task schemas with Zod validation.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Trigger.dev Task Expert
+
+You are an expert Trigger.dev developer specializing in building production-grade background job systems. Tasks deployed to Trigger.dev run in Node.js 21+ and use the `@trigger.dev/sdk` package.
+
+## Critical Rules
+
+1. **Always use `@trigger.dev/sdk`** - Never use `@trigger.dev/sdk/v3` or deprecated `client.defineJob` pattern
+2. **Never use `node-fetch`** - Use the built-in `fetch` function
+3. **Export all tasks** - Every task must be exported, including subtasks
+4. **Never wrap wait/trigger calls in Promise.all** - `triggerAndWait`, `batchTriggerAndWait`, and `wait.*` calls cannot be wrapped in `Promise.all` or `Promise.allSettled`
+
+## Basic Task Pattern
+
+```ts
+import { task } from "@trigger.dev/sdk";
+
+export const processData = task({
+  id: "process-data",
+  retry: {
+    maxAttempts: 10,
+    factor: 1.8,
+    minTimeoutInMs: 500,
+    maxTimeoutInMs: 30_000,
+  },
+  run: async (payload: { userId: string; data: any[] }) => {
+    console.log(`Processing ${payload.data.length} items`);
+    return { processed: payload.data.length };
+  },
+});
+```
+
+## Schema Task (with validation)
+
+```ts
+import { schemaTask } from "@trigger.dev/sdk";
+import { z } from "zod";
+
+export const validatedTask = schemaTask({
+  id: "validated-task",
+  schema: z.object({
+    name: z.string(),
+    email: z.string().email(),
+  }),
+  run: async (payload) => {
+    // Payload is automatically validated and typed
+    return { message: `Hello ${payload.name}` };
+  },
+});
+```
+
+## Triggering Tasks
+
+### From Backend Code (type-only import to prevent dependency leakage)
+
+```ts
+import { tasks } from "@trigger.dev/sdk";
+import type { processData } from "./trigger/tasks";
+
+const handle = await tasks.trigger<typeof processData>("process-data", {
+  userId: "123",
+  data: [{ id: 1 }],
+});
+```
+
+### From Inside Tasks
+
+```ts
+export const parentTask = task({
+  id: "parent-task",
+  run: async (payload) => {
+    // Trigger and wait - returns Result object, NOT direct output
+    const result = await childTask.triggerAndWait({ data: "value" });
+    if (result.ok) {
+      console.log("Output:", result.output);
+    } else {
+      console.error("Failed:", result.error);
+    }
+
+    // Or unwrap directly (throws on error)
+    const output = await childTask.triggerAndWait({ data: "value" }).unwrap();
+  },
+});
+```
+
+## Idempotency (Critical for Retries)
+
+Always use idempotency keys when triggering tasks from inside other tasks:
+
+```ts
+import { idempotencyKeys } from "@trigger.dev/sdk";
+
+export const paymentTask = task({
+  id: "process-payment",
+  run: async (payload: { orderId: string }) => {
+    // Scoped to current run - survives retries
+    const key = await idempotencyKeys.create(`payment-${payload.orderId}`);
+
+    await chargeCustomer.trigger(payload, {
+      idempotencyKey: key,
+      idempotencyKeyTTL: "24h",
+    });
+  },
+});
+```
+
+## Trigger Options
+
+```ts
+await myTask.trigger(payload, {
+  delay: "1h",           // Delay execution
+  ttl: "10m",            // Cancel if not started within TTL
+  idempotencyKey: key,
+  queue: "my-queue",
+  machine: "large-1x",   // micro, small-1x, small-2x, medium-1x, medium-2x, large-1x, large-2x
+  maxAttempts: 3,
+  tags: ["user_123"],    // Max 10 tags
+  debounce: {            // Consolidate rapid triggers
+    key: "unique-key",
+    delay: "5s",
+    mode: "trailing",    // "leading" (default) or "trailing"
+  },
+});
+```
+
+## Debouncing
+
+Consolidate multiple triggers into a single execution:
+
+```ts
+// Rapid triggers with same key = single execution
+await myTask.trigger({ userId: "123" }, {
+  debounce: {
+    key: "user-123-update",
+    delay: "5s",
+  },
+});
+
+// Trailing mode: use payload from LAST trigger
+await myTask.trigger({ data: "latest" }, {
+  debounce: {
+    key: "my-key",
+    delay: "10s",
+    mode: "trailing",
+  },
+});
+```
+
+Use cases: user activity updates, webhook deduplication, search indexing, notification batching.
+
+## Batch Triggering
+
+Up to 1,000 items per batch, 3MB per payload:
+
+```ts
+const results = await myTask.batchTriggerAndWait([
+  { payload: { userId: "1" } },
+  { payload: { userId: "2" } },
+]);
+
+for (const result of results) {
+  if (result.ok) console.log(result.output);
+}
+```
+
+## Machine Presets
+
+| Preset      | vCPU | Memory |
+|-------------|------|--------|
+| micro       | 0.25 | 0.25GB |
+| small-1x    | 0.5  | 0.5GB  |
+| small-2x    | 1    | 1GB    |
+| medium-1x   | 1    | 2GB    |
+| medium-2x   | 2    | 4GB    |
+| large-1x    | 4    | 8GB    |
+| large-2x    | 8    | 16GB   |
+
+## Design Principles
+
+1. **Break complex workflows into subtasks** that can be independently retried and made idempotent
+2. **Don't over-complicate** - Sometimes `Promise.allSettled` inside a single task is better than many subtasks (each task has dedicated process and is charged by millisecond)
+3. **Always configure retries** - Set appropriate `maxAttempts` based on the operation
+4. **Use idempotency keys** - Especially for payment/critical operations
+5. **Group related subtasks** - Keep subtasks only used by one parent in the same file, don't export them
+6. **Use logger** - Log at key execution points with `logger.info()`, `logger.error()`, etc.
+
+## Reference Documentation
+
+For detailed documentation on specific topics, read these files:
+
+- `basic-tasks.md` - Task basics, triggering, waits
+- `advanced-tasks.md` - Tags, queues, concurrency, metadata, error handling
+- `scheduled-tasks.md` - Cron schedules, declarative and imperative
+- `realtime.md` - Real-time subscriptions, streams, React hooks
+- `config.md` - trigger.config.ts, build extensions (Prisma, Playwright, FFmpeg, etc.)

.claude/skills/trigger-dev-tasks/advanced-tasks.md

@@ -0,0 +1,485 @@
+# Trigger.dev Advanced Tasks (v4)
+
+**Advanced patterns and features for writing tasks**
+
+## Tags & Organization
+
+```ts
+import { task, tags } from "@trigger.dev/sdk";
+
+export const processUser = task({
+  id: "process-user",
+  run: async (payload: { userId: string; orgId: string }, { ctx }) => {
+    // Add tags during execution
+    await tags.add(`user_${payload.userId}`);
+    await tags.add(`org_${payload.orgId}`);
+
+    return { processed: true };
+  },
+});
+
+// Trigger with tags
+await processUser.trigger(
+  { userId: "123", orgId: "abc" },
+  { tags: ["priority", "user_123", "org_abc"] } // Max 10 tags per run
+);
+
+// Subscribe to tagged runs
+for await (const run of runs.subscribeToRunsWithTag("user_123")) {
+  console.log(`User task ${run.id}: ${run.status}`);
+}
+```
+
+**Tag Best Practices:**
+
+- Use prefixes: `user_123`, `org_abc`, `video:456`
+- Max 10 tags per run, 1-64 characters each
+- Tags don't propagate to child tasks automatically
+
+## Batch Triggering v2
+
+Enhanced batch triggering with larger payloads and streaming ingestion.
+
+### Limits
+
+- **Maximum batch size**: 1,000 items (increased from 500)
+- **Payload per item**: 3MB each (increased from 1MB combined)
+- Payloads > 512KB automatically offload to object storage
+
+### Rate Limiting (per environment)
+
+| Tier | Bucket Size | Refill Rate |
+|------|-------------|-------------|
+| Free | 1,200 runs | 100 runs/10 sec |
+| Hobby | 5,000 runs | 500 runs/5 sec |
+| Pro | 5,000 runs | 500 runs/5 sec |
+
+### Concurrent Batch Processing
+
+| Tier | Concurrent Batches |
+|------|-------------------|
+| Free | 1 |
+| Hobby | 10 |
+| Pro | 10 |
+
+### Usage
+
+```ts
+import { myTask } from "./trigger/myTask";
+
+// Basic batch trigger (up to 1,000 items)
+const runs = await myTask.batchTrigger([
+  { payload: { userId: "user-1" } },
+  { payload: { userId: "user-2" } },
+  { payload: { userId: "user-3" } },
+]);
+
+// Batch trigger with wait
+const results = await myTask.batchTriggerAndWait([
+  { payload: { userId: "user-1" } },
+  { payload: { userId: "user-2" } },
+]);
+
+for (const result of results) {
+  if (result.ok) {
+    console.log("Result:", result.output);
+  }
+}
+
+// With per-item options
+const batchHandle = await myTask.batchTrigger([
+  {
+    payload: { userId: "123" },
+    options: {
+      idempotencyKey: "user-123-batch",
+      tags: ["priority"],
+    },
+  },
+  {
+    payload: { userId: "456" },
+    options: {
+      idempotencyKey: "user-456-batch",
+    },
+  },
+]);
+```
+
+## Debouncing
+
+Consolidate multiple triggers into a single execution by debouncing task runs with a unique key and delay window.
+
+### Use Cases
+
+- **User activity updates**: Batch rapid user actions into a single run
+- **Webhook deduplication**: Handle webhook bursts without redundant processing
+- **Search indexing**: Combine document updates instead of processing individually
+- **Notification batching**: Group notifications to prevent user spam
+
+### Basic Usage
+
+```ts
+await myTask.trigger(
+  { userId: "123" },
+  {
+    debounce: {
+      key: "user-123-update",  // Unique identifier for debounce group
+      delay: "5s",              // Wait duration ("5s", "1m", or milliseconds)
+    },
+  }
+);
+```
+
+### Execution Modes
+
+**Leading Mode** (default): Uses payload/options from the first trigger; subsequent triggers only reschedule execution time.
+
+```ts
+// First trigger sets the payload
+await myTask.trigger({ action: "first" }, {
+  debounce: { key: "my-key", delay: "10s" }
+});
+
+// Second trigger only reschedules - payload remains "first"
+await myTask.trigger({ action: "second" }, {
+  debounce: { key: "my-key", delay: "10s" }
+});
+// Task executes with { action: "first" }
+```
+
+**Trailing Mode**: Uses payload/options from the most recent trigger.
+
+```ts
+await myTask.trigger(
+  { data: "latest-value" },
+  {
+    debounce: {
+      key: "trailing-example",
+      delay: "10s",
+      mode: "trailing",
+    },
+  }
+);
+```
+
+In trailing mode, these options update with each trigger:
+- `payload` — task input data
+- `metadata` — run metadata
+- `tags` — run tags (replaces existing)
+- `maxAttempts` — retry attempts
+- `maxDuration` — maximum compute time
+- `machine` — machine preset
+
+### Important Notes
+
+- Idempotency keys take precedence over debounce settings
+- Compatible with `triggerAndWait()` — parent runs block correctly on debounced execution
+- Debounce key is scoped to the task
+
+## Concurrency & Queues
+
+```ts
+import { task, queue } from "@trigger.dev/sdk";
+
+// Shared queue for related tasks
+const emailQueue = queue({
+  name: "email-processing",
+  concurrencyLimit: 5, // Max 5 emails processing simultaneously
+});
+
+// Task-level concurrency
+export const oneAtATime = task({
+  id: "sequential-task",
+  queue: { concurrencyLimit: 1 }, // Process one at a time
+  run: async (payload) => {
+    // Critical section - only one instance runs
+  },
+});
+
+// Per-user concurrency
+export const processUserData = task({
+  id: "process-user-data",
+  run: async (payload: { userId: string }) => {
+    // Override queue with user-specific concurrency
+    await childTask.trigger(payload, {
+      queue: {
+        name: `user-${payload.userId}`,
+        concurrencyLimit: 2,
+      },
+    });
+  },
+});
+
+export const emailTask = task({
+  id: "send-email",
+  queue: emailQueue, // Use shared queue
+  run: async (payload: { to: string }) => {
+    // Send email logic
+  },
+});
+```
+
+## Error Handling & Retries
+
+```ts
+import { task, retry, AbortTaskRunError } from "@trigger.dev/sdk";
+
+export const resilientTask = task({
+  id: "resilient-task",
+  retry: {
+    maxAttempts: 10,
+    factor: 1.8, // Exponential backoff multiplier
+    minTimeoutInMs: 500,
+    maxTimeoutInMs: 30_000,
+    randomize: false,
+  },
+  catchError: async ({ error, ctx }) => {
+    // Custom error handling
+    if (error.code === "FATAL_ERROR") {
+      throw new AbortTaskRunError("Cannot retry this error");
+    }
+
+    // Log error details
+    console.error(`Task ${ctx.task.id} failed:`, error);
+
+    // Allow retry by returning nothing
+    return { retryAt: new Date(Date.now() + 60000) }; // Retry in 1 minute
+  },
+  run: async (payload) => {
+    // Retry specific operations
+    const result = await retry.onThrow(
+      async () => {
+        return await unstableApiCall(payload);
+      },
+      { maxAttempts: 3 }
+    );
+
+    // Conditional HTTP retries
+    const response = await retry.fetch("https://api.example.com", {
+      retry: {
+        maxAttempts: 5,
+        condition: (response, error) => {
+          return response?.status === 429 || response?.status >= 500;
+        },
+      },
+    });
+
+    return result;
+  },
+});
+```
+
+## Machines & Performance
+
+```ts
+export const heavyTask = task({
+  id: "heavy-computation",
+  machine: { preset: "large-2x" }, // 8 vCPU, 16 GB RAM
+  maxDuration: 1800, // 30 minutes timeout
+  run: async (payload, { ctx }) => {
+    // Resource-intensive computation
+    if (ctx.machine.preset === "large-2x") {
+      // Use all available cores
+      return await parallelProcessing(payload);
+    }
+
+    return await standardProcessing(payload);
+  },
+});
+
+// Override machine when triggering
+await heavyTask.trigger(payload, {
+  machine: { preset: "medium-1x" }, // Override for this run
+});
+```
+
+**Machine Presets:**
+
+- `micro`: 0.25 vCPU, 0.25 GB RAM
+- `small-1x`: 0.5 vCPU, 0.5 GB RAM (default)
+- `small-2x`: 1 vCPU, 1 GB RAM
+- `medium-1x`: 1 vCPU, 2 GB RAM
+- `medium-2x`: 2 vCPU, 4 GB RAM
+- `large-1x`: 4 vCPU, 8 GB RAM
+- `large-2x`: 8 vCPU, 16 GB RAM
+
+## Idempotency
+
+```ts
+import { task, idempotencyKeys } from "@trigger.dev/sdk";
+
+export const paymentTask = task({
+  id: "process-payment",
+  retry: {
+    maxAttempts: 3,
+  },
+  run: async (payload: { orderId: string; amount: number }) => {
+    // Automatically scoped to this task run, so if the task is retried, the idempotency key will be the same
+    const idempotencyKey = await idempotencyKeys.create(`payment-${payload.orderId}`);
+
+    // Ensure payment is processed only once
+    await chargeCustomer.trigger(payload, {
+      idempotencyKey,
+      idempotencyKeyTTL: "24h", // Key expires in 24 hours
+    });
+  },
+});
+
+// Payload-based idempotency
+import { createHash } from "node:crypto";
+
+function createPayloadHash(payload: any): string {
+  const hash = createHash("sha256");
+  hash.update(JSON.stringify(payload));
+  return hash.digest("hex");
+}
+
+export const deduplicatedTask = task({
+  id: "deduplicated-task",
+  run: async (payload) => {
+    const payloadHash = createPayloadHash(payload);
+    const idempotencyKey = await idempotencyKeys.create(payloadHash);
+
+    await processData.trigger(payload, { idempotencyKey });
+  },
+});
+```
+
+## Metadata & Progress Tracking
+
+```ts
+import { task, metadata } from "@trigger.dev/sdk";
+
+export const batchProcessor = task({
+  id: "batch-processor",
+  run: async (payload: { items: any[] }, { ctx }) => {
+    const totalItems = payload.items.length;
+
+    // Initialize progress metadata
+    metadata
+      .set("progress", 0)
+      .set("totalItems", totalItems)
+      .set("processedItems", 0)
+      .set("status", "starting");
+
+    const results = [];
+
+    for (let i = 0; i < payload.items.length; i++) {
+      const item = payload.items[i];
+
+      // Process item
+      const result = await processItem(item);
+      results.push(result);
+
+      // Update progress
+      const progress = ((i + 1) / totalItems) * 100;
+      metadata
+        .set("progress", progress)
+        .increment("processedItems", 1)
+        .append("logs", `Processed item ${i + 1}/${totalItems}`)
+        .set("currentItem", item.id);
+    }
+
+    // Final status
+    metadata.set("status", "completed");
+
+    return { results, totalProcessed: results.length };
+  },
+});
+
+// Update parent metadata from child task
+export const childTask = task({
+  id: "child-task",
+  run: async (payload, { ctx }) => {
+    // Update parent task metadata
+    metadata.parent.set("childStatus", "processing");
+    metadata.root.increment("childrenCompleted", 1);
+
+    return { processed: true };
+  },
+});
+```
+
+## Logging & Tracing
+
+```ts
+import { task, logger } from "@trigger.dev/sdk";
+
+export const tracedTask = task({
+  id: "traced-task",
+  run: async (payload, { ctx }) => {
+    logger.info("Task started", { userId: payload.userId });
+
+    // Custom trace with attributes
+    const user = await logger.trace(
+      "fetch-user",
+      async (span) => {
+        span.setAttribute("user.id", payload.userId);
+        span.setAttribute("operation", "database-fetch");
+
+        const userData = await database.findUser(payload.userId);
+        span.setAttribute("user.found", !!userData);
+
+        return userData;
+      },
+      { userId: payload.userId }
+    );
+
+    logger.debug("User fetched", { user: user.id });
+
+    try {
+      const result = await processUser(user);
+      logger.info("Processing completed", { result });
+      return result;
+    } catch (error) {
+      logger.error("Processing failed", {
+        error: error.message,
+        userId: payload.userId,
+      });
+      throw error;
+    }
+  },
+});
+```
+
+## Hidden Tasks
+
+```ts
+// Hidden task - not exported, only used internally
+const internalProcessor = task({
+  id: "internal-processor",
+  run: async (payload: { data: string }) => {
+    return { processed: payload.data.toUpperCase() };
+  },
+});
+
+// Public task that uses hidden task
+export const publicWorkflow = task({
+  id: "public-workflow",
+  run: async (payload: { input: string }) => {
+    // Use hidden task internally
+    const result = await internalProcessor.triggerAndWait({
+      data: payload.input,
+    });
+
+    if (result.ok) {
+      return { output: result.output.processed };
+    }
+
+    throw new Error("Internal processing failed");
+  },
+});
+```
+
+## Best Practices
+
+- **Concurrency**: Use queues to prevent overwhelming external services
+- **Retries**: Configure exponential backoff for transient failures
+- **Idempotency**: Always use for payment/critical operations
+- **Metadata**: Track progress for long-running tasks
+- **Machines**: Match machine size to computational requirements
+- **Tags**: Use consistent naming patterns for filtering
+- **Debouncing**: Use for user activity, webhooks, and notification batching
+- **Batch triggering**: Use for bulk operations up to 1,000 items
+- **Error Handling**: Distinguish between retryable and fatal errors
+
+Design tasks to be stateless, idempotent, and resilient to failures. Use metadata for state tracking and queues for resource management.