@supergrowthai/tq 1.0.4 → 1.0.6

package/dist/index.cjs

@@ -1,6 +1,51 @@
 "use strict";
+var __knownSymbol = (name, symbol) => (symbol = Symbol[name]) ? symbol : /* @__PURE__ */ Symbol.for("Symbol." + name);
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __using = (stack, value, async) => {
+  if (value != null) {
+    if (typeof value !== "object" && typeof value !== "function") __typeError("Object expected");
+    var dispose, inner;
+    if (async) dispose = value[__knownSymbol("asyncDispose")];
+    if (dispose === void 0) {
+      dispose = value[__knownSymbol("dispose")];
+      if (async) inner = dispose;
+    }
+    if (typeof dispose !== "function") __typeError("Object not disposable");
+    if (inner) dispose = function() {
+      try {
+        inner.call(this);
+      } catch (e) {
+        return Promise.reject(e);
+      }
+    };
+    stack.push([async, dispose, value]);
+  } else if (async) {
+    stack.push([async]);
+  }
+  return value;
+};
+var __callDispose = (stack, error, hasError) => {
+  var E = typeof SuppressedError === "function" ? SuppressedError : function(e, s, m, _) {
+    return _ = Error(m), _.name = "SuppressedError", _.error = e, _.suppressed = s, _;
+  };
+  var fail = (e) => error = hasError ? new E(e, error, "An error was suppressed during disposal") : (hasError = true, e);
+  var next = (it) => {
+    while (it = stack.pop()) {
+      try {
+        var result = it[1] && it[1].call(it[2]);
+        if (it[0]) return Promise.resolve(result).then(next, (e) => (fail(e), next()));
+      } catch (e) {
+        fail(e);
+      }
+    }
+    if (hasError) throw error;
+  };
+  return next();
+};
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const PrismaAdapter = require("./PrismaAdapter-D-Bjaonm.cjs");
+const PrismaAdapter = require("./PrismaAdapter-CT8dxOZX.cjs");
 const mq = require("@supergrowthai/mq");
 const client = require("./client-DgdG7pT6.cjs");
 const utils_taskIdGen = require("./utils/task-id-gen.cjs");
@@ -555,144 +600,326 @@ function requireChunk() {
 }
 var chunkExports = requireChunk();
 const chunk = /* @__PURE__ */ getDefaultExportFromCjs(chunkExports);
