@kb-labs/workflow-engine 2.116.14 → 2.117.0

package/dist/index.d.ts

@@ -225,6 +225,19 @@ declare class WorkflowEngine {
     runFromInline(spec: unknown, input: Omit<CreateRunInput, 'spec'>): Promise<WorkflowRun>;
     getRun(runId: string): Promise<WorkflowRun | null>;
     cancelRun(runId: string): Promise<void>;
+    /**
+     * Reconcile all persisted parent/child links. This is deliberately engine-side
+     * instead of a worker-local polling task: it is safe to call after a daemon
+     * restart and is idempotent when several reconciliations race.
+     */
+    reconcileChildInvocations(): Promise<number>;
+    /** Run reconciliation on terminal-child events; startup calls it once too. */
+    reconcileChildInvocation(childRunId: string): Promise<number>;
+    private childResultEnvelope;
+    private resolveDeclaredOutputs;
+    private failChildInvocation;
+    private listStoredRuns;
+    private findChildRuns;
     /**
      * Mark job as failed and optionally schedule retry.
      * Implements exponential/linear backoff retry logic.
@@ -281,6 +294,13 @@ declare class WorkflowEngine {
      * Mark step as waiting for human approval.
      */
     markStepWaitingApproval(runId: string, jobId: string, stepId: string): Promise<void>;
+    /**
+     * Park a step while its child workflow runs. The worker returns after this
+     * transition, so parent workflows never consume the pool needed by children.
+     */
+    markStepWaitingChild(runId: string, jobId: string, stepId: string, childRunId: string): Promise<void>;
+    /** Re-queue a parked parent job after its child workflow reaches a terminal state. */
+    resumeJob(runId: string, jobId: string): Promise<void>;
     /**
      * Resolve a pending approval — approve or reject.
      * On approve: marks step as success with approval outputs.

package/dist/index.js

@@ -1,7 +1,7 @@
 import { readFile, access, mkdir, writeFile, readdir } from 'fs/promises';
 import { resolve, join, basename } from 'path';
 import { parse, stringify } from 'yaml';
-import { WorkflowSpecSchema, evaluateExpression } from '@kb-labs/workflow-contracts';
+import { WorkflowSpecSchema, resolveExpression, evaluateExpression } from '@kb-labs/workflow-contracts';
 import { randomUUID } from 'crypto';
 import { WORKFLOW_REDIS_CHANNEL, EVENT_NAMES, IDEMPOTENCY_TTL_ENV, CONCURRENCY_TTL_ENV } from '@kb-labs/workflow-constants';
 import { classifyFailure, decideRetry } from '@kb-labs/core-retry';
@@ -79,6 +79,7 @@ ${issues}`);
 };
 
 // src/state-store.ts
+var RUN_TTL_MS = 24 * 60 * 60 * 1e3;
 var StateStore = class {
   constructor(cache, logger) {
     this.logger = logger;
@@ -89,7 +90,7 @@ var StateStore = class {
   async saveRun(run) {
     const key = `kb:run:${run.id}`;
     this.logger.debug("Persisting workflow run", { runId: run.id, key });
-    await this.cache.set(key, JSON.stringify(run));
+    await this.cache.set(key, JSON.stringify(run), RUN_TTL_MS);
     const timestamp = new Date(run.createdAt).getTime();
     await this.cache.zadd("workflow:runs:index", timestamp, run.id);
   }
@@ -330,7 +331,7 @@ var RunCoordinator = class {
       createdAt: timestamp,
       queuedAt: timestamp,
       trigger: input.trigger,
-      env: input.spec.env,
+      env: input.env ?? input.spec.env,
       inputs: input.inputs,
       secrets: input.spec.secrets,
       jobs,
@@ -338,7 +339,9 @@ var RunCoordinator = class {
         idempotencyKey: input.idempotencyKey,
         concurrencyGroup: input.concurrencyGroup,
         target: input.spec.target,
-        isolation: input.spec.isolation
+        isolation: input.spec.isolation,
+        outputDeclarations: input.spec.outputs,
+        ...input.metadata
       },
       artifacts: []
     };
@@ -774,6 +777,9 @@ var WorkflowEngine = class {
   }
   async cancelRun(runId) {
     const run = await this.getRun(runId);
+    if (!run || ["success", "failed", "cancelled", "skipped", "dlq"].includes(run.status)) {
+      return;
+    }
     await this.stateStore.updateRun(runId, (draft) => {
       draft.status = "cancelled";
       draft.finishedAt = (/* @__PURE__ */ new Date()).toISOString();
