@dexto/orchestration 1.5.8

package/dist/agent-controller.js

@@ -0,0 +1,241 @@
+import { SignalBus } from "./signal-bus.js";
+import { TaskRegistry } from "./task-registry.js";
+import { ConditionEngine } from "./condition-engine.js";
+class AgentController {
+  agent;
+  logger;
+  state = "idle";
+  sessionId;
+  /** Signal bus for event routing */
+  signalBus;
+  /** Task registry for tracking background tasks */
+  taskRegistry;
+  /** Condition engine for evaluating wait conditions */
+  conditionEngine;
+  /** Signals that arrived while agent was busy */
+  pendingSignals = [];
+  /** Unsubscribe function for notify listener */
+  notifyUnsubscribe;
+  constructor(config) {
+    this.agent = config.agent;
+    if (config.logger) {
+      this.logger = config.logger;
+    }
+    this.sessionId = config.sessionId ?? `session-${Date.now()}`;
+    this.signalBus = new SignalBus();
+    this.taskRegistry = new TaskRegistry(this.signalBus, config.taskRegistry);
+    this.conditionEngine = new ConditionEngine(this.taskRegistry, this.signalBus, this.logger);
+    this.setupNotifyListener();
+  }
+  /**
+   * Set up listener for tasks with notify=true
+   */
+  setupNotifyListener() {
+    this.notifyUnsubscribe = this.signalBus.onAny((signal) => {
+      if (signal.type === "task:completed" || signal.type === "task:failed" || signal.type === "task:cancelled") {
+        const entry = this.taskRegistry.get(signal.taskId);
+        if (entry?.notify) {
+          if (this.state === "idle") {
+            this.logger?.debug(`Auto-notify triggered for task ${signal.taskId}`);
+            void this.processNotify(signal).catch((error) => {
+              const message = error instanceof Error ? error.message : String(error);
+              const signalContext = `signal.type=${signal.type} taskId=${signal.taskId}`;
+              this.logger?.error?.(
+                `AgentController.processNotify failed for ${signalContext}: ${message}`
+              );
+            });
+          } else {
+            this.pendingSignals.push(signal);
+          }
+        }
+      }
+    });
+  }
+  /**
+   * Process an auto-notify task completion
+   */
+  async processNotify(signal) {
+    if (this.state !== "idle") {
+      this.pendingSignals.push(signal);
+      return;
+    }
+    try {
+      this.state = "processing";
+      const taskInfo = signal.type === "task:completed" || signal.type === "task:failed" || signal.type === "task:cancelled" ? this.taskRegistry.getInfo(signal.taskId) : void 0;
+      const contextMessage = this.buildNotifyContext(signal, taskInfo);
+      await this.agent.generate(contextMessage, this.sessionId);
+      if (taskInfo) {
+        this.taskRegistry.acknowledgeNotify([taskInfo.taskId]);
+      }
+    } finally {
+      this.state = "idle";
+      this.processPendingSignals();
+    }
+  }
+  /**
+   * Build context message for auto-notify
+   */
+  buildNotifyContext(signal, taskInfo) {
+    if (signal.type === "task:completed" && taskInfo) {
+      const resultStr = typeof taskInfo.result === "string" ? taskInfo.result : JSON.stringify(taskInfo.result, null, 2);
+      const durationLine = taskInfo.duration !== void 0 ? `Duration: ${taskInfo.duration}ms
+` : "";
+      return `[Background Task Completed]
+Task ID: ${taskInfo.taskId}
+Type: ${taskInfo.type}
+Description: ${taskInfo.description}
+` + durationLine + `Result:
+${resultStr}`;
+    }
+    if (signal.type === "task:failed" && taskInfo) {
+      return `[Background Task Failed]
+Task ID: ${taskInfo.taskId}
+Type: ${taskInfo.type}
+Description: ${taskInfo.description}
+Error: ${taskInfo.error}`;
+    }
+    if (signal.type === "task:cancelled" && taskInfo) {
+      const cancelReason = taskInfo.error ?? "Cancelled";
+      return `[Background Task Cancelled]
+Task ID: ${taskInfo.taskId}
+Type: ${taskInfo.type}
+Description: ${taskInfo.description}
+Reason: ${cancelReason}`;
+    }
+    return `[Background Signal]
+${JSON.stringify(signal, null, 2)}`;
+  }
+  /**
+   * Process any pending signals
+   */
+  processPendingSignals() {
+    while (this.pendingSignals.length > 0 && this.state === "idle") {
+      const signal = this.pendingSignals.shift();
+      if (signal) {
+        void this.processNotify(signal).catch((error) => {
+          const message = error instanceof Error ? error.message : String(error);
+          const signalContext = signal.type === "task:completed" || signal.type === "task:failed" || signal.type === "task:cancelled" ? `signal.type=${signal.type} taskId=${signal.taskId}` : `signal.type=${signal.type}`;
+          this.logger?.error?.(
+            `AgentController.processNotify failed for ${signalContext}: ${message}`
+          );
+        });
+      }
+    }
+  }
+  /**
+   * Process user input and generate response
+   * @param content User message content
+   * @returns Agent response
+   */
+  async process(content) {
+    if (this.state !== "idle") {
+      throw new Error(`Cannot process while agent is ${this.state}`);
+    }
+    try {
+      this.state = "processing";
+      const { contextPrefix, notifyTaskIds } = this.buildTaskContext();
+      const fullContent = contextPrefix ? `${contextPrefix}
+
+${content}` : content;
+      const response = await this.agent.generate(fullContent, this.sessionId);
+      if (notifyTaskIds.length > 0) {
+        this.taskRegistry.acknowledgeNotify(notifyTaskIds);
+      }
+      return response.content;
+    } finally {
+      this.state = "idle";
+      this.processPendingSignals();
+    }
+  }
+  /**
+   * Process a signal trigger (e.g., from external source)
+   */
+  async processSignal(signal) {
+    if (this.state !== "idle") {
+      this.pendingSignals.push(signal);
+      return;
+    }
+    await this.processNotify(signal);
+  }
+  /**
+   * Build context about pending/completed tasks
+   */
+  buildTaskContext() {
+    const running = this.taskRegistry.list({ status: "running" });
+    const notifyPending = this.taskRegistry.getNotifyPending();
+    if (running.length === 0 && notifyPending.length === 0) {
+      return { contextPrefix: "", notifyTaskIds: [] };
+    }
+    const parts = [];
+    if (running.length > 0) {
+      parts.push(
+        `[Background Tasks Running: ${running.length}]
+` + running.map((t) => `- ${t.taskId}: ${t.description}`).join("\n")
+      );
+    }
+    if (notifyPending.length > 0) {
+      parts.push(
+        `[Background Tasks Completed: ${notifyPending.length}]
+` + notifyPending.map((t) => {
+          const status = t.error ? `FAILED: ${t.error}` : t.status === "cancelled" ? "CANCELLED" : "SUCCESS";
+          return `- ${t.taskId}: ${t.description} [${status}]`;
+        }).join("\n")
+      );
+    }
+    return {
+      contextPrefix: parts.join("\n\n"),
+      notifyTaskIds: notifyPending.map((task) => task.taskId)
+    };
+  }
+  /**
+   * Get current agent state
+   */
+  getState() {
+    return this.state;
+  }
+  /**
+   * Get the wrapped agent
+   */
+  getAgent() {
+    return this.agent;
+  }
+  /**
+   * Get session ID
+   */
+  getSessionId() {
+    return this.sessionId;
+  }
+  /**
+   * Inject a signal for processing
+   */
+  injectSignal(signal) {
+    this.signalBus.emit(signal);
+  }
+  /**
+   * Clean up resources
+   */
+  cleanup() {
+    if (this.notifyUnsubscribe) {
+      this.notifyUnsubscribe();
+    }
+    this.pendingSignals = [];
+    this.signalBus.clear();
+    this.taskRegistry.clear();
+  }
+  /**
+   * Start the agent (delegates to wrapped agent)
+   */
+  async start() {
+    await this.agent.start();
+  }
+  /**
+   * Stop the agent (delegates to wrapped agent)
+   */
+  async stop() {
+    this.cleanup();
+    await this.agent.stop();
+  }
+}
+export {
+  AgentController
+};

