@cadenza.io/core 3.17.1 → 3.18.0

package/dist/index.js

@@ -29,7 +29,6 @@ __export(index_exports, {
   GraphRunner: () => GraphRunner,
   SignalBroker: () => SignalBroker,
   SignalEmitter: () => SignalEmitter,
-  SignalTask: () => SignalTask,
   Task: () => Task,
   default: () => index_default
 });
@@ -1527,17 +1526,24 @@ var SignalBroker = class _SignalBroker {
         squashId,
         debounce_default(() => {
           options.squash = false;
-          this.emit(signal, this.squashedContexts.get(squashId), options);
+          this.emit(
+            signal,
+            options.mergeFunction ? options.mergeFunction(
+              this.squashedContexts.get(squashId)[0],
+              ...this.squashedContexts.get(squashId).slice(1)
+            ) : merge_default(
+              this.squashedContexts.get(squashId)[0],
+              ...this.squashedContexts.get(squashId).slice(1)
+            ),
+            options
+          );
           this.squashedEmitters.delete(squashId);
           this.squashedContexts.delete(squashId);
         }, delayMs ?? 300)
       );
-      this.squashedContexts.set(squashId, context);
+      this.squashedContexts.set(squashId, [context]);
     } else {
-      this.squashedContexts.set(
-        squashId,
-        options.mergeFunction ? options.mergeFunction(this.squashedContexts.get(squashId), context) : merge_default(this.squashedContexts.get(squashId), context)
-      );
+      this.squashedContexts.get(squashId)?.push(context);
     }
     this.squashedEmitters.get(squashId)();
   }
