@mastra/core/dist/background-tasks/manager.d.ts

Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.

import type { Mastra } from '..';
import type { PubSub } from '../events/pubsub.js';
import type { BackgroundTask, BackgroundTaskManagerConfig, EnqueueResult, TaskContext, TaskFilter, TaskPayload, TaskListResult, ToolExecutor, BackgroundTaskEvent } from './types.js';
export declare class BackgroundTaskManager {
    #private;
    private pubsub;
    config: Required<Pick<BackgroundTaskManagerConfig, 'globalConcurrency' | 'perAgentConcurrency' | 'backpressure' | 'defaultTimeoutMs'>> & BackgroundTaskManagerConfig;
    /** @internal — read by the workflow-engine step bodies in workflow.ts */
    taskContexts: Map<string, TaskContext>;
    private staticExecutors;
    /** @internal — read by the workflow-engine step bodies in workflow.ts */
    activeAbortControllers: Map<string, AbortController>;
    private workerCallback?;
    private resultCallback?;
    private shuttingDown;
    private cleanupInterval?;
    private initPromise?;
    constructor(config?: BackgroundTaskManagerConfig);
    __registerMastra(mastra: Mastra): void;
    getStorage(): Promise<import("../storage").BackgroundTasksStorage>;
    init(pubsub: PubSub): Promise<void>;
    /**
     * Register per-task hooks (executor, stream emitter, result injector).
     * Called internally by createBackgroundTask or directly for advanced usage.
     */
    registerTaskContext(taskId: string, context: TaskContext): void;
    /**
     * Remove per-task hooks. Called after task reaches terminal state.
     */
    deregisterTaskContext(taskId: string): void;
    /**
     * Register a tool executor by tool name. Used for cross-process dispatch:
     * when a worker in a different process picks up a `task.dispatch` event,
     * it has no per-task closure (`taskContexts`) for that taskId, but it can
     * resolve the executor by tool name via this registry.
     */
    registerStaticExecutor(toolName: string, executor: ToolExecutor): void;
    /**
     * Symmetric to `registerStaticExecutor`. Called when a tool is removed
     * from `Mastra`.
     */
    unregisterStaticExecutor(toolName: string): void;
    /**
     * Look up an executor by tool name. Read by the workflow-step body in
     * `workflow.ts:runAttemptStep` as a fallback when no per-task `TaskContext`
     * is registered (cross-process path).
     */
    getStaticExecutor(toolName: string): ToolExecutor | undefined;
    /**
     * Enqueue a task for background execution.
     * Prefer `createBackgroundTask()` which returns a self-contained handle.
     */
    enqueue(payload: TaskPayload, context?: TaskContext): Promise<EnqueueResult>;
    cancel(taskId: string): Promise<void>;
    /**
     * Resume a suspended task. The tool executor must be re-registered via
     * `registerTaskContext(taskId, ...)` before calling this if the original
     * registration is gone (e.g. process restart) — the manager doesn't
     * rehydrate executor closures from storage.
     *
     * `resumeData` is forwarded to the tool's `execute` options on the
     * resumed run.
     */
    resume(taskId: string, resumeData?: unknown): Promise<BackgroundTask>;
    getTask(taskId: string): Promise<BackgroundTask | null>;
    listTasks(filter?: TaskFilter): Promise<TaskListResult>;
    /**
     * Deletes old completed/failed/cancelled/timed_out task records from storage.
     */
    cleanup(): Promise<void>;
    /**
     * Returns a promise that resolves when the next task from the given set
     * reaches a terminal state.
     */
    waitForNextTask(taskIds: string[], options?: {
        timeoutMs?: number;
        onProgress?: (elapsedMs: number) => void;
        progressIntervalMs?: number;
    }): Promise<BackgroundTask>;
    /**
     * Returns a ReadableStream of all background task lifecycle events,
     * filtered by optional criteria. Intended to be piped directly to an SSE response.
     *
     * On connection, emits the current state of all non-terminal tasks as a snapshot,
     * then subscribes to live pubsub events for subsequent updates.
     *
     * Events include:
     * - `task.running` (status: 'running') — task picked up by a worker
     * - `task.completed` (status: 'completed') — task finished successfully
     * - `task.failed` (status: 'failed' or 'timed_out') — task errored or timed out
     * - `task.cancelled` (status: 'cancelled') — task was cancelled
     * - `task.suspended` (status: 'suspended') — task paused via `suspend()` from
     *   inside its tool executor; resume with `manager.resume(taskId, data)`
     * - `task.resumed` (status: 'running') — suspended task resumed
     *
     * The stream stays open until the caller's AbortSignal fires (client disconnect).
     */
    stream(options?: {
        agentId?: string;
        runId?: string;
        threadId?: string;
        resourceId?: string;
        taskId?: string;
        abortSignal?: AbortSignal;
    }): ReadableStream<Record<string, unknown>>;
    shutdown(): Promise<void>;
    private dispatch;
    /**
     * Handles a task.dispatch event. Returns true if the message was nacked (for retry).
     */
    private handleDispatch;
    /**
     * Handles a task.resume event. Mirrors the workflow branch of handleDispatch
     * but resumes an existing run from its suspended snapshot instead of starting
     * a fresh one. Concurrency gating, suspended-status validation, and the
     * `task.resumed` lifecycle publish all happen here so a different process
     * than the one that suspended the task can drive the resume.
     */
    private handleResume;
    /**
     * Run per-task hooks (onChunk, onResult, onComplete/onFailed) locally in the
     * worker path, before publishing the terminal lifecycle event. Ensures
     * memory / stream state is consistent by the time any pubsub subscriber is
     * notified. After running, the task context is deregistered so
     * `handleResult` (which also fires from pubsub) becomes a no-op for this
     * task in the same process.
     *
     * In distributed deployments where the worker runs in a different process
     * from the dispatcher, `this.taskContexts` won't contain an entry for
     * `task.id` — this method is a no-op there, and `handleResult` in the
     * dispatching process runs the hooks instead.
     */
    /**
     * Terminal-state hooks only. Called when a task reaches `'completed'` or
     * `'failed'`. Suspend is non-terminal — see `runLocalSuspendHooks` for that
     * path.
     *
     * @internal — also called by the workflow-engine step bodies in workflow.ts
     */
    runLocalCompletionHooks(task: BackgroundTask, status: 'completed' | 'failed', extras: {
        result?: unknown;
        error?: {
            message: string;
            stack?: string;
        };
    }): Promise<void>;
    /**
     * Per-task suspend hooks. Fires `ctx.onResult({ status: 'suspended', ... })`
     * so the message list / memory pick up the suspension as the tool's
     * current invocation state. Does NOT deregister the task context — resume
     * needs the executor closure intact.
     *
     * @internal — called by the workflow-engine step bodies in workflow.ts
     */
    runLocalSuspendHooks(task: BackgroundTask): Promise<void>;
    /** @internal — also called by the workflow-engine step bodies in workflow.ts */
    runLocalExecutionHook(task: BackgroundTask): Promise<void>;
    private handleResult;
    private handleCancel;
    /** @internal — also called by the workflow-engine step bodies in workflow.ts */
    publishLifecycleEvent(type: 'task.running' | 'task.completed' | 'task.failed' | 'task.cancelled' | 'task.output' | 'task.suspended' | 'task.resumed', task: BackgroundTaskEvent): Promise<void>;
    private checkConcurrency;
    private drainPending;
    /**
     * Recovers tasks left in 'running' or 'pending' state from a previous process.
     */
    private recoverStaleTasks;
}
//# sourceMappingURL=manager.d.ts.map