@supergrowthai/tq 1.0.4 → 1.0.6

package/dist/src/adapters/InMemoryAdapter.d.ts

@@ -1,7 +1,32 @@
-import { ITaskStorageAdapter } from './ITaskStorageAdapter';
+import { ITaskStorageAdapter, TaskStorageLifecycleConfig } from './ITaskStorageAdapter';
 import { CronTask } from './types';
+/**
+ * In-memory task storage adapter for @supergrowthai/tq.
+ *
+ * @description Stores scheduled tasks in memory using a Map.
+ * Data is lost on process restart - use for development and testing only.
+ *
+ * @use-case Development, testing, and prototyping
+ * @multi-instance NOT SAFE - data is not shared between processes
+ * @persistence NONE - all tasks lost on restart
+ *
+ * @features
+ * - Fast in-memory operations
+ * - Simple cleanup implementation
+ * - Auto-generated string IDs
+ *
+ * @example
+ * ```typescript
+ * const adapter = new InMemoryAdapter();
+ * const taskHandler = new TaskHandler(queue, taskQueue, adapter, cache);
+ * ```
+ */
 declare class InMemoryAdapter implements ITaskStorageAdapter<string> {
     private scheduledTasks;
+    private lifecycleProvider?;
+    private lifecycleMode;
+    setLifecycleConfig(config: TaskStorageLifecycleConfig): void;
+    private emitLifecycleEvent;
     addTasksToScheduled(tasks: CronTask<string>[]): Promise<CronTask<string>[]>;
     getMatureTasks(timestamp: number): Promise<CronTask<string>[]>;
     markTasksAsProcessing(tasks: CronTask<string>[], processingStartedAt: Date): Promise<void>;

package/dist/src/adapters/MongoDbAdapter.d.cts

@@ -1,11 +1,38 @@
 import { Collection, ObjectId } from 'mongodb';
-import { ITaskStorageAdapter } from './ITaskStorageAdapter.js';
+import { ITaskStorageAdapter, TaskStorageLifecycleConfig } from './ITaskStorageAdapter.js';
 import { CronTask } from './types.js';
 /**
- * MongoDB implementation of IDatabaseAdapter
+ * MongoDB task storage adapter for @supergrowthai/tq.
+ *
+ * @description Persists scheduled tasks to MongoDB collection with status tracking.
+ * Uses application-level locking designed for single-instance deployments.
+ *
+ * @use-case Single-instance production deployments
+ * @multi-instance NOT SAFE - designed for single-instance use.
+ *   For multi-instance deployments, implement a distributed locking strategy
+ *   or use a Kinesis-based solution with Redis lock provider.
+ * @persistence Full - tasks stored in MongoDB until processed/expired
+ * @requires MongoDB connection via abstract `collection` getter
+ *
+ * @features
+ * - Stale task recovery: tasks stuck in 'processing' for >2 days are reset
+ * - Bulk operations for efficiency
+ * - Task expiration cleanup
+ *
+ * @example
+ * ```typescript
+ * class MyTaskStorage extends MongoDbAdapter {
+ *   get collection() { return db.collection('scheduled_tasks'); }
+ * }
+ * const adapter = new MyTaskStorage();
+ * ```
  */
 export declare abstract class MongoDbAdapter implements ITaskStorageAdapter<ObjectId> {
+    private lifecycleProvider?;
+    private lifecycleMode;
     protected constructor();
+    setLifecycleConfig(config: TaskStorageLifecycleConfig): void;
+    private emitLifecycleEvent;
     abstract get collection(): Promise<Collection<Omit<CronTask<ObjectId>, 'id'> & {
         _id?: ObjectId;
     }>>;

package/dist/src/adapters/MongoDbAdapter.d.ts

@@ -1,11 +1,38 @@
 import { Collection, ObjectId } from 'mongodb';
-import { ITaskStorageAdapter } from './ITaskStorageAdapter.js';
+import { ITaskStorageAdapter, TaskStorageLifecycleConfig } from './ITaskStorageAdapter.js';
 import { CronTask } from './types.js';
 /**
- * MongoDB implementation of IDatabaseAdapter
+ * MongoDB task storage adapter for @supergrowthai/tq.
+ *
+ * @description Persists scheduled tasks to MongoDB collection with status tracking.
+ * Uses application-level locking designed for single-instance deployments.
+ *
+ * @use-case Single-instance production deployments
+ * @multi-instance NOT SAFE - designed for single-instance use.
+ *   For multi-instance deployments, implement a distributed locking strategy
+ *   or use a Kinesis-based solution with Redis lock provider.
+ * @persistence Full - tasks stored in MongoDB until processed/expired
+ * @requires MongoDB connection via abstract `collection` getter
+ *
+ * @features
+ * - Stale task recovery: tasks stuck in 'processing' for >2 days are reset
+ * - Bulk operations for efficiency
+ * - Task expiration cleanup
+ *
+ * @example
+ * ```typescript
+ * class MyTaskStorage extends MongoDbAdapter {
+ *   get collection() { return db.collection('scheduled_tasks'); }
+ * }
+ * const adapter = new MyTaskStorage();
+ * ```
  */
 export declare abstract class MongoDbAdapter implements ITaskStorageAdapter<ObjectId> {
+    private lifecycleProvider?;
+    private lifecycleMode;
     protected constructor();
+    setLifecycleConfig(config: TaskStorageLifecycleConfig): void;
+    private emitLifecycleEvent;
     abstract get collection(): Promise<Collection<Omit<CronTask<ObjectId>, 'id'> & {
         _id?: ObjectId;
     }>>;

package/dist/src/adapters/PrismaAdapter.d.cts

@@ -1,4 +1,4 @@
-import { ITaskStorageAdapter } from './ITaskStorageAdapter.js';
+import { ITaskStorageAdapter, TaskStorageLifecycleConfig } from './ITaskStorageAdapter.js';
 import { CronTask } from './types.js';
 import { PrismaClient } from '@prisma/client/extension';
 /** A Prisma client that is guaranteed to have model delegate K. */
@@ -11,10 +11,42 @@ type EntityOf<D> = D extends {
 } ? U : D extends {
     findMany(args?: any): Promise<(infer U)[]>;
 } ? U : never;
-/** Compile-time guard: model’s entity must be compatible with the shape you require. */
+/** Compile-time guard: model's entity must be compatible with the shape you require. */
 type EnsureModelShape<Delegate, Needed> = EntityOf<Delegate> extends Needed ? unknown : never;
+/**
+ * Prisma task storage adapter for @supergrowthai/tq.
+ *
+ * @description Persists scheduled tasks to any Prisma model with status tracking.
+ * Uses application-level locking designed for single-instance deployments.
+ *
+ * @use-case Single-instance production deployments with Prisma ORM
+ * @multi-instance NOT SAFE - designed for single-instance use.
+ *   For multi-instance deployments, implement a distributed locking strategy
+ *   or use a Kinesis-based solution with Redis lock provider.
+ * @persistence Full - tasks stored in database until processed/expired
+ * @requires Prisma client with a model matching CronTask structure
+ *
+ * @features
+ * - Stale task recovery: tasks stuck in 'processing' for >2 days are reset
+ * - Transaction support for batch updates
+ * - Task expiration cleanup
+ *
+ * @typeParam TId - The ID type (string, number, etc.)
+ * @typeParam K - The Prisma model key (e.g. 'scheduledTask')
+ * @typeParam Msg - The task type extending CronTask<TId>
+ *
+ * @example
+ * ```typescript
+ * const adapter = new PrismaAdapter({
+ *   prismaClient: prisma,
+ *   messageModel: 'scheduledTask'
+ * });
+ * ```
+ */
 export declare class PrismaAdapter<TId = any, K extends keyof PrismaClient = never, Msg extends CronTask<TId> = CronTask<TId>> implements ITaskStorageAdapter<TId> {
     private config;
+    private lifecycleProvider?;
+    private lifecycleMode;
     constructor(config: {
         prismaClient: ClientWithModel<K>;
         messageModel: K;
@@ -28,6 +60,8 @@ export declare class PrismaAdapter<TId = any, K extends keyof PrismaClient = nev
             id: TId;
         } ? unknown : never);
     });
+    setLifecycleConfig(config: TaskStorageLifecycleConfig): void;
+    private emitLifecycleEvent;
     get prismaClient(): PrismaClient;
     get taskTableName(): string;
     private get delegate();

package/dist/src/adapters/PrismaAdapter.d.ts

@@ -1,4 +1,4 @@
-import { ITaskStorageAdapter } from './ITaskStorageAdapter.js';
+import { ITaskStorageAdapter, TaskStorageLifecycleConfig } from './ITaskStorageAdapter.js';
 import { CronTask } from './types.js';
 import { PrismaClient } from '@prisma/client/extension';
 /** A Prisma client that is guaranteed to have model delegate K. */
@@ -11,10 +11,42 @@ type EntityOf<D> = D extends {
 } ? U : D extends {
     findMany(args?: any): Promise<(infer U)[]>;
 } ? U : never;
-/** Compile-time guard: model’s entity must be compatible with the shape you require. */
+/** Compile-time guard: model's entity must be compatible with the shape you require. */
 type EnsureModelShape<Delegate, Needed> = EntityOf<Delegate> extends Needed ? unknown : never;
+/**
+ * Prisma task storage adapter for @supergrowthai/tq.
+ *
+ * @description Persists scheduled tasks to any Prisma model with status tracking.
+ * Uses application-level locking designed for single-instance deployments.
+ *
+ * @use-case Single-instance production deployments with Prisma ORM
+ * @multi-instance NOT SAFE - designed for single-instance use.
+ *   For multi-instance deployments, implement a distributed locking strategy
+ *   or use a Kinesis-based solution with Redis lock provider.
+ * @persistence Full - tasks stored in database until processed/expired
+ * @requires Prisma client with a model matching CronTask structure
+ *
+ * @features
+ * - Stale task recovery: tasks stuck in 'processing' for >2 days are reset
+ * - Transaction support for batch updates
+ * - Task expiration cleanup
+ *
+ * @typeParam TId - The ID type (string, number, etc.)
+ * @typeParam K - The Prisma model key (e.g. 'scheduledTask')
+ * @typeParam Msg - The task type extending CronTask<TId>
+ *
+ * @example
+ * ```typescript
+ * const adapter = new PrismaAdapter({
+ *   prismaClient: prisma,
+ *   messageModel: 'scheduledTask'
+ * });
+ * ```
+ */
 export declare class PrismaAdapter<TId = any, K extends keyof PrismaClient = never, Msg extends CronTask<TId> = CronTask<TId>> implements ITaskStorageAdapter<TId> {
     private config;
+    private lifecycleProvider?;
+    private lifecycleMode;
     constructor(config: {
         prismaClient: ClientWithModel<K>;
         messageModel: K;
@@ -28,6 +60,8 @@ export declare class PrismaAdapter<TId = any, K extends keyof PrismaClient = nev
             id: TId;
         } ? unknown : never);
     });
+    setLifecycleConfig(config: TaskStorageLifecycleConfig): void;
+    private emitLifecycleEvent;
     get prismaClient(): PrismaClient;
     get taskTableName(): string;
     private get delegate();

package/dist/src/adapters/index.d.cts

@@ -1,5 +1,5 @@
 export type { CronTask } from './types.js';
-export type { ITaskStorageAdapter } from './ITaskStorageAdapter.js';
+export type { ITaskStorageAdapter, TaskStorageLifecycleConfig } from './ITaskStorageAdapter.js';
 export { MongoDbAdapter } from './MongoDbAdapter.js';
 export { InMemoryAdapter } from './InMemoryAdapter.js';
 export { PrismaAdapter } from './PrismaAdapter.js';

package/dist/src/adapters/index.d.ts

@@ -1,5 +1,5 @@
 export type { CronTask } from './types.js';
-export type { ITaskStorageAdapter } from './ITaskStorageAdapter.js';
+export type { ITaskStorageAdapter, TaskStorageLifecycleConfig } from './ITaskStorageAdapter.js';
 export { MongoDbAdapter } from './MongoDbAdapter.js';
 export { InMemoryAdapter } from './InMemoryAdapter.js';
 export { PrismaAdapter } from './PrismaAdapter.js';

package/dist/src/core/Actions.d.cts

@@ -18,6 +18,11 @@ export declare class Actions<ID = any> implements ExecutorActions<ID> {
     success(task: CronTask<ID>): void;
     addTasks(tasks: CronTask<ID>[]): void;
     addIgnoredTask(task: CronTask<ID>): void;
+    /**
+     * Check the result status for a specific task
+     * Returns 'success', 'fail', or 'pending' (no action recorded yet)
+     */
+    getTaskResultStatus(taskId: string): 'success' | 'fail' | 'pending';
     /**
      * Extract actions for a single task (used by async tasks)
      */

package/dist/src/core/Actions.d.ts

@@ -18,6 +18,11 @@ export declare class Actions<ID = any> implements ExecutorActions<ID> {
     success(task: CronTask<ID>): void;
     addTasks(tasks: CronTask<ID>[]): void;
     addIgnoredTask(task: CronTask<ID>): void;
+    /**
+     * Check the result status for a specific task
+     * Returns 'success', 'fail', or 'pending' (no action recorded yet)
+     */
+    getTaskResultStatus(taskId: string): 'success' | 'fail' | 'pending';
     /**
      * Extract actions for a single task (used by async tasks)
      */

package/dist/src/core/TaskHandler.d.cts

@@ -5,6 +5,7 @@ import { CacheProvider } from 'memoose-js';
 import { TaskQueuesManager } from './TaskQueuesManager';
 import { IAsyncTaskManager } from './async/async-task-manager';
 import { ITaskNotificationProvider } from './ITaskNotificationProvider.js';
+import { TaskHandlerConfig } from './lifecycle.js';
 export declare class TaskHandler<ID> {
     private messageQueue;
     private taskQueuesManager;
@@ -16,8 +17,18 @@ export declare class TaskHandler<ID> {
     private taskRunner;
     private readonly taskStore;
     private matureTaskTimer;
+    private heartbeatTimer;
+    private readonly config;
+    private readonly workerId;
+    private readonly workerStartedAt;
+    private enabledQueues;
+    private workerStarted;
+    private workerStats;
+    private totalProcessingMs;
     private readonly queueStats;
-    constructor(messageQueue: IMessageQueue<ID>, taskQueuesManager: TaskQueuesManager<ID>, databaseAdapter: ITaskStorageAdapter<ID>, cacheAdapter: CacheProvider<any>, asyncTaskManager?: IAsyncTaskManager<ID> | undefined, notificationProvider?: ITaskNotificationProvider | undefined);
+    constructor(messageQueue: IMessageQueue<ID>, taskQueuesManager: TaskQueuesManager<ID>, databaseAdapter: ITaskStorageAdapter<ID>, cacheAdapter: CacheProvider<any>, asyncTaskManager?: IAsyncTaskManager<ID> | undefined, notificationProvider?: ITaskNotificationProvider | undefined, config?: TaskHandlerConfig);
+    private get lifecycleProvider();
+    private get workerProvider();
     addTasks(tasks: CronTask<ID>[]): Promise<void>;
     postProcessTasks({ failedTasks: failedTasksRaw, newTasks, successTasks }: ProcessedTaskResult<ID>): Promise<void>;
     startConsumingTasks(streamName: QueueName, abortSignal?: AbortSignal): Promise<{
@@ -27,8 +38,17 @@ export declare class TaskHandler<ID> {
         asyncTasks: never[] | import('./TaskRunner.js').AsyncTask<ID>[];
         ignoredTasks: never[] | CronTask<ID>[];
     }>;
-    processMatureTasks(abortSignal?: AbortSignal): void;
     taskProcessServer(abortSignal?: AbortSignal): void;
+    private buildWorkerInfo;
+    private emitWorkerStarted;
+    private emitWorkerStopped;
+    private emitWorkerHeartbeat;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private updateWorkerStats;
+    private emitLifecycleEvent;
+    processMatureTasks(abortSignal?: AbortSignal): void;
+    private buildTaskContext;
     processBatch(queueId: QueueName, processor: MessageConsumer<ID>, limit?: number, abortSignal?: AbortSignal): Promise<void>;
     private trackDiscardedTasks;
     private getRetryCount;

package/dist/src/core/TaskHandler.d.ts

@@ -5,6 +5,7 @@ import { CacheProvider } from 'memoose-js';
 import { TaskQueuesManager } from './TaskQueuesManager';
 import { IAsyncTaskManager } from './async/async-task-manager';
 import { ITaskNotificationProvider } from './ITaskNotificationProvider.js';
+import { TaskHandlerConfig } from './lifecycle.js';
 export declare class TaskHandler<ID> {
     private messageQueue;
     private taskQueuesManager;
@@ -16,8 +17,18 @@ export declare class TaskHandler<ID> {
     private taskRunner;
     private readonly taskStore;
     private matureTaskTimer;
+    private heartbeatTimer;
+    private readonly config;
+    private readonly workerId;
+    private readonly workerStartedAt;
+    private enabledQueues;
+    private workerStarted;
+    private workerStats;
+    private totalProcessingMs;
     private readonly queueStats;
-    constructor(messageQueue: IMessageQueue<ID>, taskQueuesManager: TaskQueuesManager<ID>, databaseAdapter: ITaskStorageAdapter<ID>, cacheAdapter: CacheProvider<any>, asyncTaskManager?: IAsyncTaskManager<ID> | undefined, notificationProvider?: ITaskNotificationProvider | undefined);
+    constructor(messageQueue: IMessageQueue<ID>, taskQueuesManager: TaskQueuesManager<ID>, databaseAdapter: ITaskStorageAdapter<ID>, cacheAdapter: CacheProvider<any>, asyncTaskManager?: IAsyncTaskManager<ID> | undefined, notificationProvider?: ITaskNotificationProvider | undefined, config?: TaskHandlerConfig);
+    private get lifecycleProvider();
+    private get workerProvider();
     addTasks(tasks: CronTask<ID>[]): Promise<void>;
     postProcessTasks({ failedTasks: failedTasksRaw, newTasks, successTasks }: ProcessedTaskResult<ID>): Promise<void>;
     startConsumingTasks(streamName: QueueName, abortSignal?: AbortSignal): Promise<{
@@ -27,8 +38,17 @@ export declare class TaskHandler<ID> {
         asyncTasks: never[] | import('./TaskRunner.js').AsyncTask<ID>[];
         ignoredTasks: never[] | CronTask<ID>[];
     }>;
-    processMatureTasks(abortSignal?: AbortSignal): void;
     taskProcessServer(abortSignal?: AbortSignal): void;
+    private buildWorkerInfo;
+    private emitWorkerStarted;
+    private emitWorkerStopped;
+    private emitWorkerHeartbeat;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private updateWorkerStats;
+    private emitLifecycleEvent;
+    processMatureTasks(abortSignal?: AbortSignal): void;
+    private buildTaskContext;
     processBatch(queueId: QueueName, processor: MessageConsumer<ID>, limit?: number, abortSignal?: AbortSignal): Promise<void>;
     private trackDiscardedTasks;
     private getRetryCount;

package/dist/src/core/TaskRunner.d.cts

@@ -6,6 +6,7 @@ import { CacheProvider } from 'memoose-js';
 import { TaskQueuesManager } from './TaskQueuesManager';
 import { TaskStore } from './TaskStore';
 import { IAsyncTaskManager } from './async/async-task-manager';
+import { ITaskLifecycleProvider, TaskHandlerLifecycleConfig } from './lifecycle.js';
 export interface AsyncTask<ID> {
     task: CronTask<ID>;
     promise: Promise<void>;
@@ -17,10 +18,18 @@ export declare class TaskRunner<ID> {
     private taskQueue;
     private taskStore;
     private generateId;
+    private lifecycleProvider?;
+    private lifecycleConfig?;
     private readonly logger;
     private lockManager;
-    constructor(messageQueue: IMessageQueue<ID>, taskQueue: TaskQueuesManager<ID>, taskStore: TaskStore<ID>, cacheProvider: CacheProvider<any>, generateId: () => ID);
+    private readonly taskStartTimes;
+    constructor(messageQueue: IMessageQueue<ID>, taskQueue: TaskQueuesManager<ID>, taskStore: TaskStore<ID>, cacheProvider: CacheProvider<any>, generateId: () => ID, lifecycleProvider?: ITaskLifecycleProvider | undefined, lifecycleConfig?: TaskHandlerLifecycleConfig | undefined);
     run(taskRunnerId: string, tasksRaw: Array<CronTask<ID>>, asyncTaskManager?: IAsyncTaskManager, abortSignal?: AbortSignal): Promise<ActionResults<ID> & {
         asyncTasks: AsyncTask<ID>[];
     }>;
+    private emitLifecycleEvent;
+    private buildTaskContext;
+    private emitTaskStarted;
+    private emitTaskCompleted;
+    private emitTaskFailed;
 }

package/dist/src/core/TaskRunner.d.ts

@@ -6,6 +6,7 @@ import { CacheProvider } from 'memoose-js';
 import { TaskQueuesManager } from './TaskQueuesManager';
 import { TaskStore } from './TaskStore';
 import { IAsyncTaskManager } from './async/async-task-manager';
+import { ITaskLifecycleProvider, TaskHandlerLifecycleConfig } from './lifecycle.js';
 export interface AsyncTask<ID> {
     task: CronTask<ID>;
     promise: Promise<void>;
@@ -17,10 +18,18 @@ export declare class TaskRunner<ID> {
     private taskQueue;
     private taskStore;
     private generateId;
+    private lifecycleProvider?;
+    private lifecycleConfig?;
     private readonly logger;
     private lockManager;
-    constructor(messageQueue: IMessageQueue<ID>, taskQueue: TaskQueuesManager<ID>, taskStore: TaskStore<ID>, cacheProvider: CacheProvider<any>, generateId: () => ID);
+    private readonly taskStartTimes;
+    constructor(messageQueue: IMessageQueue<ID>, taskQueue: TaskQueuesManager<ID>, taskStore: TaskStore<ID>, cacheProvider: CacheProvider<any>, generateId: () => ID, lifecycleProvider?: ITaskLifecycleProvider | undefined, lifecycleConfig?: TaskHandlerLifecycleConfig | undefined);
     run(taskRunnerId: string, tasksRaw: Array<CronTask<ID>>, asyncTaskManager?: IAsyncTaskManager, abortSignal?: AbortSignal): Promise<ActionResults<ID> & {
         asyncTasks: AsyncTask<ID>[];
     }>;
+    private emitLifecycleEvent;
+    private buildTaskContext;
+    private emitTaskStarted;
+    private emitTaskCompleted;
+    private emitTaskFailed;
 }

package/dist/src/core/lifecycle.d.cts

@@ -0,0 +1,133 @@
+/**
+ * Task Queue Lifecycle Types
+ * Provides interfaces for task and worker lifecycle callbacks
+ */
+export interface TaskContext {
+    /** Unique task identifier */
+    task_id: string;
+    /** Optional hash for deduplication */
+    task_hash?: string;
+    /** Task type identifier */
+    task_type: string;
+    /** Queue this task belongs to */
+    queue_id: string;
+    /** Task payload (empty if include_payload is false) */
+    payload: Record<string, unknown>;
+    /** Current retry attempt (1-based) */
+    attempt: number;
+    /** Maximum retries allowed */
+    max_retries: number;
+    /** When task was scheduled */
+    scheduled_at: Date;
+    /** Worker processing this task */
+    worker_id?: string;
+}
+export interface TaskTiming {
+    /** Time spent waiting in queue (ms) */
+    queued_duration_ms: number;
+    /** Time spent executing (ms) */
+    processing_duration_ms: number;
+    /** End-to-end duration (ms) */
+    total_duration_ms: number;
+}
+export interface ITaskLifecycleProvider {
+    /** Called when a task is added to the queue */
+    onTaskScheduled?(ctx: TaskContext): void | Promise<void>;
+    /** Called when a worker picks up a task for processing */
+    onTaskStarted?(ctx: TaskContext & {
+        started_at: Date;
+        queued_duration_ms: number;
+    }): void | Promise<void>;
+    /** Called when a task completes successfully */
+    onTaskCompleted?(ctx: TaskContext & {
+        timing: TaskTiming;
+        result?: unknown;
+    }): void | Promise<void>;
+    /** Called when a task fails (before retry decision) */
+    onTaskFailed?(ctx: TaskContext & {
+        timing: TaskTiming;
+        error: Error;
+        will_retry: boolean;
+        next_attempt_at?: Date;
+    }): void | Promise<void>;
+    /** Called when a task exhausts all retries */
+    onTaskExhausted?(ctx: TaskContext & {
+        timing: TaskTiming;
+        error: Error;
+        total_attempts: number;
+    }): void | Promise<void>;
+    /** Called when a task is manually cancelled/discarded */
+    onTaskCancelled?(ctx: TaskContext & {
+        reason: string;
+    }): void | Promise<void>;
+}
+export interface WorkerInfo {
+    /** Unique worker identifier */
+    worker_id: string;
+    /** Hostname of the machine */
+    hostname: string;
+    /** Process ID */
+    pid: number;
+    /** When worker started */
+    started_at: Date;
+    /** Queues this worker is consuming */
+    enabled_queues: string[];
+}
+export interface WorkerStats {
+    /** Total tasks processed */
+    tasks_processed: number;
+    /** Successfully completed tasks */
+    tasks_succeeded: number;
+    /** Failed tasks */
+    tasks_failed: number;
+    /** Average processing time (ms) */
+    avg_processing_ms: number;
+    /** Currently processing task info */
+    current_task?: {
+        task_type: string;
+        started_at: Date;
+    };
+}
+export interface IWorkerLifecycleProvider {
+    /** Called when a worker starts consuming tasks */
+    onWorkerStarted?(info: WorkerInfo): void | Promise<void>;
+    /** Called periodically with worker stats */
+    onWorkerHeartbeat?(info: WorkerInfo & {
+        stats: WorkerStats;
+        memory_usage_mb: number;
+        cpu_percent?: number;
+    }): void | Promise<void>;
+    /** Called when a worker stops */
+    onWorkerStopped?(info: WorkerInfo & {
+        reason: 'shutdown' | 'error' | 'idle_timeout';
+        final_stats: WorkerStats;
+    }): void | Promise<void>;
+    /** Called when worker starts processing a batch */
+    onBatchStarted?(info: WorkerInfo & {
+        batch_size: number;
+        task_types: string[];
+    }): void | Promise<void>;
+    /** Called when worker finishes processing a batch */
+    onBatchCompleted?(info: WorkerInfo & {
+        batch_size: number;
+        succeeded: number;
+        failed: number;
+        duration_ms: number;
+    }): void | Promise<void>;
+}
+export interface TaskHandlerLifecycleConfig {
+    /** Callback execution mode: 'sync' blocks, 'async' is fire-and-forget */
+    mode?: 'sync' | 'async';
+    /** Heartbeat interval in ms (default: 5000) */
+    heartbeat_interval_ms?: number;
+    /** Include payload in task context (default: false for performance) */
+    include_payload?: boolean;
+}
+export interface TaskHandlerConfig {
+    /** Task lifecycle event provider */
+    lifecycleProvider?: ITaskLifecycleProvider;
+    /** Worker lifecycle event provider */
+    workerProvider?: IWorkerLifecycleProvider;
+    /** Lifecycle callback configuration */
+    lifecycle?: TaskHandlerLifecycleConfig;
+}