package/dist/condition-engine.cjs

@@ -0,0 +1,276 @@
+"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 condition_engine_exports = {};
+__export(condition_engine_exports, {
+  ConditionEngine: () => ConditionEngine
+});
+module.exports = __toCommonJS(condition_engine_exports);
+var import_crypto = require("crypto");
+class ConditionEngine {
+  constructor(taskRegistry, signalBus, logger) {
+    this.taskRegistry = taskRegistry;
+    this.signalBus = signalBus;
+    this.logger = logger;
+  }
+  /**
+   * Wait for a condition to be met
+   * @param condition Wait condition to evaluate
+   * @returns Promise resolving to the signal(s) that satisfied the condition
+   */
+  async wait(condition) {
+    const immediate = this.check(condition);
+    if (immediate) {
+      return immediate;
+    }
+    return this.evaluate(condition);
+  }
+  /**
+   * Check if a condition is already satisfied (non-blocking)
+   * @returns WaitResult if satisfied, null if not
+   */
+  check(condition) {
+    switch (condition.type) {
+      case "task":
+        return this.checkTask(condition.taskId);
+      case "any":
+        return this.checkAny(condition.conditions);
+      case "all":
+        return this.checkAll(condition.conditions);
+      case "timeout":
+        return null;
+      case "race":
+        return this.check(condition.task);
+    }
+  }
+  /**
+   * Check if a single task is completed
+   */
+  checkTask(taskId) {
+    const result = this.taskRegistry.getResult(taskId);
+    if (!result) {
+      return null;
+    }
+    if (result.status === "completed") {
+      return {
+        signal: {
+          type: "task:completed",
+          taskId,
+          result: result.result
+        }
+      };
+    }
+    if (result.status === "failed") {
+      return {
+        signal: {
+          type: "task:failed",
+          taskId,
+          error: result.error ?? "Unknown error"
+        }
+      };
+    }
+    if (result.status === "cancelled") {
+      return {
+        signal: {
+          type: "task:cancelled",
+          taskId
+        }
+      };
+    }
+    return null;
+  }
+  /**
+   * Check if any of the conditions is satisfied
+   */
+  checkAny(conditions) {
+    for (const condition of conditions) {
+      const result = this.check(condition);
+      if (result) {
+        return result;
+      }
+    }
+    return null;
+  }
+  /**
+   * Check if all conditions are satisfied
+   */
+  checkAll(conditions) {
+    const signals = [];
+    for (const condition of conditions) {
+      const result = this.check(condition);
+      if (!result) {
+        return null;
+      }
+      signals.push(result.signal);
+    }
+    const primarySignal = signals[0];
+    if (!primarySignal) {
+      throw new Error("Internal error: no signals in checkAll result");
+    }
+    return {
+      signal: primarySignal,
+      allSignals: signals
+    };
+  }
+  /**
+   * Evaluate a condition asynchronously
+   */
+  async evaluate(condition) {
+    switch (condition.type) {
+      case "task":
+        return this.evaluateTask(condition.taskId);
+      case "any":
+        return this.evaluateAny(condition.conditions);
+      case "all":
+        return this.evaluateAll(condition.conditions);
+      case "timeout":
+        return this.evaluateTimeout(condition.ms, condition.conditionId);
+      case "race":
+        return this.evaluateRace(condition.task, condition.timeout);
+    }
+  }
+  /**
+   * Wait for a single task to complete
+   *
+   * Uses subscribe-then-check pattern to avoid race conditions where
+   * the task completes between checking and subscribing.
+   */
+  async evaluateTask(taskId) {
+    this.logger?.debug(`[ConditionEngine] evaluateTask called for taskId=${taskId}`);
+    return new Promise((resolve) => {
+      let unsubscribe;
+      const handler = (signal) => {
+        this.logger?.debug(
+          `[ConditionEngine] Received signal: type=${signal.type}, taskId=${"taskId" in signal ? signal.taskId : "N/A"}`
+        );
+        if ((signal.type === "task:completed" || signal.type === "task:failed" || signal.type === "task:cancelled") && signal.taskId === taskId) {
+          this.logger?.debug(
+            `[ConditionEngine] Signal matches taskId=${taskId}, resolving`
+          );
+          if (unsubscribe) {
+            unsubscribe();
+          }
+          resolve({ signal });
+        }
+      };
+      unsubscribe = this.signalBus.onAny(handler);
+      this.logger?.debug(`[ConditionEngine] Subscribed to signals for taskId=${taskId}`);
+      const immediate = this.checkTask(taskId);
+      this.logger?.debug(
+        `[ConditionEngine] checkTask(${taskId}) returned: ${immediate ? "found" : "null"}`
+      );
+      if (immediate) {
+        unsubscribe();
+        resolve(immediate);
+      }
+    });
+  }
+  /**
+   * Wait for any of the conditions to be satisfied
+   */
+  async evaluateAny(conditions) {
+    const immediate = this.checkAny(conditions);
+    if (immediate) {
+      return immediate;
+    }
+    const promises = conditions.map((c) => this.evaluate(c));
+    const result = await Promise.race(promises);
+    return result;
+  }
+  /**
+   * Wait for all conditions to be satisfied
+   */
+  async evaluateAll(conditions) {
+    const immediate = this.checkAll(conditions);
+    if (immediate) {
+      return immediate;
+    }
+    const results = await Promise.all(conditions.map((c) => this.evaluate(c)));
+    const signals = results.map((r) => r.signal);
+    const primarySignal = signals[0];
+    if (!primarySignal) {
+      throw new Error("Internal error: no signals in evaluateAll result");
+    }
+    return {
+      signal: primarySignal,
+      allSignals: signals
+    };
+  }
+  /**
+   * Wait for a timeout
+   */
+  async evaluateTimeout(ms, conditionId) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+    const signal = {
+      type: "timeout",
+      conditionId
+    };
+    this.signalBus.emit(signal);
+    return { signal };
+  }
+  /**
+   * Race a task condition against a timeout
+   */
+  async evaluateRace(taskCondition, timeoutCondition) {
+    const immediate = this.check(taskCondition);
+    if (immediate) {
+      return immediate;
+    }
+    const result = await Promise.race([
+      this.evaluate(taskCondition),
+      this.evaluate(timeoutCondition)
+    ]);
+    return result;
+  }
+  /**
+   * Helper to create a race condition with timeout
+   */
+  static createRaceWithTimeout(taskId, timeoutMs) {
+    return {
+      type: "race",
+      task: { type: "task", taskId },
+      timeout: {
+        type: "timeout",
+        ms: timeoutMs,
+        conditionId: `timeout-${(0, import_crypto.randomUUID)().slice(0, 8)}`
+      }
+    };
+  }
+  /**
+   * Helper to create an 'any' condition from task IDs
+   */
+  static createAnyTask(taskIds) {
+    return {
+      type: "any",
+      conditions: taskIds.map((taskId) => ({ type: "task", taskId }))
+    };
+  }
+  /**
+   * Helper to create an 'all' condition from task IDs
+   */
+  static createAllTasks(taskIds) {
+    return {
+      type: "all",
+      conditions: taskIds.map((taskId) => ({ type: "task", taskId }))
+    };
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ConditionEngine
+});