+class DisposableLockBatch {
+  constructor(lockManager, onError) {
+    this.lockManager = lockManager;
+    this.onError = onError;
+    this.lockIds = [];
+    this.disposed = false;
+  }
+  /**
+   * Get the list of currently held lock IDs
+   */
+  get heldLocks() {
+    return this.lockIds;
+  }
+  /**
+   * Number of locks currently held
+   */
+  get size() {
+    return this.lockIds.length;
+  }
+  /**
+   * Acquire a lock and track it for automatic release
+   */
+  async acquire(lockId, timeout) {
+    if (this.disposed) {
+      throw new Error("Cannot acquire lock on disposed DisposableLockBatch");
+    }
+    const acquired = await this.lockManager.acquire(lockId, timeout);
+    if (acquired) {
+      this.lockIds.push(lockId);
+    }
+    return acquired;
+  }
+  /**
+   * AsyncDisposable implementation - releases all locks
+   */
+  async [Symbol.asyncDispose]() {
+    if (this.disposed) return;
+    this.disposed = true;
+    await Promise.all(
+      this.lockIds.map(
+        (lockId) => this.lockManager.release(lockId).catch((err) => {
+          if (this.onError) {
+            this.onError(lockId, err);
+          }
+        })
+      )
+    );
+  }
+}
 class TaskRunner {
-  constructor(messageQueue, taskQueue, taskStore, cacheProvider, generateId) {
+  constructor(messageQueue, taskQueue, taskStore, cacheProvider, generateId, lifecycleProvider, lifecycleConfig) {
     this.messageQueue = messageQueue;
     this.taskQueue = taskQueue;
     this.taskStore = taskStore;
     this.generateId = generateId;
+    this.lifecycleProvider = lifecycleProvider;
+    this.lifecycleConfig = lifecycleConfig;
+    this.taskStartTimes = /* @__PURE__ */ new Map();
     this.logger = new client.Logger("TaskRunner", client.LogLevel.INFO);
     this.lockManager = new LockManager(cacheProvider, {
       prefix: "task_lock_",
       defaultTimeout: 30 * 60
     });
   }
+  // ============ Lifecycle Helpers ============
   async run(taskRunnerId, tasksRaw, asyncTaskManager, abortSignal) {
-    this.logger.info(`[${taskRunnerId}] Starting task runner`);
-    this.logger.info(`[${taskRunnerId}] Processing ${tasksRaw.length} provided tasks`);
-    if (abortSignal?.aborted) {
-      this.logger.info(`[${taskRunnerId}] AbortSignal already aborted, returning empty results`);
-      return { successTasks: [], failedTasks: [], newTasks: [], ignoredTasks: [], asyncTasks: [] };
-    }
-    const tasks = await this.lockManager.filterLocked(tasksRaw, utils_taskIdGen.tId);
-    this.logger.info(`[${taskRunnerId}] Found ${tasks.length} not locked tasks to process`);
-    await Promise.all(tasks.map((t) => this.lockManager.acquire(utils_taskIdGen.tId(t))));
-    const groupedTasksObject = tasks.reduce((acc, task) => {
-      acc[task.type] = acc[task.type] || [];
-      acc[task.type].push(task);
-      return acc;
-    }, {});
-    const groupedTasksArray = Object.keys(groupedTasksObject).reduce((acc, type) => {
-      acc.push({ type, tasks: groupedTasksObject[type] });
-      return acc;
-    }, []);
-    this.logger.info(`[${taskRunnerId}] Task groups: ${groupedTasksArray.map((g) => `${g.type}: ${g.tasks.length}`).join(", ")}`);
-    const actions = new core_Actions.Actions(taskRunnerId);
-    const asyncTasks = [];
-    const processedTaskIds = /* @__PURE__ */ new Set();
-    for (let i = 0; i < groupedTasksArray.length; i++) {
+    var _stack = [];
+    try {
+      this.logger.info(`[${taskRunnerId}] Starting task runner`);
+      this.logger.info(`[${taskRunnerId}] Processing ${tasksRaw.length} provided tasks`);
       if (abortSignal?.aborted) {
-        this.logger.info(`[${taskRunnerId}] AbortSignal detected, stopping task group processing`);
-        break;
+        this.logger.info(`[${taskRunnerId}] AbortSignal already aborted, returning empty results`);
+        return { successTasks: [], failedTasks: [], newTasks: [], ignoredTasks: [], asyncTasks: [] };
       }
-      const taskGroup = groupedTasksArray[i];
-      const firstTask = taskGroup.tasks[0];
-      if (!firstTask) {
-        this.logger.warn(`[${taskRunnerId}] No tasks found for type: ${taskGroup.type}`);
-        continue;
+      const tasks = await this.lockManager.filterLocked(tasksRaw, utils_taskIdGen.tId);
+      this.logger.info(`[${taskRunnerId}] Found ${tasks.length} not locked tasks to process`);
+      const locks = __using(_stack, new DisposableLockBatch(
+        this.lockManager,
+        (lockId, err) => this.logger.error(`[${taskRunnerId}] Failed to release lock ${lockId}:`, err)
+      ), true);
+      for (const task of tasks) {
+        await locks.acquire(utils_taskIdGen.tId(task));
       }
-      const executor = this.taskQueue.getExecutor(firstTask.queue_id, taskGroup.type);
-      if (!executor) {
-        this.logger.warn(`[${taskRunnerId}] No executor found for type: ${taskGroup.type} in queue ${firstTask.queue_id}`);
-        for (const task of taskGroup.tasks) {
-          const taskWithId = task.id ? task : { ...task, id: this.generateId() };
-          actions.addIgnoredTask(taskWithId);
+      const groupedTasksObject = tasks.reduce((acc, task) => {
+        acc[task.type] = acc[task.type] || [];
+        acc[task.type].push(task);
+        return acc;
+      }, {});
+      const groupedTasksArray = Object.keys(groupedTasksObject).reduce((acc, type) => {
+        acc.push({ type, tasks: groupedTasksObject[type] });
+        return acc;
+      }, []);
+      this.logger.info(`[${taskRunnerId}] Task groups: ${groupedTasksArray.map((g) => `${g.type}: ${g.tasks.length}`).join(", ")}`);
+      const actions = new core_Actions.Actions(taskRunnerId);
+      const asyncTasks = [];
+      const processedTaskIds = /* @__PURE__ */ new Set();
+      for (let i = 0; i < groupedTasksArray.length; i++) {
+        if (abortSignal?.aborted) {
+          this.logger.info(`[${taskRunnerId}] AbortSignal detected, stopping task group processing`);
+          break;
         }
-        continue;
-      }
-      if (executor.asyncConfig?.handoffTimeout && asyncTaskManager && !asyncTaskManager.canAcceptTask()) {
-        this.logger.warn(`[${taskRunnerId}] Async queue full, rescheduling ${taskGroup.tasks.length} ${taskGroup.type} tasks for 3 min later`);
-        const rescheduledTasks = taskGroup.tasks.map((task) => ({
-          ...task,
-          execute_at: new Date(Date.now() + 18e4),
-          status: "scheduled"
-        }));
-        await this.taskStore.updateTasksForRetry(rescheduledTasks);
-        continue;
-      }
-      taskGroup.tasks.forEach((task) => processedTaskIds.add(utils_taskIdGen.tId(task)));
-      this.logger.info(`[${taskRunnerId}] Processing ${taskGroup.tasks.length} tasks of type: ${taskGroup.type}`);
-      if (executor.multiple) {
-        await executor.onTasks(taskGroup.tasks, actions).catch((err) => this.logger.error(`[${taskRunnerId}] executor.onTasks failed: ${err}`));
-      } else {
-        if (executor.parallel) {
-          const chunks = chunk(taskGroup.tasks, executor.chunkSize);
-          this.logger.info(`[${taskRunnerId}] Processing in parallel chunks of ${executor.chunkSize}`);
-          for (const chunk2 of chunks) {
-            const chunkTasks = [];
-            for (let j = 0; j < chunk2.length; j++) {
-              const taskActions = actions.forkForTask(chunk2[j]);
-              chunkTasks.push(executor.onTask(chunk2[j], taskActions).catch((err) => this.logger.error(`[${taskRunnerId}] executor.onTask failed: ${err}`)));
-            }
-            await Promise.all(chunkTasks);
+        const taskGroup = groupedTasksArray[i];
+        const firstTask = taskGroup.tasks[0];
+        if (!firstTask) {
+          this.logger.warn(`[${taskRunnerId}] No tasks found for type: ${taskGroup.type}`);
+          continue;
+        }
+        const executor = this.taskQueue.getExecutor(firstTask.queue_id, taskGroup.type);
+        if (!executor) {
+          this.logger.warn(`[${taskRunnerId}] No executor found for type: ${taskGroup.type} in queue ${firstTask.queue_id}`);
+          for (const task of taskGroup.tasks) {
+            const taskWithId = task.id ? task : { ...task, id: this.generateId() };
+            actions.addIgnoredTask(taskWithId);
           }
+          continue;
+        }
+        if (executor.asyncConfig?.handoffTimeout && asyncTaskManager && !asyncTaskManager.canAcceptTask()) {
+          this.logger.warn(`[${taskRunnerId}] Async queue full, rescheduling ${taskGroup.tasks.length} ${taskGroup.type} tasks for 3 min later`);
+          const rescheduledTasks = taskGroup.tasks.map((task) => ({
+            ...task,
+            execute_at: new Date(Date.now() + 18e4),
+            status: "scheduled"
+          }));
+          await this.taskStore.updateTasksForRetry(rescheduledTasks);
+          continue;
+        }
+        taskGroup.tasks.forEach((task) => processedTaskIds.add(utils_taskIdGen.tId(task)));
+        this.logger.info(`[${taskRunnerId}] Processing ${taskGroup.tasks.length} tasks of type: ${taskGroup.type}`);
+        if (executor.multiple) {
+          await executor.onTasks(taskGroup.tasks, actions).catch((err) => this.logger.error(`[${taskRunnerId}] executor.onTasks failed: ${err}`));
         } else {
-          const timeoutMs = executor.asyncConfig?.handoffTimeout;
-          for (let j = 0; j < taskGroup.tasks.length; j++) {
-            const task = taskGroup.tasks[j];
-            if (!timeoutMs) {
-              const taskActions = actions.forkForTask(task);
-              await executor.onTask(task, taskActions).catch((err) => this.logger.error(`[${taskRunnerId}] executor.onTask failed: ${err}`));
-            } else {
-              const startTime = Date.now();
-              const taskActions = actions.forkForTask(task);
-              const taskPromise = executor.onTask(task, taskActions).catch((err) => {
-                this.logger.error(`[${taskRunnerId}] executor.onTask failed: ${err}`);
-              });
-              let timeoutId;
-              const timeoutPromise = new Promise((resolve) => {
-                timeoutId = setTimeout(() => {
-                  resolve("~~~timeout");
-                }, timeoutMs);
-              });
-              const result = await Promise.race([taskPromise, timeoutPromise]);
-              if (timeoutId) {
-                clearTimeout(timeoutId);
+          if (executor.parallel) {
+            const chunks = chunk(taskGroup.tasks, executor.chunkSize);
+            this.logger.info(`[${taskRunnerId}] Processing in parallel chunks of ${executor.chunkSize}`);
+            for (const taskChunk of chunks) {
+              for (const task of taskChunk) {
+                this.emitTaskStarted(task, taskRunnerId);
               }
-              if (result === "~~~timeout") {
-                this.logger.info(`[${taskRunnerId}] Task ${utils_taskIdGen.tId(task)} (${task.type}) exceeded ${timeoutMs}ms, marking for async handoff`);
-                if (!asyncTaskManager) {
-                  throw new Error(`Task ${task.type} exceeded timeout but AsyncTaskManager not initialized!`);
+              const chunkPromises = [];
+              for (let j = 0; j < taskChunk.length; j++) {
+                const taskActions = actions.forkForTask(taskChunk[j]);
+                chunkPromises.push(executor.onTask(taskChunk[j], taskActions).catch((err) => this.logger.error(`[${taskRunnerId}] executor.onTask failed: ${err}`)));
+              }
+              await Promise.all(chunkPromises);
+              for (const task of taskChunk) {
+                const resultStatus = actions.getTaskResultStatus(utils_taskIdGen.tId(task));
+                if (resultStatus === "success") {
+                  this.emitTaskCompleted(task, taskRunnerId);
+                } else if (resultStatus === "fail") {
+                  const retryCount = task.execution_stats?.retry_count || 0;
+                  const maxRetries = task.retries ?? executor.default_retries ?? 0;
+                  const willRetry = retryCount < maxRetries;
+                  this.emitTaskFailed(task, taskRunnerId, new Error("Task failed"), willRetry);
+                }
+              }
+            }
+          } else {
+            const timeoutMs = executor.asyncConfig?.handoffTimeout;
+            for (let j = 0; j < taskGroup.tasks.length; j++) {
+              const task = taskGroup.tasks[j];
+              if (!timeoutMs) {
+                this.emitTaskStarted(task, taskRunnerId);
+                const taskActions = actions.forkForTask(task);
+                await executor.onTask(task, taskActions).catch((err) => this.logger.error(`[${taskRunnerId}] executor.onTask failed: ${err}`));
+                const resultStatus = actions.getTaskResultStatus(utils_taskIdGen.tId(task));
+                if (resultStatus === "success") {
+                  this.emitTaskCompleted(task, taskRunnerId);
+                } else if (resultStatus === "fail") {
+                  const retryCount = task.execution_stats?.retry_count || 0;
+                  const maxRetries = task.retries ?? executor.default_retries ?? 0;
+                  const willRetry = retryCount < maxRetries;
+                  this.emitTaskFailed(task, taskRunnerId, new Error("Task failed"), willRetry);
                 }
-                if (!task.id) {
-                  this.logger.error(`[${taskRunnerId}] Cannot hand off task without id (type: ${task.type}). Task will continue but won't be tracked.`);
-                } else {
-                  const asyncActions = new core_async_AsyncActions.AsyncActions(this.messageQueue, this.taskStore, this.taskQueue, actions, task, this.generateId);
-                  const asyncPromise = taskPromise.finally(async () => {
-                    try {
-                      await asyncActions.onPromiseFulfilled();
-                    } catch (err) {
-                      this.logger.error(`[${taskRunnerId}] Failed to execute async actions for task ${utils_taskIdGen.tId(task)}:`, err);
-                    }
-                  });
-                  asyncTasks.push({
-                    task,
-                    promise: asyncPromise,
-                    startTime,
-                    actions: asyncActions
-                  });
+              } else {
+                this.emitTaskStarted(task, taskRunnerId);
+                const startTime = Date.now();
+                const taskActions = actions.forkForTask(task);
+                const taskPromise = executor.onTask(task, taskActions).catch((err) => {
+                  this.logger.error(`[${taskRunnerId}] executor.onTask failed: ${err}`);
+                });
+                let timeoutId;
+                const timeoutPromise = new Promise((resolve) => {
+                  timeoutId = setTimeout(() => {
+                    resolve("~~~timeout");
+                  }, timeoutMs);
+                });
+                const result = await Promise.race([taskPromise, timeoutPromise]);
+                if (timeoutId) {
+                  clearTimeout(timeoutId);
+                }
+                if (result !== "~~~timeout") {
+                  const resultStatus = actions.getTaskResultStatus(utils_taskIdGen.tId(task));
+                  if (resultStatus === "success") {
+                    this.emitTaskCompleted(task, taskRunnerId);
+                  } else if (resultStatus === "fail") {
+                    const retryCount = task.execution_stats?.retry_count || 0;
+                    const maxRetries = task.retries ?? executor.default_retries ?? 0;
+                    const willRetry = retryCount < maxRetries;
+                    this.emitTaskFailed(task, taskRunnerId, new Error("Task failed"), willRetry);
+                  }
+                }
+                if (result === "~~~timeout") {
+                  this.logger.info(`[${taskRunnerId}] Task ${utils_taskIdGen.tId(task)} (${task.type}) exceeded ${timeoutMs}ms, marking for async handoff`);
+                  if (!asyncTaskManager) {
+                    throw new Error(`Task ${task.type} exceeded timeout but AsyncTaskManager not initialized!`);
+                  }
+                  if (!task.id) {
+                    this.logger.error(`[${taskRunnerId}] Cannot hand off task without id (type: ${task.type}). Task will continue but won't be tracked.`);
+                  } else {
+                    const asyncActions = new core_async_AsyncActions.AsyncActions(this.messageQueue, this.taskStore, this.taskQueue, actions, task, this.generateId);
+                    const asyncPromise = taskPromise.finally(async () => {
+                      try {
+                        await asyncActions.onPromiseFulfilled();
+                      } catch (err) {
+                        this.logger.error(`[${taskRunnerId}] Failed to execute async actions for task ${utils_taskIdGen.tId(task)}:`, err);
+                      }
+                    });
+                    asyncTasks.push({
+                      task,
+                      promise: asyncPromise,
+                      startTime,
+                      actions: asyncActions
+                    });
+                  }
                 }
               }
             }
           }
         }
       }
+      const asyncTaskIds = asyncTasks.map((at) => utils_taskIdGen.tId(at.task));
+      const results = actions.extractSyncResults(asyncTaskIds);
+      this.logger.info(`[${taskRunnerId}] Completing run - Success: ${results.successTasks.length}, Failed: ${results.failedTasks.length}, New: ${results.newTasks.length}, Async: ${asyncTasks.length}, Ignored: ${results.ignoredTasks.length}`);
+      return { ...results, asyncTasks };
+    } catch (_) {
+      var _error = _, _hasError = true;
+    } finally {
+      var _promise = __callDispose(_stack, _error, _hasError);
+      _promise && await _promise;
+    }
+  }
+  emitLifecycleEvent(callback, ctx) {
+    if (!callback) return;
+    try {
+      const result = callback(ctx);
+      if (result instanceof Promise) {
+        result.catch((err) => {
+          this.logger.error(`[TQ] Lifecycle callback error: ${err}`);
+        });
+      }
+    } catch (err) {
+      this.logger.error(`[TQ] Lifecycle callback error: ${err}`);
+    }
+  }
+  buildTaskContext(task, workerId) {
+    const retryCount = task.execution_stats && typeof task.execution_stats.retry_count === "number" ? task.execution_stats.retry_count : 0;
+    const executor = this.taskQueue.getExecutor(task.queue_id, task.type);
+    const maxRetries = task.retries ?? executor?.default_retries ?? 0;
+    const payload = task.payload;
+    return {
+      task_id: task.id?.toString() || utils_taskIdGen.tId(task),
+      task_hash: payload?.task_hash,
+      task_type: task.type,
+      queue_id: task.queue_id,
+      payload: this.lifecycleConfig?.include_payload ? payload : {},
+      attempt: retryCount + 1,
+      max_retries: maxRetries,
+      scheduled_at: task.created_at || /* @__PURE__ */ new Date(),
+      worker_id: workerId
+    };
+  }
+  emitTaskStarted(task, workerId) {
+    const startedAt = Date.now();
+    this.taskStartTimes.set(utils_taskIdGen.tId(task), startedAt);
+    if (this.lifecycleProvider?.onTaskStarted) {
+      const ctx = this.buildTaskContext(task, workerId);
+      const queuedDuration = startedAt - (task.created_at?.getTime() || startedAt);
+      this.emitLifecycleEvent(
+        this.lifecycleProvider.onTaskStarted,
+        {
+          ...ctx,
+          started_at: new Date(startedAt),
+          queued_duration_ms: queuedDuration
+        }
+      );
+    }
+  }
+  emitTaskCompleted(task, workerId, result) {
+    const completedAt = Date.now();
+    const startedAt = this.taskStartTimes.get(utils_taskIdGen.tId(task)) || completedAt;
+    this.taskStartTimes.delete(utils_taskIdGen.tId(task));
+    if (this.lifecycleProvider?.onTaskCompleted) {
+      const ctx = this.buildTaskContext(task, workerId);
+      const timing = {
+        queued_duration_ms: startedAt - (task.created_at?.getTime() || startedAt),
+        processing_duration_ms: completedAt - startedAt,
+        total_duration_ms: completedAt - (task.created_at?.getTime() || completedAt)
+      };
+      this.emitLifecycleEvent(
+        this.lifecycleProvider.onTaskCompleted,
+        { ...ctx, timing, result }
+      );
+    }
+  }
+  emitTaskFailed(task, workerId, error, willRetry, nextAttemptAt) {
+    const completedAt = Date.now();
+    const startedAt = this.taskStartTimes.get(utils_taskIdGen.tId(task)) || completedAt;
+    this.taskStartTimes.delete(utils_taskIdGen.tId(task));
+    if (this.lifecycleProvider?.onTaskFailed) {
+      const ctx = this.buildTaskContext(task, workerId);
+      const timing = {
+        queued_duration_ms: startedAt - (task.created_at?.getTime() || startedAt),
+        processing_duration_ms: completedAt - startedAt,
+        total_duration_ms: completedAt - (task.created_at?.getTime() || completedAt)
+      };
+      this.emitLifecycleEvent(
+        this.lifecycleProvider.onTaskFailed,
+        { ...ctx, timing, error, will_retry: willRetry, next_attempt_at: nextAttemptAt }
+      );
     }
-    const asyncTaskIds = asyncTasks.map((at) => utils_taskIdGen.tId(at.task));
-    const results = actions.extractSyncResults(asyncTaskIds);
-    this.logger.info(`[${taskRunnerId}] Completing run - Success: ${results.successTasks.length}, Failed: ${results.failedTasks.length}, New: ${results.newTasks.length}, Async: ${asyncTasks.length}, Ignored: ${results.ignoredTasks.length}`);
-    await Promise.all(tasks.filter((t) => processedTaskIds.has(utils_taskIdGen.tId(t))).map((t) => this.lockManager.release(utils_taskIdGen.tId(t))));
-    return { ...results, asyncTasks };
   }
 }
 function getEnabledQueues() {
@@ -706,7 +933,7 @@ const STATS_THRESHOLD = parseInt(process.env.TQ_STATS_THRESHOLD || "1000");
 const FAILURE_THRESHOLD = parseInt(process.env.TQ_STATS_FAILURE_THRESHOLD || "100");
 const INSTANCE_ID = process.env.INSTANCE_ID || "unknown";
 class TaskHandler {
-  constructor(messageQueue, taskQueuesManager, databaseAdapter, cacheAdapter, asyncTaskManager, notificationProvider) {
+  constructor(messageQueue, taskQueuesManager, databaseAdapter, cacheAdapter, asyncTaskManager, notificationProvider, config) {
     this.messageQueue = messageQueue;
     this.taskQueuesManager = taskQueuesManager;
     this.databaseAdapter = databaseAdapter;
@@ -714,10 +941,39 @@ class TaskHandler {
     this.asyncTaskManager = asyncTaskManager;
     this.notificationProvider = notificationProvider;
     this.matureTaskTimer = null;
+    this.heartbeatTimer = null;
+    this.enabledQueues = [];
+    this.workerStarted = false;
+    this.workerStats = {
+      tasks_processed: 0,
+      tasks_succeeded: 0,
+      tasks_failed: 0,
+      avg_processing_ms: 0,
+      current_task: void 0
+    };
+    this.totalProcessingMs = 0;
     this.queueStats = /* @__PURE__ */ new Map();
     this.logger = new client.Logger("TaskHandler", client.LogLevel.INFO);
+    this.config = config || {};
+    this.workerId = `${(void 0)()}-${process.pid}-${Date.now()}`;
+    this.workerStartedAt = /* @__PURE__ */ new Date();
     this.taskStore = new TaskStore(databaseAdapter);
-    this.taskRunner = new TaskRunner(messageQueue, taskQueuesManager, this.taskStore, this.cacheAdapter, databaseAdapter.generateId.bind(databaseAdapter));
+    this.taskRunner = new TaskRunner(
+      messageQueue,
+      taskQueuesManager,
+      this.taskStore,
+      this.cacheAdapter,
+      databaseAdapter.generateId.bind(databaseAdapter),
+      this.config.lifecycleProvider,
+      this.config.lifecycle
+    );
+  }
+  // ============ Lifecycle Event Helpers ============
+  get lifecycleProvider() {
+    return this.config.lifecycleProvider;
+  }
+  get workerProvider() {
+    return this.config.workerProvider;
   }
   async addTasks(tasks) {
     const diffedItems = tasks.reduce(
@@ -743,24 +999,40 @@ class TaskHandler {
     const iQueues = Object.keys(diffedItems.immediate);
     for (let i = 0; i < iQueues.length; i++) {
       const queue = iQueues[i];
-      const tasks2 = diffedItems.immediate[queue].map((task) => {
+      const queueTasks = diffedItems.immediate[queue].map((task) => {
         const executor = this.taskQueuesManager.getExecutor(task.queue_id, task.type);
         const shouldStoreOnFailure = executor?.store_on_failure ?? false;
         const id = shouldStoreOnFailure ? { id: this.databaseAdapter.generateId() } : {};
         return { ...id, ...task };
       });
-      await this.messageQueue.addMessages(queue, tasks2);
+      await this.messageQueue.addMessages(queue, queueTasks);
+      if (this.lifecycleProvider?.onTaskScheduled) {
+        for (const task of queueTasks) {
+          this.emitLifecycleEvent(
+            this.lifecycleProvider.onTaskScheduled,
+            this.buildTaskContext(task)
+          );
+        }
+      }
     }
     const fQueues = Object.keys(diffedItems.future);
     for (let i = 0; i < fQueues.length; i++) {
       const queue = fQueues[i];
-      const tasks2 = diffedItems.future[queue].map((task) => {
+      const queueTasks = diffedItems.future[queue].map((task) => {
         const executor = this.taskQueuesManager.getExecutor(task.queue_id, task.type);
         const shouldStoreOnFailure = executor?.store_on_failure ?? false;
         const id = shouldStoreOnFailure ? { id: this.databaseAdapter.generateId() } : {};
         return { ...id, ...task };
       });
-      await this.taskStore.addTasksToScheduled(tasks2);
+      await this.taskStore.addTasksToScheduled(queueTasks);
+      if (this.lifecycleProvider?.onTaskScheduled) {
+        for (const task of queueTasks) {
+          this.emitLifecycleEvent(
+            this.lifecycleProvider.onTaskScheduled,
+            this.buildTaskContext(task)
+          );
+        }
+      }
     }
   }
   async postProcessTasks({
@@ -771,10 +1043,12 @@ class TaskHandler {
     const tasksToRetry = [];
     const finalFailedTasks = [];
     let discardedTasksCount = 0;
+    const MAX_RETRY_DELAY_MS = 5 * 60 * 1e3;
     for (const task of failedTasksRaw) {
       const taskRetryCount = task.execution_stats && typeof task.execution_stats.retry_count === "number" ? task.execution_stats.retry_count : 0;
       const taskRetryAfter = task.retry_after || 2e3;
-      const retryAfter = taskRetryAfter * Math.pow(taskRetryCount + 1, 2);
+      const calculatedDelay = taskRetryAfter * Math.pow(taskRetryCount + 1, 2);
+      const retryAfter = Math.min(calculatedDelay, MAX_RETRY_DELAY_MS);
       const executeAt = Date.now() + retryAfter;
       const maxRetries = this.getRetryCount(task);
       if (task.id && taskRetryCount < maxRetries) {
@@ -816,6 +1090,23 @@ class TaskHandler {
       } else {
         discardedTasksCount++;
         this.logger.info(`Discarding task of type ${task.type} after ${taskRetryCount} retries`);
+        if (this.lifecycleProvider?.onTaskExhausted) {
+          const ctx = this.buildTaskContext(task);
+          const errorMessage = task.execution_stats?.last_error || "Task exhausted all retries";
+          this.emitLifecycleEvent(
+            this.lifecycleProvider.onTaskExhausted,
+            {
+              ...ctx,
+              timing: {
+                queued_duration_ms: 0,
+                processing_duration_ms: 0,
+                total_duration_ms: Date.now() - (task.created_at?.getTime() || Date.now())
+              },
+              error: new Error(errorMessage),
+              total_attempts: taskRetryCount + 1
+            }
+          );
+        }
       }
     }
     if (discardedTasksCount > 0) {
@@ -840,6 +1131,18 @@ class TaskHandler {
         this.logger.info(`AbortSignal detected, skipping processing of ${tasks.length} tasks for stream ${streamName}`);
         return { failedTasks: [], newTasks: [], successTasks: [], asyncTasks: [], ignoredTasks: [] };
       }
+      const batchStartTime = Date.now();
+      const taskTypes = [...new Set(tasks.map((t) => t.type))];
+      if (this.workerProvider?.onBatchStarted) {
+        this.emitLifecycleEvent(
+          this.workerProvider.onBatchStarted,
+          {
+            ...this.buildWorkerInfo(),
+            batch_size: tasks.length,
+            task_types: taskTypes
+          }
+        );
+      }
       this.logger.debug(`Processing ${tasks.length} tasks for stream ${streamName}`);
       const {
         failedTasks,
@@ -890,10 +1193,118 @@ class TaskHandler {
       stats.async += asyncTasks.length;
       stats.ignored += ignoredTasks.length;
       await this.reportQueueStats(streamName);
+      const batchDuration = Date.now() - batchStartTime;
+      this.updateWorkerStats(successTasks.length, failedTasks.length, batchDuration);
+      if (this.workerProvider?.onBatchCompleted) {
+        this.emitLifecycleEvent(
+          this.workerProvider.onBatchCompleted,
+          {
+            ...this.buildWorkerInfo(),
+            batch_size: tasks.length,
+            succeeded: successTasks.length,
+            failed: failedTasks.length,
+            duration_ms: batchDuration
+          }
+        );
+      }
       this.logger.debug(`Completed processing for stream ${streamName}: ${successTasks.length} succeeded, ${failedTasks.length} failed, ${newTasks.length} new tasks, ${ignoredTasks.length} ignored`);
       return { failedTasks, newTasks, successTasks, asyncTasks, ignoredTasks };
     }, abortSignal);
   }
+  taskProcessServer(abortSignal) {
+    const queues = getEnabledQueues();
+    this.enabledQueues = queues;
+    if (!this.workerStarted) {
+      this.workerStarted = true;
+      this.emitWorkerStarted();
+      this.startHeartbeat();
+    }
+    for (let i = 0; i < queues.length; i++) {
+      this.logger.info(`Starting consumer for queue: ${queues[i]}`);
+      this.startConsumingTasks(queues[i], abortSignal);
+    }
+    this.logger.info("Starting mature tasks processor");
+    this.processMatureTasks(abortSignal);
+    abortSignal?.addEventListener("abort", () => {
+      this.stopHeartbeat();
+      this.emitWorkerStopped("shutdown");
+    });
+  }
+  buildWorkerInfo() {
+    return {
+      worker_id: this.workerId,
+      hostname: (void 0)(),
+      pid: process.pid,
+      started_at: this.workerStartedAt,
+      enabled_queues: this.enabledQueues
+    };
+  }
+  emitWorkerStarted() {
+    if (!this.workerProvider?.onWorkerStarted) return;
+    this.emitLifecycleEvent(this.workerProvider.onWorkerStarted, this.buildWorkerInfo());
+  }
+  emitWorkerStopped(reason) {
+    if (!this.workerProvider?.onWorkerStopped) return;
+    this.emitLifecycleEvent(
+      this.workerProvider.onWorkerStopped,
+      {
+        ...this.buildWorkerInfo(),
+        reason,
+        final_stats: { ...this.workerStats }
+      }
+    );
+  }
+  emitWorkerHeartbeat() {
+    if (!this.workerProvider?.onWorkerHeartbeat) return;
+    const memUsage = process.memoryUsage();
+    this.emitLifecycleEvent(
+      this.workerProvider.onWorkerHeartbeat,
+      {
+        ...this.buildWorkerInfo(),
+        stats: { ...this.workerStats },
+        memory_usage_mb: memUsage.heapUsed / 1024 / 1024
+      }
+    );
+  }
+  startHeartbeat() {
+    if (this.heartbeatTimer) return;
+    const intervalMs = this.config.lifecycle?.heartbeat_interval_ms || 5e3;
+    this.heartbeatTimer = setInterval(() => {
+      this.emitWorkerHeartbeat();
+    }, intervalMs);
+  }
+  stopHeartbeat() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+  updateWorkerStats(succeeded, failed, processingMs) {
+    this.workerStats.tasks_processed += succeeded + failed;
+    this.workerStats.tasks_succeeded += succeeded;
+    this.workerStats.tasks_failed += failed;
+    this.totalProcessingMs += processingMs;
+    if (this.workerStats.tasks_processed > 0) {
+      this.workerStats.avg_processing_ms = this.totalProcessingMs / this.workerStats.tasks_processed;
+    }
+  }
+  emitLifecycleEvent(callback, ctx) {
+    if (!callback) return;
+    try {
+      const result = callback(ctx);
+      if (this.config.lifecycle?.mode === "sync" && result instanceof Promise) {
+        result.catch((err) => {
+          this.logger.error(`[TQ] Lifecycle callback error: ${err}`);
+        });
+      } else if (result instanceof Promise) {
+        result.catch((err) => {
+          this.logger.error(`[TQ] Lifecycle callback error: ${err}`);
+        });
+      }
+    } catch (err) {
+      this.logger.error(`[TQ] Lifecycle callback error: ${err}`);
+    }
+  }
   processMatureTasks(abortSignal) {
     if (this.matureTaskTimer) clearInterval(this.matureTaskTimer);
     if (abortSignal?.aborted) {
@@ -937,14 +1348,20 @@ class TaskHandler {
       });
     });
   }
-  taskProcessServer(abortSignal) {
-    const queues = getEnabledQueues();
-    for (let i = 0; i < queues.length; i++) {
-      this.logger.info(`Starting consumer for queue: ${queues[i]}`);
-      this.startConsumingTasks(queues[i], abortSignal);
-    }
-    this.logger.info("Starting mature tasks processor");
-    this.processMatureTasks(abortSignal);
+  buildTaskContext(task) {
+    const maxRetries = this.getRetryCount(task);
+    const retryCount = task.execution_stats && typeof task.execution_stats.retry_count === "number" ? task.execution_stats.retry_count : 0;
+    const payload = task.payload;
+    return {
+      task_id: task.id?.toString() || "",
+      task_hash: payload?.task_hash,
+      task_type: task.type,
+      queue_id: task.queue_id,
+      payload: this.config.lifecycle?.include_payload ? payload : {},
+      attempt: retryCount + 1,
+      max_retries: maxRetries,
+      scheduled_at: task.created_at || /* @__PURE__ */ new Date()
+    };
   }
   processBatch(queueId, processor, limit, abortSignal) {
     if (abortSignal?.aborted) {
@@ -1056,6 +1473,7 @@ class TaskHandler {
     }
   }
 }
+const logger = new client.Logger("TaskQueuesManager", client.LogLevel.INFO);
 class TaskQueuesManager {
   constructor(messageQueue) {
     this.messageQueue = messageQueue;
@@ -1075,7 +1493,7 @@ class TaskQueuesManager {
     }
     const queueMap = this.queueTaskExecutorMap.get(queueName);
     queueMap.set(taskType, executor);
-    console.log(`Registered task executor for ${taskType} on queue ${queueName}`);
+    logger.info(`Registered task executor for ${taskType} on queue ${queueName}`);
   }
   /**
    * Gets the task executor for a specific queue and task type
@@ -1112,6 +1530,62 @@ class TaskQueuesManager {
     return Array.from(queueMap.keys());
   }
 }
+class ConsoleHealthProvider {
+  constructor(prefix = "[Health]") {
+    this.prefix = prefix;
+  }
+  // ============ Task Lifecycle ============
+  onTaskScheduled(ctx) {
+    console.log(`${this.prefix} Task scheduled: ${ctx.task_type} (${ctx.task_id}) in queue ${ctx.queue_id}`);
+  }
+  onTaskStarted(ctx) {
+    console.log(`${this.prefix} Task started: ${ctx.task_type} (${ctx.task_id}) - queued for ${ctx.queued_duration_ms}ms`);
+  }
+  onTaskCompleted(ctx) {
+    console.log(
+      `${this.prefix} Task completed: ${ctx.task_type} (${ctx.task_id}) - processing: ${ctx.timing.processing_duration_ms}ms, total: ${ctx.timing.total_duration_ms}ms`
+    );
+  }
+  onTaskFailed(ctx) {
+    console.log(
+      `${this.prefix} Task failed: ${ctx.task_type} (${ctx.task_id}) - error: ${ctx.error.message}, will_retry: ${ctx.will_retry}`
+    );
+  }
+  onTaskExhausted(ctx) {
+    console.log(
+      `${this.prefix} Task exhausted: ${ctx.task_type} (${ctx.task_id}) - total attempts: ${ctx.total_attempts}, error: ${ctx.error.message}`
+    );
+  }
+  onTaskCancelled(ctx) {
+    console.log(`${this.prefix} Task cancelled: ${ctx.task_type} (${ctx.task_id}) - reason: ${ctx.reason}`);
+  }
+  // ============ Worker Lifecycle ============
+  onWorkerStarted(info) {
+    console.log(
+      `${this.prefix} Worker started: ${info.worker_id} on ${info.hostname} (PID: ${info.pid}) - queues: [${info.enabled_queues.join(", ")}]`
+    );
+  }
+  onWorkerHeartbeat(info) {
+    console.log(
+      `${this.prefix} Worker heartbeat: ${info.worker_id} - processed: ${info.stats.tasks_processed}, success: ${info.stats.tasks_succeeded}, failed: ${info.stats.tasks_failed}, avg: ${info.stats.avg_processing_ms.toFixed(2)}ms, memory: ${info.memory_usage_mb.toFixed(2)}MB`
+    );
+  }
+  onWorkerStopped(info) {
+    console.log(
+      `${this.prefix} Worker stopped: ${info.worker_id} - reason: ${info.reason} - final stats: ${info.final_stats.tasks_processed} processed, ${info.final_stats.tasks_succeeded} succeeded, ${info.final_stats.tasks_failed} failed`
+    );
+  }
+  onBatchStarted(info) {
+    console.log(
+      `${this.prefix} Batch started: ${info.batch_size} tasks - types: [${info.task_types.join(", ")}]`
+    );
+  }
+  onBatchCompleted(info) {
+    console.log(
+      `${this.prefix} Batch completed: ${info.batch_size} tasks in ${info.duration_ms}ms - succeeded: ${info.succeeded}, failed: ${info.failed}`
+    );
+  }
+}
 exports.InMemoryAdapter = PrismaAdapter.InMemoryAdapter;
 exports.MongoDbAdapter = PrismaAdapter.MongoDbAdapter;
 exports.PrismaAdapter = PrismaAdapter.PrismaAdapter;
@@ -1119,6 +1593,7 @@ exports.tId = utils_taskIdGen.tId;
 exports.Actions = core_Actions.Actions;
 exports.AsyncActions = core_async_AsyncActions.AsyncActions;
 exports.AsyncTaskManager = core_async_AsyncTaskManager.AsyncTaskManager;
+exports.ConsoleHealthProvider = ConsoleHealthProvider;
 exports.TaskHandler = TaskHandler;
 exports.TaskQueuesManager = TaskQueuesManager;
 exports.TaskRunner = TaskRunner;