Add onStartAttempt hook and deprecate onSuccess

Author: ericallam

apps/webapp/app/components/runs/v3/RunIcon.tsx

@@ -97,6 +97,7 @@ export function RunIcon({ name, className, spanName }: TaskIconProps) {
       return <RunFunctionIcon className={cn(className, "text-text-dimmed")} />;
     case "task-hook-init":
     case "task-hook-onStart":
+    case "task-hook-onStartAttempt":
     case "task-hook-onSuccess":
     case "task-hook-onWait":
     case "task-hook-onResume":

docs/tasks/overview.mdx

@@ -247,19 +247,16 @@ export const myTask = task({
 });
 ```
 
-### `onStart` function
+### `onStartAttempt` function
 
-When a task run starts, the `onStart` function is called. It's useful for sending notifications, logging, and other side effects.
+<Info>The `onStartAttempt` function was introduced in v4.1.0</Info>
 
-<Warning>
-  This function will only be called once per run (not per attempt). If you want to run code before
-  each attempt, use a middleware function.
-</Warning>
+Before a task run attempt starts, the `onStartAttempt` function is called. It's useful for sending notifications, logging, and other side effects.
 
 ```ts /trigger/on-start.ts
-export const taskWithOnStart = task({
-  id: "task-with-on-start",
-  onStart: async ({ payload, ctx }) => {
+export const taskWithOnStartAttempt = task({
+  id: "task-with-on-start-attempt",
+  onStartAttempt: async ({ payload, ctx }) => {
     //...
   },
   run: async (payload: any, { ctx }) => {
@@ -268,17 +265,33 @@ export const taskWithOnStart = task({
 });
 ```
 
-You can also define a global `onStart` function using `tasks.onStart()`.
+You can also define a global `onStartAttempt` function using `tasks.onStartAttempt()`.
 
 ```ts init.ts
 import { tasks } from "@trigger.dev/sdk";
 
-tasks.onStart(({ ctx, payload, task }) => {
-  console.log(`Run ${ctx.run.id} started on task ${task}`, ctx.run);
+tasks.onStartAttempt(({ ctx, payload, task }) => {
+  console.log(
+    `Run ${ctx.run.id} started on task ${task} attempt ${ctx.run.attempt.number}`,
+    ctx.run
+  );
 });
 ```
 
-<Info>Errors thrown in the `onStart` function will cause the attempt to fail.</Info>
+<Info>Errors thrown in the `onStartAttempt` function will cause the attempt to fail.</Info>
+
+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);
+    }
+  },
+});
+```
 
 ### `onWait` and `onResume` functions
 
@@ -522,6 +535,41 @@ export const cancelExampleTask = task({
   point the process will be killed.
 </Note>
 
+### `onStart` function (deprecated)
+
+<Info>The `onStart` function was deprecated in v4.1.0. Use `onStartAttempt` instead.</Info>
+
+When a task run starts, the `onStart` function is called. It's useful for sending notifications, logging, and other side effects.
+
+<Warning>
+  This function will only be called once per run (not per attempt). If you want to run code before
+  each attempt, use a middleware function or the `onStartAttempt` function.
+</Warning>
+
+```ts /trigger/on-start.ts
+export const taskWithOnStart = task({
+  id: "task-with-on-start",
+  onStart: async ({ payload, ctx }) => {
+    //...
+  },
+  run: async (payload: any, { ctx }) => {
+    //...
+  },
+});
+```
+
+You can also define a global `onStart` function using `tasks.onStart()`.
+
+```ts init.ts
+import { tasks } from "@trigger.dev/sdk";
+
+tasks.onStart(({ ctx, payload, task }) => {
+  console.log(`Run ${ctx.run.id} started on task ${task}`, ctx.run);
+});
+```
+
+<Info>Errors thrown in the `onStart` function will cause the attempt to fail.</Info>
+
 ### `init` function (deprecated)
 
 <Warning>

packages/core/src/v3/lifecycleHooks/index.ts

@@ -18,6 +18,7 @@ import {
   RegisterHookFunctionParams,
   TaskWait,
   type LifecycleHooksManager,
+  AnyOnStartAttemptHookFunction,
 } from "./types.js";
 
 const NOOP_LIFECYCLE_HOOKS_MANAGER = new NoopLifecycleHooksManager();
@@ -81,6 +82,27 @@ export class LifecycleHooksAPI {
     return this.#getManager().getGlobalStartHooks();
   }
 
+  public registerTaskStartAttemptHook(
+    taskId: string,
+    hook: RegisterHookFunctionParams<AnyOnStartAttemptHookFunction>
+  ): void {
+    this.#getManager().registerTaskStartAttemptHook(taskId, hook);
+  }
+
+  public registerGlobalStartAttemptHook(
+    hook: RegisterHookFunctionParams<AnyOnStartAttemptHookFunction>
+  ): void {
+    this.#getManager().registerGlobalStartAttemptHook(hook);
+  }
+
+  public getTaskStartAttemptHook(taskId: string): AnyOnStartAttemptHookFunction | undefined {
+    return this.#getManager().getTaskStartAttemptHook(taskId);
+  }
+
+  public getGlobalStartAttemptHooks(): RegisteredHookFunction<AnyOnStartAttemptHookFunction>[] {
+    return this.#getManager().getGlobalStartAttemptHooks();
+  }
+
   public registerGlobalFailureHook(
     hook: RegisterHookFunctionParams<AnyOnFailureHookFunction>
   ): void {

packages/core/src/v3/lifecycleHooks/manager.ts

@@ -14,6 +14,7 @@ import {
   AnyOnCleanupHookFunction,
   TaskWait,
   AnyOnCancelHookFunction,
+  AnyOnStartAttemptHookFunction,
 } from "./types.js";
 
 export class StandardLifecycleHooksManager implements LifecycleHooksManager {
@@ -23,6 +24,15 @@ export class StandardLifecycleHooksManager implements LifecycleHooksManager {
   private globalStartHooks: Map<string, RegisteredHookFunction<AnyOnStartHookFunction>> = new Map();
   private taskStartHooks: Map<string, RegisteredHookFunction<AnyOnStartHookFunction>> = new Map();
 
+  private globalStartAttemptHooks: Map<
+    string,
+    RegisteredHookFunction<AnyOnStartAttemptHookFunction>
+  > = new Map();
+  private taskStartAttemptHooks: Map<
+    string,
+    RegisteredHookFunction<AnyOnStartAttemptHookFunction>
+  > = new Map();
+
   private globalFailureHooks: Map<string, RegisteredHookFunction<AnyOnFailureHookFunction>> =
     new Map();
   private taskFailureHooks: Map<string, RegisteredHookFunction<AnyOnFailureHookFunction>> =
@@ -129,6 +139,37 @@ export class StandardLifecycleHooksManager implements LifecycleHooksManager {
     return Array.from(this.globalStartHooks.values());
   }
 
+  registerGlobalStartAttemptHook(
+    hook: RegisterHookFunctionParams<AnyOnStartAttemptHookFunction>
+  ): void {
+    const id = generateHookId(hook);
+    this.globalStartAttemptHooks.set(id, {
+      id,
+      name: hook.id,
+      fn: hook.fn,
+    });
+  }
+
+  registerTaskStartAttemptHook(
+    taskId: string,
+    hook: RegisterHookFunctionParams<AnyOnStartAttemptHookFunction>
+  ): void {
+    const id = generateHookId(hook);
+    this.taskStartAttemptHooks.set(taskId, {
+      id,
+      name: hook.id,
+      fn: hook.fn,
+    });
+  }
+
+  getTaskStartAttemptHook(taskId: string): AnyOnStartAttemptHookFunction | undefined {
+    return this.taskStartAttemptHooks.get(taskId)?.fn;
+  }
+
+  getGlobalStartAttemptHooks(): RegisteredHookFunction<AnyOnStartAttemptHookFunction>[] {
+    return Array.from(this.globalStartAttemptHooks.values());
+  }
+
   registerGlobalInitHook(hook: RegisterHookFunctionParams<AnyOnInitHookFunction>): void {
     // if there is no id, lets generate one based on the contents of the function
     const id = generateHookId(hook);
@@ -527,6 +568,22 @@ export class NoopLifecycleHooksManager implements LifecycleHooksManager {
     return [];
   }
 
+  registerGlobalStartAttemptHook(): void {
+    // Noop
+  }
+
+  registerTaskStartAttemptHook(): void {
+    // Noop
+  }
+
+  getTaskStartAttemptHook(): undefined {
+    return undefined;
+  }
+
+  getGlobalStartAttemptHooks(): RegisteredHookFunction<AnyOnStartAttemptHookFunction>[] {
+    return [];
+  }
+
   registerGlobalFailureHook(hook: RegisterHookFunctionParams<AnyOnFailureHookFunction>): void {
     // Noop
   }

packages/core/src/v3/lifecycleHooks/types.ts

@@ -33,6 +33,19 @@ export type OnStartHookFunction<TPayload, TInitOutput extends TaskInitOutput = T
 
 export type AnyOnStartHookFunction = OnStartHookFunction<unknown, TaskInitOutput>;
 
+export type TaskStartAttemptHookParams<TPayload = unknown> = {
+  ctx: TaskRunContext;
+  payload: TPayload;
+  task: string;
+  signal: AbortSignal;
+};
+
+export type OnStartAttemptHookFunction<TPayload> = (
+  params: TaskStartAttemptHookParams<TPayload>
+) => undefined | void | Promise<undefined | void>;
+
+export type AnyOnStartAttemptHookFunction = OnStartAttemptHookFunction<unknown>;
+
 export type TaskWait =
   | {
       type: "duration";
@@ -268,6 +281,17 @@ export interface LifecycleHooksManager {
   ): void;
   getTaskStartHook(taskId: string): AnyOnStartHookFunction | undefined;
   getGlobalStartHooks(): RegisteredHookFunction<AnyOnStartHookFunction>[];
+
+  registerGlobalStartAttemptHook(
+    hook: RegisterHookFunctionParams<AnyOnStartAttemptHookFunction>
+  ): void;
+  registerTaskStartAttemptHook(
+    taskId: string,
+    hook: RegisterHookFunctionParams<AnyOnStartAttemptHookFunction>
+  ): void;
+  getTaskStartAttemptHook(taskId: string): AnyOnStartAttemptHookFunction | undefined;
+  getGlobalStartAttemptHooks(): RegisteredHookFunction<AnyOnStartAttemptHookFunction>[];
+
   registerGlobalFailureHook(hook: RegisterHookFunctionParams<AnyOnFailureHookFunction>): void;
   registerTaskFailureHook(
     taskId: string,

packages/core/src/v3/types/tasks.ts

@@ -13,6 +13,7 @@ import {
   OnSuccessHookFunction,
   OnWaitHookFunction,
   OnCancelHookFunction,
+  OnStartAttemptHookFunction,
 } from "../lifecycleHooks/types.js";
 import { RunTags } from "../schemas/api.js";
 import {
@@ -114,6 +115,13 @@ export type StartFnParams = Prettify<{
   signal: AbortSignal;
 }>;
 
+export type StartAttemptFnParams = Prettify<{
+  ctx: Context;
+  init?: InitOutput;
+  /** Abort signal that is aborted when a task run exceeds it's maxDuration or if the task run is cancelled. Can be used to automatically cancel downstream requests */
+  signal: AbortSignal;
+}>;
+
 export type CancelFnParams = Prettify<{
   ctx: Context;
   /** Abort signal that is aborted when a task run exceeds it's maxDuration or if the task run is cancelled. Can be used to automatically cancel downstream requests */
@@ -328,9 +336,18 @@ type CommonTaskOptions<
 
   /**
    * onStart is called the first time a task is executed in a run (not before every retry)
+   *
+   * @deprecated Use onStartAttempt instead
    */
   onStart?: OnStartHookFunction<TPayload, TInitOutput>;
 
+  /**
+   * onStartAttempt is called before each attempt of a task is executed.
+   *
+   * You can detect the first attempt by checking `ctx.attempt.number === 1`.
+   */
+  onStartAttempt?: OnStartAttemptHookFunction<TPayload>;
+
   /**
    * onSuccess is called after the run function has successfully completed.
    */
@@ -912,6 +929,7 @@ export type TaskMetadataWithFunctions = TaskMetadata & {
     onSuccess?: (payload: any, output: any, params: SuccessFnParams<any>) => Promise<void>;
     onFailure?: (payload: any, error: unknown, params: FailureFnParams<any>) => Promise<void>;
     onStart?: (payload: any, params: StartFnParams) => Promise<void>;
+    onStartAttempt?: (payload: any, params: StartAttemptFnParams) => Promise<void>;
     parsePayload?: AnySchemaParseFn;
   };
   schema?: TaskSchema;