package/dist/condition-engine.d.cts

@@ -0,0 +1,87 @@
+import { WaitCondition, WaitResult } from './types.cjs';
+import { SignalBus } from './signal-bus.cjs';
+import { TaskRegistry } from './task-registry.cjs';
+
+/**
+ * ConditionEngine
+ *
+ * Evaluates wait conditions and resolves when met.
+ * Supports single task, any/all of multiple tasks, timeouts, and races.
+ */
+
+type LoggerLike = {
+    debug: (message: string) => void;
+};
+/**
+ * ConditionEngine - Evaluates composable wait conditions
+ */
+declare class ConditionEngine {
+    private taskRegistry;
+    private signalBus;
+    private logger?;
+    constructor(taskRegistry: TaskRegistry, signalBus: SignalBus, logger?: LoggerLike | undefined);
+    /**
+     * Wait for a condition to be met
+     * @param condition Wait condition to evaluate
+     * @returns Promise resolving to the signal(s) that satisfied the condition
+     */
+    wait(condition: WaitCondition): Promise<WaitResult>;
+    /**
+     * Check if a condition is already satisfied (non-blocking)
+     * @returns WaitResult if satisfied, null if not
+     */
+    check(condition: WaitCondition): WaitResult | null;
+    /**
+     * Check if a single task is completed
+     */
+    private checkTask;
+    /**
+     * Check if any of the conditions is satisfied
+     */
+    private checkAny;
+    /**
+     * Check if all conditions are satisfied
+     */
+    private checkAll;
+    /**
+     * Evaluate a condition asynchronously
+     */
+    private evaluate;
+    /**
+     * Wait for a single task to complete
+     *
+     * Uses subscribe-then-check pattern to avoid race conditions where
+     * the task completes between checking and subscribing.
+     */
+    private evaluateTask;
+    /**
+     * Wait for any of the conditions to be satisfied
+     */
+    private evaluateAny;
+    /**
+     * Wait for all conditions to be satisfied
+     */
+    private evaluateAll;
+    /**
+     * Wait for a timeout
+     */
+    private evaluateTimeout;
+    /**
+     * Race a task condition against a timeout
+     */
+    private evaluateRace;
+    /**
+     * Helper to create a race condition with timeout
+     */
+    static createRaceWithTimeout(taskId: string, timeoutMs: number): WaitCondition;
+    /**
+     * Helper to create an 'any' condition from task IDs
+     */
+    static createAnyTask(taskIds: string[]): WaitCondition;
+    /**
+     * Helper to create an 'all' condition from task IDs
+     */
+    static createAllTasks(taskIds: string[]): WaitCondition;
+}
+
+export { ConditionEngine };

