jsfe 0.8.0 → 0.9.1

package/README.md

@@ -34,17 +34,20 @@ const engine = new WorkflowEngine(
 );
 
 // 2. Initialize a session for each user
-const sessionContext = engine.initSession(yourLogger, 'user-123', 'session-456');
+let sessionContext = engine.initSession(yourLogger, 'user-123', 'session-456');
 
-// 3. Plug-in the engine to process User message
+// 3. Process user message and update session context
 const userEntry = {
   role: 'user',
   content: 'I need help with my account',
 };
-const result = await engine.updateActivity(userEntry, sessionContext);
-if (result) {
-  // Intent detected and handled no need to proceed to normal response generation
-  return result;
+const updatedSessionContext = await engine.updateActivity(userEntry, sessionContext);
+sessionContext = updatedSessionContext; // CRITICAL: Always update your session reference
+
+if (updatedSessionContext.response) {
+  // Intent detected and handled - return the workflow response
+  // If flow activated you should not proceed to your normal handling
+  return updatedSessionContext.response;
 }
 
 // 4. Call your normal Generate reply process as usual
@@ -53,9 +56,9 @@ const reply = await yourConversationalReply(input);
 // 5. Update the engine's context with the generated reply
 const assistantEntry = {
   role: 'assistant',
-  content: 'I can help you with your account. What specific issue are you experiencing?',
+  content: reply, // The reply generated by your process
 };
-await engine.updateActivity(assistantEntry, sessionContext);
+sessionContext = await engine.updateActivity(assistantEntry, sessionContext);
 
 // Return the generated reply to the user
 return reply;
@@ -91,10 +94,10 @@ The WorkflowEngine constructor accepts the following parameters in order, each s
 - **Validation**: Parameter schemas validated against OpenAI Function Calling Standard
 - **Security**: Tools define their own security levels and authentication requirements
 
-**5. APPROVED_FUNCTIONS** (Map<string, Function>)
+**5. APPROVED_FUNCTIONS** (Object)
 - **Purpose**: Secure registry of pre-approved local JavaScript functions
-- **Security**: Only functions in this map can be executed by local-type tools
-- **Format**: `Map` where keys are function names and values are the actual functions
+- **Security**: Only functions in this object can be executed by local-type tools
+- **Format**: Plain object where keys are function names and values are the actual functions
 - **Validation**: Functions must match tool definitions in toolsRegistry
 
 **6. globalVariables** (Record<string, unknown>, optional)
@@ -102,6 +105,31 @@ The WorkflowEngine constructor accepts the following parameters in order, each s
 - **Scope**: Available to all flows in the session via variable interpolation
 - **Security**: Safe sharing of host application data with workflows
 - **Examples**: User ID, session ID, application configuration, environmental data
+- **Nature**: **STATIC** - Set during engine initialization, same for all sessions
+
+### Dynamic Session Data: The `cargo` Property
+
+Unlike `globalVariables` which are static and shared across all sessions, each `EngineSessionContext` has a `cargo` property for **dynamic, session-specific data sharing**:
+
+```javascript
+// After initSession, you can set dynamic session data
+let sessionContext = engine.initSession(logger, 'user-123', 'session-456');
+
+// Set dynamic data that workflows can access
+sessionContext.cargo.userPreferences = { theme: 'dark', language: 'en' };
+sessionContext.cargo.currentOrder = { id: 'ORD-123', total: 99.99 };
+sessionContext.cargo.temporaryData = 'Any dynamic content';
+
+// Workflows can reference cargo data with variable interpolation
+// Example in flow step: "Your order {{cargo.currentOrder.id}} total is ${{cargo.currentOrder.total}}"
+```
+
+**Key Differences: `globalVariables` vs `cargo`**
+- **globalVariables**: Static, engine-wide, set at initialization, same for all sessions
+- **cargo**: Dynamic, session-specific, can be modified anytime during conversation
+- **Use Cases**: 
+  - `globalVariables`: API keys, system config, app metadata
+  - `cargo`: User data, conversation state, temporary values, personalization
 
 **7. validateOnInit** (boolean, optional)
 - **Purpose**: Enable comprehensive flow and tool validation during initialization
@@ -254,7 +282,7 @@ const toolsRegistry = [
 
 #### 3. **Approved Functions Registry** - Secure Local Functions
 ```javascript
-const APPROVED_FUNCTIONS = new Map();
+const APPROVED_FUNCTIONS = {};
 
 // Define secure local functions
 async function processPayment(args) {
@@ -263,7 +291,7 @@ async function processPayment(args) {
 }
 
 // Register approved functions
-APPROVED_FUNCTIONS.set('processPayment', processPayment);
+APPROVED_FUNCTIONS['processPayment'] = processPayment;
 ```
 
 #### 4. **Global Variables** - Secure Sharing of Local Data
@@ -278,8 +306,62 @@ const globalVariables = {
 ### Session Management
 
 - Each user requires a unique session context via `initSession(logger, userId, sessionId)`
+- **CRITICAL**: `updateActivity()` returns an updated `EngineSessionContext` - you must always update your session reference
 - The `EngineSessionContext` object should be persisted by your application
 - Pass the same session context to `updateActivity` for conversation continuity
+- **Session Isolation**: Each user/session must have its own context to prevent state contamination
+
+#### Session Cargo for Dynamic Data
+
+Each session context includes a `cargo` property for dynamic, session-specific data that workflows can access:
+
+```javascript
+// Initialize session
+let sessionContext = engine.initSession(logger, 'user-123', 'session-456');
+
+// Set dynamic session data that workflows can reference
+sessionContext.cargo.userProfile = {
+  name: 'John Doe',
+  tier: 'premium',
+  preferences: { notifications: true }
+};
+
+// Workflows can access cargo data: "Welcome {{cargo.userProfile.name}}!"
+sessionContext = await engine.updateActivity(userEntry, sessionContext);
+```
+
+#### Correct Session Update Pattern
+
+```javascript
+// Initialize session
+let sessionContext = engine.initSession(logger, 'user-123', 'session-456');
+
+// For every updateActivity call, capture the returned context
+sessionContext = await engine.updateActivity(userEntry, sessionContext);
+
+// Check for workflow response
+if (sessionContext.response) {
+  return sessionContext.response;
+}
+
+
+// Continue with regular conversation...
+sessionContext = await engine.updateActivity(assistantEntry, sessionContext);
+```
+
+#### ❌ Common Mistake - Not Updating Session Reference
+```javascript
+// WRONG - This will cause session corruption
+const sessionContext = engine.initSession(logger, 'user-123', 'session-456');
+await engine.updateActivity(userEntry, sessionContext); // Session state lost!
+```
+
+#### ✅ Correct Pattern - Always Update Session Reference
+```javascript
+// CORRECT - Session state maintained
+let sessionContext = engine.initSession(logger, 'user-123', 'session-456');
+sessionContext = await engine.updateActivity(userEntry, sessionContext); // Session updated
+```
 
 ### Context Entry Types
 
@@ -299,6 +381,63 @@ interface ContextEntry {
 }
 ```
 
+## UpdateActivity Method
+
+The `updateActivity` method is the primary interface for processing user inputs and assistant responses. It returns an updated `EngineSessionContext` that must be captured and used for subsequent calls.
+
+### Method Signature
+
+```typescript
+async updateActivity(
+  contextEntry: ContextEntry, 
+  engineSessionContext: EngineSessionContext
+): Promise<EngineSessionContext>
+```
+
+### Return Value
+
+The method returns an updated `EngineSessionContext` containing:
+
+- **Updated flow state**: Modified flow stacks, variables, and execution context
+- **Response data**: If a workflow was triggered, `sessionContext.response` contains the result
+- **Session metadata**: Updated timestamps, accumulated messages, and transaction data
+
+### Integration Pattern
+
+```javascript
+// Process user input
+let sessionContext = await engine.updateActivity({
+  role: 'user',
+  content: userMessage,
+  timestamp: Date.now()
+}, sessionContext);
+
+// Check if a workflow was activated
+if (sessionContext.response) {
+  // Workflow handled the input - return the workflow response
+  return sessionContext.response;
+}
+
+// No workflow triggered - proceed with normal conversation
+const aiResponse = await yourAIFunction(userMessage);
+
+// Update context with AI response
+sessionContext = await engine.updateActivity({
+  role: 'assistant', 
+  content: aiResponse,
+  timestamp: Date.now()
+}, sessionContext);
+
+return aiResponse;
+```
+
+### Critical Notes
+
+- **Always capture the return value**: Failing to update your session reference will cause state corruption
+- **Session isolation**: Each user/conversation needs its own session context
+- **Response checking**: Check `sessionContext.response` to determine if a workflow handled the input
+- **Persistence**: Your application should persist the updated session context between requests
+
 ## Architecture Overview
 
 ### Stack-of-Stacks Design
@@ -543,6 +682,128 @@ The Flow Engine implements a sophisticated "stack-of-stacks" architecture that a
 - ✅ **FLOW** - Sub-flow execution with multiple call types
 - ✅ **SWITCH** - Enhanced conditional branching with expressions
 
+### Expression System
+
+The JSFE engine features a **powerful, unified JavaScript expression evaluator** that provides consistent syntax and behavior across all contexts. This system supports the full range of JavaScript expressions while maintaining security through a trusted developer model.
+
+#### Core Features
+- ✅ **Full JavaScript Expression Support** - All standard operators, functions, and syntax
+- ✅ **Type Preservation** - Numeric, boolean, and object types maintained correctly
+- ✅ **Template Interpolation** - `{{expression}}` syntax for string templates
+- ✅ **Direct Expression Evaluation** - Pure expressions return their native JavaScript types
+- ✅ **Unified Security Model** - Same safety framework across all evaluation contexts
+
+#### Expression Types
+
+**Single Expressions** (preserve JavaScript types):
+```javascript
+// SET steps with pure expressions return native types
+{ type: "SET", variable: "count", value: "{{attempt_count + 1}}" }        // Returns number
+{ type: "SET", variable: "isValid", value: "{{age >= 18 && verified}}" }  // Returns boolean
+{ type: "SET", variable: "user", value: "{{api_response.user}}" }         // Returns object
+```
+
+**Template Strings** (convert to strings for interpolation):
+```javascript
+// String templates with embedded expressions
+{ type: "SAY", value: "Attempt {{attempt_count + 1}}/{{max_attempts}}" }  // String result
+{ type: "SAY", value: "Welcome {{user.name}} ({{user.verified ? 'Verified' : 'Unverified'}})" }
+```
+
+#### Supported JavaScript Features
+- **Arithmetic**: `+`, `-`, `*`, `/`, `%`, `**` (exponentiation)
+- **Comparison**: `===`, `!==`, `>`, `<`, `>=`, `<=`, `==`, `!=`
+- **Logical**: `&&`, `||`, `!`, `??` (nullish coalescing)
+- **Ternary**: `condition ? true_value : false_value`
+- **Object/Array Access**: `obj.prop`, `obj['key']`, `arr[index]`
+- **Method Calls**: `str.toUpperCase()`, `arr.length`, `Math.round(num)`
+- **Template Literals**: `` `Hello ${name}` `` (within expressions)
+
+#### Security Model
+- **Developer Trust**: Workflows authored by developers, not end users
+- **Parameter Filtering**: Only valid JavaScript identifiers allowed as parameters
+- **No eval()**: Direct Function constructor with parameter validation
+- **User Input Safety**: User inputs are treated as values, not code
+
+### Internationalization and Localization
+
+The JSFE engine supports multiple languages through localized properties in flow definitions and steps. This allows you to create workflows that automatically display messages in the user's preferred language.
+
+#### Flow-Level Localization
+
+Add localized prompts to your flow definitions using the `prompt_xx` pattern:
+
+```javascript
+const flowsMenu = [
+  {
+    id: "payment-flow",
+    name: "ProcessPayment",
+    prompt: "Process a payment",           // Default (English)
+    prompt_es: "Procesar un pago",        // Spanish
+    prompt_fr: "Traiter un paiement",     // French
+    prompt_de: "Eine Zahlung bearbeiten", // German
+    description: "Handle payment processing",
+    steps: [ /* ... */ ]
+  }
+];
+```
+
+#### Step-Level Localization
+
+Add localized messages to individual steps using the `value_xx` pattern:
+
+```javascript
+{
+  type: "SAY-GET",
+  variable: "amount",
+  value: "Please enter the payment amount:",           // Default (English)
+  value_es: "Por favor ingrese el monto del pago:",    // Spanish
+  value_fr: "Veuillez saisir le montant du paiement:", // French
+  value_de: "Bitte geben Sie den Zahlungsbetrag ein:"  // German
+}
+```
+
+#### Language Selection
+
+Set the user's preferred language when initializing the engine:
+
+```javascript
+const engine = new WorkflowEngine(
+  logger,
+  aiCallback,
+  flowsMenu,
+  toolsRegistry,
+  APPROVED_FUNCTIONS,
+  globalVariables,
+  true,           // validateOnInit
+  'es',           // language - Spanish
+  messageRegistry,
+  guidanceConfig
+);
+```
+
+#### Supported Language Codes
+
+- `en` - English (default)
+- `es` - Spanish (Español)
+- `pt` - Portuguese (Português)
+- `fr` - French (Français)
+- `de` - German (Deutsch)
+- Any ISO 639-1 language code
+
+#### Language Fallback
+
+If a localized property is not found for the specified language, the engine automatically falls back to the default `prompt` or `value` property. This ensures your flows always work even if some translations are missing.
+
+```javascript
+// Example: User has language='es' but only English is available
+{
+  type: "SAY",
+  value: "Welcome to our service!"  // Will be used as fallback
+  // value_es is missing, so English value is used
+}
+```
+
 ### Expression Template System
 
 The engine supports safe JavaScript expressions within `{{}}` templates:
@@ -623,13 +884,61 @@ For demos, tests, or developer convenience, you can set `aiCallback` to `null` w
 
 This makes it easy to run demos and tests without requiring a real AI intent detection function. In production, always provide a real `aiCallback` for robust intent detection.
 
+### Test Suite Patterns
+
+When creating test suites, follow these patterns to ensure session isolation and prevent state contamination:
+
+#### Proper Test Isolation Pattern
+
+```javascript
+// ❌ Wrong - Shared session causes contamination
+const globalSession = engine.initSession(logger, 'test-user', 'test-session');
+
+for (const testCase of testCases) {
+  // This will cause session corruption!
+  await runTest(testCase, globalSession);
+}
+
+// ✅ Correct - Fresh session per test
+for (let i = 0; i < testCases.length; i++) {
+  const testCase = testCases[i];
+  
+  // Create fresh session for each test
+  let sessionContext = engine.initSession(logger, 'test-user', `test-session-${i+1}`);
+  
+  await runTest(testCase, sessionContext);
+}
+```
+
+#### Test Function Pattern
+
+```javascript
+async function runTest(inputs, sessionContext) {
+  for (const input of inputs) {
+    // Always update session context
+    sessionContext = await engine.updateActivity({
+      role: 'user',
+      content: input,
+      timestamp: Date.now()
+    }, sessionContext);
+    
+    // Check for workflow response
+    if (sessionContext.response) {
+      console.log('Workflow Response:', sessionContext.response);
+    }
+  }
+}
+```
+
+This pattern ensures that each test runs in complete isolation, preventing the session corruption that can occur when tests share state.
+
 ## Security & Compliance
 
 ### Expression Security
-- ✅ **Safe Expression Evaluation** - No eval(), no code injection
-- ✅ **Safe Method Allowlist** - Only pre-approved methods allowed
-- ✅ **Pattern-Based Security** - Block dangerous operations
-- ✅ **Variable Path Validation** - Secure nested property access
+- ✅ **Direct JavaScript Evaluation** - Native JavaScript execution with security framework
+- ✅ **Controlled Access** - Only exported variables and functions are accessable JavaScript identifiers allowed as parameters
+scope
+- ✅ **User Input Safety** - User inputs treated as values, with protection against code injection
 
 ### Transaction Management
 - ✅ **Comprehensive Audit Trail** - Every action logged
@@ -765,4 +1074,81 @@ The engine supports completely generic response transformation through declarati
     }
   }
 }
+```
+
+## Troubleshooting
+
+### Common Session Management Issues
+
+#### Problem: "engineSessionContext.flowStacks was invalid, initialized fresh flowStacks"
+
+**Cause**: Session context corruption due to improper session management.
+
+**Solutions**:
+1. **Always update session reference**: 
+   ```javascript
+   // ❌ Wrong
+   await engine.updateActivity(entry, sessionContext);
+   
+   // ✅ Correct  
+   sessionContext = await engine.updateActivity(entry, sessionContext);
+   ```
+
+2. **Use unique sessions per user/conversation**:
+   ```javascript
+   // ❌ Wrong - sharing sessions
+   const sharedSession = engine.initSession(logger, 'shared', 'shared');
+   
+   // ✅ Correct - isolated sessions
+   const userSession = engine.initSession(logger, `user-${userId}`, `session-${sessionId}`);
+   ```
+
+3. **Initialize fresh sessions for testing**:
+   ```javascript
+   // For each test case
+   let sessionContext = engine.initSession(logger, 'test-user', `test-session-${testIndex}`);
+   ```
+
+#### Problem: Workflows not triggering or mock responses
+
+**Cause**: Corrupted session state or improper context handling.
+
+**Solution**: Ensure proper session lifecycle:
+```javascript
+// Initialize once per user/conversation
+let sessionContext = engine.initSession(logger, userId, sessionId);
+
+// Update for every interaction
+sessionContext = await engine.updateActivity(userInput, sessionContext);
+
+// Check workflow response
+if (sessionContext.response) {
+  return sessionContext.response;
+}
+
+// Continue with regular conversation
+sessionContext = await engine.updateActivity(assistantResponse, sessionContext);
+```
+
+#### Problem: State bleeding between users/sessions
+
+**Cause**: Shared session contexts between different users or conversations.
+
+**Solution**: Maintain strict session isolation:
+```javascript
+// Create session per user
+const userSessions = new Map();
+
+function getOrCreateSession(userId, sessionId) {
+  const key = `${userId}-${sessionId}`;
+  if (!userSessions.has(key)) {
+    userSessions.set(key, engine.initSession(logger, userId, sessionId));
+  }
+  return userSessions.get(key);
+}
+
+// Update and store session
+let sessionContext = getOrCreateSession(userId, sessionId);
+sessionContext = await engine.updateActivity(entry, sessionContext);
+userSessions.set(`${userId}-${sessionId}`, sessionContext);
 ```

package/dist/index.d.ts

@@ -46,6 +46,7 @@ export interface Logger {
     warn(message: string, ...args: unknown[]): void;
     error(message: string, ...args: unknown[]): void;
     debug(message: string, ...args: unknown[]): void;
+    setLevel?(level: string): void;
 }
 export type MessageTemplates = Record<string, string>;
 export type MessageRegistry = Record<string, MessageTemplates>;
@@ -136,6 +137,8 @@ export interface EngineSessionContext {
         assistant?: ContextEntry;
     };
     globalVariables: Record<string, unknown>;
+    response?: string | null;
+    completedTransactions?: TransactionData[];
     cargo: Record<string, unknown> | undefined;
 }
 export interface FlowStep {
@@ -186,7 +189,7 @@ export interface TransactionStep {
     timestamp: Date;
     retryCount?: number;
 }
-export interface TransactionObj {
+export interface TransactionData {
     id: string;
     flowName: string;
     initiator: string;
@@ -199,12 +202,15 @@ export interface TransactionObj {
     rolledBackAt?: Date;
     failureReason?: string;
     metadata: Record<string, unknown>;
-    addStep: (step: FlowStep, result: unknown, duration: number, status?: 'success' | 'error') => void;
-    addError: (step: FlowStep, error: Error, duration: number) => void;
-    sanitizeForLog: (data: unknown) => unknown;
-    rollback: () => void;
-    complete: () => void;
-    fail: (reason: string) => void;
+}
+export declare class TransactionManager {
+    static create(flowName: string, initiator: string, userId: string): TransactionData;
+    static addStep(transaction: TransactionData, step: FlowStep, result: unknown, duration: number, status?: 'success' | 'error'): void;
+    static addError(transaction: TransactionData, step: FlowStep, error: Error, duration: number): void;
+    static sanitizeForLog(data: unknown): unknown;
+    static rollback(transaction: TransactionData): void;
+    static complete(transaction: TransactionData): void;
+    static fail(transaction: TransactionData, reason: string): void;
 }
 export interface FlowFrame {
     flowName: string;
@@ -214,7 +220,7 @@ export interface FlowFrame {
     contextStack: ContextEntry[];
     inputStack: unknown[];
     variables: Record<string, unknown>;
-    transaction: TransactionObj;
+    transaction: TransactionData;
     userId: string;
     startTime: number;
     pendingVariable?: string;
@@ -224,28 +230,7 @@ export interface FlowFrame {
     parentTransaction?: string;
     justResumed?: boolean;
 }
-export interface Engine {
-    flowStacks: FlowFrame[][];
-    flowsMenu?: FlowDefinition[];
-    toolsRegistry?: ToolDefinition[];
-    language?: string;
-    messageRegistry?: MessageRegistry;
-    guidanceConfig?: GuidanceConfig;
-    globalVariables?: Record<string, unknown>;
-    hasAccumulatedMessages: () => boolean;
-    getAndClearAccumulatedMessages?: (engineSessionContext?: EngineSessionContext) => string[];
-    addAccumulatedMessage?: (message: string, engineSessionContext?: EngineSessionContext) => void;
-    sessionId?: string;
-    APPROVED_FUNCTIONS?: ApprovedFunctions;
-    aiCallback: AiCallbackFunction;
-    lastChatTurn: {
-        user?: ContextEntry;
-        assistant?: ContextEntry;
-    };
-    initSession?: (hostLogger: Logger | null, userId: string, sessionId: string) => EngineSessionContext;
-    updateActivity?: (contextEntry: ContextEntry, engineSessionContext?: EngineSessionContext) => Promise<string | null>;
-    cargo: Record<string, unknown> | undefined;
-}
+export type Engine = WorkflowEngine;
 export interface FlowDefinition {
     id: string;
     name: string;
@@ -258,6 +243,7 @@ export interface FlowDefinition {
     [key: `prompt_${string}`]: string | undefined;
     description: string;
     version: string;
+    interruptable?: boolean;
     steps: FlowStep[];
     variables?: Record<string, {
         type: string;
@@ -334,8 +320,7 @@ export interface AuthConfig {
     header?: string;
 }
 export interface ApprovedFunctions {
-    get(functionName: string): ((...args: unknown[]) => unknown) | undefined;
-    [functionName: string]: unknown;
+    [functionName: string]: ((...args: unknown[]) => unknown) | undefined;
 }
 export interface SystemContext {
     [key: string]: string | number | boolean | null | undefined;
@@ -447,8 +432,6 @@ export declare class WorkflowEngine implements Engine {
     flowsMenu: FlowDefinition[];
     toolsRegistry: ToolDefinition[];
     APPROVED_FUNCTIONS: ApprovedFunctions;
-    flowStacks: FlowFrame[][];
-    globalAccumulatedMessages: string[];
     sessionId: string;
     createdAt: Date;
     lastActivity: Date;
@@ -457,7 +440,10 @@ export declare class WorkflowEngine implements Engine {
     guidanceConfig?: GuidanceConfig;
     globalVariables?: Record<string, unknown>;
     aiCallback: AiCallbackFunction;
-    lastChatTurn: {
+    private sessionContext;
+    get flowStacks(): FlowFrame[][];
+    get globalAccumulatedMessages(): string[];
+    get lastChatTurn(): {
         user?: ContextEntry;
         assistant?: ContextEntry;
     };
@@ -491,9 +477,9 @@ export declare class WorkflowEngine implements Engine {
      *   const session = engine.initSession(yourLogger, 'user-123', 'session-456');
      */
     initSession(hostLogger: Logger | null, userId: string, sessionId: string): EngineSessionContext;
-    updateActivity(contextEntry: ContextEntry, engineSessionContext?: EngineSessionContext): Promise<string | null>;
-    addAccumulatedMessage(message: string, engineSessionContext?: EngineSessionContext): void;
-    getAndClearAccumulatedMessages(engineSessionContext?: EngineSessionContext): string[];
+    updateActivity(contextEntry: ContextEntry, engineSessionContext: EngineSessionContext): Promise<EngineSessionContext>;
+    addAccumulatedMessage(message: string): void;
+    getAndClearAccumulatedMessages(): string[];
     hasAccumulatedMessages(): boolean;
     initializeFlowStacks(): void;
     getCurrentStack(): FlowFrame[];
@@ -501,7 +487,7 @@ export declare class WorkflowEngine implements Engine {
     getCurrentFlowFrame(): FlowFrame;
     createNewStack(): void;
     pushToCurrentStack(flowFrame: FlowFrame): void;
-    popFromCurrentStack(): FlowFrame | undefined;
+    popFromCurrentStack(): FlowFrame;
     getFlowForInput(input: string): Promise<FlowDefinition | null>;
     /**
      * Performs comprehensive validation of all flows during engine initialization
@@ -571,7 +557,7 @@ export declare class WorkflowEngine implements Engine {
     validateAllFlows(options?: any): any;
     /**
      * Gets the current variable scope available at a specific step
-     * This includes variables defined in flow definition + variables created by previous steps
+     * This includes variables defined in flow definition + variables created by previous steps + parent flow variables
      */
     private _getCurrentStepScope;
     /**