feat(webapp,sdk,core,cli): replay a run with overrides from the API, SDK and MCP

Replay a run with a different payload, metadata or trigger options from
the API, the SDK and the MCP server. The replay endpoint takes an
optional body using the same option names as `trigger()`; an empty body
replays the run unchanged, so existing clients keep working.

```ts
import { runs } from "@trigger.dev/sdk";

const { id } = await runs.replay("run_1234", {
  payload: { userId: "user_456" },
  metadata: { source: "replay" },
  tags: ["replayed"],
  machine: "large-1x",
  version: "20250101.1",
  delay: "10m",
});
```

Supported overrides: `payload`, `metadata`, `tags`, `queue`,
`concurrencyKey`, `machine`, `version`, `region`, `delay`, `ttl`,
`idempotencyKey`, `idempotencyKeyTTL`, `maxAttempts`, `maxDuration` and
`priority`. The SDK serializes a payload override like `trigger()` does,
so `Date`, `BigInt`, `Map` and `Set` values keep their types; raw HTTP
callers send plain JSON, or a SuperJSON string with `payloadType:
"application/super+json"`. The replay stays in the original run's
environment.

- The MCP server has a new `replay_run` tool with the same overrides. It
is hidden in `--readonly` mode.
- The replay endpoint accepts public access tokens. Every replay needs
permission to trigger the run's task as well as write access to the run,
the same as the trigger API.
- Replay reports why it failed: an unknown queue, an undeployed version
or an invalid option returns its message instead of "Failed to create
new run", and an unknown field in the body is rejected.
- A payload override now applies to runs whose payload was offloaded to
object storage.
- Replaying from the dashboard keeps the original payload for runs whose
payload can't be edited there, instead of sending an empty object.
- Triggering with an unknown `lockToVersion` returns a 4xx with a
message instead of a 500.

Mono-RevId: 889adbbf384910d821b41d74c75e02675c145a00

Author: ericallam

.changeset/mcp-replay-run.md

@@ -0,0 +1,5 @@
+---
+"trigger.dev": patch
+---
+
+Add a `replay_run` tool to the MCP server, so your AI assistant can replay a run, optionally with a new payload, metadata, tags, machine, version, delay or other trigger options. It is hidden in `--readonly` mode.

.changeset/replay-run-overrides.md

@@ -0,0 +1,16 @@
+---
+"@trigger.dev/sdk": patch
+"@trigger.dev/core": patch
+---
+
+`runs.replay()` now takes options, so you can replay a run with a different payload, metadata, tags, queue, machine, version, delay and other trigger options. Anything you leave out comes from the original run, as before, and the payload is serialized like `trigger()`, so values like `Date` and `BigInt` keep their types.
+
+```ts
+import { runs } from "@trigger.dev/sdk";
+
+await runs.replay("run_1234", {
+  payload: { userId: "user_456" },
+  tags: ["replayed"],
+  delay: "10m",
+});
+```

apps/webapp/app/routes/api.v1.runs.$runParam.replay.ts

@@ -1,15 +1,22 @@
+import { EngineServiceValidationError } from "@internal/run-engine";
 import { json } from "@remix-run/server-runtime";
+import { ReplayRunRequestBody } from "@trigger.dev/core/v3";
 import type { TaskRun } from "@trigger.dev/database";
 import { z } from "zod";
+import { fromZodError } from "zod-validation-error";
 import { prisma } from "~/db.server";
+import { env } from "~/env.server";
 import { runStore } from "~/v3/runStore.server";
 import { logger } from "~/services/logger.server";
 import { anyResource, createActionApiRoute } from "~/services/routeBuilders/apiBuilder.server";
 import { ReplayTaskRunService } from "~/v3/services/replayTaskRun.server";
+import { ServiceValidationError } from "~/v3/services/baseService.server";
 import { findRunByIdWithMollifierFallback } from "~/v3/mollifier/readFallback.server";
 import { resolveRunForMutation } from "~/v3/mollifier/resolveRunForMutation.server";
 import { sanitizeTriggerSource } from "~/utils/triggerSource";
 import { clientSafeErrorMessage } from "~/utils/prismaErrors";
