v4: New lifecycle hooks

.changeset/weak-jobs-hide.md

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

.cursor/rules/executing-commands.mdc

@@ -13,12 +13,12 @@ But often, when running tests, it's better to `cd` into the directory and then r
 
 ```
 cd apps/webapp
-pnpm run test
+pnpm run test --run
 ```
 
 This way you can run for a single file easily:
 
 ```
 cd internal-packages/run-engine
-pnpm run test ./src/engine/tests/ttl.test.ts
+pnpm run test ./src/engine/tests/ttl.test.ts --run
 ```

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

@@ -44,6 +44,9 @@ export function RunIcon({ name, className, spanName }: TaskIconProps) {
   }
 
   if (!name) return <Squares2X2Icon className={cn(className, "text-text-dimmed")} />;
+  if (tablerIcons.has(name)) {
+    return <TablerIcon name={name} className={className} />;
+  }
 
   switch (name) {
     case "task":
@@ -73,6 +76,28 @@ export function RunIcon({ name, className, spanName }: TaskIconProps) {
       return <InformationCircleIcon className={cn(className, "text-rose-500")} />;
     case "fatal":
       return <HandRaisedIcon className={cn(className, "text-rose-800")} />;
+    case "task-middleware":
+      return <InformationCircleIcon className={cn(className, "text-text-dimmed")} />;
+    case "task-fn-run":
+      return <InformationCircleIcon className={cn(className, "text-text-dimmed")} />;
+    case "task-hook-init":
+      return <InformationCircleIcon className={cn(className, "text-text-dimmed")} />;
+    case "task-hook-onStart":
+      return <InformationCircleIcon className={cn(className, "text-text-dimmed")} />;
+    case "task-hook-onSuccess":
+      return <InformationCircleIcon className={cn(className, "text-text-dimmed")} />;
+    case "task-hook-onFailure":
+      return <InformationCircleIcon className={cn(className, "text-text-dimmed")} />;
+    case "task-hook-onComplete":
+      return <InformationCircleIcon className={cn(className, "text-text-dimmed")} />;
+    case "task-hook-onWait":
+      return <InformationCircleIcon className={cn(className, "text-text-dimmed")} />;
+    case "task-hook-onResume":
+      return <InformationCircleIcon className={cn(className, "text-text-dimmed")} />;
+    case "task-hook-catchError":
+      return <InformationCircleIcon className={cn(className, "text-text-dimmed")} />;
+    case "task-hook-cleanup":
+      return <InformationCircleIcon className={cn(className, "text-text-dimmed")} />;
   }
 
   return <InformationCircleIcon className={cn(className, "text-text-dimmed")} />;

internal-packages/run-engine/src/engine/errors.ts

@@ -13,6 +13,9 @@ export function runStatusFromError(error: TaskRunError): TaskRunStatus {
   //e.g. a bug
   switch (error.code) {
     case "RECURSIVE_WAIT_DEADLOCK":
+    case "TASK_INPUT_ERROR":
+    case "TASK_OUTPUT_ERROR":
+    case "TASK_MIDDLEWARE_ERROR":
       return "COMPLETED_WITH_ERRORS";
     case "TASK_RUN_CANCELLED":
       return "CANCELED";
@@ -41,8 +44,6 @@ export function runStatusFromError(error: TaskRunError): TaskRunStatus {
     case "TASK_RUN_STALLED_EXECUTING_WITH_WAITPOINTS":
     case "TASK_HAS_N0_EXECUTION_SNAPSHOT":
     case "GRACEFUL_EXIT_TIMEOUT":
-    case "TASK_INPUT_ERROR":
-    case "TASK_OUTPUT_ERROR":
     case "POD_EVICTED":
     case "POD_UNKNOWN_ERROR":
     case "TASK_EXECUTION_ABORTED":

packages/cli-v3/src/build/bundle.ts

@@ -47,6 +47,7 @@ export type BundleResult = {
   runControllerEntryPoint: string | undefined;
   indexWorkerEntryPoint: string | undefined;
   indexControllerEntryPoint: string | undefined;
+  initEntryPoint: string | undefined;
   stop: (() => Promise<void>) | undefined;
 };
 
@@ -229,11 +230,26 @@ export async function getBundleResultFromBuild(
   let runControllerEntryPoint: string | undefined;
   let indexWorkerEntryPoint: string | undefined;
   let indexControllerEntryPoint: string | undefined;
+  let initEntryPoint: string | undefined;
 
   const configEntryPoint = resolvedConfig.configFile
     ? relative(resolvedConfig.workingDir, resolvedConfig.configFile)
     : "trigger.config.ts";
 
+  // Check if the entry point is an init.ts file at the root of a trigger directory
+  function isInitEntryPoint(entryPoint: string): boolean {
+    const normalizedEntryPoint = entryPoint.replace(/\\/g, "/"); // Normalize path separators
+    const initFileNames = ["init.ts", "init.mts", "init.cts", "init.js", "init.mjs", "init.cjs"];
+
+    // Check if it's directly in one of the trigger directories
+    return resolvedConfig.dirs.some((dir) => {
+      const normalizedDir = dir.replace(/\\/g, "/");
+      return initFileNames.some(
+        (fileName) => normalizedEntryPoint === `${normalizedDir}/${fileName}`
+      );
+    });
+  }
+
   for (const [outputPath, outputMeta] of Object.entries(result.metafile.outputs)) {
     if (outputPath.endsWith(".mjs")) {
       const $outputPath = resolve(workingDir, outputPath);
@@ -254,6 +270,8 @@ export async function getBundleResultFromBuild(
         indexControllerEntryPoint = $outputPath;
       } else if (isIndexWorkerForTarget(outputMeta.entryPoint, target)) {
         indexWorkerEntryPoint = $outputPath;
+      } else if (isInitEntryPoint(outputMeta.entryPoint)) {
+        initEntryPoint = $outputPath;
       } else {
         if (
           !outputMeta.entryPoint.startsWith("..") &&
@@ -280,6 +298,7 @@ export async function getBundleResultFromBuild(
     runControllerEntryPoint,
     indexWorkerEntryPoint,
     indexControllerEntryPoint,
+    initEntryPoint,
     contentHash: hasher.digest("hex"),
   };
 }
@@ -357,6 +376,7 @@ export async function createBuildManifestFromBundle({
     runControllerEntryPoint: bundle.runControllerEntryPoint ?? getRunControllerForTarget(target),
     runWorkerEntryPoint: bundle.runWorkerEntryPoint ?? getRunWorkerForTarget(target),
     loaderEntryPoint: bundle.loaderEntryPoint,
+    initEntryPoint: bundle.initEntryPoint,
     configPath: bundle.configPath,
     customConditions: resolvedConfig.build.conditions ?? [],
     deploy: {

packages/cli-v3/src/entryPoints/dev-index-worker.ts

@@ -141,6 +141,7 @@ await sendMessageInCatalog(
       controllerEntryPoint: buildManifest.runControllerEntryPoint,
       loaderEntryPoint: buildManifest.loaderEntryPoint,
       customConditions: buildManifest.customConditions,
+      initEntryPoint: buildManifest.initEntryPoint,
     },
     importErrors,
   },

packages/cli-v3/src/entryPoints/dev-run-worker.ts

@@ -1,23 +1,30 @@
 import type { Tracer } from "@opentelemetry/api";
 import type { Logger } from "@opentelemetry/api-logs";
 import {
+  AnyOnCatchErrorHookFunction,
+  AnyOnFailureHookFunction,
+  AnyOnInitHookFunction,
+  AnyOnStartHookFunction,
+  AnyOnSuccessHookFunction,
   apiClientManager,
   clock,
   ExecutorToWorkerMessageCatalog,
   type HandleErrorFunction,
+  lifecycleHooks,
+  localsAPI,
   logger,
   LogLevel,
+  resourceCatalog,
   runMetadata,
   runtime,
-  resourceCatalog,
+  runTimelineMetrics,
   TaskRunErrorCodes,
   TaskRunExecution,
   timeout,
   TriggerConfig,
   waitUntil,
   WorkerManifest,
   WorkerToExecutorMessageCatalog,
-  runTimelineMetrics,
 } from "@trigger.dev/core/v3";
 import { TriggerTracer } from "@trigger.dev/core/v3/tracer";
 import {
@@ -29,15 +36,17 @@ import {
   logLevels,
   ManagedRuntimeManager,
   OtelTaskLogger,
+  StandardLifecycleHooksManager,
+  StandardLocalsManager,
   StandardMetadataManager,
   StandardResourceCatalog,
+  StandardRunTimelineMetricsManager,
   StandardWaitUntilManager,
   TaskExecutor,
   TracingDiagnosticLogLevel,
   TracingSDK,
   usage,
   UsageTimeoutManager,
-  StandardRunTimelineMetricsManager,
 } from "@trigger.dev/core/v3/workers";
 import { ZodIpcConnection } from "@trigger.dev/core/v3/zodIpc";
 import { readFile } from "node:fs/promises";
@@ -89,10 +98,16 @@ process.on("uncaughtException", function (error, origin) {
 
 const heartbeatIntervalMs = getEnvVar("HEARTBEAT_INTERVAL_MS");
 
+const standardLocalsManager = new StandardLocalsManager();
+localsAPI.setGlobalLocalsManager(standardLocalsManager);
+
 const standardRunTimelineMetricsManager = new StandardRunTimelineMetricsManager();
 runTimelineMetrics.setGlobalManager(standardRunTimelineMetricsManager);
 standardRunTimelineMetricsManager.seedMetricsFromEnvironment();
 
+const standardLifecycleHooksManager = new StandardLifecycleHooksManager();
+lifecycleHooks.setGlobalLifecycleHooksManager(standardLifecycleHooksManager);
+
 const devUsageManager = new DevUsageManager();
 usage.setGlobalUsageManager(devUsageManager);
 timeout.setGlobalManager(new UsageTimeoutManager(devUsageManager));
@@ -170,12 +185,46 @@ async function bootstrap() {
 
   logger.setGlobalTaskLogger(otelTaskLogger);
 
+  if (config.init) {
+    lifecycleHooks.registerGlobalInitHook({
+      id: "config",
+      fn: config.init as AnyOnInitHookFunction,
+    });
+  }
+
+  if (config.onStart) {
+    lifecycleHooks.registerGlobalStartHook({
+      id: "config",
+      fn: config.onStart as AnyOnStartHookFunction,
+    });
+  }
+
+  if (config.onSuccess) {
+    lifecycleHooks.registerGlobalSuccessHook({
+      id: "config",
+      fn: config.onSuccess as AnyOnSuccessHookFunction,
+    });
+  }
+
+  if (config.onFailure) {
+    lifecycleHooks.registerGlobalFailureHook({
+      id: "config",
+      fn: config.onFailure as AnyOnFailureHookFunction,
+    });
+  }
+
+  if (handleError) {
+    lifecycleHooks.registerGlobalCatchErrorHook({
+      id: "config",
+      fn: handleError as AnyOnCatchErrorHookFunction,
+    });
+  }
+
   return {
     tracer,
     tracingSDK,
     consoleInterceptor,
     config,
-    handleErrorFn: handleError,
     workerManifest,
   };
 }
@@ -217,7 +266,7 @@ const zodIpc = new ZodIpcConnection({
       }
 
       try {
-        const { tracer, tracingSDK, consoleInterceptor, config, handleErrorFn, workerManifest } =
+        const { tracer, tracingSDK, consoleInterceptor, config, workerManifest } =
           await bootstrap();
 
         _tracingSDK = tracingSDK;
@@ -257,6 +306,18 @@ const zodIpc = new ZodIpcConnection({
             async () => {
               const beforeImport = performance.now();
               resourceCatalog.setCurrentFileContext(taskManifest.entryPoint, taskManifest.filePath);
+
+              // Load init file if it exists
+              if (workerManifest.initEntryPoint) {
+                try {
+                  await import(normalizeImportPath(workerManifest.initEntryPoint));
+                  log(`Loaded init file from ${workerManifest.initEntryPoint}`);
+                } catch (err) {
+                  logError(`Failed to load init file`, err);
+                  throw err;
+                }
+              }
+
               await import(normalizeImportPath(taskManifest.entryPoint));
               resourceCatalog.clearCurrentFileContext();
               const durationMs = performance.now() - beforeImport;
@@ -321,8 +382,7 @@ const zodIpc = new ZodIpcConnection({
           tracer,
           tracingSDK,
           consoleInterceptor,
-          config,
-          handleErrorFn,
+          retries: config.retries,
         });
 
         try {
@@ -340,42 +400,7 @@ const zodIpc = new ZodIpcConnection({
             ? timeout.abortAfterTimeout(execution.run.maxDuration)
             : undefined;
 
-          signal?.addEventListener("abort", async (e) => {
-            if (_isRunning) {
-              _isRunning = false;
-              _execution = undefined;
-
-              const usageSample = usage.stop(measurement);
-
-              await sender.send("TASK_RUN_COMPLETED", {
-                execution,
-                result: {
-                  ok: false,
-                  id: execution.run.id,
-                  error: {
-                    type: "INTERNAL_ERROR",
-                    code: TaskRunErrorCodes.MAX_DURATION_EXCEEDED,
-                    message:
-                      signal.reason instanceof Error
-                        ? signal.reason.message
-                        : String(signal.reason),
-                  },
-                  usage: {
-                    durationMs: usageSample.cpuTime,
-                  },
-                  metadata: runMetadataManager.stopAndReturnLastFlush(),
-                },
-              });
-            }
-          });
-
-          const { result } = await executor.execute(
-            execution,
-            metadata,
-            traceContext,
-            measurement,
-            signal
-          );
+          const { result } = await executor.execute(execution, metadata, traceContext, signal);
 
           const usageSample = usage.stop(measurement);
 

packages/cli-v3/src/entryPoints/managed-index-worker.ts

@@ -141,6 +141,7 @@ await sendMessageInCatalog(
       controllerEntryPoint: buildManifest.runControllerEntryPoint,
       loaderEntryPoint: buildManifest.loaderEntryPoint,
       customConditions: buildManifest.customConditions,
+      initEntryPoint: buildManifest.initEntryPoint,
     },
     importErrors,
   },