@solidxai/core 0.1.13-beta.3 → 0.1.13-beta.4

package/src/services/workflow/workflow-runtime.service.ts

@@ -161,7 +161,11 @@ export class WorkflowRuntimeService {
     const execution = existingExecution
       ? await this.writer.startExecution(existingExecution, effectiveRequest)
       : await this.writer.createExecution(definition, effectiveRequest);
-    const nodeCount = this.countNodes(definitionDsl.nodes);
+    const nodeCount = this.countNodes([
+      ...(definitionDsl.nodes ?? []),
+      ...(definitionDsl.errors ?? []),
+      ...(definitionDsl.finally ?? []),
+    ]);
     const outputs: Record<string, any> = {};
     const runtimeContext: WorkflowRuntimeContext = {
       execution,
@@ -175,26 +179,52 @@ export class WorkflowRuntimeService {
       },
     };
 
+    this.logger.log(
+      `Starting workflow execution ${execution.executionIdentifier} for ${definition.key} with ${nodeCount} node(s).`,
+    );
+    await this.writer.writeLog(execution, undefined, {
+      level: 'info',
+      eventType: 'execution.started',
+      message: `Workflow execution started for ${definition.key}.`,
+      metadata: {
+        executionIdentifier: execution.executionIdentifier,
+        workflowKey: definition.key,
+        triggerType: execution.triggerType,
+        nodeCount,
+        inputKeys: Object.keys(runtimeContext.input ?? {}),
+        variableKeys: Object.keys(runtimeContext.variables ?? {}),
+      },
+    }, this.nextLogSequence(runtimeContext));
+
+    let executionError: unknown;
+
     try {
-      this.logger.log(
-        `Starting workflow execution ${execution.executionIdentifier} for ${definition.key} with ${nodeCount} node(s).`,
-      );
+      await this.runNodes(definitionDsl.nodes, runtimeContext);
+    } catch (error) {
+      executionError = error;
+      await this.runGlobalErrorHandlers(definitionDsl, runtimeContext, error);
+    }
+
+    try {
+      await this.runFinallyHandlers(definitionDsl, runtimeContext);
+    } catch (finallyError) {
       await this.writer.writeLog(execution, undefined, {
-        level: 'info',
-        eventType: 'execution.started',
-        message: `Workflow execution started for ${definition.key}.`,
+        level: 'error',
+        eventType: 'finally.failed',
+        message: `Finally handler failed: ${this.errorMessage(finallyError)}.`,
+        context: this.summarizeError(finallyError),
         metadata: {
-          executionIdentifier: execution.executionIdentifier,
-          workflowKey: definition.key,
-          triggerType: execution.triggerType,
-          nodeCount,
-          inputKeys: Object.keys(runtimeContext.input ?? {}),
-          variableKeys: Object.keys(runtimeContext.variables ?? {}),
+          originalError: executionError
+            ? this.summarizeError(executionError)
+            : undefined,
         },
       }, this.nextLogSequence(runtimeContext));
+      if (!executionError) {
+        executionError = finallyError;
+      }
+    }
 
-      await this.runNodes(definitionDsl.nodes, runtimeContext);
-
+    if (!executionError) {
       const completed = await this.writer.completeExecution(execution, outputs);
 
       this.logger.log(
@@ -212,26 +242,26 @@ export class WorkflowRuntimeService {
       }, this.nextLogSequence(runtimeContext));
 
       return this.toResponse(completed);
-    } catch (error) {
-      const failed = await this.writer.failExecution(execution, error);
+    }
 
-      this.logger.error(
-        `Failed workflow execution ${failed.executionIdentifier} for ${definition.key}: ${failed.errorSummary}`,
-        error instanceof Error ? error.stack : undefined,
-      );
-      await this.writer.writeLog(failed, undefined, {
-        level: 'error',
-        eventType: 'execution.failed',
-        message: failed.errorSummary,
-        context: this.summarizeError(error),
-        metadata: {
-          executionIdentifier: failed.executionIdentifier,
-          durationMs: failed.durationMs,
-        },
-      }, this.nextLogSequence(runtimeContext));
+    const failed = await this.writer.failExecution(execution, executionError);
 
-      return this.toResponse(failed);
-    }
+    this.logger.error(
+      `Failed workflow execution ${failed.executionIdentifier} for ${definition.key}: ${failed.errorSummary}`,
+      executionError instanceof Error ? executionError.stack : undefined,
+    );
+    await this.writer.writeLog(failed, undefined, {
+      level: 'error',
+      eventType: 'execution.failed',
+      message: failed.errorSummary,
+      context: this.summarizeError(executionError),
+      metadata: {
+        executionIdentifier: failed.executionIdentifier,
+        durationMs: failed.durationMs,
+      },
+    }, this.nextLogSequence(runtimeContext));
+
+    return this.toResponse(failed);
   }
 
   async getExecutionStatus(executionId: number): Promise<WorkflowExecutionResponse> {
@@ -363,17 +393,19 @@ export class WorkflowRuntimeService {
     nodes: WorkflowNodeDefinition[],
     context: WorkflowRuntimeContext,
   ): Promise<Record<string, any>> {
+    const nodeOutputs: Record<string, any> = {};
+
     for (const node of nodes ?? []) {
-      await this.runNode(node, context);
+      nodeOutputs[node.id] = await this.runNode(node, context);
     }
 
-    return context.outputs;
+    return nodeOutputs;
   }
 
   private async runNode(
     node: WorkflowNodeDefinition,
     context: WorkflowRuntimeContext,
-  ): Promise<void> {
+  ): Promise<Record<string, any>> {
     const inputPayload = {
       configuration: node.configuration,
       input: context.input,
@@ -400,7 +432,7 @@ export class WorkflowRuntimeService {
         message: `Skipped disabled node ${node.id}.`,
         metadata: this.nodeLogMetadata(node, context, step),
       }, this.nextLogSequence(context));
-      return;
+      return context.outputs[node.id];
     }
 
     try {
@@ -444,7 +476,7 @@ export class WorkflowRuntimeService {
       });
 
       const output = result.output ?? {};
-      context.outputs[node.id] = output;
+      context.outputs[node.id] = this.getRuntimeContextOutput(node, output);
 
       for (const artifact of result.artifacts ?? []) {
         await this.writer.writeArtifact(context.execution, step, artifact);
@@ -472,6 +504,8 @@ export class WorkflowRuntimeService {
           artifactCount: result.artifacts?.length ?? 0,
         },
       }, this.nextLogSequence(context));
