Automate browser based workflows with AI
Python aiapiautomationbrowserbrowser-automationcomputergptllmplaywrightpowerautomatepuppeteerpythonrpaseleniumvisionworkflow
feat(SKY-8771): backend WhileLoopBlock (PR 1 of 7) (#5703)
Shuchang Zheng75baa8b9b405
diff --git a/skyvern/forge/sdk/db/repositories/workflows.py b/skyvern/forge/sdk/db/repositories/workflows.pyindex 3ff63b70b..0b8710510 100644--- a/skyvern/forge/sdk/db/repositories/workflows.py+++ b/skyvern/forge/sdk/db/repositories/workflows.py@@ -30,7 +30,7 @@ from skyvern.forge.sdk.db.models import ()from skyvern.forge.sdk.db.repositories.workflow_parameters import WorkflowParametersRepositoryfrom skyvern.forge.sdk.db.utils import convert_to_workflow, serialize_proxy_location-from skyvern.forge.sdk.workflow.models.block import Block, ForLoopBlock+from skyvern.forge.sdk.workflow.models.block import Block, ForLoopBlock, WhileLoopBlockfrom skyvern.forge.sdk.workflow.models.parameter import OutputParameterfrom skyvern.forge.sdk.workflow.models.workflow import Workflow, WorkflowDefinitionfrom skyvern.schemas.runs import ProxyLocationInput@@ -41,8 +41,8 @@ LOG = structlog.get_logger()def _align_block_output_parameters(workflow_definition: WorkflowDefinition) -> None:"""Rebind each block's ``output_parameter`` to the reconciled instance- from ``workflow_definition.parameters`` by key, recursing into- ``ForLoopBlock.loop_blocks``.+ from ``workflow_definition.parameters`` by key, recursing into nested+ loop block children.The reconcile helper mutates IDs on the top-level parameters list only.When a caller round-trips the definition through@@ -62,7 +62,7 @@ def _align_block_output_parameters(workflow_definition: WorkflowDefinition) -> Ncanonical = key_to_output_parameter.get(block.output_parameter.key)if canonical is not None and canonical is not block.output_parameter:block.output_parameter = canonical- if isinstance(block, ForLoopBlock):+ if isinstance(block, (ForLoopBlock, WhileLoopBlock)):_visit(block.loop_blocks)_visit(workflow_definition.blocks)diff --git a/skyvern/forge/sdk/routes/workflow_copilot.py b/skyvern/forge/sdk/routes/workflow_copilot.pyindex a3d9524b1..8f9d95a04 100644--- a/skyvern/forge/sdk/routes/workflow_copilot.py+++ b/skyvern/forge/sdk/routes/workflow_copilot.py@@ -56,6 +56,7 @@ from skyvern.schemas.workflows import (ConditionalBlockYAML,ForLoopBlockYAML,LoginBlockYAML,+ WhileLoopBlockYAML,WorkflowCreateYAMLRequest,WorkflowDefinitionYAML,)@@ -833,13 +834,13 @@ def _repair_next_block_label_chain(blocks: list[BlockYAML]) -> None:1. Circular references — breaks cycles so the chain has a proper terminal block.2. Disconnected paths — stitches orphaned blocks onto the end of the reachable chain.- Recursively repairs nested ForLoopBlockYAML.loop_blocks at all depths.+ Recursively repairs nested loop block ``loop_blocks`` at all depths.Mutates *blocks* in place."""if len(blocks) <= 1:# Still recurse into loop_blocks even for single-block listsfor block in blocks:- if isinstance(block, ForLoopBlockYAML) and block.loop_blocks:+ if isinstance(block, (ForLoopBlockYAML, WhileLoopBlockYAML)) and block.loop_blocks:_repair_next_block_label_chain(block.loop_blocks)return@@ -877,9 +878,9 @@ def _repair_next_block_label_chain(blocks: list[BlockYAML]) -> None:if terminal_label and ordered_orphan_labels:label_to_block[terminal_label].next_block_label = ordered_orphan_labels[0]- # Phase 3: recursively repair nested ForLoopBlockYAML.loop_blocks.+ # Phase 3: recursively repair nested loop block ``loop_blocks``.for block in blocks:- if isinstance(block, ForLoopBlockYAML) and block.loop_blocks:+ if isinstance(block, (ForLoopBlockYAML, WhileLoopBlockYAML)) and block.loop_blocks:_repair_next_block_label_chain(block.loop_blocks)diff --git a/skyvern/forge/sdk/workflow/models/block.py b/skyvern/forge/sdk/workflow/models/block.pyindex 9d762a5dd..4db4d7460 100644--- a/skyvern/forge/sdk/workflow/models/block.py+++ b/skyvern/forge/sdk/workflow/models/block.py@@ -2004,14 +2004,14 @@ class ForLoopBlock(Block):"""Validate the loop_blocks graph for cycles, orphans, and dangling references.Skips sequential defaulting so that disconnected subgraphs are detected.- Also recursively validates any nested ForLoopBlock children.+ Also recursively validates any nested loop block children.Raises InvalidWorkflowDefinition (422) on validation failure."""if not self.loop_blocks:returnself._build_loop_graph(self.loop_blocks, skip_sequential_defaulting=True)for block in self.loop_blocks:- if isinstance(block, ForLoopBlock):+ if isinstance(block, (ForLoopBlock, WhileLoopBlock)):block.validate_loop_blocks()async def _persist_partial_loop_output(@@ -2521,6 +2521,651 @@ class ForLoopBlock(Block):)+class WhileLoopBlock(Block):+ """Loop block driven by a runtime condition. Iterates while ``condition`` evaluates truthy.++ Top-of-loop semantics: the condition is evaluated *before* each iteration (including the+ first). If the condition is false on the first check, the body never runs and the block+ returns success with an empty output list.++ Safety: the loop is capped at ``DEFAULT_MAX_LOOP_ITERATIONS`` (100). Reaching the cap is+ treated as a failure so that a misbehaving condition can never spin forever.+ """++ block_type: Literal[BlockType.WHILE_LOOP] = BlockType.WHILE_LOOP # type: ignore++ loop_blocks: list[BlockTypeVar]+ # The discriminated union on ``criteria_type`` handles dict→typed coercion. Pydantic+ # rejects a dict missing ``criteria_type`` with ``union_tag_not_found`` before any+ # model_validator runs, so no extra coercion validator is needed here.+ condition: BranchCriteriaTypeVar++ def get_all_parameters(+ self,+ workflow_run_id: str,+ ) -> list[PARAMETER_TYPE]:+ parameters: set[PARAMETER_TYPE] = set()+ for loop_block in self.loop_blocks:+ for parameter in loop_block.get_all_parameters(workflow_run_id):+ parameters.add(parameter)+ return list(parameters)++ def _build_loop_graph(+ self,+ blocks: list[BlockTypeVar],+ skip_sequential_defaulting: bool = False,+ ) -> tuple[str, dict[str, BlockTypeVar], dict[str, str | None]]:+ # Duplicated from ForLoopBlock._build_loop_graph for PR 1; promotion to a shared+ # helper is tracked in PR 7 (refactor).+ label_to_block: dict[str, BlockTypeVar] = {}+ default_next_map: dict[str, str | None] = {}++ for block in blocks:+ if block.label in label_to_block:+ raise InvalidWorkflowDefinition(f"Duplicate block label detected in loop: {block.label}")+ label_to_block[block.label] = block+ default_next_map[block.label] = block.next_block_label++ if not skip_sequential_defaulting:+ has_conditional_blocks = any(block.block_type == BlockType.CONDITIONAL for block in blocks)+ if not has_conditional_blocks:+ for idx, block in enumerate(blocks[:-1]):+ if default_next_map.get(block.label) is None:+ default_next_map[block.label] = blocks[idx + 1].label++ adjacency: dict[str, set[str]] = {label: set() for label in label_to_block}+ incoming: dict[str, int] = {label: 0 for label in label_to_block}++ def _add_edge(source: str, target: str | None) -> None:+ if not target:+ return+ if target not in label_to_block:+ raise InvalidWorkflowDefinition(+ f"Block {source} references unknown next_block_label {target} inside loop {self.label}"+ )+ if target not in adjacency[source]:+ adjacency[source].add(target)+ incoming[target] += 1++ for label, block in label_to_block.items():+ if block.block_type == BlockType.CONDITIONAL:+ for branch in block.ordered_branches:+ _add_edge(label, branch.next_block_label)+ else:+ _add_edge(label, default_next_map.get(label))++ roots = [label for label, count in incoming.items() if count == 0]+ if not roots:+ raise InvalidWorkflowDefinition(+ f"Circular reference detected inside loop {self.label}: every block is the target of another"+ " block's next_block_label, so there is no starting block."+ " At least one block must not be the target of any next_block_label or branch condition."+ )+ if len(roots) > 1:+ raise InvalidWorkflowDefinition(+ f"Disconnected blocks detected inside loop {self.label}: blocks"+ f" ({', '.join(sorted(roots))}) are not reachable from any other block."+ " Every block must be reachable from the first block through next_block_label or"+ " conditional branch references."+ " Either connect them by setting another block's next_block_label to point to them, or remove them."+ )++ queue: deque[str] = deque([roots[0]])+ visited_count = 0+ in_degree = dict(incoming)+ while queue:+ node = queue.popleft()+ visited_count += 1+ for neighbor in adjacency[node]:+ in_degree[neighbor] -= 1+ if in_degree[neighbor] == 0:+ queue.append(neighbor)++ if visited_count != len(label_to_block):+ raise InvalidWorkflowDefinition(+ f"Circular reference detected inside loop {self.label}: some blocks form a loop through their"+ " next_block_label references, causing an infinite cycle."+ " Ensure that following next_block_label from any block eventually reaches a block"+ " with next_block_label set to null."+ )++ return roots[0], label_to_block, default_next_map++ def validate_loop_blocks(self) -> None:+ """Validate the loop_blocks graph and recurse into nested loop blocks."""+ if not self.loop_blocks:+ return+ self._build_loop_graph(self.loop_blocks, skip_sequential_defaulting=True)+ for block in self.loop_blocks:+ if isinstance(block, (ForLoopBlock, WhileLoopBlock)):+ block.validate_loop_blocks()++ async def _persist_partial_loop_output(+ self,+ workflow_run_id: str,+ outputs_with_loop_values: list[list[dict[str, Any]]],+ loop_idx: int,+ ) -> None:+ """Persist partial while-loop output to DB so accumulated iteration data survives+ Temporal activity timeouts. Mirrors ``ForLoopBlock._persist_partial_loop_output``.+ """+ if not self.output_parameter:+ return+ try:+ await app.DATABASE.workflow_runs.create_or_update_workflow_run_output_parameter(+ workflow_run_id=workflow_run_id,+ output_parameter_id=self.output_parameter.output_parameter_id,+ value=outputs_with_loop_values,+ )+ except Exception:+ LOG.warning(+ "Failed to incrementally persist while-loop output",+ workflow_run_id=workflow_run_id,+ output_parameter_id=self.output_parameter.output_parameter_id,+ loop_idx=loop_idx,+ exc_info=True,+ )++ async def _evaluate_condition(+ self,+ workflow_run_context: WorkflowRunContext,+ ) -> bool:+ """Evaluate the loop condition. Raises on rendering errors so the caller can convert+ the failure into a block result with a clear message."""+ evaluation_context = BranchEvaluationContext(+ workflow_run_context=workflow_run_context,+ block_label=self.label,+ template_renderer=lambda potential_template: self.format_block_parameter_template_from_workflow_run_context(+ potential_template,+ workflow_run_context,+ ),+ )+ return await self.condition.evaluate(evaluation_context)++ async def _execute_while_loop_helper(+ self,+ workflow_run_id: str,+ workflow_run_block_id: str,+ workflow_run_context: WorkflowRunContext,+ organization_id: str | None = None,+ browser_session_id: str | None = None,+ ) -> LoopBlockExecutedResult:+ outputs_with_loop_values: list[list[dict[str, Any]]] = []+ block_outputs: list[BlockResult] = []+ current_block: BlockTypeVar | None = None++ start_label, label_to_block, default_next_map = self._build_loop_graph(self.loop_blocks)+ conditional_scopes = compute_conditional_scopes(label_to_block, default_next_map)++ loop_idx = 0+ while True:+ # Evaluate the condition at the top of every iteration (including the first).+ # The cap check fires *after* the condition check so that a loop which would+ # naturally exit on the (cap+1)-th check returns success rather than tripping+ # the cap one iteration early.+ #+ # Condition rendering errors always terminate the loop, regardless of+ # ``next_loop_on_failure``. The flag governs *body* failures (which can vary+ # iteration to iteration), but a Jinja render error means the condition itself+ # is malformed and will fail identically on the next iteration — there is no+ # forward progress to be made by retrying.+ try:+ should_continue = await self._evaluate_condition(workflow_run_context)+ except (FailedToFormatJinjaStyleParameter, MissingJinjaVariables) as exc:+ LOG.error(+ "WhileLoopBlock condition evaluation failed",+ workflow_run_id=workflow_run_id,+ block_label=self.label,+ error=str(exc),+ )+ failure_block_result = await self.build_block_result(+ success=False,+ status=BlockStatus.failed,+ failure_reason=f"Failed to evaluate while-loop condition: {str(exc)}",+ workflow_run_block_id=workflow_run_block_id,+ organization_id=organization_id,+ )+ block_outputs.append(failure_block_result)+ await self._persist_partial_loop_output(workflow_run_id, outputs_with_loop_values, loop_idx)+ return LoopBlockExecutedResult(+ outputs_with_loop_values=outputs_with_loop_values,+ block_outputs=block_outputs,+ last_block=current_block,+ )++ if not should_continue:+ LOG.info(+ "WhileLoopBlock condition is false, exiting loop",+ workflow_run_id=workflow_run_id,+ loop_idx=loop_idx,+ )+ await self._persist_partial_loop_output(workflow_run_id, outputs_with_loop_values, loop_idx)+ break++ # Check max_iterations limit: only fires when the condition is still true at+ # iteration index ``cap``, i.e. the loop would have run a (cap+1)-th body.+ if loop_idx >= DEFAULT_MAX_LOOP_ITERATIONS:+ LOG.info(+ "WhileLoopBlock reached max_iterations limit, stopping loop",+ workflow_run_id=workflow_run_id,+ loop_idx=loop_idx,+ max_iterations=DEFAULT_MAX_LOOP_ITERATIONS,+ )+ failure_block_result = await self.build_block_result(+ success=False,+ status=BlockStatus.failed,+ failure_reason=f"Reached max_loop_iterations limit of {DEFAULT_MAX_LOOP_ITERATIONS}",+ workflow_run_block_id=workflow_run_block_id,+ organization_id=organization_id,+ )+ block_outputs.append(failure_block_result)+ await self._persist_partial_loop_output(workflow_run_id, outputs_with_loop_values, loop_idx)+ return LoopBlockExecutedResult(+ outputs_with_loop_values=outputs_with_loop_values,+ block_outputs=block_outputs,+ last_block=current_block,+ )++ # Capture baseline downloaded files for per-iteration scoping (SKY-7005)+ loop_context = skyvern_context.current()+ if loop_context:+ downloaded_file_sigs_before: list[tuple[str | None, str | None, str | None]] = []+ baseline_timed_out = False+ try:+ async with asyncio.timeout(GET_DOWNLOADED_FILES_TIMEOUT):+ downloaded_file_sigs_before = [+ to_downloaded_file_signature(fi)+ for fi in await app.STORAGE.get_downloaded_files(+ organization_id=organization_id or "",+ run_id=loop_context.run_id if loop_context.run_id else workflow_run_id,+ )+ ]+ except asyncio.TimeoutError:+ baseline_timed_out = True+ LOG.warning(+ "Timeout getting baseline downloaded files for loop iteration",+ workflow_run_id=workflow_run_id,+ loop_idx=loop_idx,+ )+ if baseline_timed_out:+ loop_context.loop_internal_state = None+ else:+ loop_context.loop_internal_state = {+ DOWNLOADED_FILE_SIGS_KEY: downloaded_file_sigs_before,+ }++ each_loop_output_values: list[dict[str, Any]] = []++ iteration_step_count = 0+ LOG.debug(+ "WhileLoopBlock starting iteration",+ workflow_run_id=workflow_run_id,+ loop_idx=loop_idx,+ max_steps_per_iteration=DEFAULT_MAX_STEPS_PER_ITERATION,+ )++ block_idx = 0+ current_label: str | None = start_label+ conditional_wrb_ids: dict[str, str] = {}+ while current_label:+ loop_block = label_to_block.get(current_label)+ if not loop_block:+ LOG.error(+ "Unable to find loop block with label in loop graph",+ workflow_run_id=workflow_run_id,+ loop_label=self.label,+ current_label=current_label,+ )+ failure_block_result = await self.build_block_result(+ success=False,+ status=BlockStatus.failed,+ failure_reason=f"Unable to find block with label {current_label} inside loop {self.label}",+ workflow_run_block_id=workflow_run_block_id,+ organization_id=organization_id,+ )+ block_outputs.append(failure_block_result)+ outputs_with_loop_values.append(each_loop_output_values)+ await self._persist_partial_loop_output(workflow_run_id, outputs_with_loop_values, loop_idx)+ return LoopBlockExecutedResult(+ outputs_with_loop_values=outputs_with_loop_values,+ block_outputs=block_outputs,+ last_block=current_block,+ )++ # ``current_value`` and ``current_item`` are explicitly nulled to defend+ # against the SKY-8835 leakage pattern: ``update_block_metadata`` merges+ # rather than replaces, so an outer for_loop's per-iteration values would+ # otherwise linger on this label's bag and bleed into child Jinja+ # expressions. Setting them to None overwrites the stale entries cleanly,+ # and child templates that reference ``current_value``/``current_item``+ # will render None rather than leak the outer loop's data.+ metadata: BlockMetadata = {+ "current_index": loop_idx,+ "current_value": None,+ "current_item": None,+ }+ workflow_run_context.update_block_metadata(self.label, metadata)+ workflow_run_context.update_block_metadata(loop_block.label, metadata)++ original_loop_block = loop_block+ loop_block = loop_block.model_copy(deep=True)+ current_block = loop_block++ parent_wrb_id = workflow_run_block_id+ if current_label in conditional_scopes:+ cond_label = conditional_scopes[current_label]+ if cond_label in conditional_wrb_ids:+ parent_wrb_id = conditional_wrb_ids[cond_label]++ # ``current_value`` is intentionally None: while_loop has no per-iteration+ # value to display in the timeline. ``current_index`` carries the iteration+ # counter, which is the only meaningful per-iteration data.+ block_output = await loop_block.execute_safe(+ workflow_run_id=workflow_run_id,+ parent_workflow_run_block_id=parent_wrb_id,+ organization_id=organization_id,+ browser_session_id=browser_session_id,+ current_value=None,+ current_index=loop_idx,+ )++ if loop_block.block_type == BlockType.CONDITIONAL and block_output.workflow_run_block_id:+ conditional_wrb_ids[current_label] = block_output.workflow_run_block_id++ output_value = (+ workflow_run_context.get_value(block_output.output_parameter.key)+ if workflow_run_context.has_value(block_output.output_parameter.key)+ else None+ )++ if block_output.output_parameter.key.endswith("_output"):+ LOG.debug("Block output", block_type=loop_block.block_type, output_value=output_value)++ if loop_block.block_type == BlockType.GOTO_URL:+ LOG.info("Goto URL block executed", url=loop_block.url, loop_idx=loop_idx)++ each_loop_output_values.append(+ {+ "output_parameter": block_output.output_parameter,+ "output_value": output_value,+ }+ )++ try:+ if block_output.workflow_run_block_id:+ await app.DATABASE.observer.update_workflow_run_block(+ workflow_run_block_id=block_output.workflow_run_block_id,+ organization_id=organization_id,+ current_value=None,+ current_index=loop_idx,+ )+ except Exception:+ LOG.warning(+ "Failed to update workflow run block",+ workflow_run_block_id=block_output.workflow_run_block_id,+ loop_idx=loop_idx,+ )+ loop_block = original_loop_block+ block_outputs.append(block_output)++ iteration_step_count += 1+ if iteration_step_count >= DEFAULT_MAX_STEPS_PER_ITERATION:+ LOG.info(+ "WhileLoopBlock reached max_steps_per_iteration limit, stopping iteration",+ workflow_run_id=workflow_run_id,+ loop_idx=loop_idx,+ max_steps_per_iteration=DEFAULT_MAX_STEPS_PER_ITERATION,+ iteration_step_count=iteration_step_count,+ )+ failure_block_result = await self.build_block_result(+ success=False,+ status=BlockStatus.failed,+ failure_reason=f"Reached max_steps_per_iteration limit of {DEFAULT_MAX_STEPS_PER_ITERATION}",+ workflow_run_block_id=workflow_run_block_id,+ organization_id=organization_id,+ )+ block_outputs.append(failure_block_result)+ if not self.next_loop_on_failure:+ outputs_with_loop_values.append(each_loop_output_values)+ await self._persist_partial_loop_output(workflow_run_id, outputs_with_loop_values, loop_idx)+ return LoopBlockExecutedResult(+ outputs_with_loop_values=outputs_with_loop_values,+ block_outputs=block_outputs,+ last_block=current_block,+ )+ break++ if block_output.status == BlockStatus.canceled:+ LOG.info(+ "WhileLoopBlock child block canceled, canceling while loop",+ block_type=loop_block.block_type,+ workflow_run_id=workflow_run_id,+ block_idx=block_idx,+ loop_idx=loop_idx,+ block_result=block_outputs,+ )+ outputs_with_loop_values.append(each_loop_output_values)+ await self._persist_partial_loop_output(workflow_run_id, outputs_with_loop_values, loop_idx)+ return LoopBlockExecutedResult(+ outputs_with_loop_values=outputs_with_loop_values,+ block_outputs=block_outputs,+ last_block=current_block,+ )++ if (+ not block_output.success+ and not loop_block.continue_on_failure+ and not loop_block.next_loop_on_failure+ and not self.next_loop_on_failure+ ):+ LOG.info(+ "WhileLoopBlock encountered a failure processing block, terminating early",+ block_outputs=block_outputs,+ loop_idx=loop_idx,+ block_idx=block_idx,+ loop_block_continue_on_failure=loop_block.continue_on_failure,+ failure_reason=block_output.failure_reason,+ next_loop_on_failure=loop_block.next_loop_on_failure or self.next_loop_on_failure,+ )+ outputs_with_loop_values.append(each_loop_output_values)+ await self._persist_partial_loop_output(workflow_run_id, outputs_with_loop_values, loop_idx)+ return LoopBlockExecutedResult(+ outputs_with_loop_values=outputs_with_loop_values,+ block_outputs=block_outputs,+ last_block=current_block,+ )++ if block_output.success or loop_block.continue_on_failure:+ next_label: str | None = None+ if loop_block.block_type == BlockType.CONDITIONAL:+ branch_metadata = (+ block_output.output_parameter_value+ if isinstance(block_output.output_parameter_value, dict)+ else None+ )+ next_label = (branch_metadata or {}).get("next_block_label")+ else:+ next_label = default_next_map.get(loop_block.label)++ if not next_label:+ break++ if next_label not in label_to_block:+ failure_block_result = await self.build_block_result(+ success=False,+ status=BlockStatus.failed,+ failure_reason=f"Next block label {next_label} not found inside loop {self.label}",+ workflow_run_block_id=workflow_run_block_id,+ organization_id=organization_id,+ )+ block_outputs.append(failure_block_result)+ outputs_with_loop_values.append(each_loop_output_values)+ await self._persist_partial_loop_output(workflow_run_id, outputs_with_loop_values, loop_idx)+ return LoopBlockExecutedResult(+ outputs_with_loop_values=outputs_with_loop_values,+ block_outputs=block_outputs,+ last_block=current_block,+ )++ current_label = next_label+ block_idx += 1+ continue++ if loop_block.next_loop_on_failure or self.next_loop_on_failure:+ LOG.info(+ "WhileLoopBlock child block failed but will continue to next iteration",+ block_outputs=block_outputs,+ loop_idx=loop_idx,+ block_idx=block_idx,+ loop_block_next_loop_on_failure=loop_block.next_loop_on_failure or self.next_loop_on_failure,+ )+ break++ break++ outputs_with_loop_values.append(each_loop_output_values)+ # We don't know "is_last_iteration" for a while-loop ahead of time, so persist+ # every PERSIST_LOOP_OUTPUT_INTERVAL iterations and once again at the top of the+ # next iteration when the condition is false (handled at the break above).+ if loop_idx % PERSIST_LOOP_OUTPUT_INTERVAL == 0:+ await self._persist_partial_loop_output(workflow_run_id, outputs_with_loop_values, loop_idx)++ loop_idx += 1++ return LoopBlockExecutedResult(+ outputs_with_loop_values=outputs_with_loop_values,+ block_outputs=block_outputs,+ last_block=current_block,+ )++ async def execute(+ self,+ workflow_run_id: str,+ workflow_run_block_id: str,+ organization_id: str | None = None,+ browser_session_id: str | None = None,+ **kwargs: dict,+ ) -> BlockResult:+ # Save the caller's loop_internal_state so we can restore it after this loop+ # finishes. Mirrors ForLoopBlock.execute.+ outer_context = skyvern_context.current()+ outer_loop_state = outer_context.loop_internal_state if outer_context else None+ try:+ return await self._run_loop(+ workflow_run_id=workflow_run_id,+ workflow_run_block_id=workflow_run_block_id,+ organization_id=organization_id,+ browser_session_id=browser_session_id,+ **kwargs,+ )+ finally:+ if outer_context:+ outer_context.loop_internal_state = outer_loop_state++ async def _run_loop(+ self,+ workflow_run_id: str,+ workflow_run_block_id: str,+ organization_id: str | None = None,+ browser_session_id: str | None = None,+ **kwargs: dict,+ ) -> BlockResult:+ workflow_run_context = self.get_workflow_run_context(workflow_run_id)++ if isinstance(self.condition, PromptBranchCriteria):+ # Prompt criteria support is deferred to a follow-up PR; the prompt evaluator+ # is currently coupled to ConditionalBlock. Reject explicitly so the user gets+ # a clear, actionable error rather than a silent fall-through.+ return await self.build_block_result(+ success=False,+ failure_reason=(+ "Prompt criteria are not yet supported in while_loop blocks. "+ "Use a Jinja2 expression like '{{ should_continue }}' instead."+ ),+ status=BlockStatus.failed,+ workflow_run_block_id=workflow_run_block_id,+ organization_id=organization_id,+ )++ if not self.loop_blocks:+ LOG.info(+ "No defined blocks to loop, terminating block",+ block_type=self.block_type,+ workflow_run_id=workflow_run_id,+ num_loop_blocks=len(self.loop_blocks),+ )+ await self.record_output_parameter_value(workflow_run_context, workflow_run_id, [])+ return await self.build_block_result(+ success=False,+ failure_reason="No defined blocks to loop",+ status=BlockStatus.terminated,+ workflow_run_block_id=workflow_run_block_id,+ organization_id=organization_id,+ )++ try:+ loop_executed_result = await self._execute_while_loop_helper(+ workflow_run_id=workflow_run_id,+ workflow_run_block_id=workflow_run_block_id,+ workflow_run_context=workflow_run_context,+ organization_id=organization_id,+ browser_session_id=browser_session_id,+ )+ except InvalidWorkflowDefinition as exc:+ LOG.error(+ "While-loop graph validation failed",+ error=str(exc),+ workflow_run_id=workflow_run_id,+ loop_label=self.label,+ )+ return await self.build_block_result(+ success=False,+ failure_reason=str(exc),+ status=BlockStatus.failed,+ workflow_run_block_id=workflow_run_block_id,+ organization_id=organization_id,+ )++ await self.record_output_parameter_value(+ workflow_run_context, workflow_run_id, loop_executed_result.outputs_with_loop_values+ )++ # Special case: condition false on the very first check. The body never ran, so+ # there are no block_outputs. Return success with an empty output list — this is+ # the normal/expected "nothing to do" path for a while-loop.+ if not loop_executed_result.block_outputs:+ return await self.build_block_result(+ success=True,+ failure_reason=None,+ output_parameter_value=loop_executed_result.outputs_with_loop_values,+ status=BlockStatus.completed,+ workflow_run_block_id=workflow_run_block_id,+ organization_id=organization_id,+ )++ block_status = BlockStatus.failed+ success = False++ if loop_executed_result.is_canceled():+ block_status = BlockStatus.canceled+ elif loop_executed_result.is_completed():+ block_status = BlockStatus.completed+ success = True+ elif loop_executed_result.is_terminated():+ block_status = BlockStatus.terminated+ else:+ block_status = BlockStatus.failed++ return await self.build_block_result(+ success=success,+ failure_reason=loop_executed_result.get_failure_reason(),+ output_parameter_value=loop_executed_result.outputs_with_loop_values,+ status=block_status,+ workflow_run_block_id=workflow_run_block_id,+ organization_id=organization_id,+ )++class Credential(SimpleNamespace):pass@@ -7367,8 +8012,8 @@ def get_all_blocks(blocks: list[BlockTypeVar]) -> list[BlockTypeVar]:"""Recursively get "all blocks" in a workflow definition.- At time of writing, blocks can be nested via the ForLoop block. This function- returns all blocks, flattened.+ Blocks can be nested via ForLoop and WhileLoop blocks. This function returns+ all blocks, flattened."""all_blocks: list[BlockTypeVar] = []@@ -7376,7 +8021,7 @@ def get_all_blocks(blocks: list[BlockTypeVar]) -> list[BlockTypeVar]:for block in blocks:all_blocks.append(block)- if block.block_type == BlockType.FOR_LOOP:+ if block.block_type in (BlockType.FOR_LOOP, BlockType.WHILE_LOOP):nested_blocks = get_all_blocks(block.loop_blocks)all_blocks.extend(nested_blocks)@@ -7392,6 +8037,7 @@ from skyvern.forge.sdk.workflow.models.google_sheets_blocks import ( # noqa: E4BlockSubclasses = Union[ConditionalBlock,ForLoopBlock,+ WhileLoopBlock,TaskBlock,CodeBlock,TextPromptBlock,diff --git a/skyvern/forge/sdk/workflow/models/workflow.py b/skyvern/forge/sdk/workflow/models/workflow.pyindex 3f0701929..7d21f9aab 100644--- a/skyvern/forge/sdk/workflow/models/workflow.py+++ b/skyvern/forge/sdk/workflow/models/workflow.py@@ -13,7 +13,7 @@ from skyvern.forge.sdk.workflow.exceptions import (NonTerminalFinallyBlock,WorkflowDefinitionHasDuplicateBlockLabels,)-from skyvern.forge.sdk.workflow.models.block import BlockTypeVar, ForLoopBlock, get_all_blocks+from skyvern.forge.sdk.workflow.models.block import BlockTypeVar, ForLoopBlock, WhileLoopBlock, get_all_blocksfrom skyvern.forge.sdk.workflow.models.parameter import PARAMETER_TYPE, OutputParameterfrom skyvern.forge.sdk.workflow.models.validators import normalize_run_withfrom skyvern.schemas.runs import ProxyLocationInput, ScriptRunResponse@@ -68,7 +68,7 @@ class WorkflowDefinition(BaseModel):duplicate_labels.add(block.label)else:all_labels.add(block.label)- if isinstance(block, ForLoopBlock) and block.loop_blocks:+ if isinstance(block, (ForLoopBlock, WhileLoopBlock)) and block.loop_blocks:_collect_labels(block.loop_blocks)_collect_labels(self.blocks)diff --git a/skyvern/forge/sdk/workflow/service.py b/skyvern/forge/sdk/workflow/service.pyindex 72de9e53a..3c43303d9 100644--- a/skyvern/forge/sdk/workflow/service.py+++ b/skyvern/forge/sdk/workflow/service.py@@ -81,6 +81,7 @@ from skyvern.forge.sdk.workflow.models.block import (ForLoopBlock,NavigationBlock,TaskV2Block,+ WhileLoopBlock,WorkflowTriggerBlock,compute_conditional_scopes,get_all_blocks,@@ -176,13 +177,13 @@ BLOCK_TYPES_THAT_SHOULD_BE_CACHED = {def _collect_uncached_loop_children(- block: ForLoopBlock,+ block: ForLoopBlock | WhileLoopBlock,script_blocks_by_label: dict[str, object],blocks_to_update: set[str],) -> None:- """Recursively collect uncached cacheable children from nested for-loops.+ """Recursively collect uncached cacheable children from nested loop blocks.- ForLoopBlock children execute via block.py's execute_loop_helper(),+ Loop block children execute via block.py's execute_*_loop_helper(),bypassing _execute_single_block() where blocks_to_update tracking lives.This function walks all nesting levels so the script generator producescached functions for deeply nested blocks (e.g., file_download inside@@ -195,9 +196,9 @@ def _collect_uncached_loop_children(and child.block_type in BLOCK_TYPES_THAT_SHOULD_BE_CACHED):blocks_to_update.add(child.label)- # Recurse into nested for-loops regardless of whether the for-loop+ # Recurse into nested loop blocks regardless of whether the loop# itself is cached — its children may not be.- if isinstance(child, ForLoopBlock):+ if isinstance(child, (ForLoopBlock, WhileLoopBlock)):_collect_uncached_loop_children(child, script_blocks_by_label, blocks_to_update)@@ -2767,13 +2768,13 @@ class WorkflowService:# recorded and the reviewer will patch the specific block that failed.# See _trigger_script_reviewer() for the capped reviewer flow.- # Track uncached for-loop child blocks for regeneration.- # ForLoopBlock children execute via block.py's execute_loop_helper(),+ # Track uncached loop block children for regeneration.+ # Loop block children execute via block.py's execute_*_loop_helper(),# bypassing _execute_single_block. Recursively walk all nesting levels# so deeply nested blocks (e.g., file_download inside a double-nested- # for-loop) get cached functions generated.+ # loop) get cached functions generated.if (- isinstance(block, ForLoopBlock)+ isinstance(block, (ForLoopBlock, WhileLoopBlock))and (is_adaptive_caching(workflow, workflow_run) or is_script_run)and workflow_run_block_result.status in cacheable_statuses):@@ -2782,7 +2783,7 @@ class WorkflowService:new_labels = sorted(blocks_to_update - previous_labels)if new_labels:LOG.info(- "For-loop child blocks marked for caching",+ "Loop block child blocks marked for caching",parent_label=block.label,child_labels=new_labels,child_count=len(new_labels),@@ -3274,9 +3275,9 @@ class WorkflowService:@staticmethoddef _validate_nested_blocks(blocks: list[BlockTypeVar]) -> None:- """Recursively validate ForLoopBlock graphs at all nesting depths."""+ """Recursively validate loop block graphs at all nesting depths."""for block in blocks:- if isinstance(block, ForLoopBlock):+ if isinstance(block, (ForLoopBlock, WhileLoopBlock)):block.validate_loop_blocks()@staticmethoddiff --git a/skyvern/forge/sdk/workflow/workflow_definition_converter.py b/skyvern/forge/sdk/workflow/workflow_definition_converter.pyindex 1df8c0a5b..9b0a0f9d6 100644--- a/skyvern/forge/sdk/workflow/workflow_definition_converter.py+++ b/skyvern/forge/sdk/workflow/workflow_definition_converter.py@@ -56,6 +56,7 @@ from skyvern.forge.sdk.workflow.models.block import (UrlBlock,ValidationBlock,WaitBlock,+ WhileLoopBlock,WorkflowTriggerBlock,)from skyvern.forge.sdk.workflow.models.google_sheets_blocks import (@@ -86,6 +87,7 @@ from skyvern.schemas.workflows import (BLOCK_YAML_TYPES,BlockType,ForLoopBlockYAML,+ WhileLoopBlockYAML,WorkflowDefinitionYAML,)@@ -341,11 +343,11 @@ def convert_workflow_definition(def _collect_all_block_labels(block_yamls: list[BLOCK_YAML_TYPES]) -> list[str]:- """Recursively collect all block labels including those inside for-loop blocks."""+ """Recursively collect all block labels including those inside loop blocks."""labels = []for block_yaml in block_yamls:labels.append(block_yaml.label)- if isinstance(block_yaml, ForLoopBlockYAML) and block_yaml.loop_blocks:+ if isinstance(block_yaml, (ForLoopBlockYAML, WhileLoopBlockYAML)) and block_yaml.loop_blocks:labels.extend(_collect_all_block_labels(block_yaml.loop_blocks))return labels@@ -365,8 +367,8 @@ def _create_all_output_parameters_for_workflow(modified_at=datetime.utcnow(),)output_parameters[block_yaml.label] = output_parameter- # Recursively create output parameters for for-loop blocks- if isinstance(block_yaml, ForLoopBlockYAML):+ # Recursively create output parameters for loop blocks+ if isinstance(block_yaml, (ForLoopBlockYAML, WhileLoopBlockYAML)):output_parameters.update(_create_all_output_parameters_for_workflow(workflow_id=workflow_id, block_yamls=block_yaml.loop_blocks))@@ -447,6 +449,38 @@ def block_yaml_to_block(complete_if_empty=block_yaml.complete_if_empty,data_schema=block_yaml.data_schema,)+ elif block_yaml.block_type == BlockType.WHILE_LOOP:+ loop_blocks = [block_yaml_to_block(loop_block, parameters) for loop_block in block_yaml.loop_blocks]++ condition_yaml = block_yaml.condition+ condition: JinjaBranchCriteria | PromptBranchCriteria+ if condition_yaml.criteria_type == "jinja2_template":+ condition = JinjaBranchCriteria(+ criteria_type=condition_yaml.criteria_type,+ expression=condition_yaml.expression,+ description=condition_yaml.description,+ )+ elif condition_yaml.criteria_type == "prompt":+ condition = PromptBranchCriteria(+ criteria_type=condition_yaml.criteria_type,+ expression=condition_yaml.expression,+ description=condition_yaml.description,+ )+ else:+ # Defensive: BranchCriteriaYAML.criteria_type is a Literal, so Pydantic+ # rejects unknown values at parse time. This branch surfaces the error+ # explicitly if the schema ever grows a third criteria type without a+ # converter update — better to fail loudly than silently coerce to Jinja.+ raise InvalidWorkflowDefinition(+ f"Unknown criteria_type {condition_yaml.criteria_type!r} for while_loop "+ f"block {block_yaml.label!r}. Supported types: jinja2_template, prompt."+ )++ return WhileLoopBlock(+ **base_kwargs,+ loop_blocks=loop_blocks,+ condition=condition,+ )elif block_yaml.block_type == BlockType.CONDITIONAL:branch_conditions = []for branch in block_yaml.branch_conditions:@@ -784,7 +818,7 @@ def _collect_undefined_parameters(parameters: dict[str, PARAMETER_TYPE],) -> dict[str, list[str]]:"""- Collect all undefined parameters referenced by blocks (including nested blocks in for_loop).+ Collect all undefined parameters referenced by blocks (including nested blocks in loop blocks).Returns a dict mapping block labels to lists of undefined parameter keys."""undefined_params: dict[str, list[str]] = {}@@ -795,8 +829,8 @@ def _collect_undefined_parameters(if undefined_for_block:undefined_params[block_yaml.label] = undefined_for_block- # Recursively check nested blocks in for_loop- if isinstance(block_yaml, ForLoopBlockYAML) and block_yaml.loop_blocks:+ # Recursively check nested blocks in loop blocks+ if isinstance(block_yaml, (ForLoopBlockYAML, WhileLoopBlockYAML)) and block_yaml.loop_blocks:nested_undefined = _collect_undefined_parameters(block_yaml.loop_blocks, parameters)undefined_params.update(nested_undefined)@@ -815,6 +849,6 @@ def _has_dag_metadata(block_yamls: list[BLOCK_YAML_TYPES]) -> bool:for block_yaml in block_yamls:if block_yaml.next_block_label:return True- if isinstance(block_yaml, ForLoopBlockYAML) and _has_dag_metadata(block_yaml.loop_blocks):+ if isinstance(block_yaml, (ForLoopBlockYAML, WhileLoopBlockYAML)) and _has_dag_metadata(block_yaml.loop_blocks):return Truereturn Falsediff --git a/skyvern/schemas/workflows.py b/skyvern/schemas/workflows.pyindex 47cd945ce..9d4da9ec3 100644--- a/skyvern/schemas/workflows.py+++ b/skyvern/schemas/workflows.py@@ -412,6 +412,7 @@ class BlockType(StrEnum):TASK = "task"TaskV2 = "task_v2"FOR_LOOP = "for_loop"+ WHILE_LOOP = "while_loop"CONDITIONAL = "conditional"CODE = "code"TEXT_PROMPT = "text_prompt"@@ -708,6 +709,13 @@ class BranchCriteriaYAML(BaseModel):description: str | None = None+class WhileLoopBlockYAML(BlockYAML):+ block_type: Literal[BlockType.WHILE_LOOP] = BlockType.WHILE_LOOP # type: ignore++ loop_blocks: list["BLOCK_YAML_SUBCLASSES"]+ condition: BranchCriteriaYAML++class BranchConditionYAML(BaseModel):criteria: BranchCriteriaYAML | None = Nonenext_block_label: str | None = None@@ -1090,6 +1098,7 @@ PARAMETER_YAML_TYPES = Annotated[PARAMETER_YAML_SUBCLASSES, Field(discriminator=BLOCK_YAML_SUBCLASSES = (TaskBlockYAML| ForLoopBlockYAML+ | WhileLoopBlockYAML| CodeBlockYAML| TextPromptBlockYAML| DownloadToS3BlockYAMLdiff --git a/tests/unit/test_mcp_block_type_parity.py b/tests/unit/test_mcp_block_type_parity.pyindex 52ba27a96..483947cd8 100644--- a/tests/unit/test_mcp_block_type_parity.py+++ b/tests/unit/test_mcp_block_type_parity.py@@ -35,6 +35,8 @@ _KNOWN_DRIFT_ALLOWLIST: frozenset[str] = frozenset({"google_sheets_read","google_sheets_write",+ # SKY-8771: Fern SDK regeneration for the new while_loop block lands in PR 2.+ "while_loop",})diff --git a/tests/unit/test_nested_loop_output_parameters.py b/tests/unit/test_nested_loop_output_parameters.pyindex d95a75dc1..076fe979d 100644--- a/tests/unit/test_nested_loop_output_parameters.py+++ b/tests/unit/test_nested_loop_output_parameters.py@@ -17,7 +17,7 @@ from skyvern.forge.sdk.workflow.exceptions import (OutputParameterKeyCollisionError,WorkflowDefinitionHasDuplicateBlockLabels,)-from skyvern.forge.sdk.workflow.models.block import ForLoopBlock, TaskBlock+from skyvern.forge.sdk.workflow.models.block import ForLoopBlock, JinjaBranchCriteria, TaskBlock, WhileLoopBlockfrom skyvern.forge.sdk.workflow.models.parameter import OutputParameterfrom skyvern.forge.sdk.workflow.models.workflow import Workflow, WorkflowDefinitionfrom skyvern.forge.sdk.workflow.workflow_definition_converter import (@@ -26,8 +26,10 @@ from skyvern.forge.sdk.workflow.workflow_definition_converter import (convert_workflow_definition,)from skyvern.schemas.workflows import (+ BranchCriteriaYAML,ForLoopBlockYAML,TaskBlockYAML,+ WhileLoopBlockYAML,WorkflowDefinitionYAML,)@@ -104,6 +106,25 @@ class TestCollectAllBlockLabels:labels = _collect_all_block_labels(blocks)assert labels.count("shared_label") == 2+ def test_recurses_into_while_loop_blocks(self) -> None:+ """SKY-8771: _collect_all_block_labels recurses into while_loop blocks."""+ blocks = [+ WhileLoopBlockYAML(+ label="outer_while",+ loop_blocks=[+ ForLoopBlockYAML(+ label="inner_for",+ loop_blocks=[+ TaskBlockYAML(label="deep_task", url="https://example.com"),+ ],+ ),+ ],+ condition=BranchCriteriaYAML(criteria_type="jinja2_template", expression="{{ x }}"),+ ),+ ]+ labels = _collect_all_block_labels(blocks)+ assert labels == ["outer_while", "inner_for", "deep_task"]+class TestCreateAllOutputParametersForNestedLoops:"""Tests for _create_all_output_parameters_for_workflow with nested loops."""@@ -151,6 +172,25 @@ class TestCreateAllOutputParametersForNestedLoops:assert "inner_loop" in paramsassert "deep_task" in params+ def test_creates_parameters_for_while_loop_children(self) -> None:+ """SKY-8771: output parameters are created for blocks nested inside a while_loop."""+ blocks = [+ WhileLoopBlockYAML(+ label="outer_while",+ loop_blocks=[+ TaskBlockYAML(label="inside_task", url="https://example.com"),+ ],+ condition=BranchCriteriaYAML(criteria_type="jinja2_template", expression="{{ x }}"),+ ),+ ]+ params = _create_all_output_parameters_for_workflow(+ workflow_id="test_wf",+ block_yamls=blocks,+ )+ assert "outer_while" in params+ assert "inside_task" in params+ assert params["inside_task"].key == "inside_task_output"+class TestConvertWorkflowDefinitionNestedLoopValidation:"""Tests for convert_workflow_definition with nested loop duplicate label detection."""@@ -275,6 +315,51 @@ class TestWorkflowDefinitionValidateNestedLabels:)definition.validate() # Should not raise+ def test_validate_catches_duplicate_inside_while_loop(self) -> None:+ """validate() recurses into while_loop blocks for label uniqueness checks (SKY-8771)."""+ inner_task = TaskBlock(+ label="shared_label",+ output_parameter=self._make_output_param("shared_label_inner"),+ )+ outer_task = TaskBlock(+ label="shared_label",+ output_parameter=self._make_output_param("shared_label_outer"),+ )+ while_loop = WhileLoopBlock(+ label="while_1",+ output_parameter=self._make_output_param("while_1"),+ loop_blocks=[inner_task],+ condition=JinjaBranchCriteria(expression="{{ x }}"),+ )+ definition = WorkflowDefinition(+ parameters=[],+ blocks=[outer_task, while_loop],+ )+ with pytest.raises(WorkflowDefinitionHasDuplicateBlockLabels):+ definition.validate()++ def test_validate_catches_duplicate_for_inside_while(self) -> None:+ """Mixed for-inside-while nesting still detects duplicate labels (SKY-8771)."""+ deepest = TaskBlock(label="dup", output_parameter=self._make_output_param("dup_inner"))+ for_loop = ForLoopBlock(+ label="for_1",+ output_parameter=self._make_output_param("for_1"),+ loop_blocks=[deepest],+ )+ sibling = TaskBlock(label="dup", output_parameter=self._make_output_param("dup_sibling"))+ while_loop = WhileLoopBlock(+ label="while_1",+ output_parameter=self._make_output_param("while_1"),+ loop_blocks=[for_loop, sibling],+ condition=JinjaBranchCriteria(expression="{{ x }}"),+ )+ definition = WorkflowDefinition(+ parameters=[],+ blocks=[while_loop],+ )+ with pytest.raises(WorkflowDefinitionHasDuplicateBlockLabels):+ definition.validate()+class TestWorkflowGetOutputParameterNested:"""Tests for Workflow.get_output_parameter() searching nested loop blocks (SKY-8397)."""diff --git a/tests/unit/test_while_loop_block.py b/tests/unit/test_while_loop_block.pynew file mode 100644index 000000000..a056707dd--- /dev/null+++ b/tests/unit/test_while_loop_block.py@@ -0,0 +1,578 @@+"""Tests for WhileLoopBlock (PR 1 of SKY-8771).++Covers schema validation, top-of-loop semantics, max-iteration safety,+condition rendering errors, per-iteration metadata shape, cancellation+propagation, get_all_blocks recursion, and nested-label validation.+"""++from datetime import UTC, datetime+from typing import Any+from unittest.mock import AsyncMock, MagicMock, patch++import pytest+from pydantic import ValidationError++from skyvern.forge.sdk.workflow.exceptions import (+ FailedToFormatJinjaStyleParameter,+ MissingJinjaVariables,+ WorkflowDefinitionHasDuplicateBlockLabels,+)+from skyvern.forge.sdk.workflow.models.block import (+ Block,+ ForLoopBlock,+ JinjaBranchCriteria,+ PromptBranchCriteria,+ TaskBlock,+ WhileLoopBlock,+ get_all_blocks,+)+from skyvern.forge.sdk.workflow.models.parameter import OutputParameter+from skyvern.forge.sdk.workflow.models.workflow import WorkflowDefinition+from skyvern.forge.sdk.workflow.workflow_definition_converter import convert_workflow_definition+from skyvern.schemas.workflows import (+ BlockResult,+ BlockStatus,+ BlockType,+ BranchCriteriaYAML,+ ForLoopBlockYAML,+ TaskBlockYAML,+ WhileLoopBlockYAML,+ WorkflowDefinitionYAML,+)++# ---------------------------------------------------------------------------+# Helpers+# ---------------------------------------------------------------------------+++def _make_output_param(label: str) -> OutputParameter:+ now = datetime.now(UTC)+ return OutputParameter(+ output_parameter_id=f"op_{label}",+ key=f"{label}_output",+ workflow_id="wf_test",+ created_at=now,+ modified_at=now,+ )+++def _make_block_result(output_param: OutputParameter, status: BlockStatus = BlockStatus.completed) -> BlockResult:+ return BlockResult(+ success=status == BlockStatus.completed,+ output_parameter=output_param,+ output_parameter_value={"value": "ok"},+ status=status,+ )+++def _make_while_loop(condition_expression: str = "{{ keep_going }}") -> WhileLoopBlock:+ inner = TaskBlock(label="inner_task", output_parameter=_make_output_param("inner_task"))+ return WhileLoopBlock(+ label="my_while",+ output_parameter=_make_output_param("my_while"),+ loop_blocks=[inner],+ condition=JinjaBranchCriteria(expression=condition_expression),+ )+++# ---------------------------------------------------------------------------+# 1) Schema validation+# ---------------------------------------------------------------------------+++class TestWhileLoopBlockYAMLSchema:+ """YAML-level schema validation for WhileLoopBlockYAML."""++ def test_jinja_condition_accepted(self) -> None:+ block = WhileLoopBlockYAML(+ label="loop",+ loop_blocks=[TaskBlockYAML(label="t", url="https://example.com")],+ condition=BranchCriteriaYAML(criteria_type="jinja2_template", expression="{{ x > 0 }}"),+ )+ assert block.block_type == BlockType.WHILE_LOOP+ assert block.condition.criteria_type == "jinja2_template"++ def test_prompt_condition_accepted_at_parse_time(self) -> None:+ # Forward-compat: prompt criteria parses cleanly. Execution-time rejection+ # is verified separately in the runtime tests below.+ block = WhileLoopBlockYAML(+ label="loop",+ loop_blocks=[TaskBlockYAML(label="t", url="https://example.com")],+ condition=BranchCriteriaYAML(criteria_type="prompt", expression="dates are recent"),+ )+ assert block.condition.criteria_type == "prompt"++ def test_missing_condition_rejected(self) -> None:+ with pytest.raises(ValidationError):+ WhileLoopBlockYAML( # type: ignore[call-arg]+ label="loop",+ loop_blocks=[TaskBlockYAML(label="t", url="https://example.com")],+ )++ def test_round_trip_through_workflow_definition_yaml(self) -> None:+ yaml_def = WorkflowDefinitionYAML(+ parameters=[],+ blocks=[+ WhileLoopBlockYAML(+ label="loop",+ loop_blocks=[TaskBlockYAML(label="inner", url="https://example.com")],+ condition=BranchCriteriaYAML(criteria_type="jinja2_template", expression="{{ a }}"),+ ),+ ],+ )+ # round-trip through dict — ensures discriminator works in both directions+ as_dict = yaml_def.model_dump()+ restored = WorkflowDefinitionYAML(**as_dict)+ assert restored.blocks[0].block_type == BlockType.WHILE_LOOP+ assert isinstance(restored.blocks[0], WhileLoopBlockYAML)+++# ---------------------------------------------------------------------------+# 2) Validation: nested labels+# ---------------------------------------------------------------------------+++class TestWhileLoopNestedLabelValidation:+ """Duplicate label detection across while_loop nesting."""++ def test_duplicate_label_top_level_vs_inside_while_loop(self) -> None:+ yaml_def = WorkflowDefinitionYAML(+ parameters=[],+ blocks=[+ TaskBlockYAML(label="dup", url="https://example.com"),+ WhileLoopBlockYAML(+ label="loop",+ loop_blocks=[TaskBlockYAML(label="dup", url="https://example.com")],+ condition=BranchCriteriaYAML(criteria_type="jinja2_template", expression="{{ x }}"),+ ),+ ],+ )+ with pytest.raises(WorkflowDefinitionHasDuplicateBlockLabels):+ convert_workflow_definition(yaml_def, workflow_id="wf_test")++ def test_duplicate_label_for_loop_inside_while_loop(self) -> None:+ yaml_def = WorkflowDefinitionYAML(+ parameters=[],+ blocks=[+ WhileLoopBlockYAML(+ label="outer_while",+ loop_blocks=[+ ForLoopBlockYAML(+ label="inner_for",+ loop_variable_reference="items",+ loop_blocks=[TaskBlockYAML(label="dup", url="https://example.com")],+ ),+ TaskBlockYAML(label="dup", url="https://example.com"),+ ],+ condition=BranchCriteriaYAML(criteria_type="jinja2_template", expression="{{ x }}"),+ ),+ ],+ )+ with pytest.raises(WorkflowDefinitionHasDuplicateBlockLabels):+ convert_workflow_definition(yaml_def, workflow_id="wf_test")++ def test_unique_labels_in_nested_loops_pass(self) -> None:+ # No exception should be raised+ wf = WorkflowDefinition(+ parameters=[],+ blocks=[+ _make_while_loop(),+ ],+ )+ wf.validate()+++# ---------------------------------------------------------------------------+# 3) Execution: top-of-loop semantics+# ---------------------------------------------------------------------------+++class TestExecuteTopOfLoopSemantics:+ """Condition is evaluated before each iteration."""++ @pytest.mark.asyncio+ async def test_condition_false_on_first_check_skips_body(self) -> None:+ loop_block = _make_while_loop()+ mock_context = MagicMock()++ with (+ patch.object(WhileLoopBlock, "_evaluate_condition", new_callable=AsyncMock, return_value=False),+ patch.object(Block, "execute_safe", new_callable=AsyncMock) as mock_execute_safe,+ patch("skyvern.forge.sdk.workflow.models.block.app") as mock_app,+ patch("skyvern.forge.sdk.workflow.models.block.skyvern_context") as mock_skyvern_ctx,+ ):+ mock_skyvern_ctx.current.return_value = None+ mock_app.DATABASE.workflow_runs.create_or_update_workflow_run_output_parameter = AsyncMock()++ result = await loop_block._execute_while_loop_helper(+ workflow_run_id="wr_test",+ workflow_run_block_id="wrb_loop",+ workflow_run_context=mock_context,+ organization_id="org_test",+ )++ # Body never ran+ assert mock_execute_safe.call_count == 0+ assert result.outputs_with_loop_values == []+ assert result.block_outputs == []++ @pytest.mark.asyncio+ async def test_condition_true_twice_then_false_runs_two_iterations(self) -> None:+ loop_block = _make_while_loop()+ inner_block = loop_block.loop_blocks[0]+ inner_result = _make_block_result(inner_block.output_parameter)++ mock_context = MagicMock()+ mock_context.has_value.return_value = False+ mock_context.update_block_metadata = MagicMock()+ mock_context.set_value = MagicMock()++ condition_results = iter([True, True, False])++ async def fake_eval(_self: Any, _ctx: Any) -> bool: # type: ignore[override]+ return next(condition_results)++ with (+ patch.object(WhileLoopBlock, "_evaluate_condition", new=fake_eval),+ patch.object(Block, "execute_safe", new_callable=AsyncMock, return_value=inner_result),+ patch("skyvern.forge.sdk.workflow.models.block.app") as mock_app,+ patch("skyvern.forge.sdk.workflow.models.block.skyvern_context") as mock_skyvern_ctx,+ ):+ mock_skyvern_ctx.current.return_value = None+ mock_app.DATABASE.workflow_runs.create_or_update_workflow_run_output_parameter = AsyncMock()+ mock_app.DATABASE.observer.update_workflow_run_block = AsyncMock()++ result = await loop_block._execute_while_loop_helper(+ workflow_run_id="wr_test",+ workflow_run_block_id="wrb_loop",+ workflow_run_context=mock_context,+ organization_id="org_test",+ )++ # Exactly two iterations executed+ assert len(result.outputs_with_loop_values) == 2+ assert len(result.block_outputs) == 2++ # Verify per-iteration metadata sets current_index 0 and 1, with+ # current_value / current_item explicitly nulled so a stale outer-loop+ # value can't leak into child Jinja expressions (SKY-8835).+ metadata_calls = [c.args for c in mock_context.update_block_metadata.call_args_list]+ indices_set = [args[1].get("current_index") for args in metadata_calls if isinstance(args[1], dict)]+ assert 0 in indices_set+ assert 1 in indices_set+ for args in metadata_calls:+ meta = args[1]+ assert meta.get("current_value") is None+ assert meta.get("current_item") is None++ @pytest.mark.asyncio+ async def test_metadata_explicitly_nulls_for_loop_keys(self) -> None:+ """SKY-8771 review fix (SKY-8835 dependency): when WhileLoopBlock writes its+ per-iteration metadata, ``current_value`` and ``current_item`` must be present+ as explicit None so that ``update_block_metadata``'s merge semantics overwrite+ any stale outer for_loop values rather than letting them linger.+ """+ loop_block = _make_while_loop()+ inner_block = loop_block.loop_blocks[0]+ inner_result = _make_block_result(inner_block.output_parameter)++ mock_context = MagicMock()+ mock_context.has_value.return_value = False+ mock_context.update_block_metadata = MagicMock()+ mock_context.set_value = MagicMock()++ condition_results = iter([True, False])++ async def fake_eval(_self: Any, _ctx: Any) -> bool: # type: ignore[override]+ return next(condition_results)++ with (+ patch.object(WhileLoopBlock, "_evaluate_condition", new=fake_eval),+ patch.object(Block, "execute_safe", new_callable=AsyncMock, return_value=inner_result),+ patch("skyvern.forge.sdk.workflow.models.block.app") as mock_app,+ patch("skyvern.forge.sdk.workflow.models.block.skyvern_context") as mock_skyvern_ctx,+ ):+ mock_skyvern_ctx.current.return_value = None+ mock_app.DATABASE.workflow_runs.create_or_update_workflow_run_output_parameter = AsyncMock()+ mock_app.DATABASE.observer.update_workflow_run_block = AsyncMock()++ await loop_block._execute_while_loop_helper(+ workflow_run_id="wr_test",+ workflow_run_block_id="wrb_loop",+ workflow_run_context=mock_context,+ organization_id="org_test",+ )++ # Every metadata write must carry the for_loop keys with explicit None values.+ metadata_calls = [c.args[1] for c in mock_context.update_block_metadata.call_args_list]+ assert metadata_calls, "expected at least one metadata write"+ for meta in metadata_calls:+ assert "current_value" in meta and meta["current_value"] is None+ assert "current_item" in meta and meta["current_item"] is None+ assert isinstance(meta.get("current_index"), int)+++# ---------------------------------------------------------------------------+# 4) Execution: max iterations safety+# ---------------------------------------------------------------------------+++class TestExecuteMaxIterationsCap:+ @pytest.mark.asyncio+ async def test_condition_permanently_true_terminates_at_cap(self) -> None:+ loop_block = _make_while_loop()+ inner_block = loop_block.loop_blocks[0]+ inner_result = _make_block_result(inner_block.output_parameter)++ mock_context = MagicMock()+ mock_context.has_value.return_value = False+ mock_context.update_block_metadata = MagicMock()+ mock_context.set_value = MagicMock()++ # Patch the cap to a small number so the test is fast.+ with (+ patch("skyvern.forge.sdk.workflow.models.block.DEFAULT_MAX_LOOP_ITERATIONS", 5),+ patch.object(WhileLoopBlock, "_evaluate_condition", new_callable=AsyncMock, return_value=True),+ patch.object(Block, "execute_safe", new_callable=AsyncMock, return_value=inner_result),+ patch("skyvern.forge.sdk.workflow.models.block.app") as mock_app,+ patch("skyvern.forge.sdk.workflow.models.block.skyvern_context") as mock_skyvern_ctx,+ ):+ mock_skyvern_ctx.current.return_value = None+ mock_app.DATABASE.workflow_runs.create_or_update_workflow_run_output_parameter = AsyncMock()+ mock_app.DATABASE.observer.update_workflow_run_block = AsyncMock()++ result = await loop_block._execute_while_loop_helper(+ workflow_run_id="wr_test",+ workflow_run_block_id="wrb_loop",+ workflow_run_context=mock_context,+ organization_id="org_test",+ )++ # 5 successful iterations + 1 final failure block result for the cap+ assert len(result.outputs_with_loop_values) == 5+ assert result.block_outputs[-1].success is False+ assert result.block_outputs[-1].status == BlockStatus.failed+ assert "max_loop_iterations" in (result.block_outputs[-1].failure_reason or "")++ @pytest.mark.asyncio+ async def test_condition_false_on_cap_plus_one_check_succeeds(self) -> None:+ """SKY-8771 review fix: a loop that completes exactly N=cap iterations and would+ naturally exit on the next condition check must succeed, not trip the cap.++ With cap=3 and condition iter([True, True, True, False]), the loop must run 3+ bodies and then exit cleanly when the 4th check returns False — *not* return+ a max_loop_iterations failure.+ """+ loop_block = _make_while_loop()+ inner_block = loop_block.loop_blocks[0]+ inner_result = _make_block_result(inner_block.output_parameter)++ mock_context = MagicMock()+ mock_context.has_value.return_value = False+ mock_context.update_block_metadata = MagicMock()+ mock_context.set_value = MagicMock()++ condition_results = iter([True, True, True, False])++ async def fake_eval(_self: Any, _ctx: Any) -> bool: # type: ignore[override]+ return next(condition_results)++ with (+ patch("skyvern.forge.sdk.workflow.models.block.DEFAULT_MAX_LOOP_ITERATIONS", 3),+ patch.object(WhileLoopBlock, "_evaluate_condition", new=fake_eval),+ patch.object(Block, "execute_safe", new_callable=AsyncMock, return_value=inner_result),+ patch("skyvern.forge.sdk.workflow.models.block.app") as mock_app,+ patch("skyvern.forge.sdk.workflow.models.block.skyvern_context") as mock_skyvern_ctx,+ ):+ mock_skyvern_ctx.current.return_value = None+ mock_app.DATABASE.workflow_runs.create_or_update_workflow_run_output_parameter = AsyncMock()+ mock_app.DATABASE.observer.update_workflow_run_block = AsyncMock()++ result = await loop_block._execute_while_loop_helper(+ workflow_run_id="wr_test",+ workflow_run_block_id="wrb_loop",+ workflow_run_context=mock_context,+ organization_id="org_test",+ )++ # Exactly 3 body iterations executed, then condition false → clean exit.+ assert len(result.outputs_with_loop_values) == 3+ assert len(result.block_outputs) == 3+ # No max_loop_iterations failure result was appended.+ assert all("max_loop_iterations" not in (b.failure_reason or "") for b in result.block_outputs)+++# ---------------------------------------------------------------------------+# 5) Execution: condition rendering errors+# ---------------------------------------------------------------------------+++class TestExecuteConditionRenderingErrors:+ @pytest.mark.asyncio+ async def test_failed_jinja_format_returns_failure_result(self) -> None:+ loop_block = _make_while_loop()+ mock_context = MagicMock()++ async def raise_format_error(_self: Any, _ctx: Any) -> bool: # type: ignore[override]+ raise FailedToFormatJinjaStyleParameter("{{ ??? }}", "syntax error")++ with (+ patch.object(WhileLoopBlock, "_evaluate_condition", new=raise_format_error),+ patch("skyvern.forge.sdk.workflow.models.block.app") as mock_app,+ patch("skyvern.forge.sdk.workflow.models.block.skyvern_context") as mock_skyvern_ctx,+ ):+ mock_skyvern_ctx.current.return_value = None+ mock_app.DATABASE.workflow_runs.create_or_update_workflow_run_output_parameter = AsyncMock()+ mock_app.DATABASE.observer.update_workflow_run_block = AsyncMock()++ result = await loop_block._execute_while_loop_helper(+ workflow_run_id="wr_test",+ workflow_run_block_id="wrb_loop",+ workflow_run_context=mock_context,+ organization_id="org_test",+ )++ assert len(result.block_outputs) == 1+ assert result.block_outputs[0].success is False+ assert "Failed to evaluate while-loop condition" in (result.block_outputs[0].failure_reason or "")++ @pytest.mark.asyncio+ async def test_missing_jinja_variables_returns_failure_result(self) -> None:+ loop_block = _make_while_loop()+ mock_context = MagicMock()++ async def raise_missing(_self: Any, _ctx: Any) -> bool: # type: ignore[override]+ raise MissingJinjaVariables("{{ undefined_var }}", {"undefined_var"})++ with (+ patch.object(WhileLoopBlock, "_evaluate_condition", new=raise_missing),+ patch("skyvern.forge.sdk.workflow.models.block.app") as mock_app,+ patch("skyvern.forge.sdk.workflow.models.block.skyvern_context") as mock_skyvern_ctx,+ ):+ mock_skyvern_ctx.current.return_value = None+ mock_app.DATABASE.workflow_runs.create_or_update_workflow_run_output_parameter = AsyncMock()+ mock_app.DATABASE.observer.update_workflow_run_block = AsyncMock()++ result = await loop_block._execute_while_loop_helper(+ workflow_run_id="wr_test",+ workflow_run_block_id="wrb_loop",+ workflow_run_context=mock_context,+ organization_id="org_test",+ )++ assert len(result.block_outputs) == 1+ assert result.block_outputs[0].success is False+++# ---------------------------------------------------------------------------+# 6) Cancellation propagation+# ---------------------------------------------------------------------------+++class TestExecuteCancellationPropagation:+ @pytest.mark.asyncio+ async def test_canceled_child_terminates_loop_with_partial_outputs(self) -> None:+ loop_block = _make_while_loop()+ inner_block = loop_block.loop_blocks[0]+ canceled_result = _make_block_result(inner_block.output_parameter, status=BlockStatus.canceled)++ mock_context = MagicMock()+ mock_context.has_value.return_value = False+ mock_context.update_block_metadata = MagicMock()+ mock_context.set_value = MagicMock()++ with (+ patch.object(WhileLoopBlock, "_evaluate_condition", new_callable=AsyncMock, return_value=True),+ patch.object(Block, "execute_safe", new_callable=AsyncMock, return_value=canceled_result),+ patch("skyvern.forge.sdk.workflow.models.block.app") as mock_app,+ patch("skyvern.forge.sdk.workflow.models.block.skyvern_context") as mock_skyvern_ctx,+ ):+ mock_skyvern_ctx.current.return_value = None+ mock_app.DATABASE.workflow_runs.create_or_update_workflow_run_output_parameter = AsyncMock()+ mock_app.DATABASE.observer.update_workflow_run_block = AsyncMock()++ result = await loop_block._execute_while_loop_helper(+ workflow_run_id="wr_test",+ workflow_run_block_id="wrb_loop",+ workflow_run_context=mock_context,+ organization_id="org_test",+ )++ # One iteration ran and was canceled+ assert len(result.outputs_with_loop_values) == 1+ assert result.is_canceled() is True+++# ---------------------------------------------------------------------------+# 7) Prompt criteria rejected at runtime+# ---------------------------------------------------------------------------+++class TestPromptCriteriaRejected:+ @pytest.mark.asyncio+ async def test_prompt_criteria_returns_clear_failure(self) -> None:+ inner = TaskBlock(label="inner_task", output_parameter=_make_output_param("inner_task"))+ loop_block = WhileLoopBlock(+ label="my_while",+ output_parameter=_make_output_param("my_while"),+ loop_blocks=[inner],+ condition=PromptBranchCriteria(expression="dates on the page are still recent"),+ )++ mock_context = MagicMock()++ with (+ patch.object(Block, "get_workflow_run_context", return_value=mock_context),+ patch("skyvern.forge.sdk.workflow.models.block.app") as mock_app,+ ):+ mock_app.DATABASE.observer.update_workflow_run_block = AsyncMock()++ result = await loop_block._run_loop(+ workflow_run_id="wr_test",+ workflow_run_block_id="wrb_loop",+ organization_id="org_test",+ )++ assert result.success is False+ assert result.status == BlockStatus.failed+ assert "Prompt criteria are not yet supported" in (result.failure_reason or "")+++# ---------------------------------------------------------------------------+# 8) get_all_blocks recursion+# ---------------------------------------------------------------------------+++class TestGetAllBlocksRecursion:+ def test_get_all_blocks_recurses_into_while_loop(self) -> None:+ inner_a = TaskBlock(label="a", output_parameter=_make_output_param("a"))+ inner_b = TaskBlock(label="b", output_parameter=_make_output_param("b"))+ loop_block = WhileLoopBlock(+ label="loop",+ output_parameter=_make_output_param("loop"),+ loop_blocks=[inner_a, inner_b],+ condition=JinjaBranchCriteria(expression="{{ x }}"),+ )++ all_blocks = get_all_blocks([loop_block])+ labels = [b.label for b in all_blocks]+ assert labels == ["loop", "a", "b"]++ def test_get_all_blocks_recurses_into_nested_for_inside_while(self) -> None:+ deep = TaskBlock(label="deep", output_parameter=_make_output_param("deep"))+ for_loop = ForLoopBlock(+ label="inner_for",+ output_parameter=_make_output_param("inner_for"),+ loop_blocks=[deep],+ loop_variable_reference="items",+ )+ while_loop = WhileLoopBlock(+ label="outer_while",+ output_parameter=_make_output_param("outer_while"),+ loop_blocks=[for_loop],+ condition=JinjaBranchCriteria(expression="{{ x }}"),+ )++ all_blocks = get_all_blocks([while_loop])+ labels = [b.label for b in all_blocks]+ assert labels == ["outer_while", "inner_for", "deep"]