Add onStartAttempt hook and deprecate onStart hook

Author: ericallam

.changeset/tiny-carrots-rest.md

@@ -1,5 +1,41 @@
 ---
-"@trigger.dev/sdk": patch
+"@trigger.dev/sdk": minor
 ---
 
-Prevent onSuccess, onComplete, and onFailure lifecycle hooks from failing attempts/runs
+Prevent uncaught errors in the `onSuccess`, `onComplete`, and `onFailure` lifecycle hooks from failing attempts/runs.
+
+Deprecated the `onStart` lifecycle hook (which only fires before the `run` function on the first attempt). Replaced with `onStartAttempt` that fires before the run function on every attempt:
+
+```ts
+export const taskWithOnStartAttempt = task({
+  id: "task-with-on-start-attempt",
+  onStartAttempt: async ({ payload, ctx }) => {
+    //...
+  },
+  run: async (payload: any, { ctx }) => {
+    //...
+  },
+});
+
+// Default a global lifecycle hook using tasks
+tasks.onStartAttempt(({ ctx, payload, task }) => {
+  console.log(
+    `Run ${ctx.run.id} started on task ${task} attempt ${ctx.run.attempt.number}`,
+    ctx.run
+  );
+});
+```
+
+If you want to execute code before just the first attempt, you can use the `onStartAttempt` function and check `ctx.run.attempt.number === 1`:
+
+```ts /trigger/on-start-attempt.ts
+export const taskWithOnStartAttempt = task({
+  id: "task-with-on-start-attempt",
+  onStartAttempt: async ({ payload, ctx }) => {
+    if (ctx.run.attempt.number === 1) {
+      console.log("Run started on attempt 1", ctx.run);
+    }
+  },
+});
+```
+

packages/cli-v3/package.json

@@ -155,4 +155,4 @@
       }
     }
   }
-}
+}

packages/core/src/v3/lifecycle-hooks-api.ts

@@ -35,4 +35,5 @@ export type {
   TaskCancelHookParams,
   OnCancelHookFunction,
   AnyOnCancelHookFunction,
+  AnyOnStartAttemptHookFunction,
 } from "./lifecycleHooks/types.js";

packages/core/src/v3/workers/taskExecutor.ts

@@ -1030,7 +1030,7 @@ export class TaskExecutor {
         if (taskStartHook) {
           const [hookError] = await tryCatch(
             this._tracer.startActiveSpan(
-              "onStart()",
+              "onStartAttempt()",
               async (span) => {
                 await taskStartHook({
                   payload,

packages/trigger-sdk/src/v3/hooks.ts

@@ -12,8 +12,8 @@ import {
   type AnyOnCatchErrorHookFunction,
   type AnyOnMiddlewareHookFunction,
   type AnyOnCancelHookFunction,
+  type AnyOnStartAttemptHookFunction,
 } from "@trigger.dev/core/v3";
-import { AnyOnStartAttemptHookFunction } from "../../../core/src/v3/lifecycleHooks/types.js";
 
 export type {
   AnyOnStartHookFunction,

packages/trigger-sdk/src/v3/shared.ts

@@ -90,8 +90,8 @@ import type {
   TriggerAndWaitOptions,
   TriggerApiRequestOptions,
   TriggerOptions,
+  AnyOnStartAttemptHookFunction,
 } from "@trigger.dev/core/v3";
-import { AnyOnStartAttemptHookFunction } from "../../../core/src/v3/lifecycleHooks/types.js";
 
 export type {
   AnyRunHandle,

references/hello-world/src/trigger/example.ts

@@ -507,3 +507,24 @@ export const throwErrorInInitHookTask = task({
     throw new Error("Forced error to cause a retry");
   },
 });
+
+export const testStartAttemptHookTask = task({
+  id: "test-start-attempt-hook",
+  retry: {
+    maxAttempts: 3,
+  },
+  run: async (payload: { message: string }, { ctx }) => {
+    logger.info("Hello, world from the test start attempt hook task", { message: payload.message });
+
+    if (ctx.attempt.number === 1) {
+      throw new Error("Forced error to cause a retry so we can test the onStartAttempt hook");
+    }
+  },
+  onStartAttempt: async ({ payload, ctx }) => {
+    console.log(`onStartAttempt hook called ${ctx.attempt.number}`);
+  },
+});
+
+tasks.onStartAttempt(({ payload, ctx }) => {
+  console.log(`global onStartAttempt hook called ${ctx.attempt.number}`);
+});