package/dist/condition-engine.d.ts

@@ -0,0 +1,87 @@
+import { WaitCondition, WaitResult } from './types.js';
+import { SignalBus } from './signal-bus.js';
+import { TaskRegistry } from './task-registry.js';
+
+/**
+ * ConditionEngine
+ *
+ * Evaluates wait conditions and resolves when met.
+ * Supports single task, any/all of multiple tasks, timeouts, and races.
+ */
+
+type LoggerLike = {
+    debug: (message: string) => void;
+};
+/**
+ * ConditionEngine - Evaluates composable wait conditions
+ */
+declare class ConditionEngine {
+    private taskRegistry;
+    private signalBus;
+    private logger?;
+    constructor(taskRegistry: TaskRegistry, signalBus: SignalBus, logger?: LoggerLike | undefined);
+    /**
+     * Wait for a condition to be met
+     * @param condition Wait condition to evaluate
+     * @returns Promise resolving to the signal(s) that satisfied the condition
+     */
+    wait(condition: WaitCondition): Promise<WaitResult>;
+    /**
+     * Check if a condition is already satisfied (non-blocking)
+     * @returns WaitResult if satisfied, null if not
+     */
+    check(condition: WaitCondition): WaitResult | null;
+    /**
+     * Check if a single task is completed
+     */
+    private checkTask;
+    /**
+     * Check if any of the conditions is satisfied
+     */
+    private checkAny;
+    /**
+     * Check if all conditions are satisfied
+     */
+    private checkAll;
+    /**
+     * Evaluate a condition asynchronously
+     */
+    private evaluate;
+    /**
+     * Wait for a single task to complete
+     *
+     * Uses subscribe-then-check pattern to avoid race conditions where
+     * the task completes between checking and subscribing.
+     */
+    private evaluateTask;
+    /**
+     * Wait for any of the conditions to be satisfied
+     */
+    private evaluateAny;
+    /**
+     * Wait for all conditions to be satisfied
+     */
+    private evaluateAll;
+    /**
+     * Wait for a timeout
+     */
+    private evaluateTimeout;
+    /**
+     * Race a task condition against a timeout
+     */
+    private evaluateRace;
+    /**
+     * Helper to create a race condition with timeout
+     */
+    static createRaceWithTimeout(taskId: string, timeoutMs: number): WaitCondition;
+    /**
+     * Helper to create an 'any' condition from task IDs
+     */
+    static createAnyTask(taskIds: string[]): WaitCondition;
+    /**
+     * Helper to create an 'all' condition from task IDs
+     */
+    static createAllTasks(taskIds: string[]): WaitCondition;
+}
+
+export { ConditionEngine };