@dexto/orchestration 1.5.8

package/dist/signal-bus.d.ts

@@ -0,0 +1,78 @@
+import { Signal, SignalType } from './types.js';
+
+/**
+ * SignalBus
+ *
+ * Event emitter for routing orchestration signals.
+ * Supports typed subscriptions and promise-based waiting.
+ */
+
+/**
+ * Handler function for signal subscriptions
+ */
+type SignalHandler<T extends Signal = Signal> = (signal: T) => void;
+/**
+ * Predicate function for filtering signals
+ */
+type SignalPredicate = (signal: Signal) => boolean;
+/**
+ * SignalBus - Routes signals between orchestration components
+ */
+declare class SignalBus {
+    private emitter;
+    constructor();
+    /**
+     * Emit a signal to all subscribers
+     */
+    emit(signal: Signal): void;
+    /**
+     * Subscribe to signals of a specific type
+     * @returns Unsubscribe function
+     */
+    on<T extends SignalType>(type: T, handler: SignalHandler<Extract<Signal, {
+        type: T;
+    }>>): () => void;
+    /**
+     * Subscribe to all signals
+     * @returns Unsubscribe function
+     */
+    onAny(handler: SignalHandler): () => void;
+    /**
+     * Subscribe to a signal type once
+     */
+    once<T extends SignalType>(type: T, handler: SignalHandler<Extract<Signal, {
+        type: T;
+    }>>): void;
+    /**
+     * Remove a specific handler
+     */
+    off<T extends SignalType>(type: T, handler: SignalHandler<Extract<Signal, {
+        type: T;
+    }>>): void;
+    /**
+     * Wait for a signal matching the predicate
+     * @param predicate Function to test signals
+     * @param timeout Optional timeout in milliseconds
+     * @returns Promise that resolves with the matching signal
+     */
+    waitFor(predicate: SignalPredicate, timeout?: number): Promise<Signal>;
+    /**
+     * Wait for a signal for a specific task
+     */
+    waitForTask(taskId: string, timeout?: number): Promise<Signal>;
+    /**
+     * Wait for any of multiple tasks to complete
+     */
+    waitForAnyTask(taskIds: string[], timeout?: number): Promise<Signal>;
+    /**
+     * Wait for all tasks to complete
+     * @returns Promise that resolves with all signals
+     */
+    waitForAllTasks(taskIds: string[], timeout?: number, resolveInitial?: (taskId: string) => Signal | undefined): Promise<Signal[]>;
+    /**
+     * Remove all listeners
+     */
+    clear(): void;
+}
+
+export { SignalBus, type SignalHandler, type SignalPredicate };

package/dist/signal-bus.js