@@ -790,6 +796,112 @@ var WorkflowEngine = class {
       runId,
       payload: { reason: "cancelled by parent workflow" }
     });
+    const descendants = await this.findChildRuns(runId);
+    await Promise.all(descendants.map((child) => this.cancelRun(child.id)));
+    await this.reconcileChildInvocation(runId);
+  }
+  /**
+   * Reconcile all persisted parent/child links. This is deliberately engine-side
+   * instead of a worker-local polling task: it is safe to call after a daemon
+   * restart and is idempotent when several reconciliations race.
+   */
+  async reconcileChildInvocations() {
+    const runs = await this.listStoredRuns();
+    let reconciled = 0;
+    for (const parent of runs) {
+      for (const job of parent.jobs) {
+        for (const step of job.steps) {
+          if (step.status !== "waiting_child") {
+            continue;
+          }
+          const childRunId = step.metadata?.["childRunId"];
+          if (typeof childRunId !== "string") {
+            continue;
+          }
+          const child = await this.getRun(childRunId);
+          if (parent.status === "cancelled") {
+            if (child) {
+              await this.cancelRun(child.id);
+            }
+            continue;
+          }
+          if (!child) {
+            await this.failChildInvocation(parent.id, job.id, step.id, childRunId, "not found");
+            reconciled++;
+            continue;
+          }
+          if (!["success", "failed", "cancelled", "skipped", "dlq"].includes(child.status)) {
+            continue;
+          }
+          if (child.status === "success") {
+            const outputs = this.childResultEnvelope(child);
+            await this.markStepCompleted(parent.id, job.id, step.id, outputs);
+            await this.resumeJob(parent.id, job.id);
+          } else {
+            await this.failChildInvocation(parent.id, job.id, step.id, child.id, child.status);
+          }
+          reconciled++;
+        }
+      }
+    }
+    return reconciled;
+  }
+  /** Run reconciliation on terminal-child events; startup calls it once too. */
+  async reconcileChildInvocation(childRunId) {
+    const parents = (await this.listStoredRuns()).filter(
+      (run) => run.jobs.some((job) => job.steps.some(
+        (step) => step.status === "waiting_child" && step.metadata?.["childRunId"] === childRunId
+      ))
+    );
+    if (parents.length === 0) {
+      return 0;
+    }
+    return this.reconcileChildInvocations();
+  }
+  childResultEnvelope(child) {
+    const stepOutputs = {};
+    for (const job of child.jobs) {
+      for (const step of job.steps) {
+        if (step.status === "success" && step.spec.id && step.outputs) {
+          stepOutputs[step.spec.id] = step.outputs;
+        }
+      }
+    }
+    return {
+      runId: child.id,
+      status: child.status,
+      outputs: Object.keys(child.result?.outputs ?? {}).length > 0 ? child.result?.outputs : stepOutputs,
+      artifacts: child.artifacts ?? []
+    };
+  }
+  resolveDeclaredOutputs(run) {
+    const declarations = run.metadata?.outputDeclarations;
+    if (!declarations) {
+      return {};
+    }
+    const context = this.buildExpressionContext(run);
+    return Object.fromEntries(Object.entries(declarations).map(([name, declaration]) => {
+      const source = declaration && typeof declaration === "object" ? declaration.source : void 0;
+      return [name, typeof source === "string" ? resolveExpression(source, context) : void 0];
+    }));
+  }
+  async failChildInvocation(parentRunId, parentJobId, parentStepId, childRunId, childStatus) {
+    const error = new Error(`Child workflow ${childStatus} (run ${childRunId})`);
+    await this.markStepFailed(parentRunId, parentJobId, parentStepId, error, {
+      runId: childRunId,
+      status: childStatus
+    });
+    await this.markJobFailed(parentRunId, parentJobId, error, void 0, false);
+  }
+  async listStoredRuns() {
+    const runIds = await this.stateStore.getAllRunIds();
+    const runs = await Promise.all([...new Set(runIds)].map((id) => this.getRun(id)));
+    return runs.filter((run) => run !== null);
+  }
+  async findChildRuns(parentRunId) {
+    return (await this.listStoredRuns()).filter(
+      (run) => run.trigger.parentRunId === parentRunId || run.metadata?.parentRunId === parentRunId
+    );
   }
   /**
    * Mark job as failed and optionally schedule retry.
@@ -1055,6 +1167,11 @@ var WorkflowEngine = class {
       const updated = await this.stateStore.updateRun(runId, (draft) => {
         draft.status = "success";
         draft.finishedAt = (/* @__PURE__ */ new Date()).toISOString();
