@dexto/orchestration 1.5.8

package/dist/task-registry.d.ts

@@ -0,0 +1,124 @@
+import { Task, RegisterTaskOptions, TaskEntry, TaskStatus, TaskInfo, TaskFilter } from './types.js';
+import { SignalBus } from './signal-bus.js';
+
+/**
+ * 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 };

package/dist/task-registry.js

@@ -0,0 +1,321 @@
+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;
+  }
+}
+export {
+  TaskRegistry
+};

package/dist/tools/check-task.cjs

@@ -0,0 +1,65 @@
+"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 check_task_exports = {};
+__export(check_task_exports, {
+  CheckTaskInputSchema: () => CheckTaskInputSchema,
+  createCheckTaskTool: () => createCheckTaskTool
+});
+module.exports = __toCommonJS(check_task_exports);
+var import_zod = require("zod");
+const CheckTaskInputSchema = import_zod.z.object({
+  /** Task ID to check */
+  taskId: import_zod.z.string().describe("Task ID to check status of")
+}).strict();
+function createCheckTaskTool() {
+  return {
+    id: "check_task",
+    description: "Check the status of a background task. Returns immediately without waiting. Use this to poll task status or check if a task is done.",
+    inputSchema: CheckTaskInputSchema,
+    execute: async (rawInput, context) => {
+      const input = CheckTaskInputSchema.parse(rawInput);
+      const info = context.taskRegistry.getInfo(input.taskId);
+      if (!info) {
+        return {
+          taskId: input.taskId,
+          found: false
+        };
+      }
+      return {
+        taskId: info.taskId,
+        found: true,
+        type: info.type,
+        status: info.status,
+        startedAt: info.startedAt.toISOString(),
+        ...info.description !== void 0 && { description: info.description },
+        ...info.completedAt !== void 0 && {
+          completedAt: info.completedAt.toISOString()
+        },
+        ...info.duration !== void 0 && { duration: info.duration },
+        ...info.result !== void 0 && { result: info.result },
+        ...info.error !== void 0 && { error: info.error }
+      };
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CheckTaskInputSchema,
+  createCheckTaskTool
+});

package/dist/tools/check-task.d.cts

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+import { OrchestrationTool } from './types.cjs';
+import '../task-registry.cjs';
+import '../types.cjs';
+import '../signal-bus.cjs';
+import '../condition-engine.cjs';
+
+/**
+ * check_task Tool
+ *
+ * Non-blocking status check for a background task.
+ */
+
+/**
+ * Input schema for check_task tool
+ */
+declare const CheckTaskInputSchema: z.ZodObject<{
+    /** Task ID to check */
+    taskId: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    taskId: string;
+}, {
+    taskId: string;
+}>;
+type CheckTaskInput = z.output<typeof CheckTaskInputSchema>;
+/**
+ * Output from check_task tool
+ */
+interface CheckTaskOutput {
+    /** Task ID */
+    taskId: string;
+    /** Whether task was found */
+    found: boolean;
+    /** Task type */
+    type?: 'agent' | 'process' | 'generic';
+    /** Current status */
+    status?: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+    /** Description of what the task is doing */
+    description?: string;
+    /** When the task started */
+    startedAt?: string;
+    /** When the task completed (if done) */
+    completedAt?: string;
+    /** Duration in milliseconds (if completed) */
+    duration?: number;
+    /** Result (if completed successfully) */
+    result?: unknown;
+    /** Error message (if failed) */
+    error?: string;
+}
+/**
+ * Create the check_task tool
+ */
+declare function createCheckTaskTool(): OrchestrationTool;
+
+export { type CheckTaskInput, CheckTaskInputSchema, type CheckTaskOutput, createCheckTaskTool };

package/dist/tools/check-task.d.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+import { OrchestrationTool } from './types.js';
+import '../task-registry.js';
+import '../types.js';
+import '../signal-bus.js';
+import '../condition-engine.js';
+
+/**
+ * check_task Tool
+ *
+ * Non-blocking status check for a background task.
+ */
+
+/**
+ * Input schema for check_task tool
+ */
+declare const CheckTaskInputSchema: z.ZodObject<{
+    /** Task ID to check */
+    taskId: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    taskId: string;
+}, {
+    taskId: string;
+}>;
+type CheckTaskInput = z.output<typeof CheckTaskInputSchema>;
+/**
+ * Output from check_task tool
+ */
+interface CheckTaskOutput {
+    /** Task ID */
+    taskId: string;
+    /** Whether task was found */
+    found: boolean;
+    /** Task type */
+    type?: 'agent' | 'process' | 'generic';
+    /** Current status */
+    status?: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+    /** Description of what the task is doing */
+    description?: string;
+    /** When the task started */
+    startedAt?: string;
+    /** When the task completed (if done) */
+    completedAt?: string;
+    /** Duration in milliseconds (if completed) */
+    duration?: number;
+    /** Result (if completed successfully) */
+    result?: unknown;
+    /** Error message (if failed) */
+    error?: string;
+}
+/**
+ * Create the check_task tool
+ */
+declare function createCheckTaskTool(): OrchestrationTool;
+
+export { type CheckTaskInput, CheckTaskInputSchema, type CheckTaskOutput, createCheckTaskTool };

package/dist/tools/check-task.js

@@ -0,0 +1,40 @@
+import { z } from "zod";
+const CheckTaskInputSchema = z.object({
+  /** Task ID to check */
+  taskId: z.string().describe("Task ID to check status of")
+}).strict();
+function createCheckTaskTool() {
+  return {
+    id: "check_task",
+    description: "Check the status of a background task. Returns immediately without waiting. Use this to poll task status or check if a task is done.",
+    inputSchema: CheckTaskInputSchema,
+    execute: async (rawInput, context) => {
+      const input = CheckTaskInputSchema.parse(rawInput);
+      const info = context.taskRegistry.getInfo(input.taskId);
+      if (!info) {
+        return {
+          taskId: input.taskId,
+          found: false
+        };
+      }
+      return {
+        taskId: info.taskId,
+        found: true,
+        type: info.type,
+        status: info.status,
+        startedAt: info.startedAt.toISOString(),
+        ...info.description !== void 0 && { description: info.description },
+        ...info.completedAt !== void 0 && {
+          completedAt: info.completedAt.toISOString()
+        },
+        ...info.duration !== void 0 && { duration: info.duration },
+        ...info.result !== void 0 && { result: info.result },
+        ...info.error !== void 0 && { error: info.error }
+      };
+    }
+  };
+}
+export {
+  CheckTaskInputSchema,
+  createCheckTaskTool
+};