@@ -0,0 +1,162 @@
+import { EventEmitter } from "events";
+class SignalBus {
+  emitter = new EventEmitter();
+  constructor() {
+    this.emitter.setMaxListeners(100);
+  }
+  /**
+   * Emit a signal to all subscribers
+   */
+  emit(signal) {
+    this.emitter.emit(signal.type, signal);
+    this.emitter.emit("*", signal);
+  }
+  /**
+   * Subscribe to signals of a specific type
+   * @returns Unsubscribe function
+   */
+  on(type, handler) {
+    this.emitter.on(type, handler);
+    return () => this.emitter.off(type, handler);
+  }
+  /**
+   * Subscribe to all signals
+   * @returns Unsubscribe function
+   */
+  onAny(handler) {
+    this.emitter.on("*", handler);
+    return () => this.emitter.off("*", handler);
+  }
+  /**
+   * Subscribe to a signal type once
+   */
+  once(type, handler) {
+    this.emitter.once(type, handler);
+  }
+  /**
+   * Remove a specific handler
+   */
+  off(type, handler) {
+    this.emitter.off(type, handler);
+  }
+  /**
+   * Wait for a signal matching the predicate
+   * @param predicate Function to test signals
+   * @param timeout Optional timeout in milliseconds
+   * @returns Promise that resolves with the matching signal
+   */
+  waitFor(predicate, timeout) {
+    return new Promise((resolve, reject) => {
+      let timeoutId;
+      let unsubscribe;
+      const cleanup = () => {
+        if (timeoutId) {
+          clearTimeout(timeoutId);
+        }
+        if (unsubscribe) {
+          unsubscribe();
+        }
+      };
+      const handler = (signal) => {
+        if (predicate(signal)) {
+          cleanup();
+          resolve(signal);
+        }
+      };
+      unsubscribe = this.onAny(handler);
+      if (timeout !== void 0 && timeout > 0) {
+        timeoutId = setTimeout(() => {
+          cleanup();
+          reject(new Error(`Signal wait timed out after ${timeout}ms`));
+        }, timeout);
+      }
+    });
+  }
+  /**
+   * Wait for a signal for a specific task
+   */
+  waitForTask(taskId, timeout) {
+    return this.waitFor(
+      (signal) => (signal.type === "task:completed" || signal.type === "task:failed" || signal.type === "task:cancelled") && signal.taskId === taskId,
+      timeout
+    );
+  }
+  /**
+   * Wait for any of multiple tasks to complete
+   */
+  waitForAnyTask(taskIds, timeout) {
+    if (taskIds.length === 0) {
+      return Promise.reject(new Error("taskIds must not be empty"));
+    }
+    const taskIdSet = new Set(taskIds);
+    return this.waitFor(
+      (signal) => (signal.type === "task:completed" || signal.type === "task:failed" || signal.type === "task:cancelled") && taskIdSet.has(signal.taskId),
+      timeout
+    );
+  }
+  /**
+   * Wait for all tasks to complete
+   * @returns Promise that resolves with all signals
+   */
+  async waitForAllTasks(taskIds, timeout, resolveInitial) {
+    if (taskIds.length === 0) {
+      return [];
+    }
+    const remaining = new Set(taskIds);
+    const signals = [];
+    if (resolveInitial) {
+      for (const taskId of taskIds) {
+        const signal = resolveInitial(taskId);
+        if (signal) {
+          remaining.delete(taskId);
+          signals.push(signal);
+        }
+      }
+    }
+    if (remaining.size === 0) {
+      return signals;
+    }
+    return new Promise((resolve, reject) => {
+      let timeoutId;
+      let unsubscribe;
+      const cleanup = () => {
+        if (timeoutId) {
+          clearTimeout(timeoutId);
+        }
+        if (unsubscribe) {
+          unsubscribe();
+        }
+      };
+      const handler = (signal) => {
+        if ((signal.type === "task:completed" || signal.type === "task:failed" || signal.type === "task:cancelled") && remaining.has(signal.taskId)) {
+          remaining.delete(signal.taskId);
+          signals.push(signal);
+          if (remaining.size === 0) {
+            cleanup();
+            resolve(signals);
+          }
+        }
+      };
+      unsubscribe = this.onAny(handler);
+      if (timeout !== void 0 && timeout > 0) {
+        timeoutId = setTimeout(() => {
+          cleanup();
+          reject(
+            new Error(
+              `Waiting for all tasks timed out after ${timeout}ms. Remaining tasks: ${Array.from(remaining).join(", ")}`
+            )
+          );
+        }, timeout);
+      }
+    });
+  }
+  /**
+   * Remove all listeners
+   */
+  clear() {
+    this.emitter.removeAllListeners();
+  }
+}
+export {
+  SignalBus
+};

package/dist/task-registry.cjs