@@ -2115,7 +2121,7 @@ var SignalEmitter = class {
    * @param options
    */
   emit(signal, data = {}, options = {}) {
-    Cadenza.broker.emit(signal, data, options);
+    Cadenza.signalBroker.emit(signal, data, options);
   }
   /**
    * Emits a signal via the broker if not silent.
@@ -2127,7 +2133,7 @@ var SignalEmitter = class {
     if (this.silent) {
       return;
     }
-    Cadenza.broker.emit(signal, data, options);
+    Cadenza.signalBroker.emit(signal, data, options);
   }
 };
 
@@ -2439,7 +2445,7 @@ var GraphNode = class _GraphNode extends SignalEmitter {
     );
     if (this.graphDone()) {
       const context2 = this.context.getFullContext();
-      if (context2.__isDeputy)
+      if (context2.__isDeputy || context2.__isInquiry)
         this.emitWithMetadata(
           `meta.node.graph_completed:${this.routineExecId}`,
           context2
@@ -2547,6 +2553,7 @@ var GraphNode = class _GraphNode extends SignalEmitter {
       const result = this.task.execute(
         this.context,
         this.emitWithMetadata.bind(this),
+        this.inquire.bind(this),
         this.onProgress.bind(this),
         { nodeId: this.id, routineExecId: this.routineExecId }
       );
@@ -2565,6 +2572,13 @@ var GraphNode = class _GraphNode extends SignalEmitter {
       });
     }
   }
+  inquire(inquiry, context, options) {
+    return Cadenza.inquire(
+      inquiry,
+      { ...context, __executionTraceId: this.executionTraceId },
+      options
+    );
+  }
   /**
    * Emits a signal along with its associated metadata. The metadata includes
    * task-specific information such as task name, version, execution ID, and
@@ -3193,8 +3207,7 @@ var GraphRoutine = class extends SignalEmitter {
    */
   doOn(...signals) {
     signals.forEach((signal) => {
-      if (this.observedSignals.has(signal)) return;
-      Cadenza.broker.observe(signal, this);
+      this.tasks.forEach((task) => task.doOn(signal));
       this.observedSignals.add(signal);
     });
     return this;
@@ -3208,7 +3221,7 @@ var GraphRoutine = class extends SignalEmitter {
    */
   unsubscribeAll() {
     this.observedSignals.forEach(
-      (signal) => Cadenza.broker.unsubscribe(signal, this)
+      (signal) => this.tasks.forEach((task) => task.unsubscribe(signal))
     );
     this.observedSignals.clear();
     return this;
@@ -3221,10 +3234,8 @@ var GraphRoutine = class extends SignalEmitter {
    */
   unsubscribe(...signals) {
     signals.forEach((signal) => {
-      if (this.observedSignals.has(signal)) {
-        Cadenza.broker.unsubscribe(signal, this);
-        this.observedSignals.delete(signal);
-      }
+      this.tasks.forEach((task) => task.unsubscribe(signal));
+      this.observedSignals.delete(signal);
     });
     return this;
   }
@@ -3509,7 +3520,8 @@ var Task = class _Task extends SignalEmitter {
     this.signalsToEmitAfter = /* @__PURE__ */ new Set();
     this.signalsToEmitOnFail = /* @__PURE__ */ new Set();
     this.observedSignals = /* @__PURE__ */ new Set();
-    this.intents = /* @__PURE__ */ new Set();
+    this.handlesIntents = /* @__PURE__ */ new Set();
+    this.inquiresIntents = /* @__PURE__ */ new Set();
     this.name = name;
     this.taskFunction = task;
     this.description = description;
@@ -3588,7 +3600,8 @@ var Task = class _Task extends SignalEmitter {
             observed: Array.from(this.observedSignals)
           },
           intents: {
-            handles: Array.from(this.intents)
+            handles: Array.from(this.handlesIntents),
+            inquires: Array.from(this.inquiresIntents)
           }
         },
         taskInstance: this,
@@ -3880,14 +3893,16 @@ var Task = class _Task extends SignalEmitter {
    *
    * @param {GraphContext} context The execution context which provides data and functions necessary for the task.
    * @param {function(string, AnyObject): void} emit A function to emit signals and communicate intermediate results or states.
+   * @param {function(string, AnyObject, InquiryOptions): Promise<AnyObject>} inquire A function to inquire something from another task.
    * @param {function(number): void} progressCallback A callback function used to report task progress as a percentage (0 to 100).
    * @param {{ nodeId: string; routineExecId: string }} nodeData An object containing identifiers related to the node and execution routine.
    * @return {TaskResult} The result of the executed task.
    */
-  execute(context, emit, progressCallback, nodeData) {
+  execute(context, emit, inquire, progressCallback, nodeData) {
     return this.taskFunction(
       this.isMeta ? context.getClonedFullContext() : context.getClonedContext(),
       emit,
+      inquire,
       progressCallback
     );
   }
@@ -4097,7 +4112,7 @@ var Task = class _Task extends SignalEmitter {
   doOn(...signals) {
     signals.forEach((signal) => {
       if (this.observedSignals.has(signal)) return;
-      Cadenza.broker.observe(signal, this);
+      Cadenza.signalBroker.observe(signal, this);
       this.observedSignals.add(signal);
       if (this.register) {
         this.emitWithMetadata("meta.task.observed_signal", {
@@ -4151,7 +4166,7 @@ var Task = class _Task extends SignalEmitter {
   attachSignal(...signals) {
     signals.forEach((signal) => {
       this.emitsSignals.add(signal);
-      Cadenza.broker.registerEmittedSignal(signal);
+      Cadenza.signalBroker.registerEmittedSignal(signal);
       if (this.register) {
         const data = {
           signals: {
@@ -4183,7 +4198,7 @@ var Task = class _Task extends SignalEmitter {
   unsubscribe(...signals) {
     signals.forEach((signal) => {
       if (this.observedSignals.has(signal)) {
-        Cadenza.broker.unsubscribe(signal, this);
+        Cadenza.signalBroker.unsubscribe(signal, this);
         this.observedSignals.delete(signal);
         if (this.register) {
           signal = signal.split(":")[0];
@@ -4243,8 +4258,30 @@ var Task = class _Task extends SignalEmitter {
     this.signalsToEmitAfter.clear();
     return this;
   }
-  handlesIntent(intent) {
-    this.intents.add(intent);
+  respondsTo(...inquires) {
+    for (const intentName of inquires) {
+      this.handlesIntents.add(intentName);
+      Cadenza.inquiryBroker.observe(intentName, this);
+      const intent = Cadenza.inquiryBroker.intents.get(intentName);
+      this.inputContextSchema = intent?.input;
+      this.outputContextSchema = intent?.output;
+    }
+    return this;
+  }
+  attachIntents(...intentNames) {
+    for (const intent of intentNames) {
+      this.inquiresIntents.add(intent);
+    }
+    return this;
+  }
+  detachIntents(...intentNames) {
+    for (const intent of intentNames) {
+      this.inquiresIntents.delete(intent);
+    }
+    return this;
+  }
+  detachAllIntents() {
+    this.inquiresIntents.clear();
     return this;
   }
   /**
@@ -4581,6 +4618,7 @@ var DebounceTask = class extends Task {
     this.lastTimeout = null;
     this.lastProgressCallback = null;
     this.lastEmitFunction = null;
+    this.lastInquireFunction = null;
     this.debounceTime = debounceTime;
     this.leading = leading;
     this.trailing = trailing;
@@ -4603,6 +4641,7 @@ var DebounceTask = class extends Task {
       result = this.taskFunction(
         this.lastContext.getClonedContext(),
         this.lastEmitFunction,
+        this.lastInquireFunction,
         this.lastProgressCallback
       );
     } catch (error) {
@@ -4618,6 +4657,11 @@ var DebounceTask = class extends Task {
         this.lastResolve(result);
       }
     }
+    this.lastContext = null;
+    this.lastTimeout = null;
+    this.lastProgressCallback = null;
+    this.lastEmitFunction = null;
+    this.lastInquireFunction = null;
   }
   /**
    * Executes a debounced operation, ensuring controlled execution of functions
@@ -4629,10 +4673,11 @@ var DebounceTask = class extends Task {
    * @param {GraphContext} context - The execution context for the operation.
    * @param {NodeJS.Timeout} timeout - A timeout object for managing execution delays.
    * @param {Function} emit - A callback function to emit signals with a specific context.
+   * @param inquire
    * @param {Function} progressCallback - A callback function to report progress during operation execution.
    * @return {void} Does not return a value but sets internal timers and invokes provided callbacks.
    */
-  debouncedTrigger(resolve, reject, context, timeout, emit, progressCallback) {
+  debouncedTrigger(resolve, reject, context, timeout, emit, inquire, progressCallback) {
     const callNow = this.leading && this.timer === null;
     const isNewBurst = this.timer === null;
     if (this.timer !== null) {
@@ -4645,6 +4690,7 @@ var DebounceTask = class extends Task {
     this.lastTimeout = timeout;
     this.lastProgressCallback = progressCallback;
     this.lastEmitFunction = emit;
+    this.lastInquireFunction = inquire;
     if (!callNow) {
       this.hasLaterCall = true;
     }
@@ -4682,10 +4728,11 @@ var DebounceTask = class extends Task {
    *
    * @param {GraphContext} context - The context containing relevant graph data for the execution.
    * @param {function(string, any): void} emit - A function used to emit signals with associated context.
+   * @param inquire
    * @param {function(number): void} progressCallback - A callback function to report the progress of the task as a number between 0 and 1.
    * @return {Promise<TaskResult>} A promise that resolves with the task result upon completion or rejects on failure.
    */
-  execute(context, emit, progressCallback) {
+  execute(context, emit, inquire, progressCallback) {
     return new Promise((resolve, reject) => {
       const timeout = setTimeout(() => {
         resolve(false);
@@ -4696,6 +4743,7 @@ var DebounceTask = class extends Task {
         context,
         timeout,
         emit,
+        inquire,
         progressCallback
       );
     });
@@ -4735,12 +4783,19 @@ var EphemeralTask = class extends Task {
    *
    * @param {any} context - The execution context, carrying necessary parameters or states for the operation.
    * @param {function(string, AnyObject): void} emit - A function to emit signals with a string identifier and associated context.
+   * @param inquire
    * @param {function(number): void} progressCallback - A callback function to report the progress of the execution as a numerical value.
    * @param {{ nodeId: string, routineExecId: string }} nodeData - An object containing details about the node ID and routine execution ID.
    * @return {any} The result of the execution, returned from the base implementation or processed internally.
    */
-  execute(context, emit, progressCallback, nodeData) {
-    const result = super.execute(context, emit, progressCallback, nodeData);
+  execute(context, emit, inquire, progressCallback, nodeData) {
+    const result = super.execute(
+      context,
+      emit,
+      inquire,
+      progressCallback,
+      nodeData
+    );
     if (this.once || this.condition(result)) {
       this.destroy();
     }
@@ -5487,6 +5542,187 @@ var GraphStandardRun = class extends GraphRunStrategy {
   }
 };
 
+// src/engine/InquiryBroker.ts
+var import_uuid7 = require("uuid");
+var InquiryBroker = class _InquiryBroker extends SignalEmitter {
+  constructor() {
+    super(...arguments);
+    this.debug = false;
+    this.verbose = false;
+    this.inquiryObservers = /* @__PURE__ */ new Map();
+    this.intents = /* @__PURE__ */ new Map();
+  }
+  static get instance() {
+    if (!this.instance_) {
+      this.instance_ = new _InquiryBroker();
+    }
+    return this.instance_;
+  }
+  setDebug(value) {
+    this.debug = value;
+  }
+  setVerbose(value) {
+    this.verbose = value;
+  }
+  validateInquiryName(inquiryName) {
+    if (inquiryName.length > 100) {
+      throw new Error(
+        `Inquiry name must be less than 100 characters: ${inquiryName}`
+      );
+    }
+    if (inquiryName.includes(" ")) {
+      throw new Error(`Inquiry name must not contain spaces: ${inquiryName}"`);
+    }
+    if (inquiryName.includes("\\")) {
+      throw new Error(
+        `Inquiry name must not contain backslashes: ${inquiryName}`
+      );
+    }
+    if (inquiryName.includes(".")) {
+      throw new Error(`Inquiry name must not contain dots: ${inquiryName}`);
+    }
+  }
+  /**
+   * Initializes with runners.
+   * @param runner Standard runner for user signals.
+   * @param metaRunner Meta runner for 'meta.' signals (suppresses further meta-emits).
+   */
+  bootstrap(runner, metaRunner) {
+    this.runner = runner;
+    this.metaRunner = metaRunner;
+  }
+  init() {
+  }
+  /**
+   * Observes an inquiry with a routine/task.
+   * @param inquiry The inquiry (e.g., 'domain.action', 'domain.*' for wildcards).
+   * @param task The observer.
+   * @edge Duplicates ignored; supports wildcards for broad listening.
+   */
+  observe(inquiry, task) {
+    this.addInquiry(inquiry);
+    this.inquiryObservers.get(inquiry).tasks.add(task);
+  }
+  /**
+   * Unsubscribes a routine/task from an inquiry.
+   * @param inquiry The inquiry.
+   * @param task The observer.
+   * @edge Removes all instances if duplicate; deletes if empty.
+   */
+  unsubscribe(inquiry, task) {
+    const obs = this.inquiryObservers.get(inquiry);
+    if (obs) {
+      obs.tasks.delete(task);
+      if (obs.tasks.size === 0) {
+        this.inquiryObservers.delete(inquiry);
+      }
+    }
+  }
+  addInquiry(inquiry) {
+    if (!this.inquiryObservers.has(inquiry)) {
+      this.validateInquiryName(inquiry);
+      this.inquiryObservers.set(inquiry, {
+        fn: (runner, tasks, context) => runner.run(tasks, context),
+        tasks: /* @__PURE__ */ new Set(),
+        registered: false
+      });
+      this.addIntent({
+        name: inquiry,
+        description: "",
+        input: void 0,
+        output: void 0
+      });
+      this.emit("meta.inquiry_broker.added", { inquiryName: inquiry });
+    }
+  }
+  addIntent(intent) {
+    if (!this.intents.has(intent.name)) {
+      this.validateInquiryName(intent.name);
+      this.intents.set(intent.name, intent);
+    } else {
+      const currentIntent = this.intents.get(intent.name);
+      if (currentIntent.description !== intent.description) {
+        currentIntent.description = intent.description;
+      }
+      if (intent.input && currentIntent.input !== intent.input) {
+        currentIntent.input = intent.input;
+      }
+      if (intent.output && currentIntent.output !== intent.output) {
+        currentIntent.output = intent.output;
+      }
+      if (this.inquiryObservers.has(intent.name)) {
+        for (const task of this.inquiryObservers.get(intent.name).tasks) {
+          task.respondsTo(intent.name);
+        }
+      }
+    }
+  }
+  inquire(inquiry, context, options = {
+    timeout: 0
+  }) {
+    const tasks = this.inquiryObservers.get(inquiry)?.tasks;
+    if (!tasks) {
+      return Promise.resolve({});
+    }
+    return new Promise((resolve) => {
+      let joinedContext = {};
+      const pendingTasks = Array.from(tasks).map((task) => task.name);
+      const resolveTasks = [];
+      let timeoutId;
+      if (options.timeout > 0) {
+        timeoutId = setTimeout(() => {
+          for (const resolveTask of resolveTasks) {
+            resolveTask.destroy();
+          }
+          resolve({
+            __error: "Inquire timeout",
+            errored: true,
+            pendingTasks,
+            ...joinedContext
+          });
+        }, options.timeout);
+      }
+      for (const task of tasks) {
+        const inquiryId = (0, import_uuid7.v4)();
+        resolveTasks.push(
+          Cadenza.createEphemeralMetaTask(
+            `Resolve inquiry for ${inquiry}`,
+            (ctx) => {
+              joinedContext = { ...joinedContext, ...ctx };
+              pendingTasks.splice(pendingTasks.indexOf(task.name), 1);
+              if (pendingTasks.length === 0) {
+                resolve(joinedContext);
+              }
+              if (timeoutId) {
+                clearTimeout(timeoutId);
+                timeoutId = void 0;
+              }
+            },
+            "",
+            {
+              once: true,
+              register: false
+            }
+          ).doOn(`meta.node.graph_completed:${inquiryId}`)
+        );
+        if (task.isMeta) {
+          this.metaRunner?.run(task, {
+            ...context,
+            __routineExecId: inquiryId,
+            __isInquiry: true
+          });
+        } else {
+          this.runner?.run(task, {
+            ...context,
+            __routineExecId: inquiryId,
+            __isInquiry: true
+          });
+        }
+      }
+    });
+  }
+};
+
 // src/Cadenza.ts
 var Cadenza = class {
   /**
@@ -5499,17 +5735,21 @@ var Cadenza = class {
   static bootstrap() {
     if (this.isBootstrapped) return;
     this.isBootstrapped = true;
-    this.broker = SignalBroker.instance;
+    this.signalBroker = SignalBroker.instance;
+    this.inquiryBroker = InquiryBroker.instance;
     this.runner = new GraphRunner();
     this.metaRunner = new GraphRunner(true);
-    this.broker.bootstrap(this.runner, this.metaRunner);
+    this.signalBroker.bootstrap(this.runner, this.metaRunner);
+    this.inquiryBroker.bootstrap(this.runner, this.metaRunner);
     if (this.mode === "debug" || this.mode === "dev") {
-      this.broker.setDebug(true);
+      this.signalBroker.setDebug(true);
+      this.inquiryBroker.setDebug(true);
       this.runner.setDebug(true);
       this.metaRunner.setDebug(true);
     }
     this.registry = GraphRegistry.instance;
-    this.broker.init();
+    this.signalBroker.init();
+    this.inquiryBroker.init();
   }
   /**
    * Retrieves the available strategies for running graphs.
@@ -5536,18 +5776,18 @@ var Cadenza = class {
     this.mode = mode;
     this.bootstrap();
     if (mode === "debug" || mode === "dev") {
-      this.broker.setDebug(true);
+      this.signalBroker.setDebug(true);
       this.runner.setDebug(true);
     }
     if (mode === "verbose") {
-      this.broker.setDebug(true);
-      this.broker.setVerbose(true);
+      this.signalBroker.setDebug(true);
+      this.signalBroker.setVerbose(true);
       this.runner.setDebug(true);
       this.runner.setVerbose(true);
     }
     if (mode === "production") {
-      this.broker.setDebug(false);
-      this.broker.setVerbose(false);
+      this.signalBroker.setDebug(false);
+      this.signalBroker.setVerbose(false);
       this.runner.setDebug(false);
       this.runner.setVerbose(false);
     }
@@ -5604,13 +5844,13 @@ var Cadenza = class {
    * ```
    */
   static emit(event, data = {}, options = {}) {
-    this.broker?.emit(event, data, options);
+    this.signalBroker?.emit(event, data, options);
   }
   static schedule(taskName, context, delayMs, exactDateTime) {
-    this.broker?.schedule(taskName, context, { delayMs, exactDateTime });
+    this.signalBroker?.schedule(taskName, context, { delayMs, exactDateTime });
   }
   static interval(taskName, context, intervalMs, leading = false, startDateTime) {
-    this.broker?.interval(
+    this.signalBroker?.interval(
       taskName,
       context,
       intervalMs,
@@ -5619,7 +5859,7 @@ var Cadenza = class {
     );
   }
   static debounce(signalName, context, delayMs) {
-    this.broker?.debounce(signalName, context, { delayMs });
+    this.signalBroker?.debounce(signalName, context, { delayMs });
   }
   static get(taskName) {
     return this.registry?.tasks.get(taskName);
@@ -5627,6 +5867,13 @@ var Cadenza = class {
   static getRoutine(routineName) {
     return this.registry?.routines.get(routineName);
   }
+  static defineIntent(intent) {
+    this.inquiryBroker?.intents.set(intent.name, intent);
+    return intent;
+  }
+  static async inquire(inquiry, context, options) {
+    return this.inquiryBroker?.inquire(inquiry, context, options);
+  }
   /**
    * Creates and registers a new task with the specified parameters and options.
    * Tasks are the basic building blocks of Cadenza graphs and are responsible for executing logic.
@@ -6155,7 +6402,7 @@ var Cadenza = class {
     return new GraphRoutine(name, tasks, description, true);
   }
   static reset() {
-    this.broker?.reset();
+    this.signalBroker?.reset();
     this.registry?.reset();
     this.isBootstrapped = false;
   }
@@ -6163,14 +6410,6 @@ var Cadenza = class {
 Cadenza.isBootstrapped = false;
 Cadenza.mode = "production";
 
-// src/graph/definition/SignalTask.ts
-var SignalTask = class extends Task {
-  constructor(signal, description = "") {
-    super(signal, () => true, description);
-    this.signalsToEmitAfter.add(signal);
-  }
-};
-
 // src/index.ts
 var index_default = Cadenza;
 // Annotate the CommonJS export names for ESM import in node:
@@ -6184,7 +6423,6 @@ var index_default = Cadenza;
   GraphRunner,
   SignalBroker,
   SignalEmitter,
-  SignalTask,
   Task
 });
 /*! Bundled license information: