@objectstack/service-automation 8.0.1 → 9.0.0

package/dist/index.d.cts

@@ -438,8 +438,50 @@ declare class AutomationEngine implements IAutomationService {
      * 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).
      */
     resume(runId: string, signal?: ResumeSignal): Promise<AutomationResult>;
+    /**
+     * @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.
+     */
+    private resumeInternal;
+    /**
+     * 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`).
+     */
+    private buildSubflowResumeSignal;
+    /**
+     * 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.
+     */
+    private bubbleToParent;
+    /**
+     * 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.
+     */
+    private failSuspendedRun;
+    /**
+     * Walk a failed run's `$parentRunId` chain and fail each suspended
+     * ancestor (see {@link failSuspendedRun}). Bounded so a corrupt context
+     * can't loop forever.
+     */
+    private failAncestors;
     /**
      * List the runs currently suspended awaiting {@link resume} (ADR-0019).
      * Backs operability surfaces such as a "pending approvals" view.
@@ -1146,10 +1188,9 @@ declare const SysAutomationRun: Omit<{
         } | undefined;
         chart?: {
             chartType: "bar" | "line" | "pie" | "area" | "scatter";
-            xAxisField: string;
-            yAxisFields: string[];
-            aggregation?: "min" | "max" | "count" | "sum" | "avg" | undefined;
-            groupByField?: string | undefined;
+            dataset: string;
+            values: string[];
+            dimensions?: string[] | undefined;
         } | undefined;
         description?: string | undefined;
         sharing?: {

package/dist/index.d.ts

@@ -438,8 +438,50 @@ declare class AutomationEngine implements IAutomationService {
      * 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).
      */
     resume(runId: string, signal?: ResumeSignal): Promise<AutomationResult>;
+    /**
+     * @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.
+     */
+    private resumeInternal;
+    /**
+     * 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`).
+     */
+    private buildSubflowResumeSignal;
+    /**
+     * 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.
+     */
+    private bubbleToParent;
+    /**
+     * 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.
+     */
+    private failSuspendedRun;
+    /**
+     * Walk a failed run's `$parentRunId` chain and fail each suspended
+     * ancestor (see {@link failSuspendedRun}). Bounded so a corrupt context
+     * can't loop forever.
+     */
+    private failAncestors;
     /**
      * List the runs currently suspended awaiting {@link resume} (ADR-0019).
      * Backs operability surfaces such as a "pending approvals" view.
@@ -1146,10 +1188,9 @@ declare const SysAutomationRun: Omit<{
         } | undefined;
         chart?: {
             chartType: "bar" | "line" | "pie" | "area" | "scatter";
-            xAxisField: string;
-            yAxisFields: string[];
-            aggregation?: "min" | "max" | "count" | "sum" | "avg" | undefined;
-            groupByField?: string | undefined;
+            dataset: string;
+            values: string[];
+            dimensions?: string[] | undefined;
         } | undefined;
         description?: string | undefined;
         sharing?: {

package/dist/index.js

@@ -580,8 +580,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` };
     }
@@ -608,6 +624,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) {
@@ -647,6 +692,9 @@ var AutomationEngine = class {
           steps,
           output
         });
+        if (!skipBubble) {
+          await this.bubbleToParent(run, output);
+        }
         return { success: true, output, durationMs };
       } catch (err) {
         if (isSuspendSignal(err)) {
@@ -693,12 +741,92 @@ 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 parentRunId = run.context?.$parentRunId;
+    if (typeof parentRunId !== "string" || !parentRunId) return;
+    try {
+      const sig = 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.
@@ -2470,10 +2598,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 {
@@ -2485,7 +2614,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))`
@@ -2496,7 +2625,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 };
@@ -2504,6 +2633,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;
@@ -2535,7 +2712,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 ?? {};
@@ -2552,22 +2732,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 } };
     }
@@ -2636,9 +2827,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);
@@ -2646,6 +2836,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 {
@@ -2657,7 +2848,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");
@@ -2666,14 +2858,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;
@@ -2693,6 +2885,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;