@@ -0,0 +1,345 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var task_registry_exports = {};
+__export(task_registry_exports, {
+  TaskRegistry: () => TaskRegistry
+});
+module.exports = __toCommonJS(task_registry_exports);
+class TaskRegistry {
+  tasks = /* @__PURE__ */ new Map();
+  signalBus;
+  config;
+  constructor(signalBus, config = {}) {
+    this.signalBus = signalBus;
+    this.config = {
+      maxTasks: config.maxTasks ?? 20,
+      resultTTL: config.resultTTL ?? 5 * 60 * 1e3
+      // 5 minutes
+    };
+  }
+  /**
+   * Generate a unique task ID
+   */
+  generateTaskId() {
+    return `task-${Math.random().toString(36).slice(2, 10)}`;
+  }
+  /**
+   * Get description from task for display
+   */
+  getTaskDescription(task) {
+    switch (task.type) {
+      case "agent":
+        return task.taskDescription;
+      case "process":
+        return task.command;
+      case "generic":
+        return task.description;
+    }
+  }
+  /**
+   * Register a new task and start tracking it
+   * @param task Task to register (must include promise)
+   * @param options Registration options
+   * @returns Task ID
+   */
+  register(task, options = {}) {
+    const runningCount = this.getRunningCount();
+    if (runningCount >= this.config.maxTasks) {
+      throw new Error(
+        `Maximum concurrent tasks (${this.config.maxTasks}) exceeded. ${runningCount} tasks currently running.`
+      );
+    }
+    const entry = {
+      task,
+      status: "running",
+      startedAt: /* @__PURE__ */ new Date(),
+      timeoutHandle: void 0,
+      ...options.notify !== void 0 && { notify: options.notify }
+    };
+    this.tasks.set(task.taskId, entry);
+    task.promise.then((result) => {
+      this.onTaskComplete(task.taskId, result);
+    }).catch((error) => {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.onTaskFailed(task.taskId, errorMessage);
+    });
+    if (options.timeout !== void 0 && options.timeout > 0) {
+      const timeoutHandle = setTimeout(() => {
+        const currentEntry = this.tasks.get(task.taskId);
+        if (currentEntry && currentEntry.status === "running") {
+          this.onTaskFailed(task.taskId, `Task timed out after ${options.timeout}ms`);
+        }
+      }, options.timeout);
+      entry.timeoutHandle = timeoutHandle;
+    }
+    return task.taskId;
+  }
+  /**
+   * Create and register an agent task
+   *
+   * Note: Uses agentId as the taskId so the caller can use the same ID
+   * for wait_for/check_task operations.
+   */
+  registerAgentTask(agentId, taskDescription, promise, options = {}) {
+    const taskId = agentId;
+    if (this.tasks.has(taskId)) {
+      throw new Error(`Task '${taskId}' already exists`);
+    }
+    const task = {
+      type: "agent",
+      taskId,
+      agentId,
+      taskDescription,
+      promise
+    };
+    return this.register(task, options);
+  }
+  /**
+   * Create and register a process task
+   */
+  registerProcessTask(processId, command, promise, options = {}) {
+    const taskId = this.generateTaskId();
+    const task = {
+      type: "process",
+      taskId,
+      processId,
+      command,
+      promise
+    };
+    return this.register(task, options);
+  }
+  /**
+   * Create and register a generic task
+   */
+  registerGenericTask(description, promise, options = {}) {
+    const taskId = this.generateTaskId();
+    const task = {
+      type: "generic",
+      taskId,
+      description,
+      promise
+    };
+    return this.register(task, options);
+  }
+  /**
+   * Called when a task completes successfully
+   */
+  onTaskComplete(taskId, result) {
+    const entry = this.tasks.get(taskId);
+    if (!entry || entry.status !== "running") {
+      return;
+    }
+    if (entry.timeoutHandle) {
+      clearTimeout(entry.timeoutHandle);
+      entry.timeoutHandle = void 0;
+    }
+    entry.status = "completed";
+    entry.completedAt = /* @__PURE__ */ new Date();
+    entry.result = result;
+    this.signalBus.emit({
+      type: "task:completed",
+      taskId,
+      result
+    });
+  }
+  /**
+   * Called when a task fails
+   */
+  onTaskFailed(taskId, error) {
+    const entry = this.tasks.get(taskId);
+    if (!entry || entry.status !== "running") {
+      return;
+    }
+    if (entry.timeoutHandle) {
+      clearTimeout(entry.timeoutHandle);
+      entry.timeoutHandle = void 0;
+    }
+    entry.status = "failed";
+    entry.completedAt = /* @__PURE__ */ new Date();
+    entry.error = error;
+    this.signalBus.emit({
+      type: "task:failed",
+      taskId,
+      error
+    });
+  }
+  /**
+   * Cancel a running task
+   */
+  cancel(taskId) {
+    const entry = this.tasks.get(taskId);
+    if (!entry) {
+      throw new Error(`Task '${taskId}' not found`);
+    }
+    if (entry.status !== "running") {
+      return;
+    }
+    if (entry.timeoutHandle) {
+      clearTimeout(entry.timeoutHandle);
+      entry.timeoutHandle = void 0;
+    }
+    entry.status = "cancelled";
+    entry.completedAt = /* @__PURE__ */ new Date();
+    entry.error = entry.error ?? "Cancelled";
+    this.signalBus.emit({
+      type: "task:cancelled",
+      taskId
+    });
+  }
+  /**
+   * Get task entry by ID
+   */
+  get(taskId) {
+    return this.tasks.get(taskId);
+  }
+  /**
+   * Get task status
+   */
+  getStatus(taskId) {
+    return this.tasks.get(taskId)?.status;
+  }
+  /**
+   * Get task result (if completed)
+   */
+  getResult(taskId) {
+    const entry = this.tasks.get(taskId);
+    if (!entry) {
+      return void 0;
+    }
+    return {
+      status: entry.status,
+      ...entry.result !== void 0 && { result: entry.result },
+      ...entry.error !== void 0 && { error: entry.error }
+    };
+  }
+  /**
+   * Get task info (safe for serialization - no promise)
+   */
+  getInfo(taskId) {
+    const entry = this.tasks.get(taskId);
+    if (!entry) {
+      return void 0;
+    }
+    const duration = entry.completedAt ? entry.completedAt.getTime() - entry.startedAt.getTime() : void 0;
+    return {
+      taskId: entry.task.taskId,
+      type: entry.task.type,
+      status: entry.status,
+      startedAt: entry.startedAt,
+      description: this.getTaskDescription(entry.task),
+      ...entry.completedAt !== void 0 && { completedAt: entry.completedAt },
+      ...duration !== void 0 && { duration },
+      ...entry.result !== void 0 && { result: entry.result },
+      ...entry.error !== void 0 && { error: entry.error },
+      ...entry.status === "cancelled" && entry.error !== void 0 && {
+        cancelReason: entry.error
+      }
+    };
+  }
+  /**
+   * List tasks matching filter
+   */
+  list(filter) {
+    const results = [];
+    for (const entry of this.tasks.values()) {
+      if (filter?.status) {
+        const statuses = Array.isArray(filter.status) ? filter.status : [filter.status];
+        if (!statuses.includes(entry.status)) {
+          continue;
+        }
+      }
+      if (filter?.type && entry.task.type !== filter.type) {
+        continue;
+      }
+      const info = this.getInfo(entry.task.taskId);
+      if (info) {
+        results.push(info);
+      }
+    }
+    return results.sort((a, b) => b.startedAt.getTime() - a.startedAt.getTime());
+  }
+  /**
+   * Get count of running tasks
+   */
+  getRunningCount() {
+    let count = 0;
+    for (const entry of this.tasks.values()) {
+      if (entry.status === "running") {
+        count++;
+      }
+    }
+    return count;
+  }
+  /**
+   * Get tasks that completed with notify=true and haven't been acknowledged
+   */
+  getNotifyPending() {
+    return this.list({ status: ["completed", "failed"] }).filter((info) => {
+      const entry = this.tasks.get(info.taskId);
+      return entry?.notify === true;
+    });
+  }
+  /**
+   * Mark notify tasks as acknowledged (clear notify flag)
+   */
+  acknowledgeNotify(taskIds) {
+    for (const taskId of taskIds) {
+      const entry = this.tasks.get(taskId);
+      if (entry) {
+        entry.notify = false;
+      }
+    }
+  }
+  /**
+   * Clean up old completed tasks
+   */
+  cleanup(olderThan) {
+    const cutoff = olderThan ?? new Date(Date.now() - this.config.resultTTL);
+    let cleaned = 0;
+    for (const [taskId, entry] of this.tasks.entries()) {
+      if (entry.status !== "running" && entry.completedAt && entry.completedAt < cutoff) {
+        this.tasks.delete(taskId);
+        cleaned++;
+      }
+    }
+    return cleaned;
+  }
+  /**
+   * Clear all tasks
+   */
+  clear() {
+    this.tasks.clear();
+  }
+  /**
+   * Check if a task exists
+   */
+  has(taskId) {
+    return this.tasks.has(taskId);
+  }
+  /**
+   * Get total task count
+   */
+  get size() {
+    return this.tasks.size;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TaskRegistry
+});