+
+      return output;
     } catch (error) {
       await this.writer.failStep(step, error);
 
@@ -486,7 +520,7 @@ export class WorkflowRuntimeService {
           context: this.summarizeError(error),
           metadata: this.nodeLogMetadata(node, context, step),
         }, this.nextLogSequence(context));
-        return;
+        return context.outputs[node.id];
       }
 
       await this.writer.writeLog(context.execution, step, {
@@ -496,10 +530,158 @@ export class WorkflowRuntimeService {
         context: this.summarizeError(error),
         metadata: this.nodeLogMetadata(node, context, step),
       }, this.nextLogSequence(context));
+      await this.runLocalErrorHandlers(node, context, error);
       throw error;
     }
   }
 
+  private async runGlobalErrorHandlers(
+    definitionDsl: WorkflowDefinitionDsl,
+    context: WorkflowRuntimeContext,
+    error: unknown,
+  ): Promise<void> {
+    const errorNodes = definitionDsl.errors ?? [];
+    if (!errorNodes.length) {
+      return;
+    }
+
+    await this.runErrorHandlers(
+      errorNodes,
+      context,
+      error,
+      'global',
+      undefined,
+      undefined,
+    );
+  }
+
+  private async runFinallyHandlers(
+    definitionDsl: WorkflowDefinitionDsl,
+    context: WorkflowRuntimeContext,
+  ): Promise<void> {
+    const finallyNodes = definitionDsl.finally ?? [];
+    if (!finallyNodes.length) {
+      return;
+    }
+
+    await this.writer.writeLog(context.execution, undefined, {
+      level: 'info',
+      eventType: 'finally.started',
+      message: 'Running workflow finally handlers.',
+      metadata: {
+        handlerNodeCount: finallyNodes.length,
+      },
+    }, this.nextLogSequence(context));
+
+    await this.runNodes(finallyNodes, context);
+
+    await this.writer.writeLog(context.execution, undefined, {
+      level: 'info',
+      eventType: 'finally.completed',
+      message: 'Workflow finally handlers completed.',
+      metadata: {
+        handlerNodeCount: finallyNodes.length,
+      },
+    }, this.nextLogSequence(context));
+  }
+
+  private async runLocalErrorHandlers(
+    node: WorkflowNodeDefinition,
+    context: WorkflowRuntimeContext,
+    error: unknown,
+  ): Promise<void> {
+    const errorNodes = node.errors ?? [];
+    if (!errorNodes.length) {
+      return;
+    }
+
+    await this.runErrorHandlers(
+      errorNodes,
+      context,
+      error,
+      'local',
+      node.id,
+      context.stepExecution?.stepExecutionKey,
+    );
+  }
+
+  private async runErrorHandlers(
+    errorNodes: WorkflowNodeDefinition[],
+    context: WorkflowRuntimeContext,
+    error: unknown,
+    scope: 'global' | 'local',
+    sourceNodeId?: string,
+    sourceStepExecutionKey?: string,
+  ): Promise<void> {
+    const errorContext = this.buildErrorContext(error, sourceNodeId, sourceStepExecutionKey);
+
+    await this.writer.writeLog(context.execution, undefined, {
+      level: 'warn',
+      eventType: `error-handler.${scope}.started`,
+      message:
+        scope === 'global'
+          ? 'Running workflow-level error handlers.'
+          : `Running local error handlers for node ${sourceNodeId}.`,
+      context: errorContext,
+      metadata: {
+        sourceNodeId,
+        sourceStepExecutionKey,
+        handlerNodeCount: errorNodes.length,
+      },
+    }, this.nextLogSequence(context));
+
+    try {
+      await this.runNodes(errorNodes, {
+        ...context,
+        error: errorContext,
+        parentNodeId: sourceNodeId ?? context.parentNodeId,
+        parentStepExecutionKey:
+          sourceStepExecutionKey ?? context.parentStepExecutionKey,
+      });
+    } catch (handlerError) {
+      await this.writer.writeLog(context.execution, undefined, {
+        level: 'error',
+        eventType: `error-handler.${scope}.failed`,
+        message: `Error handler failed: ${this.errorMessage(handlerError)}.`,
+        context: this.summarizeError(handlerError),
+        metadata: {
+          originalError: errorContext,
+          sourceNodeId,
+          sourceStepExecutionKey,
+        },
+      }, this.nextLogSequence(context));
+      return;
+    }
+
+    await this.writer.writeLog(context.execution, undefined, {
+      level: 'info',
+      eventType: `error-handler.${scope}.completed`,
+      message:
+        scope === 'global'
+          ? 'Workflow-level error handlers completed.'
+          : `Local error handlers completed for node ${sourceNodeId}.`,
+      context: errorContext,
+      metadata: {
+        sourceNodeId,
+        sourceStepExecutionKey,
+      },
+    }, this.nextLogSequence(context));
+  }
+
+  private buildErrorContext(
+    error: unknown,
+    nodeId?: string,
+    stepExecutionKey?: string,
+  ): Record<string, any> {
+    const summary = this.summarizeError(error);
+    return {
+      ...summary,
+      message: this.errorMessage(error),
+      nodeId,
+      stepExecutionKey,
+    };
+  }
+
   private assertDefinitionYaml(value: any): WorkflowDefinitionDsl {
     if (!value || typeof value !== 'string') {
       throw new BadRequestException(
@@ -627,6 +809,7 @@ export class WorkflowRuntimeService {
         ...(node.then ?? []),
         ...(node.else ?? []),
         ...(node.defaults ?? []),
+        ...(node.errors ?? []),
         ...Object.values(node.cases ?? {}).flat(),
       ];
 
@@ -660,6 +843,58 @@ export class WorkflowRuntimeService {
     };
   }
 
+  private getRuntimeContextOutput(
+    node: WorkflowNodeDefinition,
+    output: Record<string, any>,
+  ): Record<string, any> {
+    const hiddenOutputPaths =
+      this.registry
+        .getMetadata(node.type)
+        .authoring?.outputs?.filter(
+          (definition) => definition.includeInRuntimeContext === false,
+        )
+        .map((definition) => definition.path ?? definition.key)
+        .filter(Boolean) ?? [];
+
+    if (!hiddenOutputPaths.length || !output || typeof output !== 'object') {
+      return output;
+    }
+
+    const runtimeOutput = this.cloneOutput(output);
+    hiddenOutputPaths.forEach((path) => {
+      this.deletePath(runtimeOutput, path);
+    });
+
+    return runtimeOutput;
+  }
+
+  private cloneOutput(output: Record<string, any>): Record<string, any> {
+    if (typeof structuredClone === 'function') {
+      return structuredClone(output);
+    }
+
+    return JSON.parse(JSON.stringify(output));
+  }
+
+  private deletePath(target: Record<string, any>, path: string) {
+    const parts = path.split('.').filter(Boolean);
+    if (!parts.length) {
+      return;
+    }
+
+    let cursor: any = target;
+    for (let index = 0; index < parts.length - 1; index += 1) {
+      cursor = cursor?.[parts[index]];
+      if (!cursor || typeof cursor !== 'object') {
+        return;
+      }
+    }
+
+    if (cursor && typeof cursor === 'object') {
+      delete cursor[parts[parts.length - 1]];
+    }
+  }
+
   private summarizeValue(value: any): any {
     if (Array.isArray(value)) {
       return {

package/src/solid-core.module.ts

@@ -441,10 +441,12 @@ import { WorkflowInvocationService } from './services/workflow/workflow-invocati
 import { WorkflowNodeRegistryService } from './services/workflow/workflow-node-registry.service';
 import { WorkflowRuntimeService } from './services/workflow/workflow-runtime.service';
 import { WorkflowScheduledTriggerJobService } from './services/workflow/workflow-scheduled-trigger.job';
+import { ExecutionFailNode } from './services/workflow/nodes/execution-fail.node';
 import { ForEachNode } from './services/workflow/nodes/for-each.node';
 import { HttpRequestNode } from './services/workflow/nodes/http-request.node';
 import { IfNode } from './services/workflow/nodes/if.node';
 import { LogWriteNode } from './services/workflow/nodes/log-write.node';
+import { LoopUntilNode } from './services/workflow/nodes/loop-until.node';
 import { ParallelNode } from './services/workflow/nodes/parallel.node';
 import { RuntimePythonNode } from './services/workflow/nodes/runtime-python.node';
 import { SequentialNode } from './services/workflow/nodes/sequential.node';
@@ -947,10 +949,12 @@ import { SwitchNode } from './services/workflow/nodes/switch.node';
     WorkflowDefinitionValidatorService,
     WorkflowNodeRegistryService,
     WorkflowScheduledTriggerJobService,
+    ExecutionFailNode,
     LogWriteNode,
     HttpRequestNode,
     IfNode,
     ForEachNode,
+    LoopUntilNode,
     ParallelNode,
     RuntimePythonNode,
     SequentialNode,

package/src/types/workflow-dsl.types.ts

@@ -200,6 +200,9 @@ export interface WorkflowNodeDefinition {
   /** Child nodes executed when no `switch.cases` entry matches the switch value. */
   defaults?: WorkflowNodeDefinition[];
 
+  /** Child nodes executed when this node or its child subtree fails. */
+  errors?: WorkflowNodeDefinition[];
+
   /**
    * Named child-node collections for `switch`.
    *
@@ -287,6 +290,12 @@ export interface WorkflowDefinitionDsl {
   /** Optional workflow triggers that can create executions. */
   triggers?: WorkflowTriggerDefinition[];
 
+  /** Workflow-level error handler nodes executed sequentially when execution fails. */
+  errors?: WorkflowNodeDefinition[];
+
+  /** Workflow-level cleanup nodes executed sequentially after success or failure. */
+  finally?: WorkflowNodeDefinition[];
+
   /** Workflow-level custom annotations for tooling. */
   metadata?: Record<string, any>;
 }
@@ -578,6 +587,13 @@ export interface WorkflowNodeOutputDefinition {
   /** Whether the output is expected on successful execution. */
   required?: boolean;
 
+  /**
+   * Whether this output is added to `outputs.<nodeId>` for downstream expressions.
+   * Defaults to true. Set false for observability-only outputs that should be
+   * stored on the step execution but not suggested or exposed to later nodes.
+   */
+  includeInRuntimeContext?: boolean;
+
   /** Optional machine schema for this output value. */
   schema?: Record<string, any>;
 }
@@ -867,6 +883,21 @@ export interface WorkflowExpressionResolver {
   resolveExpression(expression: string, context: WorkflowRuntimeContext): any;
 }
 
+/** Loop context exposed to expressions for nested itemized controls. */
+export interface WorkflowLoopContext {
+  /** Current item for this loop frame. */
+  item: any;
+
+  /** Zero-based iteration index for this loop frame. */
+  index: number;
+
+  /** Loop control node id. */
+  nodeId?: string;
+
+  /** Loop control step execution key. */
+  stepExecutionKey?: string;
+}
+
 /** Runtime context shared by workflow execution and node execution. */
 export interface WorkflowRuntimeContext {
   /** Parent workflow execution entity. */
@@ -905,6 +936,18 @@ export interface WorkflowRuntimeContext {
   /** Current item index for itemized/iterative control nodes. */
   index?: number;
 
+  /** Nearest parent loop frame, when inside nested loop children. */
+  parent?: WorkflowLoopContext;
+
+  /** Parent loop frames, nearest first. */
+  parents?: WorkflowLoopContext[];
+
+  /** Loop frames from outermost to innermost, including the current loop. */
+  loops?: WorkflowLoopContext[];
+
+  /** Current error context when executing an error handler. */
+  error?: any;
+
   /** Parent control node id when executing nested child nodes. */
   parentNodeId?: string;
 

package/.claude/settings.local.json

@@ -1,16 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(node -e:*)",
-      "WebFetch(domain:docs.solidxai.com)",
-      "WebFetch(domain:github.com)",
-      "Read(//Users/oswald/projects/Solid_Starters/solidctl/**)",
-      "Read(//Users/oswald/projects/Solid_Starters/**)",
-      "Bash(find /Users/oswald/projects/Solid_Starters/solid-core-module -type d -name migration* -o -name *database*)",
-      "Bash(node verify-imports.js)"
-    ],
-    "additionalDirectories": [
-      "/Users/oswald/projects/Solid_Starters/solidctl"
-    ]
-  }
-}

package/CLAUDE.md

@@ -1,26 +0,0 @@
-# This is the SolidX API project.
-This is included as a dependency in consuming projects.
-
-# SolidX UI
-# The corresponding UI project is at the below path:
- /Users/oswald/projects/Solid_Starters/solid-core-ui
-
-# SolidX Docs
-# The documentation project is at the below path:
-/Users/oswald/projects/solidxai-docs
-
-# SolidX Agent
-# The agent project which has the skills for helping users configure, build and use SolidX is at the below path:
-/Users/oswald/projects/Solid_Starters/agent
-
-# SolidX Control Plane Commands
-# The control plane commands for managing SolidX instances are in the below path:
-/Users/oswald/projects/Solid_Starters/solidctl
-
-# Testing reference project 
-# This is the reference library management project that is used for testing and development of SolidX features. It is located at the below path:
-/Users/oswald/projects/Solid_Starters/solid-library-management
-
-# Code Builder project
-# This is the project that contains the code builder which generates code based on user input and templates. It is located at the below path:
-/Users/oswald/projects/Solid_Starters/solid-code-builder

package/src/services/1.js

@@ -1,6 +0,0 @@
-1. Do i need to create a storeStreams method for aws service too?
-    - Handle later
-2. queues handling -> if queues is enabled by default, i.e triggerExport(exportTransactionEntity.id).
-    - startExport should either return the data or return the transaction id
-3. How to handle scenarios wherein, nested related exist.(do i need to only get the userkey)
-    - show the userKey