fyflow-scheduler 0.1.0

package/dist/types/core/FyflowScheduler.d.ts

@@ -0,0 +1,279 @@
+/**
+ * A unit of work handed to a worker pool.
+ *
+ * Tasks are independent - there is no dependency graph. A task runs as soon as
+ * its worker pool has capacity and every resource group it belongs to has a
+ * free slot.
+ *
+ * ```typescript
+ * const task = new FyflowTask({
+ *   id: 'resize-image-42',
+ *   workerType: 'ImageWorker',     // key in the scheduler's workerPools
+ *   payload: { path: '/tmp/42.png' }
+ * });
+ * const result = await scheduler.addTask(task, { createPromise: true });
+ * ```
+ */
+export declare class FyflowTask {
+    id: string;
+    workerType: string;
+    payload: any;
+    optional: boolean;
+    retryPolicy?: {
+        maxRetries: number;
+        backoffMs: number;
+    };
+    /** Retry attempts used so far, counted against `retryPolicy.maxRetries`. */
+    attempts: number;
+    /**
+     * `pending` -> `running` -> `done` | `failed`.
+     *
+     * A non-optional task that fails with no retries left ends in `user_action`,
+     * signalling that something outside the scheduler has to intervene.
+     */
+    state: string;
+    result?: any;
+    error?: string;
+    resolve?: Function;
+    reject?: Function;
+    workerGroups?: string[];
+    handleRejection: boolean;
+    startTime?: number;
+    endTime?: number;
+    /**
+     * Worker-measured execution time in ms (high resolution), set on completion.
+     * Unlike `endTime - startTime` this excludes time spent waiting for a worker
+     * slot. Cleared when a task is requeued or retried.
+     */
+    executionTime?: number;
+    /**
+     * Bucket this task belongs to for keyed resource groups. Read by the default
+     * `keyFrom` of {@link KeyedRateLimitGroup}; a group given its own `keyFrom`
+     * can derive the key from the payload instead.
+     */
+    limitKey?: string;
+    _resourcesPreAllocated?: boolean;
+    /**
+     * Keys resolved at dispatch, per keyed group id. Held so release uses the
+     * same bucket acquisition used, even if the payload changed meanwhile.
+     */
+    _resourceKeys?: Record<string, string>;
+    /**
+     * Set while this attempt is being settled, so the same outcome arriving from
+     * both the pool's `task.failed` event and the task promise settles once.
+     * Cleared on every dispatch, so each attempt gets its own settle.
+     */
+    _settling?: boolean;
+    _scheduler?: FyflowScheduler;
+    /**
+     * @param config.id Unique task id. Reusing an id overwrites the earlier entry.
+     * @param config.workerType Key into the scheduler's `workerPools`. An unknown
+     *   value makes `addTask` throw.
+     * @param config.payload Passed verbatim to the worker's `run()`.
+     * @param config.optional Default `false`. An optional task that fails
+     *   resolves `null` instead of rejecting.
+     * @param config.retryPolicy `{ maxRetries, backoffMs }`. Omitted means no retries.
+     * @param config.workerGroups Resource groups for this task, *in addition* to
+     *   the groups its WorkerManager declares.
+     * @param config.handleRejection Default `true`. Attaches a silent catch so a
+     *   fire-and-forget failure does not surface as an unhandled rejection;
+     *   `task.failed` is still emitted.
+     * @param config.limitKey Bucket for keyed resource groups, e.g. the endpoint
+     *   or tenant this task belongs to. Required when the task belongs to a
+     *   keyed group that has no custom `keyFrom`.
+     */
+    constructor({ id, workerType, payload, optional, retryPolicy, workerGroups, handleRejection, limitKey }: any);
+    /**
+     * Promise for this task alone, resolving with its result and rejecting if it
+     * fails. Prefer `addTask(task, { createPromise: true })`, which wires this up
+     * for you. Use `onCompleteDescendants()` to also wait for spawned tasks.
+     */
+    onCompletePromise(): Promise<any>;
+    /**
+     * Wait for this task AND every task spawned from it (children, grandchildren, ...)
+     * to reach a terminal state.
+     *
+     * Descendants come from runtime spawning via `context.spawnTask()` - this is
+     * lineage, not a scheduling dependency, and does not affect dispatch order.
+     *
+     * Resolves with this task's result once the whole workflow has settled. A failed
+     * descendant does not reject - descendant failures surface via `task.failed`
+     * events - but this task failing rejects, matching `onCompletePromise()`.
+     *
+     * Must be called after the task has been added to a scheduler.
+     */
+    onCompleteDescendants(): Promise<any>;
+}
+export interface FyflowSchedulerOptions {
+    periodicRetryIntervalMs?: number;
+    /**
+     * Maximum number of terminal (done/failed/user_action) tasks to keep in
+     * `scheduler.tasks`. Once exceeded, the oldest-completed tasks are evicted
+     * along with their payloads, results and spawn lineage.
+     *
+     * Default: undefined - keep everything, which is what most workloads want
+     * since task counts are bounded and completed tasks stay inspectable. Set
+     * this for long-lived schedulers, where retention is otherwise unbounded.
+     *
+     * `stats` counts every task regardless, and in-flight tasks are never
+     * evicted.
+     */
+    maxCompletedTasks?: number;
+}
+export interface AddTaskOptions {
+    createPromise?: boolean;
+}
+/**
+ * Runs tasks in parallel across worker pools, subject to resource groups.
+ *
+ * ```typescript
+ * const scheduler = new FyflowScheduler(
+ *   { ImageWorker: new WorkerManager(workerUrl, { maxThreads: 4, groups: ['cpu'] }) },
+ *   { cpu: new ConcurrentLimitGroup(8, 'cpu') }
+ * );
+ * scheduler.addTask(task);              // fire-and-forget
+ * await scheduler.shutdown();           // always shut down when finished
+ * ```
+ *
+ * Emits: `task.running`, `task.completed`, `task.failed`, `task.progress`,
+ * `task.user_action`, `task.spawn_request`, `task.spawn_failed` and
+ * `scheduler.completed`.
+ */
+export declare class FyflowScheduler extends EventTarget {
+    tasks: Map<string, FyflowTask>;
+    readyQueuesByWorker: Map<string, FyflowTask[]>;
+    blockedQueues: Map<string, FyflowTask[]>;
+    workerPools: any;
+    groups: Record<string, any>;
+    stats: {
+        queued: number;
+        running: number;
+        done: number;
+        failed: number;
+    };
+    private retryTimer;
+    private descendantTrackers;
+    private nextTrackerId;
+    private spawnedChildren;
+    private completedTaskIds;
+    private options;
+    private allListeners;
+    constructor(workerPools: any, groups?: Record<string, any>, options?: FyflowSchedulerOptions);
+    /** Every resource group a task must acquire: its own plus its pool's. */
+    private _groupsForTask;
+    /**
+     * Blocked queues are per group, and per (group, key) for keyed groups, so a
+     * saturated key never stalls tasks belonging to a different one.
+     */
+    private _blockedQueueId;
+    /**
+     * Resolve the bucket for every keyed group this task belongs to.
+     *
+     * @throws if a keyed group cannot derive a key. A keyless task would
+     *   otherwise silently share a bucket with every other keyless task, or skip
+     *   the limit entirely - both discovered only once something is throttled.
+     */
+    private _resolveResourceKeys;
+    private _hasBlockedTasks;
+    _checkCompletion(): void;
+    /**
+     * Queue a task and start dispatching.
+     *
+     * Fire-and-forget by default: returns `undefined` unless
+     * `{ createPromise: true }` is passed, in which case it returns a promise
+     * that resolves with the task's result or rejects if it fails.
+     *
+     * @throws if `task.workerType` is not a key in the scheduler's `workerPools`.
+     */
+    addTask(task: FyflowTask, options?: AddTaskOptions): Promise<any> | void;
+    /**
+     * Queue many tasks with a single dispatch pass - use this for bulk additions
+     * (>1000 tasks) instead of calling `addTask` in a loop, which would run the
+     * dispatch loop once per task.
+     *
+     * Like `addTask`, returns nothing unless `{ createPromise: true }` is passed;
+     * with it, returns one promise per task in the same order:
+     *
+     * ```typescript
+     * const results = await Promise.all(
+     *   scheduler.addTasks(tasks, { createPromise: true }) as Promise<any>[]
+     * );
+     * ```
+     *
+     * @throws if any task's `workerType` is not a key in the scheduler's
+     *   `workerPools`. The batch is validated up front, so a rejected call
+     *   queues nothing at all.
+     */
+    addTasks(tasks: FyflowTask[], options?: AddTaskOptions): Promise<any>[] | void;
+    _dispatchLoop(): void;
+    _checkAndBlockResources(task: FyflowTask, pool: any): true | 'blocked' | 'blocked-keyed';
+    _canDispatchTask(task: FyflowTask, pool: any): boolean | 'blocked' | 'blocked-keyed';
+    _dispatchTask(task: FyflowTask, pool: any): void;
+    _releaseResourcesForTask(task: FyflowTask, pool: any): void;
+    /**
+     * The one place a task settles.
+     *
+     * An outcome can reach the scheduler twice - as the pool's `task.failed`
+     * event and as the settling of the pool's task promise - and each of those
+     * is the ONLY path in some situation, so neither can be dropped:
+     *
+     * - an ordinary task throw reaches both
+     * - a worker that dies with `requeueFailedTasks: false` reaches only the event
+     * - a worker that cannot be constructed reaches only the promise
+     *
+     * They used to be two near-duplicate implementations, so a single failure
+     * emitted `task.failed` twice, counted `stats.failed` twice, raced the
+     * terminal state between `user_action` and `failed`, and - because only the
+     * promise path released resources - leaked a resource group slot whenever
+     * only the event path ran.
+     */
+    private _settleTask;
+    _onTaskComplete(task: FyflowTask, result: any, pool: any): void;
+    _onTaskFailed(task: FyflowTask, error: any, pool: any): void;
+    _retryBlockedTasks(): void;
+    /** Keys that currently have tasks blocked on this group. */
+    private _blockedKeysFor;
+    _retryBlockedTasksForGroup(groupId: string, key?: string): void;
+    _schedulePeriodicRetry(): void;
+    _clearPeriodicRetry(): void;
+    private _addInternalListener;
+    private _trackListener;
+    private _removeAllListeners;
+    _setupGroupEventListeners(): void;
+    _setupWorkerPoolListeners(): void;
+    private static readonly TERMINAL_STATES;
+    private _isTerminal;
+    private _recordSpawn;
+    _trackDescendants(task: FyflowTask, resolve: Function, reject: Function): void;
+    private _collectPendingDescendants;
+    private _recordTerminalTask;
+    private _settleDescendantTrackers;
+    private _settleTracker;
+    private _addSpawnedTaskToTrackers;
+    /**
+     * Get current metrics for all resource groups
+     *
+     * Returns real-time utilization and availability for monitoring
+     *
+     * @returns Record of group ID to metrics
+     */
+    getResourceMetrics(): Record<string, any>;
+    /**
+     * Get lifetime stats for resource groups
+     *
+     * Returns aggregated statistics for strict groups (acquisition times, rejections, etc.)
+     *
+     * @returns Record of group ID to stats (only strict groups provide stats)
+     */
+    getResourceStats(): Record<string, any>;
+    /**
+     * Wait for running tasks, then terminate every worker pool, drop all
+     * listeners and clear internal state.
+     *
+     * Always call this when finished - live workers and the periodic retry timer
+     * will otherwise keep the process alive. Pending `onCompleteDescendants()`
+     * waits reject.
+     */
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=FyflowScheduler.d.ts.map

package/dist/types/core/FyflowScheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FyflowScheduler.d.ts","sourceRoot":"","sources":["../../../core/FyflowScheduler.ts"],"names":[],"mappings":"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"}

package/dist/types/core/inlineWrapper.d.ts

@@ -0,0 +1,45 @@
+import { WorkerInstanceExtensions, WorkerInstanceState } from "./workerInterface.js";
+export declare class InlineWrapper extends EventTarget implements WorkerInstanceExtensions, WorkerInstanceState {
+    runningTasks: number;
+    maxConcurrentTasks: number;
+    runningTaskIds: Set<string>;
+    runningTaskData: Map<string, {
+        id: string;
+        payload: any;
+    }>;
+    idleTimeout: number;
+    lastActivityTime: number;
+    workerModule: any;
+    workerInstance: any;
+    scriptUrl: string;
+    config: any;
+    id: string;
+    initializing: boolean;
+    state: 'initializing' | 'healthy' | 'busy' | 'failed' | 'terminated';
+    lastError?: {
+        timestamp: number;
+        message: string;
+        metadata: any;
+    };
+    tasksCompleted: number;
+    errorCount: number;
+    createdAt: number;
+    constructor(scriptUrl: string, idleTimeout?: number, maxConcurrentTasks?: number, config?: {});
+    canAcceptTask(): boolean;
+    getRunningTaskIds(): string[];
+    getRunningTasks(): Array<{
+        id: string;
+        payload: any;
+    }>;
+    private createTerminateWithError;
+    private _handleTerminationRequest;
+    private createBaseWorkerContext;
+    get idle(): boolean;
+    updateActivity(): void;
+    _loadWorkerModule(): Promise<any>;
+    _createWorkerInstance(): Promise<any>;
+    runTask(taskId: string, payload: any): Promise<any>;
+    terminate(): Promise<void>;
+    _destroyWorkerInstance(): Promise<void>;
+}
+//# sourceMappingURL=inlineWrapper.d.ts.map

package/dist/types/core/inlineWrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inlineWrapper.d.ts","sourceRoot":"","sources":["../../../core/inlineWrapper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,mBAAmB,EAAgE,MAAM,sBAAsB,CAAC;AAEnJ,qBAAa,aAAc,SAAQ,WAAY,YAAW,wBAAwB,EAAE,mBAAmB;IACnG,YAAY,SAAK;IACjB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,CAAqB;IAChD,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,GAAG,CAAA;KAAC,CAAC,CAAiD;IACzG,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAc;IACtC,YAAY,EAAE,GAAG,CAAQ;IACzB,cAAc,EAAE,GAAG,CAAQ;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,GAAG,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,UAAS;IAGrB,KAAK,EAAE,cAAc,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,YAAY,CAAkB;IACtF,SAAS,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,GAAG,CAAA;KAAE,CAAC;IAGlE,cAAc,SAAK;IACnB,UAAU,SAAK;IACf,SAAS,EAAE,MAAM,CAAc;gBACnB,SAAS,EAAE,MAAM,EAAE,WAAW,SAAO,EAAE,kBAAkB,SAAI,EAAE,MAAM,KAAK;IAStF,aAAa,IAAI,OAAO;IAKxB,iBAAiB,IAAI,MAAM,EAAE;IAI7B,eAAe,IAAI,KAAK,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,GAAG,CAAA;KAAC,CAAC;IAKpD,OAAO,CAAC,wBAAwB;IAQhC,OAAO,CAAC,yBAAyB;IA2CjC,OAAO,CAAC,uBAAuB;IAO/B,IAAI,IAAI,IAAI,OAAO,CAElB;IAED,cAAc;IAIR,iBAAiB,IAAI,OAAO,CAAC,GAAG,CAAC;IAOjC,qBAAqB,IAAI,OAAO,CAAC,GAAG,CAAC;IA2GrC,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IAkHnD,SAAS;IAWT,sBAAsB;CAiC/B"}

package/dist/types/core/threadWrapper.d.ts

@@ -0,0 +1,59 @@
+import { WorkerInstanceExtensions, WorkerInstanceState } from "./workerInterface.js";
+export declare class ThreadWrapper extends EventTarget implements WorkerInstanceExtensions, WorkerInstanceState {
+    worker: Worker | null;
+    runningTasks: number;
+    maxConcurrentTasks: number;
+    idleTimeout: number;
+    callbacks: Map<string, {
+        resolve: Function;
+        reject: Function;
+    }>;
+    taskStartTimes: Map<string, number>;
+    runningTaskData: Map<string, {
+        id: string;
+        payload: any;
+    }>;
+    lastActivityTime: number;
+    config: any;
+    id: string;
+    initialized: boolean;
+    originalScriptUrl: string;
+    initializing: boolean;
+    taskQueue: Array<{
+        taskId: string;
+        payload: any;
+        resolve: Function;
+        reject: Function;
+    }>;
+    state: 'initializing' | 'healthy' | 'busy' | 'failed' | 'terminated';
+    lastError?: {
+        timestamp: number;
+        message: string;
+        metadata: any;
+    };
+    tasksCompleted: number;
+    errorCount: number;
+    createdAt: number;
+    private initStartTime;
+    private teardownStartTime;
+    private pendingTerminationRequest;
+    constructor(scriptUrl: string, idleTimeout?: number, maxConcurrentTasks?: number, config?: {});
+    canAcceptTask(): boolean;
+    getRunningTaskIds(): string[];
+    getRunningTasks(): Array<{
+        id: string;
+        payload: any;
+    }>;
+    private createTerminateWithError;
+    private _handleTerminationRequest;
+    private _setupUnexpectedExitDetection;
+    private _handleUnexpectedExit;
+    private createBaseWorkerContext;
+    get idle(): boolean;
+    updateActivity(): void;
+    _ensureInitialized(): Promise<void>;
+    runTask(taskId: string, payload: any): Promise<any>;
+    private _processTaskQueue;
+    terminate(): Promise<void>;
+}
+//# sourceMappingURL=threadWrapper.d.ts.map

package/dist/types/core/threadWrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"threadWrapper.d.ts","sourceRoot":"","sources":["../../../core/threadWrapper.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,wBAAwB,EAAE,mBAAmB,EAA6C,MAAM,sBAAsB,CAAC;AAEhI,qBAAa,aAAc,SAAQ,WAAY,YAAW,wBAAwB,EAAE,mBAAmB;IACnG,MAAM,EAAE,MAAM,GAAG,IAAI,CAAQ;IAC7B,YAAY,SAAK;IACjB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE;QAAC,OAAO,EAAE,QAAQ,CAAC;QAAC,MAAM,EAAE,QAAQ,CAAA;KAAC,CAAC,CAA4D;IACzH,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAA6B;IAChE,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,GAAG,CAAA;KAAC,CAAC,CAAiD;IACzG,gBAAgB,EAAE,MAAM,CAAc;IACtC,MAAM,EAAE,GAAG,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,UAAS;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,UAAS;IAErB,SAAS,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,GAAG,CAAC;QAAC,OAAO,EAAE,QAAQ,CAAC;QAAC,MAAM,EAAE,QAAQ,CAAA;KAAC,CAAC,CAAM;IAG3F,KAAK,EAAE,cAAc,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,YAAY,CAAkB;IACtF,SAAS,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,GAAG,CAAA;KAAE,CAAC;IAGlE,cAAc,SAAK;IACnB,UAAU,SAAK;IACf,SAAS,EAAE,MAAM,CAAc;IAC/B,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,iBAAiB,CAAK;IAG9B,OAAO,CAAC,yBAAyB,CAIjB;gBAGJ,SAAS,EAAE,MAAM,EAAE,WAAW,SAAO,EAAE,kBAAkB,SAAI,EAAE,MAAM,KAAK;IAatF,aAAa,IAAI,OAAO;IAQxB,iBAAiB,IAAI,MAAM,EAAE;IAM7B,eAAe,IAAI,KAAK,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,GAAG,CAAA;KAAC,CAAC;IAOpD,OAAO,CAAC,wBAAwB;IAoBhC,OAAO,CAAC,yBAAyB;IA2CjC,OAAO,CAAC,6BAA6B;IAsBrC,OAAO,CAAC,qBAAqB;IAwC7B,OAAO,CAAC,uBAAuB;IAO/B,IAAI,IAAI,IAAI,OAAO,CAElB;IAED,cAAc;IAIR,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;IA+OnC,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IA8BzD,OAAO,CAAC,iBAAiB;IAkBnB,SAAS;CAmChB"}

package/dist/types/core/workerInterface.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Thrown into the task that was running when a worker asked to terminate itself
+ * via `context.terminateWithError()`. Catch it to distinguish worker shutdown
+ * from an ordinary task failure.
+ */
+export declare class WorkerTerminationError extends Error {
+    readonly metadata: {
+        canRestart?: boolean;
+        restartDelay?: number;
+    };
+    constructor(message: string, metadata?: {
+        canRestart?: boolean;
+        restartDelay?: number;
+    });
+}
+export interface WorkerConfig {
+    [key: string]: any;
+}
+/**
+ * Messages a worker thread sends back to its ThreadWrapper.
+ *
+ * `setup_started` / `setup_completed` exist so a threaded worker can report
+ * setup timing from inside the thread, letting ThreadWrapper emit the same
+ * `worker.setup.*` events an inline worker emits.
+ */
+export interface WorkerMessage {
+    type: 'init' | 'teardown' | 'result' | 'error' | 'progress' | 'spawn_task' | 'setup_started' | 'setup_completed';
+    taskId?: string;
+    data?: any;
+    timestamp?: number;
+}
+export interface ProgressData {
+    progress: number;
+    message?: string;
+    details?: any;
+}
+export interface SpawnTaskConfig {
+    id: string;
+    workerType: string;
+    payload: any;
+    parents?: string[];
+    optional?: boolean;
+    retryPolicy?: {
+        maxRetries: number;
+        backoffMs: number;
+    };
+    workerGroups?: string[];
+}
+/**
+ * Worker-level context, passed as the SECOND constructor argument to every
+ * worker instance. Forward it to `super(config, workerContext)` - a worker that
+ * only accepts `config` silently loses the ability to self-terminate.
+ */
+export interface BaseWorkerContext {
+    /** Id of this worker instance, as reported by `WorkerManager.getWorkerIds()`. */
+    workerId: string;
+    /**
+     * Ask the pool to tear this worker down, e.g. after detecting a corrupt
+     * connection. In-flight tasks are requeued when the pool's
+     * `requeueFailedTasks` allows it and `canRestart` is not false.
+     */
+    terminateWithError: (error: Error, metadata?: {
+        canRestart?: boolean;
+        restartDelay?: number;
+    }) => void;
+}
+/**
+ * Task-level context, passed as the second argument to `run()`. Adds per-task
+ * capabilities on top of {@link BaseWorkerContext}.
+ */
+export interface TaskWorkerContext extends BaseWorkerContext {
+    /** Id of the task currently being run. */
+    taskId: string;
+    /**
+     * Report progress as a fraction from 0 to 1 (NOT a percentage). Surfaces as
+     * a `task.progress` event on the scheduler.
+     */
+    sendProgress: (progress: number, message?: string, details?: any) => void;
+    /**
+     * Create another task while this one runs. The spawned task is a descendant
+     * of this one, so `parentTask.onCompleteDescendants()` waits for it.
+     *
+     * Spawning does not block: the call returns immediately and the task is
+     * queued. A spawn naming an unregistered `workerType` emits
+     * `task.spawn_failed` and fails only that spawn.
+     */
+    spawnTask: (config: SpawnTaskConfig) => void;
+}
+export interface WorkerContext extends TaskWorkerContext {
+}
+export interface WorkerInterface {
+    /**
+     * Initialize the worker with configuration
+     * Called once when the worker is first created
+     */
+    setup?(): Promise<void> | void;
+    /**
+     * Execute a task with the given payload
+     * This is the main method where work is performed
+     * @param payload - The task data to process
+     * @param context - Task context with progress, spawn, and termination capabilities
+     * @returns The result of the task execution
+     */
+    run(payload: any, context?: TaskWorkerContext): Promise<any> | any;
+    /**
+     * Clean up resources when the worker is terminated
+     * Called when the worker is being shut down
+     */
+    teardown?(): Promise<void> | void;
+}
+/**
+ * Abstract base class for workers providing common functionality
+ * Workers can extend this class or implement WorkerInterface directly
+ */
+/**
+ * Base class for workers. A worker script must `export default` a class.
+ *
+ * ```typescript
+ * export default class MyWorker extends BaseWorker {
+ *   constructor(config: WorkerConfig = {}, workerContext?: BaseWorkerContext) {
+ *     super(config, workerContext);   // forward BOTH arguments
+ *   }
+ *   async setup() {}                  // required, may be empty
+ *   async teardown() {}               // required, may be empty
+ *   async run(payload: any, context?: TaskWorkerContext) {
+ *     return payload.value * 2;
+ *   }
+ * }
+ * ```
+ *
+ * `setup` and `teardown` are abstract: extending without them is a compile
+ * error, even when there is nothing to do.
+ */
+export declare abstract class BaseWorker implements WorkerInterface {
+    protected config: WorkerConfig;
+    protected workerContext?: BaseWorkerContext;
+    constructor(config?: WorkerConfig, workerContext?: BaseWorkerContext);
+    abstract setup(): Promise<void>;
+    abstract run(payload: any, context?: TaskWorkerContext): Promise<any> | any;
+    abstract teardown(): Promise<void> | void;
+}
+export interface WorkerInstanceState {
+    state: 'initializing' | 'healthy' | 'busy' | 'failed' | 'terminated';
+    lastError?: {
+        timestamp: number;
+        message: string;
+        metadata: any;
+    };
+}
+export interface WorkerInstanceExtensions {
+    getRunningTaskIds(): string[];
+    getRunningTasks(): Array<{
+        id: string;
+        payload: any;
+    }>;
+    canAcceptTask(): boolean;
+}
+export interface WorkerStatus extends WorkerInstanceState {
+    id: string;
+    tasksCompleted: number;
+    errorCount: number;
+    uptime: number;
+    currentTasks: string[];
+    resourcesHeld: string[];
+}
+//# sourceMappingURL=workerInterface.d.ts.map

package/dist/types/core/workerInterface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workerInterface.d.ts","sourceRoot":"","sources":["../../../core/workerInterface.ts"],"names":[],"mappings":"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"}