@objectstack/service-automation 8.0.1 → 9.0.1

package/dist/index.cjs

@@ -496,6 +496,8 @@ var AutomationEngine = class {
     }
     const runId = this.nextRunId();
     variables.set("$runId", runId);
+    variables.set("$flowName", flowName);
+    variables.set("$flowLabel", flow.label ?? flowName);
     const startedAt = (/* @__PURE__ */ new Date()).toISOString();
     const steps = [];
     try {
@@ -616,8 +618,24 @@ var AutomationEngine = class {
    * restricted to the edge labelled `signal.branchLabel` (e.g. the approval
    * decision). The continuation may itself suspend again, in which case this
    * returns `{ status: 'paused', runId }` afresh.
+   *
+   * **Subflow chains (nested pause, linked-runs model).** A run paused at a
+   * `subflow` node (correlation `subflow:<childRunId>`) DELEGATES the signal
+   * down to the suspended child; a run that completes and carries
+   * `$parentRunId` in its context BUBBLES its output up by auto-resuming the
+   * parent. Both directions compose recursively, so arbitrarily nested
+   * subflow pauses resolve from either end (UI holds the parent run id;
+   * approval/wait infrastructure holds the child's).
    */
   async resume(runId, signal) {
+    return this.resumeInternal(runId, signal, false);
+  }
+  /**
+   * @param skipBubble - Set when the caller is the subflow DELEGATION path,
+   *   which continues the parent itself after the child completes — the
+   *   child's own up-bubble must stay off so the parent isn't resumed twice.
+   */
+  async resumeInternal(runId, signal, skipBubble) {
     if (this.resuming.has(runId)) {
       return { success: false, error: `Run '${runId}' is already being resumed` };
     }
@@ -644,6 +662,35 @@ var AutomationEngine = class {
       if (!node) {
         return { success: false, error: `Suspended node '${run.nodeId}' no longer exists in flow '${run.flowName}'` };
       }
+      if (typeof run.correlation === "string" && run.correlation.startsWith("subflow:")) {
+        const childRunId = run.correlation.slice("subflow:".length);
+        const childRun = this.suspendedRuns.get(childRunId) ?? (this.store ? await this.store.load(childRunId).catch(() => null) : null);
+        if (childRun) {
+          const childRes = await this.resumeInternal(childRunId, signal, true);
+          if (childRes.status === "paused") {
+            if (childRes.screen && childRes.screen !== run.screen) {
+              await this.persistSuspendedRun({ ...run, screen: childRes.screen });
+            }
+            return {
+              success: true,
+              status: "paused",
+              runId,
+              durationMs: Date.now() - run.startTime,
+              screen: childRes.screen
+            };
+          }
+          if (!childRes.success) {
+            const error = `subflow run '${childRunId}' (${childRun.flowName}) failed: ${childRes.error ?? "unknown error"}`;
+            await this.failSuspendedRun(run, error);
+            return { success: false, error, durationMs: Date.now() - run.startTime };
+          }
+          signal = this.buildSubflowResumeSignal(childRun.context, childRes.output);
+        } else {
+          this.logger.warn(
+            `[automation] run '${runId}' is paused at subflow node '${run.nodeId}' but child run '${childRunId}' is gone \u2014 continuing without child output`
+          );
+        }
+      }
       await this.forgetSuspendedRun(runId);
       const variables = new Map(Object.entries(run.variables));
       if (signal?.output) {
@@ -659,7 +706,11 @@ var AutomationEngine = class {
       const steps = run.steps;
       const context = run.context;
       try {
-        await this.traverseNext(node, flow, variables, context, steps, signal?.branchLabel);
+        if (typeof run.correlation === "string" && run.correlation.startsWith("map:")) {
+          await this.executeNode(node, flow, variables, context, steps);
+        } else {
+          await this.traverseNext(node, flow, variables, context, steps, signal?.branchLabel);
+        }
         const output = {};
         if (flow.variables) {
           for (const v of flow.variables) {
@@ -683,6 +734,9 @@ var AutomationEngine = class {
           steps,
           output
         });
+        if (!skipBubble) {
+          await this.bubbleToParent(run, output);
+        }
         return { success: true, output, durationMs };
       } catch (err) {
         if (isSuspendSignal(err)) {
@@ -729,12 +783,94 @@ var AutomationEngine = class {
           steps,
           error: errorMessage
         });
+        if (!skipBubble) {
+          await this.failAncestors(run.context, errorMessage);
+        }
         return { success: false, error: errorMessage, durationMs };
       }
     } finally {
       this.resuming.delete(runId);
     }
   }
+  /**
+   * Build the resume signal that maps a completed subflow child's output
+   * into its parent — mirroring the synchronous path exactly: the engine's
+   * standard `signal.output` merge lands it under `${subflowNodeId}.output`,
+   * and `signal.variables` writes the bare `config.outputVariable` when the
+   * child's context carries one (`$parentOutputVariable`).
+   */
+  buildSubflowResumeSignal(childContext, childOutput) {
+    const outVar = childContext?.$parentOutputVariable;
+    return {
+      output: { output: childOutput ?? null },
+      ...typeof outVar === "string" && outVar ? { variables: { [outVar]: childOutput ?? null } } : {}
+    };
+  }
+  /**
+   * Up-bubble for the subflow chain: when a completed run carries
+   * `$parentRunId`, resume that parent with this run's output. Recursion via
+   * the parent's own completion bubbles multi-level chains. Best-effort —
+   * a failed parent continuation is logged, never thrown back at the
+   * caller who resumed the child.
+   */
+  async bubbleToParent(run, output) {
+    const ctx = run.context;
+    const parentRunId = ctx?.$parentRunId;
+    if (typeof parentRunId !== "string" || !parentRunId) return;
+    try {
+      const mapNode = ctx?.$parentMapNode;
+      const sig = typeof mapNode === "string" && mapNode ? { variables: { [`${mapNode}.$mapItemOutput`]: output ?? null, [`${mapNode}.$mapItemDone`]: true } } : this.buildSubflowResumeSignal(run.context, output);
+      const parentRes = await this.resumeInternal(parentRunId, sig, false);
+      if (!parentRes.success) {
+        this.logger.warn(
+          `[automation] subflow run '${run.runId}' completed but resuming parent '${parentRunId}' failed: ${parentRes.error}`
+        );
+      }
+    } catch (err) {
+      this.logger.warn(
+        `[automation] subflow run '${run.runId}' completed but resuming parent '${parentRunId}' threw: ${err.message}`
+      );
+    }
+  }
+  /**
+   * Terminally fail a suspended run: consume its continuation and record a
+   * `failed` log so it stops surfacing as resumable. Used when a subflow
+   * descendant fails — the ancestor awaiting it can never be resumed.
+   */
+  async failSuspendedRun(run, error) {
+    await this.forgetSuspendedRun(run.runId);
+    this.recordLog({
+      id: run.runId,
+      flowName: run.flowName,
+      flowVersion: run.flowVersion,
+      status: "failed",
+      startedAt: run.startedAt,
+      completedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      durationMs: Date.now() - run.startTime,
+      trigger: {
+        type: run.context?.event ?? "manual",
+        userId: run.context?.userId,
+        object: run.context?.object
+      },
+      steps: run.steps,
+      error
+    });
+  }
+  /**
+   * Walk a failed run's `$parentRunId` chain and fail each suspended
+   * ancestor (see {@link failSuspendedRun}). Bounded so a corrupt context
+   * can't loop forever.
+   */
+  async failAncestors(context, error) {
+    let parentId = context?.$parentRunId;
+    let hops = 0;
+    while (typeof parentId === "string" && parentId && hops++ < 32) {
+      const parent = this.suspendedRuns.get(parentId) ?? (this.store ? await this.store.load(parentId).catch(() => null) : null);
+      if (!parent) return;
+      await this.failSuspendedRun(parent, `subflow descendant failed: ${error}`);
+      parentId = parent.context?.$parentRunId;
+    }
+  }
   /**
    * List the runs currently suspended awaiting {@link resume} (ADR-0019).
    * Backs operability surfaces such as a "pending approvals" view.
@@ -2506,10 +2642,11 @@ function registerWaitNode(engine, ctx) {
       const runId = variables.get("$runId");
       if (eventType === "timer") {
         const durationMs = parseIsoDuration(wec.timerDuration ?? loose.timerDuration ?? loose.duration) ?? (typeof wec.timeoutMs === "number" ? wec.timeoutMs : void 0) ?? (typeof loose.timeoutMs === "number" ? loose.timeoutMs : void 0);
+        const at = durationMs && durationMs > 0 ? new Date(Date.now() + durationMs).toISOString() : void 0;
+        const output = at ? { waitUntil: at } : void 0;
         const job = getJobService();
-        if (job && runId != null && durationMs && durationMs > 0) {
+        if (job && runId != null && at) {
           const jobName = `flow-wait:${String(runId)}:${node.id}`;
-          const at = new Date(Date.now() + durationMs).toISOString();
           try {
             await job.schedule(jobName, { type: "once", at }, async () => {
               try {
@@ -2521,7 +2658,7 @@ function registerWaitNode(engine, ctx) {
                 }
               }
             });
-            return { success: true, suspend: true, correlation: jobName };
+            return { success: true, suspend: true, correlation: jobName, output };
           } catch (err) {
             ctx.logger.warn(
               `[wait] node '${node.id}': failed to schedule timer resume (${err?.message ?? err}); suspending without auto-resume (resume it via resume(runId))`
@@ -2532,7 +2669,7 @@ function registerWaitNode(engine, ctx) {
             `[wait] node '${node.id}': no job service registered \u2014 suspending without an auto-resume timer (resume it via resume(runId), or install the job service for durable timers)`
           );
         }
-        return { success: true, suspend: true, correlation: `timer:${node.id}` };
+        return { success: true, suspend: true, correlation: `timer:${node.id}`, output };
       }
       const signal = String(wec.signalName ?? loose.signalName ?? loose.signal ?? `wait:${node.id}`);
       return { success: true, suspend: true, correlation: signal };
@@ -2540,6 +2677,54 @@ function registerWaitNode(engine, ctx) {
   });
   ctx.logger.info("[Wait Node] 1 built-in node executor registered");
 }
+async function rearmSuspendedWaitTimers(engine, store, job, logger) {
+  let runs;
+  try {
+    runs = await store.list();
+  } catch (err) {
+    logger.warn(`[wait] timer re-arm: failed to list suspended runs: ${err?.message ?? err}`);
+    return 0;
+  }
+  let rearmed = 0;
+  for (const run of runs) {
+    const wakeAt = run.variables?.[`${run.nodeId}.waitUntil`];
+    if (typeof wakeAt !== "string" || !wakeAt) continue;
+    const atMs = Date.parse(wakeAt);
+    if (Number.isNaN(atMs)) continue;
+    if (atMs <= Date.now()) {
+      try {
+        await engine.resume(run.runId);
+        rearmed++;
+      } catch (err) {
+        logger.warn(`[wait] timer re-arm: resume of overdue run '${run.runId}' failed: ${err?.message ?? err}`);
+      }
+      continue;
+    }
+    if (!job) {
+      logger.warn(
+        `[wait] timer re-arm: run '${run.runId}' waits until ${wakeAt} but no job service is registered \u2014 resume it externally via resume(runId)`
+      );
+      continue;
+    }
+    const jobName = `flow-wait:${run.runId}:${run.nodeId}`;
+    try {
+      await job.schedule(jobName, { type: "once", at: wakeAt }, async () => {
+        try {
+          await engine.resume(run.runId);
+        } finally {
+          try {
+            await job.cancel?.(jobName);
+          } catch {
+          }
+        }
+      });
+      rearmed++;
+    } catch (err) {
+      logger.warn(`[wait] timer re-arm: failed to re-schedule run '${run.runId}': ${err?.message ?? err}`);
+    }
+  }
+  return rearmed;
+}
 function parseIsoDuration(input) {
   if (typeof input === "number" && Number.isFinite(input)) return input > 0 ? input : void 0;
   if (typeof input !== "string") return void 0;
@@ -2571,7 +2756,10 @@ function registerSubflowNode(engine, ctx) {
       description: "Invoke another flow as a reusable step and capture its output.",
       icon: "workflow",
       category: "logic",
-      source: "builtin"
+      source: "builtin",
+      // A child that suspends (approval/screen/wait) suspends this node too —
+      // the parent run pauses here and resumes when the child completes.
+      supportsPause: true
     }),
     async execute(node, variables, context) {
       const cfg = node.config ?? {};
@@ -2588,22 +2776,33 @@ function registerSubflowNode(engine, ctx) {
       }
       const rawInput = cfg.input && typeof cfg.input === "object" ? cfg.input : {};
       const params = interpolate(rawInput, variables, context ?? {});
+      const outVar = typeof cfg.outputVariable === "string" && cfg.outputVariable ? cfg.outputVariable : void 0;
+      const parentRunId = variables.get("$runId");
       const childContext = {
         ...context ?? {},
         $subflowDepth: depth + 1,
-        params
+        params,
+        ...parentRunId != null ? {
+          $parentRunId: String(parentRunId),
+          $parentNodeId: node.id,
+          ...outVar ? { $parentOutputVariable: outVar } : {}
+        } : {}
       };
       const child = await engine.execute(flowName, childContext);
       if (child.status === "paused") {
+        if (!child.runId) {
+          return { success: false, error: `subflow '${flowName}' paused without a run id \u2014 cannot link the runs` };
+        }
         return {
-          success: false,
-          error: `subflow '${flowName}' suspended at a pausing node \u2014 a nested approval/screen/wait pause from a subflow is not yet supported`
+          success: true,
+          suspend: true,
+          correlation: `subflow:${child.runId}`,
+          screen: child.screen
         };
       }
       if (!child.success) {
         return { success: false, error: `subflow '${flowName}' failed: ${child.error ?? "unknown error"}` };
       }
-      const outVar = typeof cfg.outputVariable === "string" && cfg.outputVariable ? cfg.outputVariable : void 0;
       if (outVar) variables.set(outVar, child.output ?? null);
       return { success: true, output: { output: child.output ?? null } };
     }
@@ -2611,6 +2810,96 @@ function registerSubflowNode(engine, ctx) {
   ctx.logger.info("[Subflow Node] 1 built-in node executor registered");
 }
 
+// src/builtin/map-node.ts
+var import_automation13 = require("@objectstack/spec/automation");
+var MAX_MAP_ITEMS = 1e4;
+function registerMapNode(engine, ctx) {
+  engine.registerNodeExecutor({
+    type: "map",
+    descriptor: (0, import_automation13.defineActionDescriptor)({
+      type: "map",
+      version: "1.0.0",
+      name: "Map",
+      description: "Run a per-item subflow for each element of a collection, one at a time (each item may pause).",
+      icon: "list-check",
+      category: "logic",
+      source: "builtin",
+      // Each item's subflow may pause, so the map suspends and resumes per item.
+      supportsPause: true,
+      isAsync: true
+    }),
+    async execute(node, variables, context) {
+      const cfg = node.config ?? {};
+      const flowName = typeof cfg.flowName === "string" ? cfg.flowName : typeof cfg.flow === "string" ? cfg.flow : void 0;
+      if (!flowName) {
+        return { success: false, error: `map '${node.id}': config.flowName (the per-item subflow) is required` };
+      }
+      const iteratorVariable = typeof cfg.iteratorVariable === "string" && cfg.iteratorVariable ? cfg.iteratorVariable : "item";
+      const indexVariable = typeof cfg.indexVariable === "string" && cfg.indexVariable ? cfg.indexVariable : void 0;
+      const outVar = typeof cfg.outputVariable === "string" && cfg.outputVariable ? cfg.outputVariable : void 0;
+      const rawCollection = cfg.collection;
+      let collection;
+      if (Array.isArray(rawCollection)) {
+        collection = rawCollection;
+      } else if (typeof rawCollection === "string") {
+        collection = interpolate(rawCollection, variables, context ?? {});
+        if (collection == null && variables.has(rawCollection)) collection = variables.get(rawCollection);
+      }
+      if (!Array.isArray(collection)) {
+        return { success: false, error: `map '${node.id}': collection '${String(rawCollection)}' did not resolve to an array` };
+      }
+      if (collection.length > MAX_MAP_ITEMS) {
+        return { success: false, error: `map '${node.id}': collection length ${collection.length} exceeds the ${MAX_MAP_ITEMS} cap` };
+      }
+      const stateKey = `${node.id}.$mapState`;
+      const state = variables.get(stateKey) ?? {
+        started: 0,
+        results: []
+      };
+      if (variables.get(`${node.id}.$mapItemDone`) === true) {
+        state.results.push(variables.get(`${node.id}.$mapItemOutput`) ?? null);
+        variables.delete(`${node.id}.$mapItemDone`);
+        variables.delete(`${node.id}.$mapItemOutput`);
+      }
+      const parentRunId = variables.get("$runId");
+      while (state.started < collection.length) {
+        const idx = state.started;
+        const item = collection[idx];
+        variables.set(iteratorVariable, item);
+        if (indexVariable) variables.set(indexVariable, idx);
+        const rawInput = cfg.input && typeof cfg.input === "object" ? cfg.input : {};
+        const params = interpolate(rawInput, variables, context ?? {});
+        const itemIsRecord = item != null && typeof item === "object" && typeof item.id === "string";
+        const itemObject = typeof cfg.itemObject === "string" ? cfg.itemObject : context?.object;
+        const childContext = {
+          ...context ?? {},
+          params,
+          ...itemIsRecord ? { record: item, object: itemObject } : {},
+          ...parentRunId != null ? { $parentRunId: String(parentRunId), $parentMapNode: node.id } : {}
+        };
+        const child = await engine.execute(flowName, childContext);
+        if (child.status === "paused") {
+          if (!child.runId) {
+            return { success: false, error: `map '${node.id}': item ${idx} paused without a run id \u2014 cannot link the runs` };
+          }
+          state.started = idx + 1;
+          variables.set(stateKey, state);
+          return { success: true, suspend: true, correlation: `map:${child.runId}` };
+        }
+        if (!child.success) {
+          return { success: false, error: `map '${node.id}': item ${idx} (subflow '${flowName}') failed: ${child.error ?? "unknown error"}` };
+        }
+        state.started = idx + 1;
+        state.results.push(child.output ?? null);
+      }
+      variables.set(stateKey, state);
+      if (outVar) variables.set(outVar, state.results);
+      return { success: true, output: { results: state.results, count: state.results.length } };
+    }
+  });
+  ctx.logger.info("[Map Node] 1 built-in node executor registered");
+}
+
 // src/builtin/index.ts
 function installBuiltinNodes(engine, ctx) {
   registerLogicNodes(engine, ctx);
@@ -2624,6 +2913,7 @@ function installBuiltinNodes(engine, ctx) {
   registerNotifyNode(engine, ctx);
   registerWaitNode(engine, ctx);
   registerSubflowNode(engine, ctx);
+  registerMapNode(engine, ctx);
   const types = engine.getRegisteredNodeTypes();
   ctx.logger.info(
     `[Automation] ${types.length} built-in node executors installed: ${types.join(", ")}`
@@ -2672,9 +2962,8 @@ var AutomationServicePlugin = class {
     ctx.logger.info("[Automation] Engine initialized");
   }
   async start(ctx) {
-    console.warn("[Automation:start] entering start()");
     if (!this.engine) {
-      console.warn("[Automation:start] engine missing, bailing");
+      ctx.logger.warn("[Automation] start() called before init() \u2014 engine missing, skipping");
       return;
     }
     await ctx.trigger("automation:ready", this.engine);
@@ -2682,6 +2971,7 @@ var AutomationServicePlugin = class {
     ctx.logger.info(
       `[Automation] Engine started with ${nodeTypes.length} node types: ${nodeTypes.join(", ") || "(none)"}`
     );
+    let durableStore = null;
     if ((this.options.suspendedRunStore ?? "auto") !== "memory") {
       let dataEngine = null;
       try {
@@ -2693,7 +2983,8 @@ var AutomationServicePlugin = class {
         }
       }
       if (dataEngine && typeof dataEngine.find === "function" && typeof dataEngine.insert === "function") {
-        this.engine.setSuspendedRunStore(new ObjectStoreSuspendedRunStore(dataEngine, ctx.logger));
+        durableStore = new ObjectStoreSuspendedRunStore(dataEngine, ctx.logger);
+        this.engine.setSuspendedRunStore(durableStore);
         ctx.logger.info("[Automation] Suspended-run persistence enabled (sys_automation_run)");
       } else {
         ctx.logger.info("[Automation] No ObjectQL engine \u2014 suspended runs kept in-memory only");
@@ -2702,14 +2993,14 @@ var AutomationServicePlugin = class {
     try {
       const ql = ctx.getService("objectql");
       if (!ql) {
-        console.warn("[Automation] objectql service not found at start()");
+        ctx.logger.debug("[Automation] objectql service not found at start()");
       } else if (!ql.registry) {
-        console.warn("[Automation] objectql.registry is undefined at start()");
+        ctx.logger.debug("[Automation] objectql.registry is undefined at start()");
       } else if (typeof ql.registry.listItems !== "function") {
-        console.warn("[Automation] objectql.registry.listItems is not a function");
+        ctx.logger.debug("[Automation] objectql.registry.listItems is not a function");
       }
       const flows = ql?.registry?.listItems?.("flow") ?? [];
-      console.warn(`[Automation] flow pull: registry returned ${flows.length} flow(s)`);
+      ctx.logger.debug(`[Automation] flow pull: registry returned ${flows.length} flow(s)`);
       let registered = 0;
       for (const f of flows) {
         const def = f;
@@ -2729,6 +3020,21 @@ var AutomationServicePlugin = class {
       const msg = err instanceof Error ? err.message : String(err);
       ctx.logger.warn(`[Automation] flow pull from ObjectQL registry failed: ${msg}`);
     }
+    if (durableStore) {
+      let job;
+      try {
+        job = ctx.getService("job");
+      } catch {
+      }
+      try {
+        const rearmed = await rearmSuspendedWaitTimers(this.engine, durableStore, job, ctx.logger);
+        if (rearmed > 0) {
+          ctx.logger.info(`[Automation] Re-armed ${rearmed} suspended wait timer(s) after restart`);
+        }
+      } catch (err) {
+        ctx.logger.warn(`[Automation] wait-timer re-arm failed: ${err.message}`);
+      }
+    }
   }
   async destroy() {
     this.engine = void 0;