+        draft.result = {
+          ...draft.result ?? { status: "success" },
+          status: "success",
+          outputs: this.resolveDeclaredOutputs(draft)
+        };
         return draft;
       });
       this.logger.info("Workflow run completed successfully", { runId });
@@ -1073,6 +1190,7 @@ var WorkflowEngine = class {
       if (updated) {
         await this.snapshotTerminalRun(updated);
       }
+      await this.reconcileChildInvocation(runId);
     } else if (anyFailed) {
       const failedJob = run.jobs.find((j) => j.status === "failed");
       const updated = await this.stateStore.updateRun(runId, (draft) => {
@@ -1106,6 +1224,7 @@ var WorkflowEngine = class {
       if (updated) {
         await this.snapshotTerminalRun(updated);
       }
+      await this.reconcileChildInvocation(runId);
     }
   }
   /**
@@ -1183,6 +1302,34 @@ var WorkflowEngine = class {
     });
     this.logger.info("Step waiting for approval", { runId, jobId, stepId });
   }
+  /**
+   * Park a step while its child workflow runs. The worker returns after this
+   * transition, so parent workflows never consume the pool needed by children.
+   */
+  async markStepWaitingChild(runId, jobId, stepId, childRunId) {
+    await this.stateStore.updateStep(runId, jobId, stepId, (draft) => {
+      draft.status = "waiting_child";
+      draft.startedAt ??= (/* @__PURE__ */ new Date()).toISOString();
+      draft.metadata = { ...draft.metadata ?? {}, childRunId };
+    });
+    await this.events.publish({
+      type: EVENT_NAMES.step.waitingChild,
+      runId,
+      jobId,
+      stepId,
+      payload: { childRunId }
+    });
+  }
+  /** Re-queue a parked parent job after its child workflow reaches a terminal state. */
+  async resumeJob(runId, jobId) {
+    const job = await this.stateStore.updateJob(runId, jobId, (draft) => {
+      draft.status = "queued";
+      draft.finishedAt = void 0;
+    });
+    if (job) {
+      await this.scheduler.enqueueJob(runId, job, job.priority ?? "normal");
+    }
+  }
   /**
    * Resolve a pending approval — approve or reject.
    * On approve: marks step as success with approval outputs.
@@ -1245,6 +1392,10 @@ var WorkflowEngine = class {
     const runIds = await this.stateStore.getAllRunIds();
     const now = (/* @__PURE__ */ new Date()).toISOString();
     let count = 0;
+    const runs = await this.listStoredRuns();
+    const protectedChildRunIds = new Set(
+      runs.flatMap((run) => run.jobs.flatMap((job) => job.steps.filter((step) => step.status === "waiting_child").map((step) => step.metadata?.["childRunId"]).filter((id) => typeof id === "string")))
+    );
     await Promise.all(
       runIds.map(async (runId) => {
         const run = await this.stateStore.getRun(runId);
@@ -1254,6 +1405,30 @@ var WorkflowEngine = class {
         if (run.status !== "running" && run.status !== "queued") {
           return;
         }
+        if (run.jobs.some((job) => job.steps.some((step) => step.status === "waiting_child"))) {
+          return;
+        }
+        if (protectedChildRunIds.has(run.id)) {
+          const hasRunningJob = run.jobs.some((job) => job.status === "running");
+          if (hasRunningJob) {
+            await this.stateStore.updateRun(runId, (draft) => {
+              for (const job of draft.jobs) {
+                if (job.status === "running") {
+                  job.status = "interrupted";
+                  job.finishedAt = now;
+                  for (const step of job.steps) {
+                    if (step.status === "running") {
+                      step.status = "queued";
+                      step.startedAt = void 0;
+                      step.finishedAt = void 0;
+                    }
+                  }
+                }
+              }
+            });
+          }
+          return;
+        }
         await this.stateStore.updateRun(runId, (draft) => {
           draft.status = "failed";
           draft.finishedAt = now;