mcp-agent-foundry 1.3.0 → 2.0.0

package/dist/background/task-runner.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Background Task Runner
+ *
+ * Manages background task execution for non-blocking agent invocations
+ * and pipeline steps. Supports concurrency limits, cancellation,
+ * progress tracking, and event-based notifications.
+ */
+import { EventEmitter } from 'events';
+import type { Logger } from '../observability/logger.js';
+import type { BackgroundTask, BackgroundTaskConfig, BackgroundTaskType, SubmitTaskOptions, SerializedBackgroundTask } from './types.js';
+/**
+ * Manages background task execution with concurrency control.
+ *
+ * Features:
+ * - Queue-based execution with configurable concurrency
+ * - Task cancellation via AbortController
+ * - Progress tracking and notifications
+ * - Event emission for task lifecycle
+ * - Automatic cleanup of old tasks
+ *
+ * @example
+ * ```typescript
+ * const runner = new BackgroundTaskRunner({ maxConcurrent: 3 }, logger);
+ *
+ * // Submit a background task
+ * const taskId = await runner.run(
+ *   'agent_invocation',
+ *   'Review authentication code',
+ *   async () => {
+ *     return await orchestrator.executeWithFailover('reviewer', messages, options);
+ *   },
+ *   { role: 'reviewer', provider: 'openai' }
+ * );
+ *
+ * // Check status later
+ * const task = runner.getTask(taskId);
+ * if (task?.status === 'completed') {
+ *   console.log('Result:', task.result);
+ * }
+ *
+ * // Or wait for completion
+ * const completed = await runner.waitFor(taskId, 60000);
+ * ```
+ */
+export declare class BackgroundTaskRunner extends EventEmitter {
+    private readonly tasks;
+    private readonly queue;
+    private runningCount;
+    private readonly config;
+    private readonly logger;
+    private isEnabled;
+    private isShuttingDown;
+    constructor(config: Partial<BackgroundTaskConfig>, logger: Logger);
+    /**
+     * Check if background tasks are enabled.
+     * Respects AGENT_FOUNDRY_DISABLE_BACKGROUND_TASKS env var.
+     */
+    isBackgroundEnabled(): boolean;
+    /**
+     * Enable or disable background task execution.
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Submit a task to run in the background.
+     * Returns immediately with task ID.
+     *
+     * @param task - Task definition (without id, status, createdAt)
+     * @returns Task ID for tracking
+     */
+    submit(task: Omit<BackgroundTask, 'id' | 'status' | 'createdAt'>): string;
+    /**
+     * Execute a function as a background task.
+     *
+     * @param type - Task type
+     * @param description - Task description
+     * @param fn - Async function to execute
+     * @param options - Additional options
+     * @returns Task ID for tracking
+     */
+    run<T>(type: BackgroundTaskType, description: string, fn: () => Promise<T>, options?: SubmitTaskOptions): Promise<string>;
+    /**
+     * Get task by ID.
+     */
+    getTask(taskId: string): BackgroundTask | undefined;
+    /**
+     * Get all tasks.
+     */
+    getAllTasks(): BackgroundTask[];
+    /**
+     * Get running tasks.
+     */
+    getRunningTasks(): BackgroundTask[];
+    /**
+     * Get pending tasks in queue.
+     */
+    getPendingTasks(): BackgroundTask[];
+    /**
+     * Get completed tasks.
+     */
+    getCompletedTasks(): BackgroundTask[];
+    /**
+     * Cancel a running or pending task.
+     *
+     * @param taskId - ID of task to cancel
+     * @returns true if task was cancelled, false if not found or already complete
+     */
+    cancel(taskId: string): boolean;
+    /**
+     * Wait for a task to complete.
+     *
+     * @param taskId - ID of task to wait for
+     * @param timeout - Maximum time to wait in ms (default: 60000)
+     * @returns The completed task
+     * @throws Error if task not found or timeout exceeded
+     */
+    waitFor(taskId: string, timeout?: number): Promise<BackgroundTask>;
+    /**
+     * Update task progress.
+     *
+     * @param taskId - ID of task to update
+     * @param progress - Progress percentage (0-100)
+     * @param message - Optional progress message
+     */
+    updateProgress(taskId: string, progress: number, message?: string): void;
+    /**
+     * Clean up completed/failed tasks older than specified age.
+     *
+     * @param maxAgeMs - Maximum age in ms (default: 1 hour)
+     * @returns Number of tasks cleaned up
+     */
+    cleanup(maxAgeMs?: number): number;
+    /**
+     * Shutdown the runner - cancel pending tasks and wait for running tasks.
+     *
+     * @param timeout - Maximum time to wait for running tasks in ms (default: 30000)
+     */
+    shutdown(timeout?: number): Promise<void>;
+    /**
+     * Get statistics about the task runner.
+     */
+    getStats(): {
+        pending: number;
+        running: number;
+        completed: number;
+        failed: number;
+        cancelled: number;
+        total: number;
+        queueLength: number;
+        maxConcurrent: number;
+    };
+    /**
+     * Serialize tasks for persistence.
+     * Only serializes metadata, not results or errors.
+     */
+    serializeTasks(): SerializedBackgroundTask[];
+    /**
+     * Process the task queue, starting tasks up to maxConcurrent.
+     */
+    private processQueue;
+    /**
+     * Execute a single task.
+     */
+    private executeTask;
+    /**
+     * Mark a task as completed.
+     */
+    private markCompleted;
+    /**
+     * Mark a task as failed.
+     */
+    private markFailed;
+    /**
+     * Send a notification if enabled.
+     */
+    private notify;
+}
+//# sourceMappingURL=task-runner.d.ts.map