package/dist/task-registry.d.cts

@@ -0,0 +1,124 @@
+import { Task, RegisterTaskOptions, TaskEntry, TaskStatus, TaskInfo, TaskFilter } from './types.cjs';
+import { SignalBus } from './signal-bus.cjs';
+
+/**
+ * TaskRegistry
+ *
+ * Tracks all background tasks and their results.
+ * Emits signals on task completion for the ConditionEngine.
+ */
+
+/**
+ * Configuration for TaskRegistry
+ */
+interface TaskRegistryConfig {
+    /** Maximum number of concurrent tasks (default: 20) */
+    maxTasks?: number;
+    /** TTL for completed task results in ms (default: 5 minutes) */
+    resultTTL?: number;
+}
+/**
+ * TaskRegistry - Manages background task lifecycle
+ */
+declare class TaskRegistry {
+    private tasks;
+    private signalBus;
+    private config;
+    constructor(signalBus: SignalBus, config?: TaskRegistryConfig);
+    /**
+     * Generate a unique task ID
+     */
+    private generateTaskId;
+    /**
+     * Get description from task for display
+     */
+    private getTaskDescription;
+    /**
+     * Register a new task and start tracking it
+     * @param task Task to register (must include promise)
+     * @param options Registration options
+     * @returns Task ID
+     */
+    register(task: Task, options?: RegisterTaskOptions): string;
+    /**
+     * Create and register an agent task
+     *
+     * Note: Uses agentId as the taskId so the caller can use the same ID
+     * for wait_for/check_task operations.
+     */
+    registerAgentTask(agentId: string, taskDescription: string, promise: Promise<unknown>, options?: RegisterTaskOptions): string;
+    /**
+     * Create and register a process task
+     */
+    registerProcessTask(processId: string, command: string, promise: Promise<unknown>, options?: RegisterTaskOptions): string;
+    /**
+     * Create and register a generic task
+     */
+    registerGenericTask(description: string, promise: Promise<unknown>, options?: RegisterTaskOptions): string;
+    /**
+     * Called when a task completes successfully
+     */
+    private onTaskComplete;
+    /**
+     * Called when a task fails
+     */
+    private onTaskFailed;
+    /**
+     * Cancel a running task
+     */
+    cancel(taskId: string): void;
+    /**
+     * Get task entry by ID
+     */
+    get(taskId: string): TaskEntry | undefined;
+    /**
+     * Get task status
+     */
+    getStatus(taskId: string): TaskStatus | undefined;
+    /**
+     * Get task result (if completed)
+     */
+    getResult(taskId: string): {
+        status: TaskStatus;
+        result?: unknown;
+        error?: string;
+    } | undefined;
+    /**
+     * Get task info (safe for serialization - no promise)
+     */
+    getInfo(taskId: string): TaskInfo | undefined;
+    /**
+     * List tasks matching filter
+     */
+    list(filter?: TaskFilter): TaskInfo[];
+    /**
+     * Get count of running tasks
+     */
+    getRunningCount(): number;
+    /**
+     * Get tasks that completed with notify=true and haven't been acknowledged
+     */
+    getNotifyPending(): TaskInfo[];
+    /**
+     * Mark notify tasks as acknowledged (clear notify flag)
+     */
+    acknowledgeNotify(taskIds: string[]): void;
+    /**
+     * Clean up old completed tasks
+     */
+    cleanup(olderThan?: Date): number;
+    /**
+     * Clear all tasks
+     */
+    clear(): void;
+    /**
+     * Check if a task exists
+     */
+    has(taskId: string): boolean;
+    /**
+     * Get total task count
+     */
+    get size(): number;
+}
+
+export { TaskRegistry, type TaskRegistryConfig };