@bubblelab/bubble-runtime 0.1.14 → 0.1.16

package/dist/extraction/BubbleParser.js

@@ -1,8 +1,22 @@
+import { AST_NODE_TYPES } from '@typescript-eslint/typescript-estree';
 import { buildClassNameLookup } from '../utils/bubble-helper';
-import { BubbleParameterType } from '@bubblelab/shared-schemas';
+import { BubbleParameterType, hashToVariableId, buildCallSiteKey, } from '@bubblelab/shared-schemas';
 import { parseToolsParamValue } from '../utils/parameter-formatter';
 export class BubbleParser {
     bubbleScript;
+    cachedAST = null;
+    methodInvocationOrdinalMap = new Map();
+    invocationBubbleCloneCache = new Map();
+    /**
+     * Track which call expressions have been assigned an invocation index.
+     * Key: `methodName:startOffset` (using AST range start position)
+     * Value: the assigned invocation index
+     * This prevents double-counting when the same call site is processed multiple times
+     * (e.g., once in .map() callback processing, again in Promise.all resolution)
+     */
+    processedCallSiteIndexes = new Map();
+    /** Custom tool func ranges for marking bubbles inside custom tools */
+    customToolFuncs = [];
     constructor(bubbleScript) {
         this.bubbleScript = bubbleScript;
     }
@@ -17,13 +31,35 @@ export class BubbleParser {
         }
         const nodes = {};
         const errors = [];
-        // Find handle method location
-        const handleMethodLocation = this.findHandleMethodLocation(ast);
+        // Find main BubbleFlow class and all its instance methods
+        const mainClass = this.findMainBubbleFlowClass(ast);
+        const instanceMethodsLocation = {};
+        if (mainClass) {
+            const methods = this.findAllInstanceMethods(mainClass);
+            const methodNames = methods.map((m) => m.methodName);
+            const invocations = this.findMethodInvocations(ast, methodNames);
+            // Combine method locations with invocation lines
+            for (const method of methods) {
+                instanceMethodsLocation[method.methodName] = {
+                    startLine: method.startLine,
+                    endLine: method.endLine,
+                    definitionStartLine: method.definitionStartLine,
+                    bodyStartLine: method.bodyStartLine,
+                    invocationLines: invocations[method.methodName] || [],
+                };
+            }
+        }
+        // Clear custom tool func tracking from previous runs
+        this.customToolFuncs = [];
         // Visit AST nodes to find bubble instantiations
         this.visitNode(ast, nodes, classNameToInfo, scopeManager);
         if (errors.length > 0) {
             throw new Error(`Failed to trace bubble dependencies: ${errors.join(', ')}`);
         }
+        // Find custom tools in ai-agent bubbles and populate customToolFuncs
+        this.findCustomToolsInAIAgentBubbles(ast, nodes, classNameToInfo);
+        // Mark bubbles that are inside custom tool funcs
+        this.markBubblesInsideCustomTools(nodes);
         // Build a set of used variable IDs to ensure uniqueness for any synthetic IDs we allocate
         const usedVariableIds = new Set();
         for (const [idStr, node] of Object.entries(nodes)) {
@@ -59,10 +95,69 @@ export class BubbleParser {
             ordinalCounters, usedVariableIds, bubble.variableId, // Root variable id mirrors the parsed bubble's variable id
             true, // suppress adding self segment for root
             bubble.variableName);
+            // Add functionCallChildren for ai-agent bubbles with custom tools
+            if (bubble.bubbleName === 'ai-agent' &&
+                bubble.dependencyGraph &&
+                this.customToolFuncs.length > 0) {
+                const toolsForThisBubble = this.customToolFuncs.filter((t) => t.parentBubbleVariableId === bubble.variableId);
+                if (toolsForThisBubble.length > 0) {
+                    const functionCallChildren = [];
+                    for (const toolFunc of toolsForThisBubble) {
+                        // Find all bubbles that are inside this custom tool func
+                        const childBubbleNodes = [];
+                        for (const [, bubbleInfo] of Object.entries(nodes)) {
+                            if (bubbleInfo.containingCustomToolId ===
+                                `${toolFunc.parentBubbleVariableId}.${toolFunc.toolName}`) {
+                                childBubbleNodes.push({
+                                    type: 'bubble',
+                                    variableId: bubbleInfo.variableId,
+                                });
+                            }
+                        }
+                        // Create FunctionCallWorkflowNode for this custom tool
+                        const funcCallNode = {
+                            type: 'function_call',
+                            functionName: toolFunc.toolName,
+                            description: toolFunc.description,
+                            isMethodCall: false,
+                            code: `customTool:${toolFunc.toolName}`,
+                            variableId: hashToVariableId(`${bubble.variableId}.customTool.${toolFunc.toolName}`),
+                            location: {
+                                startLine: toolFunc.startLine,
+                                startCol: toolFunc.startCol,
+                                endLine: toolFunc.endLine,
+                                endCol: toolFunc.endCol,
+                            },
+                            methodDefinition: {
+                                location: {
+                                    startLine: toolFunc.startLine,
+                                    endLine: toolFunc.endLine,
+                                },
+                                isAsync: toolFunc.isAsync,
+                                parameters: ['input'], // Custom tools always have 'input' parameter
+                            },
+                            children: childBubbleNodes,
+                        };
+                        functionCallChildren.push(funcCallNode);
+                    }
+                    bubble.dependencyGraph.functionCallChildren = functionCallChildren;
+                }
+            }
+        }
+        // Store AST for method definition lookup
+        this.cachedAST = ast;
+        this.methodInvocationOrdinalMap.clear();
+        this.invocationBubbleCloneCache.clear();
+        this.processedCallSiteIndexes.clear();
+        // Build hierarchical workflow structure
+        const workflow = this.buildWorkflowTree(ast, nodes, scopeManager);
+        for (const clone of this.invocationBubbleCloneCache.values()) {
+            nodes[clone.variableId] = clone;
         }
         return {
             bubbles: nodes,
-            handleMethodLocation,
+            workflow,
+            instanceMethodsLocation,
         };
     }
     findDependenciesForBubble(currentDependencies, bubbleFactory, parameters, seen = new Set()) {
@@ -143,7 +238,7 @@ export class BubbleParser {
                 : `${bubbleName}#${nextOrdinal}`;
         const variableId = typeof explicitVariableId === 'number'
             ? explicitVariableId
-            : this.hashUniqueIdToVarId(uniqueId);
+            : hashToVariableId(uniqueId);
         const metadata = bubbleFactory.getMetadata(bubbleName);
         if (seen.has(bubbleName)) {
             return {
@@ -180,7 +275,7 @@ export class BubbleParser {
                         const aiOrdinal = (ordinalCounters.get(aiCountKey) || 0) + 1;
                         ordinalCounters.set(aiCountKey, aiOrdinal);
                         const aiAgentUniqueId = `${uniqueId}.ai-agent#${aiOrdinal}`;
-                        const aiAgentVarId = this.hashUniqueIdToVarId(aiAgentUniqueId);
+                        const aiAgentVarId = hashToVariableId(aiAgentUniqueId);
                         const toolChildren = [];
                         for (const toolName of toolsForChild) {
                             toolChildren.push(this.buildDependencyGraph(toolName, bubbleFactory, nextSeen, undefined, aiAgentUniqueId, ordinalCounters, usedVariableIds, undefined, false, toolName));
@@ -225,17 +320,6 @@ export class BubbleParser {
         };
         return nodeObj;
     }
-    // Deterministic non-negative integer ID from uniqueId string
-    hashUniqueIdToVarId(input) {
-        let hash = 2166136261; // FNV-1a 32-bit offset basis
-        for (let i = 0; i < input.length; i++) {
-            hash ^= input.charCodeAt(i);
-            hash = (hash * 16777619) >>> 0; // unsigned 32-bit
-        }
-        // Map to 6-digit range to avoid colliding with small AST ids while readable
-        const mapped = 100000 + (hash % 900000);
-        return mapped;
-    }
     /**
      * Build a JSON Schema object for the payload parameter of the top-level `handle` entrypoint.
      * Supports primitives, arrays, unions (anyOf), intersections (allOf), type literals, and
@@ -549,8 +633,21 @@ export class BubbleParser {
             if (!keyName)
                 continue;
             const propSchema = m.typeAnnotation
-                ? this.tsTypeToJsonSchema(m.typeAnnotation.typeAnnotation, ast)
+                ? this.tsTypeToJsonSchema(m.typeAnnotation.typeAnnotation, ast) || {}
                 : {};
+            // Extract comment/description and JSDoc tags for this property
+            const jsDocInfo = this.extractJSDocForNode(m);
+            if (jsDocInfo.description) {
+                propSchema.description = jsDocInfo.description;
+            }
+            // Add canBeFile flag to schema if explicitly specified in JSDoc
+            if (jsDocInfo.canBeFile !== undefined) {
+                propSchema.canBeFile = jsDocInfo.canBeFile;
+            }
+            // Add canBeGoogleFile flag to schema if explicitly specified in JSDoc
+            if (jsDocInfo.canBeGoogleFile !== undefined) {
+                propSchema.canBeGoogleFile = jsDocInfo.canBeGoogleFile;
+            }
             properties[keyName] = propSchema;
             if (!m.optional)
                 required.push(keyName);
@@ -586,15 +683,6 @@ export class BubbleParser {
                 },
             };
         }
-        if (eventKey === 'gmail/email_received') {
-            return {
-                type: 'object',
-                properties: {
-                    email: { type: 'string' },
-                },
-                required: ['email'],
-            };
-        }
         if (eventKey === 'schedule/cron') {
             return {
                 type: 'object',
@@ -641,122 +729,411 @@ export class BubbleParser {
         return null;
     }
     /**
-     * Find the handle method location in the AST
+     * Find the main class that extends BubbleFlow
      */
-    findHandleMethodLocation(ast) {
+    findMainBubbleFlowClass(ast) {
         for (const statement of ast.body) {
-            // Look for function declarations named 'handle'
-            if (statement.type === 'FunctionDeclaration' &&
-                statement.id?.name === 'handle') {
-                const definitionStart = statement.loc?.start.line || -1;
-                const bodyStart = statement.body?.loc?.start.line || definitionStart;
-                return {
-                    startLine: definitionStart,
-                    endLine: statement.loc?.end.line || -1,
-                    definitionStartLine: definitionStart,
-                    bodyStartLine: bodyStart,
-                };
-            }
-            // Look for exported function declarations: export function handle() {}
+            let classDecl = null;
+            // Check exported class declarations
             if (statement.type === 'ExportNamedDeclaration' &&
-                statement.declaration?.type === 'FunctionDeclaration' &&
-                statement.declaration.id?.name === 'handle') {
-                const decl = statement.declaration;
-                const definitionStart = decl.loc?.start.line || -1;
-                const bodyStart = decl.body?.loc?.start.line || definitionStart;
-                return {
-                    startLine: definitionStart,
-                    endLine: decl.loc?.end.line || -1,
-                    definitionStartLine: definitionStart,
-                    bodyStartLine: bodyStart,
-                };
+                statement.declaration?.type === 'ClassDeclaration') {
+                classDecl = statement.declaration;
             }
-            // Look for variable declarations with function expressions: const handle = () => {}
-            if (statement.type === 'VariableDeclaration') {
-                for (const declarator of statement.declarations) {
-                    if (declarator.type === 'VariableDeclarator' &&
-                        declarator.id.type === 'Identifier' &&
-                        declarator.id.name === 'handle' &&
-                        (declarator.init?.type === 'FunctionExpression' ||
-                            declarator.init?.type === 'ArrowFunctionExpression')) {
-                        const init = declarator.init;
-                        const definitionStart = declarator.loc?.start.line || -1;
-                        const bodyStart = init.type === 'FunctionExpression'
-                            ? init.body?.loc?.start.line || definitionStart
-                            : init.body?.loc?.start.line || definitionStart;
-                        return {
-                            startLine: definitionStart,
-                            endLine: init.loc?.end.line || -1,
-                            definitionStartLine: definitionStart,
-                            bodyStartLine: bodyStart,
-                        };
-                    }
-                }
+            // Check non-exported class declarations
+            else if (statement.type === 'ClassDeclaration') {
+                classDecl = statement;
             }
-            // Look for exported variable declarations: export const handle = () => {}
-            if (statement.type === 'ExportNamedDeclaration' &&
-                statement.declaration?.type === 'VariableDeclaration') {
-                for (const declarator of statement.declaration.declarations) {
-                    if (declarator.type === 'VariableDeclarator' &&
-                        declarator.id.type === 'Identifier' &&
-                        declarator.id.name === 'handle' &&
-                        (declarator.init?.type === 'FunctionExpression' ||
-                            declarator.init?.type === 'ArrowFunctionExpression')) {
-                        const init = declarator.init;
-                        const definitionStart = declarator.loc?.start.line || -1;
-                        const bodyStart = init.type === 'FunctionExpression'
-                            ? init.body?.loc?.start.line || definitionStart
-                            : init.body?.loc?.start.line || definitionStart;
-                        return {
-                            startLine: definitionStart,
-                            endLine: init.loc?.end.line || -1,
-                            definitionStartLine: definitionStart,
-                            bodyStartLine: bodyStart,
-                        };
+            if (classDecl) {
+                // Check if this class extends BubbleFlow
+                if (classDecl.superClass) {
+                    const superClass = classDecl.superClass;
+                    // Handle simple identifier like extends BubbleFlow
+                    if (superClass.type === 'Identifier' &&
+                        superClass.name === 'BubbleFlow') {
+                        return classDecl;
+                    }
+                    // Handle generic type like BubbleFlow<'webhook/http'>
+                    // Check if it's a TSTypeReference with type parameters
+                    // Use type assertion since TSESTree types may not fully expose this
+                    if (superClass.type === 'TSTypeReference') {
+                        const typeName = superClass.typeName;
+                        if (typeName &&
+                            typeName.type === 'Identifier' &&
+                            typeName.name === 'BubbleFlow') {
+                            return classDecl;
+                        }
                     }
-                }
-            }
-            // Look for exported class declarations with handle method
-            if (statement.type === 'ExportNamedDeclaration' &&
-                statement.declaration?.type === 'ClassDeclaration') {
-                const handleMethod = this.findHandleMethodInClass(statement.declaration);
-                if (handleMethod) {
-                    return handleMethod;
-                }
-            }
-            // Look for class declarations with handle method
-            if (statement.type === 'ClassDeclaration') {
-                const handleMethod = this.findHandleMethodInClass(statement);
-                if (handleMethod) {
-                    return handleMethod;
                 }
             }
         }
-        return null; // Handle method not found
+        return null;
     }
     /**
-     * Find handle method within a class declaration
+     * Extract all instance methods from a class
      */
-    findHandleMethodInClass(classDeclaration) {
+    findAllInstanceMethods(classDeclaration) {
+        const methods = [];
         if (!classDeclaration.body)
-            return null;
+            return methods;
         for (const member of classDeclaration.body.body) {
+            // Only process instance methods (not static, not getters/setters)
             if (member.type === 'MethodDefinition' &&
+                !member.static &&
+                member.kind === 'method' &&
                 member.key.type === 'Identifier' &&
-                member.key.name === 'handle' &&
                 member.value.type === 'FunctionExpression') {
+                const methodName = member.key.name;
                 const definitionStart = member.loc?.start.line || -1;
                 const bodyStart = member.value.body?.loc?.start.line || definitionStart;
                 const definitionEnd = member.loc?.end.line || -1;
-                return {
+                methods.push({
+                    methodName,
                     startLine: definitionStart,
                     endLine: definitionEnd,
                     definitionStartLine: definitionStart,
                     bodyStartLine: bodyStart,
-                };
+                });
             }
         }
-        return null;
+        return methods;
+    }
+    /**
+     * Find all method invocations in the AST with full details
+     */
+    findMethodInvocations(ast, methodNames) {
+        const invocations = {};
+        const methodNameSet = new Set(methodNames);
+        const visitedNodes = new WeakSet();
+        const parentMap = new WeakMap();
+        const invocationCounters = new Map();
+        // Initialize invocations map
+        for (const methodName of methodNames) {
+            invocations[methodName] = [];
+        }
+        // First pass: Build parent map
+        const buildParentMap = (node, parent) => {
+            if (parent) {
+                parentMap.set(node, parent);
+            }
+            // Visit children
+            const visitValue = (value) => {
+                if (value && typeof value === 'object') {
+                    if (Array.isArray(value)) {
+                        value.forEach(visitValue);
+                    }
+                    else if ('type' in value && typeof value.type === 'string') {
+                        buildParentMap(value, node);
+                    }
+                    else {
+                        Object.values(value).forEach(visitValue);
+                    }
+                }
+            };
+            const nodeObj = node;
+            for (const [key, value] of Object.entries(nodeObj)) {
+                if (key === 'parent' || key === 'loc' || key === 'range') {
+                    continue;
+                }
+                visitValue(value);
+            }
+        };
+        buildParentMap(ast);
+        const isPromiseAllArrayElement = (arrayNode, elementNode) => {
+            if (!elementNode || !arrayNode.elements.includes(elementNode)) {
+                return false;
+            }
+            const parentCall = parentMap.get(arrayNode);
+            if (!parentCall || parentCall.type !== 'CallExpression') {
+                return false;
+            }
+            const callee = parentCall.callee;
+            if (callee.type !== 'MemberExpression' ||
+                callee.object.type !== 'Identifier' ||
+                callee.object.name !== 'Promise' ||
+                callee.property.type !== 'Identifier' ||
+                callee.property.name !== 'all') {
+                return false;
+            }
+            return (parentCall.arguments.length > 0 && parentCall.arguments[0] === arrayNode);
+        };
+        const visitNode = (node, parent) => {
+            // Skip if already visited
+            if (visitedNodes.has(node)) {
+                return;
+            }
+            visitedNodes.add(node);
+            // Look for CallExpression nodes
+            if (node.type === 'CallExpression') {
+                const callee = node.callee;
+                // Check if it's a method call: this.methodName()
+                if (callee.type === 'MemberExpression') {
+                    const object = callee.object;
+                    const property = callee.property;
+                    if (object.type === 'ThisExpression' &&
+                        property.type === 'Identifier' &&
+                        methodNameSet.has(property.name)) {
+                        const methodName = property.name;
+                        const lineNumber = node.loc?.start.line;
+                        const endLineNumber = node.loc?.end.line;
+                        const columnNumber = node.loc?.start.column ?? -1;
+                        if (!lineNumber || !endLineNumber)
+                            return;
+                        // Extract arguments
+                        const args = node.arguments
+                            .map((arg) => this.bubbleScript.substring(arg.range[0], arg.range[1]))
+                            .join(', ');
+                        // Determine statement type by looking at parent context
+                        let statementType = 'simple';
+                        let variableName;
+                        let variableType;
+                        let destructuringPattern;
+                        let hasAwait = false;
+                        // For condition_expression: track the containing statement info
+                        let containingStatementLine;
+                        let callRange;
+                        let callText;
+                        // Check if parent is AwaitExpression
+                        if (parent?.type === 'AwaitExpression') {
+                            hasAwait = true;
+                        }
+                        // Find the statement containing this call using parent map
+                        // We need to check parent chain to identify:
+                        // 1. VariableDeclarator -> VariableDeclaration (for const/let/var x = ...)
+                        // 2. AssignmentExpression (for x = ...)
+                        // 3. ReturnStatement (for return ...)
+                        // Also check for complex expressions that should not be instrumented
+                        let currentParent = parentMap.get(node);
+                        let isInComplexExpression = false;
+                        let invocationContext = 'default';
+                        let currentChild = node;
+                        while (currentParent) {
+                            const parentIsPromiseAllElement = currentParent.type === 'ArrayExpression' &&
+                                isPromiseAllArrayElement(currentParent, currentChild);
+                            // Check if we're inside a complex expression before reaching the statement level
+                            // These expressions cannot be instrumented inline without breaking syntax
+                            if (currentParent.type === 'ConditionalExpression' || // Ternary: a ? b : c
+                                currentParent.type === 'ObjectExpression' || // Object literal: { key: value }
+                                (currentParent.type === 'ArrayExpression' &&
+                                    !parentIsPromiseAllElement) || // Array literal outside Promise.all
+                                currentParent.type === 'Property' || // Object property
+                                currentParent.type === 'SpreadElement' // Spread: ...expr
+                            ) {
+                                isInComplexExpression = true;
+                                break;
+                            }
+                            // Check if we're inside an arrow function expression body (no braces)
+                            // e.g., arr.map((x) => this.method(x)) - the body is just an expression
+                            // These need to be wrapped in an async IIFE, similar to promise_all_element
+                            if (currentParent.type === 'ArrowFunctionExpression' &&
+                                currentChild === currentParent.body &&
+                                currentParent.body.type !== 'BlockStatement') {
+                                invocationContext = 'promise_all_element';
+                                // Capture call text for proper replacement
+                                const callNode = hasAwait ? parent : node;
+                                if (callNode?.range) {
+                                    callRange = {
+                                        start: callNode.range[0],
+                                        end: callNode.range[1],
+                                    };
+                                    callText = this.bubbleScript.substring(callRange.start, callRange.end);
+                                }
+                                // Don't break - continue to find the outer statement for line info
+                            }
+                            // Check if we're inside the condition/test part of a control flow statement
+                            // These need special handling - extract call before the statement and replace in-place
+                            // IMPORTANT: Only treat as condition_expression if the call is in the test/condition,
+                            // not in the body (consequent/alternate/etc)
+                            if (currentParent.type === 'IfStatement' ||
+                                currentParent.type === 'WhileStatement' ||
+                                currentParent.type === 'DoWhileStatement' ||
+                                currentParent.type === 'ForStatement' ||
+                                currentParent.type === 'SwitchStatement') {
+                                // Check if currentChild is actually in the test/condition part
+                                const isInCondition = this.isNodeInConditionPart(currentParent, currentChild);
+                                if (isInCondition) {
+                                    statementType = 'condition_expression';
+                                    containingStatementLine = currentParent.loc?.start.line;
+                                    // Capture the call range - include await if present
+                                    const callNode = hasAwait ? parent : node;
+                                    if (callNode?.range) {
+                                        callRange = {
+                                            start: callNode.range[0],
+                                            end: callNode.range[1],
+                                        };
+                                        callText = this.bubbleScript.substring(callRange.start, callRange.end);
+                                    }
+                                    break;
+                                }
+                                // If not in condition part, continue walking up - the call is in the body
+                                // and should be treated as a normal statement
+                            }
+                            if (parentIsPromiseAllElement) {
+                                invocationContext = 'promise_all_element';
+                            }
+                            // Check if we're nested inside another CallExpression (e.g., arr.push(this.method()))
+                            // This needs special handling similar to condition_expression - extract call before
+                            // the statement and replace the call text inline
+                            if (currentParent.type === 'CallExpression' &&
+                                currentParent !== node) {
+                                // This is a nested call - the tracked method is an argument to another call
+                                // Find the containing ExpressionStatement line
+                                let stmtParent = currentParent;
+                                while (stmtParent &&
+                                    stmtParent.type !== 'ExpressionStatement') {
+                                    stmtParent = parentMap.get(stmtParent);
+                                }
+                                if (stmtParent?.type === 'ExpressionStatement') {
+                                    statementType = 'nested_call_expression';
+                                    containingStatementLine = stmtParent.loc?.start.line;
+                                    // Capture the call range - include await if present
+                                    const callNode = hasAwait ? parent : node;
+                                    if (callNode?.range) {
+                                        callRange = {
+                                            start: callNode.range[0],
+                                            end: callNode.range[1],
+                                        };
+                                        callText = this.bubbleScript.substring(callRange.start, callRange.end);
+                                    }
+                                    break;
+                                }
+                            }
+                            if (currentParent.type === 'VariableDeclarator') {
+                                statementType = 'variable_declaration';
+                                if (currentParent.id.type === 'Identifier') {
+                                    variableName = currentParent.id.name;
+                                }
+                                else if (currentParent.id.type === 'ObjectPattern' ||
+                                    currentParent.id.type === 'ArrayPattern') {
+                                    // Extract the destructuring pattern from the source
+                                    const declaratorNode = currentParent;
+                                    const patternRange = declaratorNode.id.range;
+                                    if (patternRange) {
+                                        destructuringPattern = this.bubbleScript.substring(patternRange[0], patternRange[1]);
+                                    }
+                                }
+                                // Continue to find the VariableDeclaration parent to get const/let/var
+                            }
+                            else if (currentParent.type === 'VariableDeclaration') {
+                                // This should only be reached if we found VariableDeclarator first
+                                if (statementType === 'variable_declaration') {
+                                    variableType = currentParent.kind;
+                                    break;
+                                }
+                            }
+                            else if (currentParent.type === 'AssignmentExpression') {
+                                statementType = 'assignment';
+                                if (currentParent.left.type === 'Identifier') {
+                                    variableName = currentParent.left.name;
+                                }
+                                break;
+                            }
+                            else if (currentParent.type === 'ReturnStatement') {
+                                statementType = 'return';
+                                break;
+                            }
+                            // Move up the tree using parent map
+                            currentChild = currentParent;
+                            currentParent = parentMap.get(currentParent);
+                        }
+                        // Skip this invocation if it's inside a complex expression
+                        // Instrumenting these would break the syntax
+                        if (isInComplexExpression) {
+                            return;
+                        }
+                        const invocationIndex = (invocationCounters.get(methodName) ?? 0) + 1;
+                        invocationCounters.set(methodName, invocationIndex);
+                        invocations[methodName].push({
+                            lineNumber,
+                            endLineNumber,
+                            columnNumber,
+                            invocationIndex,
+                            hasAwait,
+                            arguments: args,
+                            statementType,
+                            variableName,
+                            variableType,
+                            destructuringPattern,
+                            context: invocationContext,
+                            containingStatementLine,
+                            callRange,
+                            callText,
+                        });
+                    }
+                }
+            }
+            // Check for await expressions - pass current node as parent
+            if (node.type === 'AwaitExpression' && node.argument) {
+                visitNode(node.argument, node);
+            }
+            // Recursively visit child nodes with parent context
+            this.visitChildNodesForInvocations(node, (child) => visitNode(child, node));
+        };
+        visitNode(ast);
+        return invocations;
+    }
+    /**
+     * Check if a child node is in the condition/test part of a control flow statement
+     * Returns true if the child is the test/discriminant expression, false if it's in the body
+     */
+    isNodeInConditionPart(controlFlowNode, childNode) {
+        if (!childNode)
+            return false;
+        switch (controlFlowNode.type) {
+            case 'IfStatement': {
+                const ifStmt = controlFlowNode;
+                return childNode === ifStmt.test;
+            }
+            case 'WhileStatement': {
+                const whileStmt = controlFlowNode;
+                return childNode === whileStmt.test;
+            }
+            case 'DoWhileStatement': {
+                const doWhileStmt = controlFlowNode;
+                return childNode === doWhileStmt.test;
+            }
+            case 'ForStatement': {
+                const forStmt = controlFlowNode;
+                // ForStatement has init, test, and update - all are condition-like
+                return (childNode === forStmt.init ||
+                    childNode === forStmt.test ||
+                    childNode === forStmt.update);
+            }
+            case 'SwitchStatement': {
+                const switchStmt = controlFlowNode;
+                return childNode === switchStmt.discriminant;
+            }
+            default:
+                return false;
+        }
+    }
+    /**
+     * Helper to recursively visit child nodes for finding invocations
+     */
+    visitChildNodesForInvocations(node, visitor) {
+        const visitValue = (value) => {
+            if (value && typeof value === 'object') {
+                if (Array.isArray(value)) {
+                    value.forEach(visitValue);
+                }
+                else if ('type' in value && typeof value.type === 'string') {
+                    // This is likely an AST node
+                    visitor(value);
+                }
+                else {
+                    // This is a regular object, recurse into its properties
+                    Object.values(value).forEach(visitValue);
+                }
+            }
+        };
+        // Get all property values of the node, excluding metadata properties
+        const nodeObj = node;
+        for (const [key, value] of Object.entries(nodeObj)) {
+            // Skip metadata properties that aren't part of the AST structure
+            if (key === 'parent' || key === 'loc' || key === 'range') {
+                continue;
+            }
+            visitValue(value);
+        }
     }
     /**
      * Recursively visit AST nodes to find bubble instantiations
@@ -772,6 +1149,11 @@ export class BubbleParser {
                     const bubbleNode = this.extractBubbleFromExpression(declarator.init, classNameLookup);
                     if (bubbleNode) {
                         bubbleNode.variableName = nameText;
+                        // Extract comment for this bubble node
+                        const description = this.extractCommentForNode(node);
+                        if (description) {
+                            bubbleNode.description = description;
+                        }
                         // Find the Variable object for this bubble declaration
                         const variable = this.findVariableForBubble(nameText, node, scopeManager);
                         if (variable) {
@@ -794,6 +1176,11 @@ export class BubbleParser {
             if (bubbleNode) {
                 const synthetic = `_anonymous_${bubbleNode.className}_${Object.keys(nodes).length}`;
                 bubbleNode.variableName = synthetic;
+                // Extract comment for this bubble node
+                const description = this.extractCommentForNode(node);
+                if (description) {
+                    bubbleNode.description = description;
+                }
                 // For anonymous bubbles, use negative synthetic ID (no Variable object exists)
                 const syntheticId = -1 * (Object.keys(nodes).length + 1);
                 bubbleNode.variableId = syntheticId;
@@ -822,6 +1209,11 @@ export class BubbleParser {
             if (bubbleNode) {
                 const synthetic = `_anonymous_${bubbleNode.className}_${Object.keys(nodes).length}`;
                 bubbleNode.variableName = synthetic;
+                // Extract comment for this bubble node
+                const description = this.extractCommentForNode(node);
+                if (description) {
+                    bubbleNode.description = description;
+                }
                 const syntheticId = -1 * (Object.keys(nodes).length + 1);
                 bubbleNode.variableId = syntheticId;
                 bubbleNode.parameters = this.addVariableReferencesToParameters(bubbleNode.parameters, node, scopeManager);
@@ -1020,6 +1412,7 @@ export class BubbleParser {
                                 name,
                                 ...value,
                                 location,
+                                source: 'object-property', // Parameter came from an object literal property
                             });
                         }
                     }
@@ -1041,6 +1434,7 @@ export class BubbleParser {
                             name: spreadName,
                             ...value,
                             location,
+                            source: 'spread', // Changed from 'object-property' to 'spread'
                         });
                     }
                 }
@@ -1062,6 +1456,7 @@ export class BubbleParser {
                     name: argName,
                     ...value,
                     location,
+                    source: 'first-arg', // Parameter represents the entire first argument
                 });
             }
         }
@@ -1148,5 +1543,1764 @@ export class BubbleParser {
         // Fallback
         return { value: valueText, type: BubbleParameterType.UNKNOWN };
     }
+    /**
+     * Find custom tools in ai-agent bubbles and populate customToolFuncs.
+     * This scans the AST for ai-agent instantiations and extracts custom tool func locations.
+     */
+    findCustomToolsInAIAgentBubbles(ast, nodes, classNameLookup) {
+        // Get all ai-agent bubbles from nodes
+        const aiAgentBubbles = Object.values(nodes).filter((n) => n.bubbleName === 'ai-agent');
+        if (aiAgentBubbles.length === 0)
+            return;
+        // Helper to find NewExpression nodes in the AST
+        const findNewExpressions = (node, results) => {
+            if (node.type === 'NewExpression') {
+                results.push(node);
+            }
+            for (const key of Object.keys(node)) {
+                if (key === 'parent' || key === 'range' || key === 'loc')
+                    continue;
+                const child = node[key];
+                if (Array.isArray(child)) {
+                    for (const item of child) {
+                        if (item && typeof item === 'object' && 'type' in item) {
+                            findNewExpressions(item, results);
+                        }
+                    }
+                }
+                else if (child && typeof child === 'object' && 'type' in child) {
+                    findNewExpressions(child, results);
+                }
+            }
+        };
+        const allNewExprs = [];
+        findNewExpressions(ast, allNewExprs);
+        // Find NewExpressions that are AIAgentBubble instantiations
+        for (const newExpr of allNewExprs) {
+            if (newExpr.callee.type !== 'Identifier' ||
+                !classNameLookup.has(newExpr.callee.name)) {
+                continue;
+            }
+            const info = classNameLookup.get(newExpr.callee.name);
+            if (!info || info.bubbleName !== 'ai-agent')
+                continue;
+            // Find the corresponding parsed bubble by location
+            const matchingBubble = aiAgentBubbles.find((b) => b.location.startLine === (newExpr.loc?.start.line ?? 0) &&
+                b.location.startCol === (newExpr.loc?.start.column ?? 0));
+            if (!matchingBubble)
+                continue;
+            // Find the customTools property in the first argument
+            if (!newExpr.arguments ||
+                newExpr.arguments.length === 0 ||
+                newExpr.arguments[0].type !== 'ObjectExpression') {
+                continue;
+            }
+            const firstArg = newExpr.arguments[0];
+            const customToolsProp = firstArg.properties.find((p) => p.type === 'Property' &&
+                p.key.type === 'Identifier' &&
+                p.key.name === 'customTools');
+            if (!customToolsProp ||
+                customToolsProp.value.type !== 'ArrayExpression') {
+                continue;
+            }
+            const customToolsArray = customToolsProp.value;
+            // Process each custom tool object
+            for (const element of customToolsArray.elements) {
+                if (!element || element.type !== 'ObjectExpression')
+                    continue;
+                const toolObj = element;
+                // Find name property
+                const nameProp = toolObj.properties.find((p) => p.type === 'Property' &&
+                    p.key.type === 'Identifier' &&
+                    p.key.name === 'name');
+                const toolName = nameProp?.value.type === 'Literal' &&
+                    typeof nameProp.value.value === 'string'
+                    ? nameProp.value.value
+                    : undefined;
+                if (!toolName)
+                    continue;
+                // Find description property
+                const descProp = toolObj.properties.find((p) => p.type === 'Property' &&
+                    p.key.type === 'Identifier' &&
+                    p.key.name === 'description');
+                const description = descProp?.value.type === 'Literal' &&
+                    typeof descProp.value.value === 'string'
+                    ? descProp.value.value
+                    : undefined;
+                // Find func property
+                const funcProp = toolObj.properties.find((p) => p.type === 'Property' &&
+                    p.key.type === 'Identifier' &&
+                    p.key.name === 'func');
+                if (!funcProp)
+                    continue;
+                const funcValue = funcProp.value;
+                if (funcValue.type !== 'ArrowFunctionExpression' &&
+                    funcValue.type !== 'FunctionExpression') {
+                    continue;
+                }
+                const funcExpr = funcValue;
+                // Store the custom tool func info
+                this.customToolFuncs.push({
+                    toolName,
+                    description,
+                    isAsync: funcExpr.async,
+                    startLine: funcExpr.loc?.start.line ?? 0,
+                    endLine: funcExpr.loc?.end.line ?? 0,
+                    startCol: funcExpr.loc?.start.column ?? 0,
+                    endCol: funcExpr.loc?.end.column ?? 0,
+                    parentBubbleVariableId: matchingBubble.variableId,
+                });
+            }
+        }
+    }
+    /**
+     * Mark bubbles that are inside custom tool funcs with isInsideCustomTool flag.
+     */
+    markBubblesInsideCustomTools(nodes) {
+        for (const bubble of Object.values(nodes)) {
+            // Skip ai-agent bubbles themselves
+            if (bubble.bubbleName === 'ai-agent')
+                continue;
+            // Check if this bubble's location falls inside any custom tool func
+            for (const toolFunc of this.customToolFuncs) {
+                if (bubble.location.startLine >= toolFunc.startLine &&
+                    bubble.location.endLine <= toolFunc.endLine) {
+                    bubble.isInsideCustomTool = true;
+                    bubble.containingCustomToolId = `${toolFunc.parentBubbleVariableId}.${toolFunc.toolName}`;
+                    break;
+                }
+            }
+        }
+    }
+    /**
+     * Extract comment/description for a node by looking at preceding comments
+     **/
+    extractCommentForNode(node) {
+        // Get the line number where this node starts
+        const nodeLine = node.loc?.start.line;
+        if (!nodeLine)
+            return undefined;
+        // Split the script into lines to find comments
+        const lines = this.bubbleScript.split('\n');
+        // Look backwards from the node line to find comments
+        const commentLines = [];
+        let currentLine = nodeLine - 1; // Start from the line before the node (0-indexed, but node.loc is 1-indexed)
+        let isBlockComment = false;
+        // Scan backwards to collect comment lines
+        while (currentLine > 0) {
+            const line = lines[currentLine - 1]?.trim(); // Convert to 0-indexed
+            if (!line) {
+                // Empty line - if we already have comments, stop here
+                if (commentLines.length > 0)
+                    break;
+                currentLine--;
+                continue;
+            }
+            // Check for single-line comment (//)
+            if (line.startsWith('//')) {
+                commentLines.unshift(line);
+                currentLine--;
+                continue;
+            }
+            // Check if this line is part of a block comment
+            if (line.startsWith('*') ||
+                line.startsWith('/**') ||
+                line.startsWith('/*')) {
+                commentLines.unshift(line);
+                isBlockComment = true;
+                currentLine--;
+                continue;
+            }
+            // Check if this line ends a block comment
+            if (line.endsWith('*/')) {
+                commentLines.unshift(line);
+                isBlockComment = true;
+                currentLine--;
+                // Continue collecting the rest of the comment block
+                continue;
+            }
+            // If we've already collected some comment lines and hit a non-comment, stop
+            if (commentLines.length > 0) {
+                break;
+            }
+            // Otherwise, this might be code - stop looking
+            break;
+        }
+        if (commentLines.length === 0)
+            return undefined;
+        // Join comment lines and extract the actual text
+        const fullComment = commentLines.join('\n');
+        let cleaned;
+        if (isBlockComment) {
+            // Extract text from JSDoc-style or block comments
+            // Remove /** ... */ or /* ... */ wrappers and clean up
+            cleaned = fullComment
+                .replace(/^\/\*\*?\s*/, '') // Remove opening /** or /*
+                .replace(/\s*\*\/\s*$/, '') // Remove closing */
+                .split('\n')
+                .map((line) => {
+                // Remove leading * and whitespace from each line
+                return line.replace(/^\s*\*\s?/, '').trim();
+            })
+                .filter((line) => line.length > 0) // Remove empty lines
+                .join(' ') // Join into single line
+                .trim();
+        }
+        else {
+            // Handle single-line comments (//)
+            cleaned = fullComment
+                .split('\n')
+                .map((line) => {
+                // Remove leading // and whitespace from each line
+                return line.replace(/^\/\/\s?/, '').trim();
+            })
+                .filter((line) => line.length > 0) // Remove empty lines
+                .join(' ') // Join into single line
+                .trim();
+        }
+        return cleaned || undefined;
+    }
+    /**
+     * Extract JSDoc info including description, @canBeFile, and @canBeGoogleFile tags from a node's preceding comments.
+     * The @canBeFile tag controls whether file upload is enabled for string fields in the UI.
+     * The @canBeGoogleFile tag enables Google Picker UI for Google Drive file/folder ID fields.
+     */
+    extractJSDocForNode(node) {
+        // Get the line number where this node starts
+        const nodeLine = node.loc?.start.line;
+        if (!nodeLine)
+            return {};
+        // Split the script into lines to find comments
+        const lines = this.bubbleScript.split('\n');
+        // Look backwards from the node line to find comments
+        const commentLines = [];
+        let currentLine = nodeLine - 1;
+        let isBlockComment = false;
+        // Scan backwards to collect comment lines
+        while (currentLine > 0) {
+            const line = lines[currentLine - 1]?.trim();
+            if (!line) {
+                if (commentLines.length > 0)
+                    break;
+                currentLine--;
+                continue;
+            }
+            if (line.startsWith('//')) {
+                commentLines.unshift(line);
+                currentLine--;
+                continue;
+            }
+            if (line.startsWith('*') ||
+                line.startsWith('/**') ||
+                line.startsWith('/*')) {
+                commentLines.unshift(line);
+                isBlockComment = true;
+                currentLine--;
+                continue;
+            }
+            if (line.endsWith('*/')) {
+                commentLines.unshift(line);
+                isBlockComment = true;
+                currentLine--;
+                continue;
+            }
+            if (commentLines.length > 0) {
+                break;
+            }
+            break;
+        }
+        if (commentLines.length === 0)
+            return {};
+        const fullComment = commentLines.join('\n');
+        let canBeFile;
+        let canBeGoogleFile;
+        // Parse @canBeFile tag from the raw comment
+        const canBeFileMatch = fullComment.match(/@canBeFile\s+(true|false)/i);
+        if (canBeFileMatch) {
+            canBeFile = canBeFileMatch[1].toLowerCase() === 'true';
+        }
+        // Parse @canBeGoogleFile tag from the raw comment
+        const canBeGoogleFileMatch = fullComment.match(/@canBeGoogleFile\s+(true|false)/i);
+        if (canBeGoogleFileMatch) {
+            canBeGoogleFile = canBeGoogleFileMatch[1].toLowerCase() === 'true';
+        }
+        let description;
+        if (isBlockComment) {
+            description = fullComment
+                .replace(/^\/\*\*?\s*/, '')
+                .replace(/\s*\*\/\s*$/, '')
+                .split('\n')
+                .map((line) => line.replace(/^\s*\*\s?/, '').trim())
+                .filter((line) => line.length > 0 &&
+                !line.startsWith('@canBeFile') &&
+                !line.startsWith('@canBeGoogleFile'))
+                .join(' ')
+                .trim();
+        }
+        else {
+            description = fullComment
+                .split('\n')
+                .map((line) => line.replace(/^\/\/\s?/, '').trim())
+                .filter((line) => line.length > 0 &&
+                !line.startsWith('@canBeFile') &&
+                !line.startsWith('@canBeGoogleFile'))
+                .join(' ')
+                .trim();
+        }
+        return {
+            description: description || undefined,
+            canBeFile,
+            canBeGoogleFile,
+        };
+    }
+    /**
+     * Check if a list of workflow nodes contains a terminating statement (return/throw)
+     * A branch terminates if its last statement is a return or throw
+     */
+    branchTerminates(nodes) {
+        if (nodes.length === 0)
+            return false;
+        const lastNode = nodes[nodes.length - 1];
+        // Check if last node is a return statement
+        if (lastNode.type === 'return') {
+            return true;
+        }
+        // Check if last node is a code block containing return/throw
+        if (lastNode.type === 'code_block') {
+            const code = lastNode.code.trim();
+            return (code.startsWith('return ') ||
+                code.startsWith('return;') ||
+                code === 'return' ||
+                code.startsWith('throw '));
+        }
+        // Check nested control flow - all branches must terminate
+        if (lastNode.type === 'if') {
+            const thenTerminates = this.branchTerminates(lastNode.children);
+            const elseTerminates = lastNode.elseBranch
+                ? this.branchTerminates(lastNode.elseBranch)
+                : false;
+            // Both branches must terminate for the if to terminate
+            return thenTerminates && elseTerminates;
+        }
+        if (lastNode.type === 'try_catch') {
+            const tryTerminates = this.branchTerminates(lastNode.children);
+            const catchTerminates = lastNode.catchBlock
+                ? this.branchTerminates(lastNode.catchBlock)
+                : false;
+            return tryTerminates && catchTerminates;
+        }
+        return false;
+    }
+    /**
+     * Build hierarchical workflow structure from AST
+     */
+    buildWorkflowTree(ast, bubbles, scopeManager) {
+        const handleNode = this.findHandleFunctionNode(ast);
+        if (!handleNode || handleNode.body.type !== 'BlockStatement') {
+            // If no handle method or empty body, return empty workflow
+            return {
+                root: [],
+                bubbles,
+            };
+        }
+        const workflowNodes = [];
+        const bubbleMap = new Map();
+        for (const [id, bubble] of Object.entries(bubbles)) {
+            bubbleMap.set(Number(id), bubble);
+        }
+        // Process statements in handle method body
+        const statements = handleNode.body.body;
+        for (let i = 0; i < statements.length; i++) {
+            const stmt = statements[i];
+            const node = this.buildWorkflowNodeFromStatement(stmt, bubbleMap, scopeManager);
+            if (node) {
+                // Check if this is an if with terminating then branch but no else
+                // In this case, move subsequent statements into implicit else
+                if (node.type === 'if' &&
+                    node.thenTerminates &&
+                    !node.elseBranch &&
+                    i < statements.length - 1) {
+                    // Collect remaining statements as implicit else branch
+                    const implicitElse = [];
+                    for (let j = i + 1; j < statements.length; j++) {
+                        const remainingNode = this.buildWorkflowNodeFromStatement(statements[j], bubbleMap, scopeManager);
+                        if (remainingNode) {
+                            implicitElse.push(remainingNode);
+                        }
+                    }
+                    if (implicitElse.length > 0) {
+                        node.elseBranch = implicitElse;
+                    }
+                    workflowNodes.push(node);
+                    break; // All remaining statements have been moved to else branch
+                }
+                workflowNodes.push(node);
+            }
+        }
+        // Group consecutive nodes of the same type
+        const groupedNodes = this.groupConsecutiveNodes(workflowNodes);
+        return {
+            root: groupedNodes,
+            bubbles,
+        };
+    }
+    /**
+     * Group consecutive nodes of the same type
+     * - Consecutive variable_declaration nodes → merge into one
+     * - Consecutive code_block nodes → merge into one
+     * - return nodes are NOT grouped (each is a distinct exit point)
+     */
+    groupConsecutiveNodes(nodes) {
+        if (nodes.length === 0)
+            return [];
+        const result = [];
+        let currentGroup = [];
+        let currentType = null;
+        for (const node of nodes) {
+            // Control flow nodes break grouping
+            const isControlFlow = node.type === 'if' ||
+                node.type === 'for' ||
+                node.type === 'while' ||
+                node.type === 'try_catch' ||
+                node.type === 'bubble' ||
+                node.type === 'function_call';
+            // Return nodes are never grouped
+            const isReturn = node.type === 'return';
+            // If we hit a control flow node or return, flush current group
+            if (isControlFlow || isReturn) {
+                if (currentGroup.length > 0) {
+                    result.push(...this.mergeGroup(currentGroup, currentType));
+                    currentGroup = [];
+                    currentType = null;
+                }
+                result.push(node);
+                continue;
+            }
+            // Check if this node can be grouped
+            const groupableType = node.type === 'variable_declaration' || node.type === 'code_block';
+            if (groupableType) {
+                // Don't group if node has children (e.g., function calls)
+                const hasChildren = node.children && node.children.length > 0;
+                if (hasChildren) {
+                    // Flush current group and add this node as-is
+                    if (currentGroup.length > 0) {
+                        result.push(...this.mergeGroup(currentGroup, currentType));
+                        currentGroup = [];
+                        currentType = null;
+                    }
+                    result.push(node);
+                }
+                else if (currentType === node.type) {
+                    // Same type, no children, add to group
+                    currentGroup.push(node);
+                }
+                else {
+                    // Different type, flush current group and start new one
+                    if (currentGroup.length > 0) {
+                        result.push(...this.mergeGroup(currentGroup, currentType));
+                    }
+                    currentGroup = [node];
+                    currentType = node.type;
+                }
+            }
+            else {
+                // Not groupable, flush and add as-is
+                if (currentGroup.length > 0) {
+                    result.push(...this.mergeGroup(currentGroup, currentType));
+                    currentGroup = [];
+                    currentType = null;
+                }
+                result.push(node);
+            }
+        }
+        // Flush any remaining group
+        if (currentGroup.length > 0) {
+            result.push(...this.mergeGroup(currentGroup, currentType));
+        }
+        return result;
+    }
+    /**
+     * Merge a group of nodes of the same type into a single node
+     */
+    mergeGroup(group, type) {
+        if (group.length === 0)
+            return [];
+        if (group.length === 1)
+            return group;
+        if (type === 'variable_declaration') {
+            const first = group[0];
+            const allVariables = first.variables.slice();
+            let startLine = first.location.startLine;
+            let startCol = first.location.startCol;
+            let endLine = first.location.endLine;
+            let endCol = first.location.endCol;
+            let code = first.code;
+            for (let i = 1; i < group.length; i++) {
+                const node = group[i];
+                allVariables.push(...node.variables);
+                if (node.location.startLine < startLine) {
+                    startLine = node.location.startLine;
+                    startCol = node.location.startCol;
+                }
+                if (node.location.endLine > endLine) {
+                    endLine = node.location.endLine;
+                    endCol = node.location.endCol;
+                }
+                code += '\n' + node.code;
+            }
+            return [
+                {
+                    type: 'variable_declaration',
+                    location: {
+                        startLine,
+                        startCol,
+                        endLine,
+                        endCol,
+                    },
+                    code,
+                    variables: allVariables,
+                    children: [],
+                },
+            ];
+        }
+        if (type === 'code_block') {
+            const first = group[0];
+            let startLine = first.location.startLine;
+            let startCol = first.location.startCol;
+            let endLine = first.location.endLine;
+            let endCol = first.location.endCol;
+            let code = first.code;
+            for (let i = 1; i < group.length; i++) {
+                const node = group[i];
+                if (node.location.startLine < startLine) {
+                    startLine = node.location.startLine;
+                    startCol = node.location.startCol;
+                }
+                if (node.location.endLine > endLine) {
+                    endLine = node.location.endLine;
+                    endCol = node.location.endCol;
+                }
+                code += '\n' + node.code;
+            }
+            return [
+                {
+                    type: 'code_block',
+                    location: {
+                        startLine,
+                        startCol,
+                        endLine,
+                        endCol,
+                    },
+                    code,
+                    children: [],
+                },
+            ];
+        }
+        // Fallback: return as-is
+        return group;
+    }
+    /**
+     * Build a workflow node from an AST statement
+     */
+    buildWorkflowNodeFromStatement(stmt, bubbleMap, scopeManager) {
+        // Handle IfStatement
+        if (stmt.type === 'IfStatement') {
+            return this.buildIfNode(stmt, bubbleMap, scopeManager);
+        }
+        // Handle ForStatement
+        if (stmt.type === 'ForStatement' ||
+            stmt.type === 'ForInStatement' ||
+            stmt.type === 'ForOfStatement') {
+            return this.buildForNode(stmt, bubbleMap, scopeManager);
+        }
+        // Handle WhileStatement
+        if (stmt.type === 'WhileStatement') {
+            return this.buildWhileNode(stmt, bubbleMap, scopeManager);
+        }
+        // Handle TryStatement
+        if (stmt.type === 'TryStatement') {
+            return this.buildTryCatchNode(stmt, bubbleMap, scopeManager);
+        }
+        // Handle VariableDeclaration - check if it's a bubble, Promise.all, or function call
+        if (stmt.type === 'VariableDeclaration') {
+            for (const decl of stmt.declarations) {
+                if (decl.init) {
+                    // Check if it's Promise.all (supports array destructuring)
+                    const promiseAll = this.detectPromiseAll(decl.init);
+                    if (promiseAll) {
+                        return this.buildParallelExecutionNode(promiseAll, stmt, bubbleMap, scopeManager);
+                    }
+                    // Handle Identifier declarations (const foo = ...)
+                    if (decl.id.type === 'Identifier') {
+                        // Try to find bubble by variable name and location
+                        // This handles same-named variables in different scopes by matching location
+                        const variableName = decl.id.name;
+                        const stmtStartLine = stmt.loc?.start.line ?? 0;
+                        const stmtEndLine = stmt.loc?.end.line ?? 0;
+                        const bubble = Array.from(bubbleMap.values()).find((b) => b.variableName === variableName &&
+                            b.location.startLine >= stmtStartLine &&
+                            b.location.endLine <= stmtEndLine);
+                        if (bubble) {
+                            return {
+                                type: 'bubble',
+                                variableId: bubble.variableId,
+                            };
+                        }
+                        // Check if initializer is a function call
+                        const functionCall = this.detectFunctionCall(decl.init);
+                        if (functionCall) {
+                            // If variable declaration contains a function call, represent it as function_call or transformation_function
+                            // The function call node will contain the full statement code
+                            // Variable declaration is already handled inside buildFunctionCallNode
+                            return this.buildFunctionCallNode(functionCall, stmt, bubbleMap, scopeManager);
+                        }
+                        // Fallback to expression matching for bubbles
+                        const bubbleFromExpr = this.findBubbleInExpression(decl.init, bubbleMap);
+                        if (bubbleFromExpr) {
+                            return {
+                                type: 'bubble',
+                                variableId: bubbleFromExpr.variableId,
+                            };
+                        }
+                    }
+                    else if (decl.id.type === 'ObjectPattern' ||
+                        decl.id.type === 'ArrayPattern') {
+                        // Handle destructuring declarations (const { a, b } = ... or const [a, b] = ...)
+                        // Check if initializer is a function call - transformation functions take precedence
+                        const functionCall = this.detectFunctionCall(decl.init);
+                        if (functionCall) {
+                            // If variable declaration contains a function call, represent it as function_call or transformation_function
+                            // The function call node will contain the full statement code
+                            // Variable declaration is already handled inside buildFunctionCallNode
+                            return this.buildFunctionCallNode(functionCall, stmt, bubbleMap, scopeManager);
+                        }
+                        // Check for bubbles in the expression
+                        const bubbleFromExpr = this.findBubbleInExpression(decl.init, bubbleMap);
+                        if (bubbleFromExpr) {
+                            return {
+                                type: 'bubble',
+                                variableId: bubbleFromExpr.variableId,
+                            };
+                        }
+                    }
+                }
+            }
+            // If not a bubble or function call, create variable declaration node
+            return this.buildVariableDeclarationNode(stmt, bubbleMap, scopeManager);
+        }
+        // Handle ExpressionStatement - check if it's a bubble or function call
+        if (stmt.type === 'ExpressionStatement') {
+            // Handle AssignmentExpression (e.g., agentResponse = await this.method())
+            if (stmt.expression.type === 'AssignmentExpression') {
+                const assignExpr = stmt.expression;
+                // Check if right-hand side is a bubble
+                const bubble = this.findBubbleInExpression(assignExpr.right, bubbleMap);
+                if (bubble) {
+                    return {
+                        type: 'bubble',
+                        variableId: bubble.variableId,
+                    };
+                }
+                // Check if right-hand side is a function call
+                const functionCall = this.detectFunctionCall(assignExpr.right);
+                if (functionCall) {
+                    return this.buildFunctionCallNode(functionCall, stmt, bubbleMap, scopeManager);
+                }
+            }
+            else {
+                // Regular expression (not assignment)
+                const bubble = this.findBubbleInExpression(stmt.expression, bubbleMap);
+                if (bubble) {
+                    return {
+                        type: 'bubble',
+                        variableId: bubble.variableId,
+                    };
+                }
+                // Check for function calls
+                const functionCall = this.detectFunctionCall(stmt.expression);
+                if (functionCall) {
+                    return this.buildFunctionCallNode(functionCall, stmt, bubbleMap, scopeManager);
+                }
+            }
+            // If not a bubble or function call, treat as code block
+            return this.buildCodeBlockNode(stmt, bubbleMap, scopeManager);
+        }
+        // Handle ReturnStatement
+        if (stmt.type === 'ReturnStatement') {
+            if (stmt.argument) {
+                const bubble = this.findBubbleInExpression(stmt.argument, bubbleMap);
+                if (bubble) {
+                    return {
+                        type: 'bubble',
+                        variableId: bubble.variableId,
+                    };
+                }
+                // Check if return value is a function call
+                const functionCall = this.detectFunctionCall(stmt.argument);
+                if (functionCall) {
+                    // Create return node with function call as child
+                    const returnNode = this.buildReturnNode(stmt, bubbleMap, scopeManager);
+                    if (returnNode) {
+                        const funcCallNode = this.buildFunctionCallNode(functionCall, stmt, bubbleMap, scopeManager);
+                        if (funcCallNode) {
+                            returnNode.children = [funcCallNode];
+                        }
+                        return returnNode;
+                    }
+                }
+            }
+            return this.buildReturnNode(stmt, bubbleMap, scopeManager);
+        }
+        // Default: treat as code block
+        return this.buildCodeBlockNode(stmt, bubbleMap, scopeManager);
+    }
+    /**
+     * Build an if node from IfStatement
+     */
+    buildIfNode(stmt, bubbleMap, scopeManager) {
+        const condition = this.extractConditionString(stmt.test);
+        const location = this.extractLocation(stmt);
+        const children = [];
+        if (stmt.consequent.type === 'BlockStatement') {
+            for (const childStmt of stmt.consequent.body) {
+                const node = this.buildWorkflowNodeFromStatement(childStmt, bubbleMap, scopeManager);
+                if (node) {
+                    children.push(node);
+                }
+            }
+        }
+        else {
+            // Single statement (no braces)
+            const node = this.buildWorkflowNodeFromStatement(stmt.consequent, bubbleMap, scopeManager);
+            if (node) {
+                children.push(node);
+            }
+        }
+        const elseBranch = stmt.alternate
+            ? (() => {
+                if (stmt.alternate.type === 'BlockStatement') {
+                    const nodes = [];
+                    for (const childStmt of stmt.alternate.body) {
+                        const node = this.buildWorkflowNodeFromStatement(childStmt, bubbleMap, scopeManager);
+                        if (node) {
+                            nodes.push(node);
+                        }
+                    }
+                    return nodes;
+                }
+                else if (stmt.alternate.type === 'IfStatement') {
+                    // else if - treat as nested if
+                    const node = this.buildIfNode(stmt.alternate, bubbleMap, scopeManager);
+                    return [node];
+                }
+                else {
+                    // Single statement else
+                    const node = this.buildWorkflowNodeFromStatement(stmt.alternate, bubbleMap, scopeManager);
+                    return node ? [node] : [];
+                }
+            })()
+            : undefined;
+        // Check if branches terminate (contain return/throw)
+        const thenTerminates = this.branchTerminates(children);
+        const elseTerminates = elseBranch
+            ? this.branchTerminates(elseBranch)
+            : false;
+        return {
+            type: 'if',
+            location,
+            condition,
+            children,
+            elseBranch,
+            thenTerminates: thenTerminates || undefined,
+            elseTerminates: elseTerminates || undefined,
+        };
+    }
+    /**
+     * Build a for node from ForStatement/ForInStatement/ForOfStatement
+     */
+    buildForNode(stmt, bubbleMap, scopeManager) {
+        const location = this.extractLocation(stmt);
+        let condition;
+        if (stmt.type === 'ForStatement') {
+            const init = stmt.init
+                ? this.bubbleScript.substring(stmt.init.range[0], stmt.init.range[1])
+                : '';
+            const test = stmt.test
+                ? this.bubbleScript.substring(stmt.test.range[0], stmt.test.range[1])
+                : '';
+            const update = stmt.update
+                ? this.bubbleScript.substring(stmt.update.range[0], stmt.update.range[1])
+                : '';
+            condition = `${init}; ${test}; ${update}`.trim();
+        }
+        else if (stmt.type === 'ForInStatement') {
+            const left = this.bubbleScript.substring(stmt.left.range[0], stmt.left.range[1]);
+            const right = this.bubbleScript.substring(stmt.right.range[0], stmt.right.range[1]);
+            condition = `${left} in ${right}`;
+        }
+        else if (stmt.type === 'ForOfStatement') {
+            const left = this.bubbleScript.substring(stmt.left.range[0], stmt.left.range[1]);
+            const right = this.bubbleScript.substring(stmt.right.range[0], stmt.right.range[1]);
+            condition = `${left} of ${right}`;
+        }
+        const children = [];
+        if (stmt.body.type === 'BlockStatement') {
+            for (const childStmt of stmt.body.body) {
+                const node = this.buildWorkflowNodeFromStatement(childStmt, bubbleMap, scopeManager);
+                if (node) {
+                    children.push(node);
+                }
+            }
+        }
+        else {
+            // Single statement (no braces)
+            const node = this.buildWorkflowNodeFromStatement(stmt.body, bubbleMap, scopeManager);
+            if (node) {
+                children.push(node);
+            }
+        }
+        return {
+            type: stmt.type === 'ForOfStatement' ? 'for' : 'for',
+            location,
+            condition,
+            children,
+        };
+    }
+    /**
+     * Build a while node from WhileStatement
+     */
+    buildWhileNode(stmt, bubbleMap, scopeManager) {
+        const location = this.extractLocation(stmt);
+        const condition = this.extractConditionString(stmt.test);
+        const children = [];
+        if (stmt.body.type === 'BlockStatement') {
+            for (const childStmt of stmt.body.body) {
+                const node = this.buildWorkflowNodeFromStatement(childStmt, bubbleMap, scopeManager);
+                if (node) {
+                    children.push(node);
+                }
+            }
+        }
+        else {
+            // Single statement (no braces)
+            const node = this.buildWorkflowNodeFromStatement(stmt.body, bubbleMap, scopeManager);
+            if (node) {
+                children.push(node);
+            }
+        }
+        return {
+            type: 'while',
+            location,
+            condition,
+            children,
+        };
+    }
+    /**
+     * Build a try-catch node from TryStatement
+     */
+    buildTryCatchNode(stmt, bubbleMap, scopeManager) {
+        const location = this.extractLocation(stmt);
+        const children = [];
+        if (stmt.block.type === 'BlockStatement') {
+            for (const childStmt of stmt.block.body) {
+                const node = this.buildWorkflowNodeFromStatement(childStmt, bubbleMap, scopeManager);
+                if (node) {
+                    children.push(node);
+                }
+            }
+        }
+        const catchBlock = stmt.handler
+            ? (() => {
+                if (stmt.handler.body.type === 'BlockStatement') {
+                    const nodes = [];
+                    for (const childStmt of stmt.handler.body.body) {
+                        const node = this.buildWorkflowNodeFromStatement(childStmt, bubbleMap, scopeManager);
+                        if (node) {
+                            nodes.push(node);
+                        }
+                    }
+                    return nodes;
+                }
+                return [];
+            })()
+            : undefined;
+        return {
+            type: 'try_catch',
+            location,
+            children,
+            catchBlock,
+        };
+    }
+    /**
+     * Build a code block node from a statement
+     */
+    buildCodeBlockNode(stmt, bubbleMap, scopeManager) {
+        const location = this.extractLocation(stmt);
+        if (!location)
+            return null;
+        const code = this.bubbleScript.substring(stmt.range[0], stmt.range[1]);
+        // Check for nested structures
+        const children = [];
+        if (stmt.type === 'BlockStatement') {
+            for (const childStmt of stmt.body) {
+                const node = this.buildWorkflowNodeFromStatement(childStmt, bubbleMap, scopeManager);
+                if (node) {
+                    children.push(node);
+                }
+            }
+        }
+        return {
+            type: 'code_block',
+            location,
+            code,
+            children,
+        };
+    }
+    /**
+     * Find a bubble in an expression by checking if it matches any parsed bubble
+     */
+    findBubbleInExpression(expr, bubbleMap) {
+        if (!expr.loc)
+            return null;
+        // Extract the NewExpression from the expression (handles await, .action(), etc.)
+        const newExpr = this.extractNewExpression(expr);
+        if (!newExpr || !newExpr.loc)
+            return null;
+        // Match by NewExpression location (this is what bubbles are stored with)
+        for (const bubble of bubbleMap.values()) {
+            // Check if the NewExpression location overlaps with bubble location
+            // Use a tolerance for column matching since the exact column might differ slightly
+            if (bubble.location.startLine === newExpr.loc.start.line &&
+                bubble.location.endLine === newExpr.loc.end.line &&
+                Math.abs(bubble.location.startCol - newExpr.loc.start.column) <= 5) {
+                return bubble;
+            }
+        }
+        return null;
+    }
+    /**
+     * Extract the NewExpression from an expression, handling await, .action(), etc.
+     */
+    extractNewExpression(expr) {
+        // Handle await new X()
+        if (expr.type === 'AwaitExpression' && expr.argument) {
+            return this.extractNewExpression(expr.argument);
+        }
+        // Handle new X().action()
+        if (expr.type === 'CallExpression' &&
+            expr.callee.type === 'MemberExpression') {
+            if (expr.callee.object) {
+                return this.extractNewExpression(expr.callee.object);
+            }
+        }
+        // Direct NewExpression
+        if (expr.type === 'NewExpression') {
+            return expr;
+        }
+        return null;
+    }
+    /**
+     * Build a variable declaration node from a VariableDeclaration statement
+     */
+    buildVariableDeclarationNode(stmt, _bubbleMap, _scopeManager) {
+        const location = this.extractLocation(stmt);
+        if (!location)
+            return null;
+        const code = this.bubbleScript.substring(stmt.range[0], stmt.range[1]);
+        const variables = [];
+        for (const decl of stmt.declarations) {
+            if (decl.id.type === 'Identifier') {
+                variables.push({
+                    name: decl.id.name,
+                    type: stmt.kind,
+                    hasInitializer: decl.init !== null && decl.init !== undefined,
+                });
+            }
+        }
+        return {
+            type: 'variable_declaration',
+            location,
+            code,
+            variables,
+            children: [],
+        };
+    }
+    /**
+     * Build a return node from a ReturnStatement
+     */
+    buildReturnNode(stmt, _bubbleMap, _scopeManager) {
+        const location = this.extractLocation(stmt);
+        if (!location)
+            return null;
+        const code = this.bubbleScript.substring(stmt.range[0], stmt.range[1]);
+        const value = stmt.argument
+            ? this.bubbleScript.substring(stmt.argument.range[0], stmt.argument.range[1])
+            : undefined;
+        return {
+            type: 'return',
+            location,
+            code,
+            value,
+            children: [],
+        };
+    }
+    /**
+     * Detect if an expression is Promise.all([...]) or Promise.all(variable)
+     */
+    detectPromiseAll(expr) {
+        // Handle await Promise.all([...])
+        let callExpr = null;
+        if (expr.type === 'AwaitExpression' && expr.argument) {
+            if (expr.argument.type === 'CallExpression') {
+                callExpr = expr.argument;
+            }
+        }
+        else if (expr.type === 'CallExpression') {
+            callExpr = expr;
+        }
+        if (!callExpr)
+            return null;
+        // Check if it's Promise.all
+        const callee = callExpr.callee;
+        if (callee.type === 'MemberExpression' &&
+            callee.object.type === 'Identifier' &&
+            callee.object.name === 'Promise' &&
+            callee.property.type === 'Identifier' &&
+            callee.property.name === 'all') {
+            // Check if the first argument is an array or variable
+            if (callExpr.arguments.length > 0) {
+                const arg = callExpr.arguments[0];
+                if (arg.type === 'ArrayExpression') {
+                    return {
+                        callExpr,
+                        arrayExpr: arg,
+                    };
+                }
+                if (arg.type === 'Identifier') {
+                    return {
+                        callExpr,
+                        arrayExpr: arg,
+                    };
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Detect if an expression is a function call
+     */
+    detectFunctionCall(expr) {
+        // Handle await functionCall()
+        let callExpr = null;
+        if (expr.type === 'AwaitExpression' && expr.argument) {
+            if (expr.argument.type === 'CallExpression') {
+                callExpr = expr.argument;
+            }
+        }
+        else if (expr.type === 'CallExpression') {
+            callExpr = expr;
+        }
+        if (!callExpr)
+            return null;
+        const callee = callExpr.callee;
+        let functionName = null;
+        let isMethodCall = false;
+        if (callee.type === 'Identifier') {
+            // Direct function call: functionName()
+            functionName = callee.name;
+            isMethodCall = false;
+        }
+        else if (callee.type === 'MemberExpression') {
+            // Method call: this.methodName() or obj.methodName()
+            if (callee.object.type === 'ThisExpression' &&
+                callee.property.type === 'Identifier') {
+                functionName = callee.property.name;
+                isMethodCall = true;
+            }
+            else if (callee.property.type === 'Identifier') {
+                functionName = callee.property.name;
+                isMethodCall = false; // External method call, not this.method()
+            }
+        }
+        if (!functionName)
+            return null;
+        const args = callExpr.arguments
+            .map((arg) => this.bubbleScript.substring(arg.range[0], arg.range[1]))
+            .join(', ');
+        return {
+            functionName,
+            isMethodCall,
+            arguments: args,
+            callExpr,
+        };
+    }
+    /**
+     * Find a method definition in the class by name
+     */
+    findMethodDefinition(methodName, ast) {
+        const mainClass = this.findMainBubbleFlowClass(ast);
+        if (!mainClass || !mainClass.body)
+            return null;
+        for (const member of mainClass.body.body) {
+            if (member.type === 'MethodDefinition' &&
+                member.key.type === 'Identifier' &&
+                member.key.name === methodName &&
+                member.value.type === 'FunctionExpression') {
+                const func = member.value;
+                const body = func.body.type === 'BlockStatement' ? func.body : null;
+                const isAsync = func.async || false;
+                const parameters = func.params
+                    .map((param) => {
+                    if (param.type === 'Identifier')
+                        return param.name;
+                    if (param.type === 'AssignmentPattern' &&
+                        param.left.type === 'Identifier')
+                        return param.left.name;
+                    return '';
+                })
+                    .filter((name) => name !== '');
+                return {
+                    method: member,
+                    body,
+                    isAsync,
+                    parameters,
+                };
+            }
+        }
+        return null;
+    }
+    /**
+     * Check if a workflow node tree contains any bubbles (recursively)
+     */
+    containsBubbles(nodes) {
+        for (const node of nodes) {
+            if (node.type === 'bubble') {
+                return true;
+            }
+            // Check children recursively
+            if ('children' in node && Array.isArray(node.children)) {
+                if (this.containsBubbles(node.children)) {
+                    return true;
+                }
+            }
+            // Check elseBranch for if statements
+            if (node.type === 'if' && node.elseBranch) {
+                if (this.containsBubbles(node.elseBranch)) {
+                    return true;
+                }
+            }
+            // Check catchBlock for try_catch
+            if (node.type === 'try_catch' && node.catchBlock) {
+                if (this.containsBubbles(node.catchBlock)) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+    /**
+     * Build a function call node from a function call expression
+     */
+    buildFunctionCallNode(callInfo, stmt, bubbleMap, scopeManager) {
+        const location = this.extractLocation(stmt);
+        if (!location)
+            return null;
+        const code = this.bubbleScript.substring(stmt.range[0], stmt.range[1]);
+        // Try to find method definition if it's a method call
+        let methodDefinition = undefined;
+        const methodChildren = [];
+        const children = [];
+        let description = undefined;
+        const methodBubbleMap = new Map();
+        if (callInfo.isMethodCall && this.cachedAST) {
+            const methodDef = this.findMethodDefinition(callInfo.functionName, this.cachedAST);
+            if (methodDef && methodDef.body) {
+                methodDefinition = {
+                    location: {
+                        startLine: methodDef.method.loc?.start.line || 0,
+                        endLine: methodDef.method.loc?.end.line || 0,
+                    },
+                    isAsync: methodDef.isAsync,
+                    parameters: methodDef.parameters,
+                };
+                // Extract description from method comments
+                description = this.extractCommentForNode(methodDef.method);
+                // Filter bubbleMap to only include bubbles within this method's scope
+                const methodStartLine = methodDef.method.loc?.start.line || 0;
+                const methodEndLine = methodDef.method.loc?.end.line || 0;
+                for (const [id, bubble] of bubbleMap.entries()) {
+                    // Include bubble if it's within the method's line range
+                    if (bubble.location.startLine >= methodStartLine &&
+                        bubble.location.endLine <= methodEndLine) {
+                        methodBubbleMap.set(id, bubble);
+                    }
+                }
+                // Recursively build workflow nodes from method body
+                for (const childStmt of methodDef.body.body) {
+                    const node = this.buildWorkflowNodeFromStatement(childStmt, methodBubbleMap, scopeManager);
+                    if (node) {
+                        methodChildren.push(node);
+                    }
+                }
+            }
+        }
+        const shouldTrackInvocation = callInfo.isMethodCall && !!methodDefinition;
+        // Pass the call expression's start offset to deduplicate when the same call
+        // is processed multiple times (e.g., .map() callback processing vs Promise.all resolution)
+        const callExprStartOffset = callInfo.callExpr.range?.[0];
+        const invocationIndex = shouldTrackInvocation
+            ? this.getNextInvocationIndex(callInfo.functionName, callExprStartOffset)
+            : 0;
+        const callSiteKey = shouldTrackInvocation && invocationIndex > 0
+            ? buildCallSiteKey(callInfo.functionName, invocationIndex)
+            : null;
+        const invocationCloneMap = callSiteKey !== null ? new Map() : null;
+        const fallbackCallSiteKey = `${callInfo.functionName}:${location.startLine}:${location.startCol}`;
+        if (methodChildren.length > 0) {
+            if (callSiteKey && methodBubbleMap.size > 0 && invocationCloneMap) {
+                const clonedMethodChildren = this.cloneWorkflowNodesForInvocation(methodChildren, callSiteKey, methodBubbleMap, invocationCloneMap);
+                children.push(...clonedMethodChildren);
+            }
+            else {
+                children.push(...methodChildren);
+            }
+        }
+        // After method definition processing, check for callback arguments
+        if (callInfo.callExpr && callInfo.callExpr.arguments.length > 0) {
+            for (const arg of callInfo.callExpr.arguments) {
+                if (arg.type === 'ArrowFunctionExpression' ||
+                    arg.type === 'FunctionExpression') {
+                    const callbackBody = this.extractCallbackBody(arg);
+                    if (callbackBody && callbackBody.length > 0) {
+                        const callbackStartLine = arg.loc?.start.line || 0;
+                        const callbackEndLine = arg.loc?.end.line || 0;
+                        const callbackBubbleMap = new Map();
+                        for (const [id, bubble] of bubbleMap.entries()) {
+                            if (bubble.location.startLine >= callbackStartLine &&
+                                bubble.location.endLine <= callbackEndLine) {
+                                callbackBubbleMap.set(id, bubble);
+                            }
+                        }
+                        const callbackNodes = [];
+                        for (const callbackStmt of callbackBody) {
+                            const node = this.buildWorkflowNodeFromStatement(callbackStmt, callbackBubbleMap, scopeManager);
+                            if (node) {
+                                callbackNodes.push(node);
+                            }
+                        }
+                        if (callSiteKey && callbackNodes.length > 0 && invocationCloneMap) {
+                            const clonedCallbacks = this.cloneWorkflowNodesForInvocation(callbackNodes, callSiteKey, callbackBubbleMap, invocationCloneMap);
+                            children.push(...clonedCallbacks);
+                        }
+                        else {
+                            children.push(...callbackNodes);
+                        }
+                    }
+                }
+            }
+        }
+        // Check if this function call contains any bubbles
+        // Only create transformation_function if:
+        // 1. It's a method call (this.methodName())
+        // 2. A method definition was found (method exists in class)
+        // 3. It has no bubbles in its children
+        if (callInfo.isMethodCall &&
+            methodDefinition &&
+            !this.containsBubbles(children)) {
+            // Get the entire method body code
+            let fullCode = code;
+            if (this.cachedAST) {
+                const methodDef = this.findMethodDefinition(callInfo.functionName, this.cachedAST);
+                if (methodDef && methodDef.body) {
+                    // Extract the entire method body code
+                    fullCode = this.bubbleScript.substring(methodDef.body.range[0], methodDef.body.range[1]);
+                }
+            }
+            const idKey = callSiteKey ?? fallbackCallSiteKey;
+            const variableId = hashToVariableId(idKey);
+            const transformationNode = {
+                type: 'transformation_function',
+                location,
+                code: fullCode,
+                functionName: callInfo.functionName,
+                isMethodCall: callInfo.isMethodCall,
+                description,
+                arguments: callInfo.arguments,
+                variableId,
+                methodDefinition,
+            };
+            // Add variable declaration if present
+            if (stmt.type === 'VariableDeclaration' && stmt.declarations.length > 0) {
+                const decl = stmt.declarations[0];
+                if (decl.id.type === 'Identifier') {
+                    transformationNode.variableDeclaration = {
+                        variableName: decl.id.name,
+                        variableType: stmt.kind,
+                    };
+                }
+            }
+            else if (stmt.type === 'ExpressionStatement' &&
+                stmt.expression.type === 'AssignmentExpression' &&
+                stmt.expression.left.type === 'Identifier') {
+                transformationNode.variableDeclaration = {
+                    variableName: stmt.expression.left.name,
+                    variableType: 'let', // Assignment implies let/var, default to let
+                };
+            }
+            return transformationNode;
+        }
+        const variableId = hashToVariableId(callSiteKey ?? fallbackCallSiteKey);
+        const functionCallNode = {
+            type: 'function_call',
+            location,
+            functionName: callInfo.functionName,
+            isMethodCall: callInfo.isMethodCall,
+            description,
+            arguments: callInfo.arguments,
+            code,
+            variableId,
+            methodDefinition,
+            children,
+        };
+        // Add variable declaration if present
+        if (stmt.type === 'VariableDeclaration' && stmt.declarations.length > 0) {
+            const decl = stmt.declarations[0];
+            if (decl.id.type === 'Identifier') {
+                functionCallNode.variableDeclaration = {
+                    variableName: decl.id.name,
+                    variableType: stmt.kind,
+                };
+            }
+        }
+        else if (stmt.type === 'ExpressionStatement' &&
+            stmt.expression.type === 'AssignmentExpression' &&
+            stmt.expression.left.type === 'Identifier') {
+            functionCallNode.variableDeclaration = {
+                variableName: stmt.expression.left.name,
+                variableType: 'let', // Assignment implies let/var, default to let
+            };
+        }
+        return functionCallNode;
+    }
+    /**
+     * Extract the body of a callback function (arrow or regular function expression)
+     * Handles both block statements and concise arrow functions
+     */
+    extractCallbackBody(func) {
+        // Handle block statement body: (x) => { statements }
+        if (func.body.type === 'BlockStatement') {
+            return func.body.body;
+        }
+        // Handle concise arrow function: (x) => expression
+        // Convert expression to a synthetic return statement
+        const syntheticReturn = {
+            type: AST_NODE_TYPES.ReturnStatement,
+            argument: func.body,
+            range: func.body.range,
+            loc: func.body.loc,
+            parent: func,
+        };
+        return [syntheticReturn];
+    }
+    /**
+     * Find array elements from .push() calls or .map() callbacks
+     * Handles both patterns:
+     * - .push(): array.push(item1, item2, ...)
+     * - .map(): const promises = items.map(item => this.processItem(item))
+     */
+    findArrayElements(arrayVarName, ast, contextLine, scopeManager) {
+        const elements = [];
+        const varId = this.findVariableIdByName(arrayVarName, contextLine, scopeManager);
+        if (varId === undefined)
+            return elements;
+        const walk = (node) => {
+            // Handle .push() calls: array.push(item1, item2, ...)
+            if (node.type === 'CallExpression' &&
+                node.callee.type === 'MemberExpression' &&
+                node.callee.property.type === 'Identifier' &&
+                node.callee.property.name === 'push' &&
+                node.callee.object.type === 'Identifier' &&
+                node.callee.object.name === arrayVarName) {
+                const callLine = node.loc?.start.line || 0;
+                if (this.findVariableIdByName(arrayVarName, callLine, scopeManager) ===
+                    varId) {
+                    node.arguments.forEach((arg) => {
+                        elements.push(arg);
+                    });
+                }
+            }
+            // Handle .map() calls: const promises = items.map(item => ...)
+            if (node.type === 'VariableDeclaration') {
+                for (const decl of node.declarations) {
+                    if (decl.id.type === 'Identifier' &&
+                        decl.id.name === arrayVarName &&
+                        decl.init &&
+                        decl.init.type === 'CallExpression' &&
+                        decl.init.callee.type === 'MemberExpression' &&
+                        decl.init.callee.property.type === 'Identifier' &&
+                        decl.init.callee.property.name === 'map') {
+                        const declLine = node.loc?.start.line || 0;
+                        if (this.findVariableIdByName(arrayVarName, declLine, scopeManager) === varId) {
+                            if (decl.init.arguments.length > 0) {
+                                const callback = decl.init.arguments[0];
+                                const callbackExpr = this.extractCallbackExpression(callback);
+                                if (callbackExpr) {
+                                    const sourceArray = decl.init.callee.object;
+                                    const sourceElements = this.getSourceArrayElements(sourceArray, ast, declLine, scopeManager);
+                                    // Create one expression per source element, or single fallback
+                                    const count = sourceElements?.length || 1;
+                                    for (let i = 0; i < count; i++) {
+                                        elements.push(callbackExpr);
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            for (const key in node) {
+                const child = node[key];
+                if (Array.isArray(child))
+                    child.forEach(walk);
+                else if (child?.type)
+                    walk(child);
+            }
+        };
+        walk(ast);
+        return elements;
+    }
+    /**
+     * Extract expression from callback function
+     */
+    extractCallbackExpression(callback) {
+        if (callback.type === 'ArrowFunctionExpression' &&
+            callback.body.type !== 'BlockStatement') {
+            return callback.body;
+        }
+        if ((callback.type === 'ArrowFunctionExpression' ||
+            callback.type === 'FunctionExpression') &&
+            callback.body.type === 'BlockStatement') {
+            const returns = this.findReturnStatements(callback.body);
+            return returns[0]?.argument;
+        }
+        return null;
+    }
+    /**
+     * Get elements from source array (literal or variable)
+     */
+    getSourceArrayElements(sourceArray, ast, contextLine, scopeManager) {
+        if (sourceArray.type === 'ArrayExpression') {
+            return sourceArray.elements.filter((el) => el !== null && el.type !== 'SpreadElement');
+        }
+        if (sourceArray.type === 'Identifier') {
+            const varId = this.findVariableIdByName(sourceArray.name, contextLine, scopeManager);
+            if (varId === undefined)
+                return null;
+            const walk = (node) => {
+                if (node.type === 'VariableDeclaration') {
+                    for (const decl of node.declarations) {
+                        if (decl.id.type === 'Identifier' &&
+                            decl.id.name === sourceArray.name &&
+                            decl.init?.type === 'ArrayExpression' &&
+                            this.findVariableIdByName(sourceArray.name, node.loc?.start.line || 0, scopeManager) === varId) {
+                            return decl.init.elements.filter((el) => el !== null && el.type !== 'SpreadElement');
+                        }
+                    }
+                }
+                for (const key in node) {
+                    const child = node[key];
+                    if (Array.isArray(child)) {
+                        for (const c of child) {
+                            const result = walk(c);
+                            if (result)
+                                return result;
+                        }
+                    }
+                    else if (child?.type) {
+                        const result = walk(child);
+                        if (result)
+                            return result;
+                    }
+                }
+                return null;
+            };
+            return walk(ast);
+        }
+        return null;
+    }
+    /**
+     * Find all return statements in a block statement
+     */
+    findReturnStatements(block) {
+        const returns = [];
+        const walk = (node) => {
+            if (node.type === 'ReturnStatement') {
+                returns.push(node);
+            }
+            for (const key in node) {
+                const child = node[key];
+                if (Array.isArray(child))
+                    child.forEach(walk);
+                else if (child?.type)
+                    walk(child);
+            }
+        };
+        walk(block);
+        return returns;
+    }
+    /**
+     * Build a parallel execution node from Promise.all()
+     */
+    buildParallelExecutionNode(promiseAllInfo, stmt, bubbleMap, scopeManager) {
+        const location = this.extractLocation(stmt);
+        if (!location)
+            return null;
+        const code = this.bubbleScript.substring(stmt.range[0], stmt.range[1]);
+        const children = [];
+        // Handle variable reference (e.g., Promise.all(exampleScrapers))
+        if (promiseAllInfo.arrayExpr.type === 'Identifier' && this.cachedAST) {
+            const arrayVarName = promiseAllInfo.arrayExpr.name;
+            const contextLine = promiseAllInfo.arrayExpr.loc?.start.line || 0;
+            const pushedArgs = this.findArrayElements(arrayVarName, this.cachedAST, contextLine, scopeManager);
+            for (const arg of pushedArgs) {
+                const methodCall = this.detectFunctionCall(arg);
+                if (methodCall) {
+                    const syntheticStmt = {
+                        type: AST_NODE_TYPES.ExpressionStatement,
+                        expression: methodCall.callExpr,
+                        range: arg.range,
+                        loc: arg.loc,
+                        parent: stmt,
+                    };
+                    const funcCallNode = this.buildFunctionCallNode(methodCall, syntheticStmt, bubbleMap, scopeManager);
+                    if (funcCallNode)
+                        children.push(funcCallNode);
+                }
+                else {
+                    const bubble = this.findBubbleInExpression(arg, bubbleMap);
+                    if (bubble) {
+                        children.push({ type: 'bubble', variableId: bubble.variableId });
+                    }
+                }
+            }
+        }
+        else if (promiseAllInfo.arrayExpr.type === 'ArrayExpression') {
+            // Handle direct array literal (existing logic)
+            for (const element of promiseAllInfo.arrayExpr.elements) {
+                if (!element || element.type === 'SpreadElement')
+                    continue;
+                const bubble = this.findBubbleInExpression(element, bubbleMap);
+                if (bubble) {
+                    children.push({ type: 'bubble', variableId: bubble.variableId });
+                    continue;
+                }
+                const functionCall = this.detectFunctionCall(element);
+                if (functionCall) {
+                    const syntheticStmt = {
+                        type: AST_NODE_TYPES.ExpressionStatement,
+                        expression: functionCall.callExpr,
+                        range: element.range,
+                        loc: element.loc,
+                        parent: stmt,
+                    };
+                    const funcCallNode = this.buildFunctionCallNode(functionCall, syntheticStmt, bubbleMap, scopeManager);
+                    if (funcCallNode)
+                        children.push(funcCallNode);
+                }
+            }
+        }
+        // Extract variable declaration info if this is part of a variable declaration
+        let variableDeclaration;
+        if (stmt.type === 'VariableDeclaration' &&
+            stmt.declarations.length > 0 &&
+            stmt.declarations[0].id.type === 'ArrayPattern') {
+            const arrayPattern = stmt.declarations[0].id;
+            const variableNames = [];
+            for (const element of arrayPattern.elements) {
+                if (element && element.type === 'Identifier') {
+                    variableNames.push(element.name);
+                }
+            }
+            variableDeclaration = {
+                variableNames,
+                variableType: stmt.kind,
+            };
+        }
+        return {
+            type: 'parallel_execution',
+            location,
+            code,
+            variableDeclaration,
+            children,
+        };
+    }
+    /**
+     * Get the invocation index for a method call.
+     * If the same call expression (identified by its AST range) has been processed before,
+     * return the same index to avoid double-counting.
+     *
+     * @param methodName - The name of the method being called
+     * @param callExprStartOffset - Optional start offset of the CallExpression in the source.
+     *                              Used to deduplicate when the same call is processed multiple times
+     *                              (e.g., .map() callback processing vs Promise.all resolution)
+     */
+    getNextInvocationIndex(methodName, callExprStartOffset) {
+        // Check if this specific call site has already been indexed
+        if (callExprStartOffset !== undefined) {
+            const callSiteId = `${methodName}:${callExprStartOffset}`;
+            const existingIndex = this.processedCallSiteIndexes.get(callSiteId);
+            if (existingIndex !== undefined) {
+                return existingIndex;
+            }
+            // New call site - assign next index and cache it
+            const next = (this.methodInvocationOrdinalMap.get(methodName) ?? 0) + 1;
+            this.methodInvocationOrdinalMap.set(methodName, next);
+            this.processedCallSiteIndexes.set(callSiteId, next);
+            return next;
+        }
+        // Fallback: no offset provided, just increment (legacy behavior)
+        const next = (this.methodInvocationOrdinalMap.get(methodName) ?? 0) + 1;
+        this.methodInvocationOrdinalMap.set(methodName, next);
+        return next;
+    }
+    cloneWorkflowNodesForInvocation(nodes, callSiteKey, bubbleSourceMap, localCloneMap) {
+        return nodes.map((node) => this.cloneWorkflowNodeForInvocation(node, callSiteKey, bubbleSourceMap, localCloneMap));
+    }
+    cloneWorkflowNodeForInvocation(node, callSiteKey, bubbleSourceMap, localCloneMap) {
+        if (node.type === 'bubble') {
+            const originalId = Number(node.variableId);
+            const clonedId = this.ensureClonedBubbleForInvocation(originalId, callSiteKey, bubbleSourceMap, localCloneMap);
+            return { ...node, variableId: clonedId };
+        }
+        const clonedNode = { ...node };
+        if ('children' in node && Array.isArray(node.children)) {
+            clonedNode.children = node.children.map((child) => this.cloneWorkflowNodeForInvocation(child, callSiteKey, bubbleSourceMap, localCloneMap));
+        }
+        if ('elseBranch' in node && Array.isArray(node.elseBranch)) {
+            clonedNode.elseBranch = node.elseBranch.map((child) => this.cloneWorkflowNodeForInvocation(child, callSiteKey, bubbleSourceMap, localCloneMap));
+        }
+        if ('catchBlock' in node && Array.isArray(node.catchBlock)) {
+            clonedNode.catchBlock = node.catchBlock.map((child) => this.cloneWorkflowNodeForInvocation(child, callSiteKey, bubbleSourceMap, localCloneMap));
+        }
+        return clonedNode;
+    }
+    ensureClonedBubbleForInvocation(originalId, callSiteKey, bubbleSourceMap, localCloneMap) {
+        const existing = localCloneMap.get(originalId);
+        if (existing) {
+            return existing;
+        }
+        const sourceBubble = bubbleSourceMap.get(originalId);
+        if (!sourceBubble) {
+            return originalId;
+        }
+        const clonedId = this.cloneBubbleForInvocation(sourceBubble, callSiteKey, bubbleSourceMap);
+        localCloneMap.set(originalId, clonedId);
+        return clonedId;
+    }
+    cloneBubbleForInvocation(bubble, callSiteKey, bubbleSourceMap) {
+        const cacheKey = `${bubble.variableId}:${callSiteKey}`;
+        const existing = this.invocationBubbleCloneCache.get(cacheKey);
+        if (existing) {
+            return existing.variableId;
+        }
+        const clonedBubble = {
+            ...bubble,
+            variableId: hashToVariableId(cacheKey),
+            invocationCallSiteKey: callSiteKey,
+            clonedFromVariableId: bubble.variableId,
+            parameters: JSON.parse(JSON.stringify(bubble.parameters)),
+            dependencyGraph: bubble.dependencyGraph
+                ? this.cloneDependencyGraphNodeForInvocation(bubble.dependencyGraph, callSiteKey)
+                : undefined,
+        };
+        /**
+         * Also clone any bubbles that are referenced inside this bubble's
+         * dependencyGraph.functionCallChildren (e.g. bubbles instantiated
+         * inside AI agent customTools).
+         *
+         * This ensures that nested bubbles inside custom tools participate
+         * in per-invocation cloning just like top-level workflow bubbles:
+         * - They get their own cloned ParsedBubbleWithInfo entry
+         * - clonedFromVariableId points back to the original id
+         * - invocationCallSiteKey is set
+         * - Their dependencyGraph is cloned with per-invocation uniqueId/variableId
+         *
+         * We then rewrite the functionCallChildren children variableIds in the
+         * cloned dependencyGraph to point at the cloned bubble ids so that
+         * __bubbleInvocationDependencyGraphs[callSiteKey][originalId] contains
+         * a fully self-consistent graph for this invocation.
+         */
+        if (bubble.dependencyGraph &&
+            bubble.dependencyGraph.functionCallChildren &&
+            Array.isArray(bubble.dependencyGraph.functionCallChildren)) {
+            const clonedDepGraph = clonedBubble.dependencyGraph;
+            if (clonedDepGraph &&
+                Array.isArray(clonedDepGraph.functionCallChildren)) {
+                clonedDepGraph.functionCallChildren =
+                    clonedDepGraph.functionCallChildren.map((funcCallNode) => {
+                        if (!Array.isArray(funcCallNode.children)) {
+                            return funcCallNode;
+                        }
+                        const clonedChildren = funcCallNode.children.map((child) => {
+                            if (!child ||
+                                child.type !== 'bubble' ||
+                                typeof child.variableId !== 'number') {
+                                return child;
+                            }
+                            const originalChildId = child.variableId;
+                            const sourceChild = bubbleSourceMap.get(originalChildId);
+                            if (!sourceChild) {
+                                return child;
+                            }
+                            const clonedChildId = this.cloneBubbleForInvocation(sourceChild, callSiteKey, bubbleSourceMap);
+                            return {
+                                ...child,
+                                variableId: clonedChildId,
+                            };
+                        });
+                        return {
+                            ...funcCallNode,
+                            children: clonedChildren,
+                        };
+                    });
+            }
+        }
+        this.invocationBubbleCloneCache.set(cacheKey, clonedBubble);
+        return clonedBubble.variableId;
+    }
+    cloneDependencyGraphNodeForInvocation(node, callSiteKey) {
+        const uniqueId = node.uniqueId
+            ? `${node.uniqueId}@${callSiteKey}`
+            : undefined;
+        const variableId = typeof node.variableId === 'number'
+            ? hashToVariableId(`${node.variableId}:${callSiteKey}`)
+            : undefined;
+        return {
+            ...node,
+            uniqueId,
+            variableId,
+            dependencies: node.dependencies.map((child) => this.cloneDependencyGraphNodeForInvocation(child, callSiteKey)),
+        };
+    }
+    /**
+     * Extract condition string from a test expression
+     */
+    extractConditionString(test) {
+        return this.bubbleScript.substring(test.range[0], test.range[1]);
+    }
+    /**
+     * Extract location from a node
+     */
+    extractLocation(node) {
+        if (!node.loc) {
+            return { startLine: 0, startCol: 0, endLine: 0, endCol: 0 };
+        }
+        return {
+            startLine: node.loc.start.line,
+            startCol: node.loc.start.column,
+            endLine: node.loc.end.line,
+            endCol: node.loc.end.column,
+        };
+    }
 }
 //# sourceMappingURL=BubbleParser.js.map