+import { readBoundedBodyText } from "~/utils/boundedRequestBody.server";
+import { safeJsonParse } from "~/utils/json";
 
 const ParamsSchema = z.object({
   /* This is the run friendly ID */
@@ -49,10 +56,54 @@ const BufferedReplayInputSchema = z.object({
   seedMetadataType: z.string().nullable().optional(),
 });
 
+async function parseReplayOverrides(
+  request: Request
+): Promise<
+  { ok: true; overrides: z.infer<typeof ReplayRunRequestBody> } | { ok: false; response: Response }
+> {
+  const body = await readBoundedBodyText(request, env.TASK_PAYLOAD_MAXIMUM_SIZE);
+
+  if (!body.ok) {
+    return {
+      ok: false,
+      response: json(
+        {
+          error: `Request body exceeds the maximum size of ${env.TASK_PAYLOAD_MAXIMUM_SIZE} bytes`,
+        },
+        { status: 413 }
+      ),
+    };
+  }
+
+  const rawBody = body.text;
+
+  if (rawBody.trim().length === 0) {
+    return { ok: true, overrides: {} };
+  }
+
+  const parsedJson = safeJsonParse(rawBody);
+
+  if (parsedJson === null || typeof parsedJson !== "object") {
+    return { ok: false, response: json({ error: "Invalid JSON" }, { status: 400 }) };
+  }
+
+  const parsed = ReplayRunRequestBody.safeParse(parsedJson);
+
+  if (!parsed.success) {
+    return {
+      ok: false,
+      response: json({ error: fromZodError(parsed.error).toString() }, { status: 400 }),
+    };
+  }
+
+  return { ok: true, overrides: parsed.data };
+}
+
 const { action } = createActionApiRoute(
   {
     params: ParamsSchema,
     method: "POST",
+    allowJWT: true,
     findResource: (params, authentication) =>
       resolveRunForMutation({
         runParam: params.runParam,
@@ -70,9 +121,17 @@ const { action } = createActionApiRoute(
           : { type: "runs", id: params.runParam },
     },
   },
-  async ({ request, params, authentication }) => {
+  async ({ request, params, authentication, ability }) => {
     const { runParam } = params;
 
+    const body = await parseReplayOverrides(request);
+
+    if (!body.ok) {
+      return body.response;
+    }
+
+    const { overrides } = body;
+
     try {
       const env = authentication.environment;
       // PG-first. Replay works on any status per audit — no
@@ -130,10 +189,42 @@ const { action } = createActionApiRoute(
         return json({ error: "Run not found" }, { status: 404 });
       }
 
+      if (!ability.can("trigger", { type: "tasks", id: taskRun.taskIdentifier })) {
+        return json(
+          {
+            error: `Replaying this run needs permission to trigger the ${taskRun.taskIdentifier} task`,
+          },
+          { status: 403 }
+        );
+      }
+
       const triggerSource = sanitizeTriggerSource(request.headers.get("x-trigger-source")) ?? "api";
 
       const service = new ReplayTaskRunService();
-      const newRun = await service.call(taskRun, { triggerSource });
+      const newRun = await service.call(taskRun, {
+        triggerSource,
+        payload:
+          overrides.payload === undefined
+            ? undefined
+            : overrides.payloadType === "application/super+json"
+              ? (overrides.payload as string)
+              : JSON.stringify(overrides.payload),
+        payloadType: overrides.payloadType ?? "application/json",
+        metadata: overrides.metadata,
+        tags: typeof overrides.tags === "string" ? [overrides.tags] : overrides.tags,
+        queue: overrides.queue,
+        concurrencyKey: overrides.concurrencyKey,
+        machine: overrides.machine,
+        version: overrides.version,
+        region: overrides.region,
+        delay: overrides.delay,
+        ttl: overrides.ttl,
+        idempotencyKey: overrides.idempotencyKey,
+        idempotencyKeyTTL: overrides.idempotencyKeyTTL,
+        maxAttempts: overrides.maxAttempts,
+        maxDurationSeconds: overrides.maxDuration,
+        prioritySeconds: overrides.priority,
+      });
 
       if (!newRun) {
         return json({ error: "Failed to create new run" }, { status: 400 });
@@ -143,6 +234,13 @@ const { action } = createActionApiRoute(
         id: newRun?.friendlyId,
       });
     } catch (error) {
+      if (
+        error instanceof ServiceValidationError ||
+        error instanceof EngineServiceValidationError
+      ) {
+        return json({ error: error.message }, { status: error.status ?? 400 });
+      }
+
       if (error instanceof Error) {
         logger.error("Failed to replay run", {
           error: {

apps/webapp/app/v3/engineVersion.server.ts

@@ -4,6 +4,7 @@ import {
   findCurrentWorkerFromEnvironment,
   getCurrentWorkerDeploymentEngineVersion,
 } from "./models/workerDeployment.server";
+import { ServiceValidationError } from "./services/common.server";
 
 // Co-locate the per-env run-ops residency/mint decision next to the
 // engine-version decision. determineEngineVersion is intentionally left untouched so its
@@ -57,7 +58,9 @@ export async function determineEngineVersion({
     });
 
     if (!worker) {
-      throw new Error(`Worker not found: environment: ${environment.id} version: ${workerVersion}`);
+      throw new ServiceValidationError(
+        `Version ${workerVersion} was not found in this environment`
+      );
     }
 
     return worker.engine;

apps/webapp/app/v3/replayTask.ts

@@ -9,7 +9,7 @@ export const ReplayRunData = z
       .optional()
       .transform((val, ctx) => {
         if (!val) {
-          return "{}";
+          return undefined;
         }
 
         try {

apps/webapp/app/v3/services/replayTaskRun.server.ts

@@ -4,11 +4,12 @@ import {
   parsePacket,
   stringifyIO,
 } from "@trigger.dev/core/v3";
+import { EngineServiceValidationError } from "@internal/run-engine";
 import { type TaskRun } from "@trigger.dev/database";
 import { findEnvironmentById } from "~/models/runtimeEnvironment.server";
 import { baseWorkerQueue } from "~/runEngine/concerns/workerQueueSplit.server";
 import { logger } from "~/services/logger.server";
-import { BaseService } from "./baseService.server";
+import { BaseService, ServiceValidationError } from "./baseService.server";
 import { OutOfEntitlementError, TriggerTaskService } from "./triggerTask.server";
 import { type RunOptionsData } from "../testTask";
 import { replaceSuperJsonPayload } from "@trigger.dev/core/v3/utils/ioSerialization";
@@ -17,9 +18,18 @@ import { determineRealtimeStreamsVersion } from "~/services/realtime/v1StreamsGl
 type OverrideOptions = {
   environmentId?: string;
   payload?: string;
+  /**
+   * The encoding of `payload`, used as-is for the new run. Without it, an override of a
+   * SuperJSON payload is plain JSON that keeps the original payload's type annotations,
+   * which is what the dashboard's payload editor relies on.
+   */
+  payloadType?: "application/json" | "application/super+json";
   metadata?: unknown;
   bulkActionId?: string;
   triggerSource?: string;
+  delay?: string | Date;
+  ttl?: string | number;
+  idempotencyKeyTTL?: string;
   // zod v4 types `.optional().transform()` fields as required-with-undefined in the
   // output; Partial keeps them omittable for callers passing a subset of overrides.
 } & Partial<RunOptionsData>;
@@ -90,7 +100,8 @@ export class ReplayTaskRunService extends BaseService {
 
     const payloadPacket = await this.overrideExistingPayloadPacket(
       existingTaskRun,
-      overrideOptions.payload
+      overrideOptions.payload,
+      overrideOptions.payloadType
     );
     const parsedPayload =
       payloadPacket.dataType === "application/json"
@@ -118,6 +129,12 @@ export class ReplayTaskRunService extends BaseService {
         },
       });
 
+      if (overrideOptions.queue && !taskQueue) {
+        throw new ServiceValidationError(
+          `Queue "${overrideOptions.queue}" was not found in this environment`
+        );
+      }
+
       const triggerTaskService = new TriggerTaskService();
       const result = await triggerTaskService.call(
         existingTaskRun.taskIdentifier,
@@ -134,14 +151,18 @@ export class ReplayTaskRunService extends BaseService {
             test: existingTaskRun.isTest,
             tags,
             metadata: metadata,
-            delay: overrideOptions.delaySeconds
-              ? new Date(Date.now() + overrideOptions.delaySeconds * 1000)
-              : undefined,
-            ttl: overrideOptions.ttlSeconds,
+            delay:
+              overrideOptions.delay ??
+              (overrideOptions.delaySeconds
+                ? new Date(Date.now() + overrideOptions.delaySeconds * 1000)
+                : undefined),
+            ttl: overrideOptions.ttl ?? overrideOptions.ttlSeconds,
             idempotencyKey: overrideOptions.idempotencyKey,
-            idempotencyKeyTTL: overrideOptions.idempotencyKeyTTLSeconds
-              ? `${overrideOptions.idempotencyKeyTTLSeconds}s`
-              : undefined,
+            idempotencyKeyTTL:
+              overrideOptions.idempotencyKeyTTL ??
+              (overrideOptions.idempotencyKeyTTLSeconds
+                ? `${overrideOptions.idempotencyKeyTTLSeconds}s`
+                : undefined),
             concurrencyKey:
               overrideOptions.concurrencyKey ?? existingTaskRun.concurrencyKey ?? undefined,
             /**
@@ -188,6 +209,13 @@ export class ReplayTaskRunService extends BaseService {
         return;
       }
 
+      if (
+        error instanceof ServiceValidationError ||
+        error instanceof EngineServiceValidationError
+      ) {
+        throw error;
+      }
+
       logger.error("Failed to replay a run", {
         error: error instanceof Error ? error.message : error,
       });
@@ -198,16 +226,21 @@ export class ReplayTaskRunService extends BaseService {
 
   private async overrideExistingPayloadPacket(
     existingTaskRun: TaskRun,
-    stringifiedPayloadOverride: string | undefined
+    stringifiedPayloadOverride: string | undefined,
+    payloadType: "application/json" | "application/super+json" | undefined
   ) {
-    if (existingTaskRun.payloadType === "application/store") {
+    if (stringifiedPayloadOverride === undefined) {
       return conditionallyImportPacket({
         data: existingTaskRun.payload,
         dataType: existingTaskRun.payloadType,
       });
     }
 
-    if (stringifiedPayloadOverride && existingTaskRun.payloadType === "application/super+json") {
+    if (payloadType) {
+      return { data: stringifiedPayloadOverride, dataType: payloadType };
+    }
+
+    if (existingTaskRun.payloadType === "application/super+json") {
       const newPayload = await replaceSuperJsonPayload(
         existingTaskRun.payload,
         stringifiedPayloadOverride
@@ -216,10 +249,7 @@ export class ReplayTaskRunService extends BaseService {
       return stringifyIO(newPayload);
     }
 
-    return conditionallyImportPacket({
-      data: stringifiedPayloadOverride ?? existingTaskRun.payload,
-      dataType: existingTaskRun.payloadType,
-    });
+    return { data: stringifiedPayloadOverride, dataType: "application/json" };
   }
 
   private async getExistingMetadata(existingTaskRun: TaskRun) {

apps/webapp/test/replayRunData.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+import { ReplayRunData } from "~/v3/replayTask";
+
+describe("ReplayRunData", () => {
+  it("leaves the payload unset when the form does not send one", () => {
+    const result = ReplayRunData.safeParse({ failedRedirect: "/runs" });
+
+    expect(result.success).toBe(true);
+    expect(result.data?.payload).toBeUndefined();
+  });
+
+  it("keeps an edited payload", () => {
+    const result = ReplayRunData.safeParse({ failedRedirect: "/runs", payload: '{"n":2}' });
+
+    expect(result.success).toBe(true);
+    expect(result.data?.payload).toBe('{"n":2}');
+  });
+
+  it("rejects a payload that is not JSON", () => {
+    const result = ReplayRunData.safeParse({ failedRedirect: "/runs", payload: "{nope" });
+
+    expect(result.success).toBe(false);
+  });
+});

docs/mcp-tools.mdx

@@ -102,6 +102,20 @@ Cancel a running or queued run.
 - `"Cancel run run_abc123"`
 - `"Stop that task"`
 
+### replay_run
+
+Replay a run as a new run of the same task, in the same environment. The new run reuses the original run's payload, metadata, tags, queue, concurrency key, and machine unless you override them. See [Replaying](/replaying) for how each option falls back.
+
+**Parameters:**
+- `runId` (required): The run to replay, starting with `run_`
+- `payload`, `metadata`, `tags` (optional): Replace the original run's values
+- `queue`, `concurrencyKey`, `machine`, `version`, `region`, `delay`, `ttl`, `idempotencyKey`, `maxAttempts`, `maxDuration`, `priority` (optional): Override the trigger options for the new run
+
+**Example usage:**
+- `"Replay run run_abc123"`
+- `"Replay that failed run with userId set to user_456"`
+- `"Replay run run_abc123 on a large-1x machine in 10 minutes"`
+
 ## Deployment Tools
 
 ### deploy
@@ -225,7 +239,7 @@ Check the status of the dev server and view recent output. Shows whether it is s
 - `"Are there any build errors?"`
 
 <Callout type="warning">
-  The deploy and list_preview_branches tools are not available when the MCP server is running with the `--dev-only` flag. The `--readonly` flag hides deploy, trigger_task, and cancel_run.
+  The deploy and list_preview_branches tools are not available when the MCP server is running with the `--dev-only` flag. The `--readonly` flag hides deploy, trigger_task, cancel_run, and replay_run.
 </Callout>
 
 ## Agent Chat Tools