package/dist/background/task-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-runner.d.ts","sourceRoot":"","sources":["../../src/background/task-runner.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAGtC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,KAAK,EACV,cAAc,EACd,oBAAoB,EAEpB,kBAAkB,EAGlB,iBAAiB,EACjB,wBAAwB,EACzB,MAAM,YAAY,CAAC;AAwBpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;IACpD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0C;IAChE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwB;IAC9C,OAAO,CAAC,YAAY,CAAa;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,SAAS,CAAiB;IAClC,OAAO,CAAC,cAAc,CAAkB;gBAE5B,MAAM,EAAE,OAAO,CAAC,oBAAoB,CAAC,EAAE,MAAM,EAAE,MAAM;IAejE;;;OAGG;IACH,mBAAmB,IAAI,OAAO;IAQ9B;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAKlC;;;;;;OAMG;IACH,MAAM,CACJ,IAAI,EAAE,IAAI,CAAC,cAAc,EAAE,IAAI,GAAG,QAAQ,GAAG,WAAW,CAAC,GACxD,MAAM;IAqCT;;;;;;;;OAQG;IACG,GAAG,CAAC,CAAC,EACT,IAAI,EAAE,kBAAkB,EACxB,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,MAAM,CAAC;IA0BlB;;OAEG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAInD;;OAEG;IACH,WAAW,IAAI,cAAc,EAAE;IAI/B;;OAEG;IACH,eAAe,IAAI,cAAc,EAAE;IAInC;;OAEG;IACH,eAAe,IAAI,cAAc,EAAE;IAInC;;OAEG;IACH,iBAAiB,IAAI,cAAc,EAAE;IAMrC;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAsC/B;;;;;;;OAOG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,MAAc,GAAG,OAAO,CAAC,cAAc,CAAC;IAoD/E;;;;;;OAMG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAoBxE;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,GAAE,MAA+B,GAAG,MAAM;IAsB1D;;;;OAIG;IACG,QAAQ,CAAC,OAAO,GAAE,MAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BtD;;OAEG;IACH,QAAQ,IAAI;QACV,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,EAAE,MAAM,CAAC;QACpB,aAAa,EAAE,MAAM,CAAC;KACvB;IAcD;;;OAGG;IACH,cAAc,IAAI,wBAAwB,EAAE;IAuB5C;;OAEG;IACH,OAAO,CAAC,YAAY;IAgBpB;;OAEG;YACW,WAAW;IAqEzB;;OAEG;IACH,OAAO,CAAC,aAAa;IA0BrB;;OAEG;IACH,OAAO,CAAC,UAAU;IA4BlB;;OAEG;IACH,OAAO,CAAC,MAAM;CAef"}