Skip to content

Automate browser based workflows with AI

fix(SKY-10988): preserve conditional routing in v1-stored workflows (#6760)

Aaron Perezba5fac73086c
diff --git a/skyvern-frontend/src/routes/workflows/debugger/Debugger.tsx b/skyvern-frontend/src/routes/workflows/debugger/Debugger.tsx
index 5c977a331..0ce890efe 100644
--- a/skyvern-frontend/src/routes/workflows/debugger/Debugger.tsx
+++ b/skyvern-frontend/src/routes/workflows/debugger/Debugger.tsx
@@ -5,10 +5,7 @@ import { ReactFlowProvider } from "@xyflow/react";
import { LogoMinimized } from "@/components/LogoMinimized";
import { useWorkflowQuery } from "../hooks/useWorkflowQuery";
import { WorkflowSettings } from "../types/workflowTypes";
-import {
- getElements,
- upgradeWorkflowBlocksV1toV2,
-} from "@/routes/workflows/editor/workflowEditorUtils";
+import { getElements } from "@/routes/workflows/editor/workflowEditorUtils";
import { getInitialParameters } from "@/routes/workflows/editor/utils";
import { Workspace } from "@/routes/workflows/editor/Workspace";
import { useDebugSessionBlockOutputsQuery } from "../hooks/useDebugSessionBlockOutputsQuery";
@@ -66,12 +63,8 @@ function Debugger() {
return null;
}
- // Auto-upgrade v1 workflows to v2 by assigning sequential next_block_label values
- const workflowVersion = workflow.workflow_definition.version ?? 1;
- const blocksToRender =
- workflowVersion < 2
- ? upgradeWorkflowBlocksV1toV2(workflow.workflow_definition.blocks)
- : workflow.workflow_definition.blocks;
+ // getElements derives display routing (sequential defaulting + validation); the stored blocks are passed through unchanged.
+ const blocksToRender = workflow.workflow_definition.blocks;
const settings: WorkflowSettings = {
persistBrowserSession: workflow.persist_browser_session,
diff --git a/skyvern-frontend/src/routes/workflows/editor/WorkflowEditor.tsx b/skyvern-frontend/src/routes/workflows/editor/WorkflowEditor.tsx
index 82914b89d..c043745db 100644
--- a/skyvern-frontend/src/routes/workflows/editor/WorkflowEditor.tsx
+++ b/skyvern-frontend/src/routes/workflows/editor/WorkflowEditor.tsx
@@ -3,10 +3,7 @@ import { useParams, useSearchParams } from "react-router-dom";
import { useEffect } from "react";
import { usePostHog } from "posthog-js/react";
import { useWorkflowQuery } from "../hooks/useWorkflowQuery";
-import {
- getElements,
- upgradeWorkflowBlocksV1toV2,
-} from "./workflowEditorUtils";
+import { getElements } from "./workflowEditorUtils";
import { LogoMinimized } from "@/components/LogoMinimized";
import { WorkflowSettings } from "../types/workflowTypes";
import { useGlobalWorkflowsQuery } from "../hooks/useGlobalWorkflowsQuery";
@@ -72,12 +69,8 @@ function WorkflowEditor() {
globalWorkflow.workflow_permanent_id === workflowPermanentId,
);
- // Auto-upgrade v1 workflows to v2 by assigning sequential next_block_label values
- const workflowVersion = workflow.workflow_definition.version ?? 1;
- const blocksToRender =
- workflowVersion < 2
- ? upgradeWorkflowBlocksV1toV2(workflow.workflow_definition.blocks)
- : workflow.workflow_definition.blocks;
+ // getElements derives display routing (sequential defaulting + validation); the stored blocks are passed through unchanged.
+ const blocksToRender = workflow.workflow_definition.blocks;
const settings: WorkflowSettings = {
persistBrowserSession: workflow.persist_browser_session,
diff --git a/skyvern-frontend/src/routes/workflows/editor/sortable/loadValidation.test.ts b/skyvern-frontend/src/routes/workflows/editor/sortable/loadValidation.test.ts
index ddd5f3c58..19385d252 100644
--- a/skyvern-frontend/src/routes/workflows/editor/sortable/loadValidation.test.ts
+++ b/skyvern-frontend/src/routes/workflows/editor/sortable/loadValidation.test.ts
@@ -280,3 +280,84 @@ describe("validateWorkflowBlocks", () => {
);
});
});
+
+function conditional(
+ label: string,
+ next: string | null,
+ branchTargets: Array<string | null>,
+): ConditionalBlock {
+ return {
+ label,
+ block_type: "conditional",
+ continue_on_failure: false,
+ model: null,
+ next_block_label: next,
+ output_parameter: op(label),
+ branch_conditions: branchTargets.map((target, index) => ({
+ id: `br-${label}-${index}`,
+ description: null,
+ next_block_label: target,
+ criteria: null,
+ is_default: index === branchTargets.length - 1,
+ })),
+ };
+}
+
+function forLoop(
+ label: string,
+ loopBlocks: Array<WorkflowBlock>,
+): ForLoopBlock {
+ return {
+ label,
+ block_type: "for_loop",
+ continue_on_failure: false,
+ model: null,
+ next_block_label: null,
+ output_parameter: op(label),
+ loop_over: { key: "items" } as never,
+ loop_blocks: loopBlocks,
+ loop_variable_reference: null,
+ complete_if_empty: false,
+ data_schema: null,
+ };
+}
+
+// SKY-10988: MCP/API workflows stored as v1 that contain v2 graph constructs must not have their
+// routing rewritten by array-order defaulting when rendered in the editor/debugger.
+describe("applySequentialDefaulting (SKY-10988 conditional routing)", () => {
+ test("preserves explicit conditional branch + merge routing instead of array-ordering it", () => {
+ const result = applySequentialDefaulting([
+ conditional("choose", "merge", ["branch_a", "branch_b"]),
+ code("branch_a", "merge"),
+ code("branch_b", "merge"),
+ code("merge", null),
+ ]);
+
+ expect(result.map((b) => [b.label, b.next_block_label])).toEqual([
+ ["choose", "merge"],
+ ["branch_a", "merge"],
+ ["branch_b", "merge"],
+ ["merge", null],
+ ]);
+ expect(() => validateWorkflowBlocks(result)).not.toThrow();
+ });
+
+ test("connects a sequential top level while preserving a conditional nested in a loop", () => {
+ const loop = forLoop("loop", [
+ conditional("inner_choice", "inner_merge", ["leaf"]),
+ code("leaf", null),
+ code("inner_merge", null),
+ ]);
+
+ const result = applySequentialDefaulting([loop, code("after", null)]);
+
+ expect(result[0]!.next_block_label).toBe("after");
+ expect(result[1]!.next_block_label).toBeNull();
+ const loopBlocks = (result[0] as ForLoopBlock).loop_blocks;
+ expect(loopBlocks.map((b) => b.next_block_label)).toEqual([
+ "inner_merge",
+ null,
+ null,
+ ]);
+ });
+});
diff --git a/skyvern-frontend/src/routes/workflows/editor/workflowEditorUtils.ts b/skyvern-frontend/src/routes/workflows/editor/workflowEditorUtils.ts
index dda41a50c..684cb68ec 100644
--- a/skyvern-frontend/src/routes/workflows/editor/workflowEditorUtils.ts
+++ b/skyvern-frontend/src/routes/workflows/editor/workflowEditorUtils.ts
@@ -4070,32 +4070,6 @@ function clone<T>(objectToClone: T): T {
return JSON.parse(JSON.stringify(objectToClone));
}
-export function upgradeWorkflowBlocksV1toV2(
- blocks: Array<WorkflowBlock>,
-): Array<WorkflowBlock> {
- if (!blocks || blocks.length === 0) {
- return blocks;
- }
-
- return blocks.map((block, index) => {
- const nextBlock = blocks[index + 1];
- const upgradedBlock = {
- ...block,
- next_block_label: nextBlock?.label ?? null,
- };
-
- // Recursively handle loop blocks
- if (isNestedLoopWorkflowBlock(block)) {
- return {
- ...upgradedBlock,
- loop_blocks: upgradeWorkflowBlocksV1toV2(block.loop_blocks),
- } as WorkflowBlock;
- }
-
- return upgradedBlock;
- });
-}
-
export function upgradeWorkflowDefinitionToVersionTwo(
blocks: Array<BlockYAML>,
currentVersion?: number | null,
diff --git a/skyvern/forge/sdk/workflow/models/block.py b/skyvern/forge/sdk/workflow/models/block.py
index c3a439165..7c691a6fc 100644
--- a/skyvern/forge/sdk/workflow/models/block.py
+++ b/skyvern/forge/sdk/workflow/models/block.py
@@ -2211,6 +2211,9 @@ class ForLoopBlock(Block):
if default_next_map.get(block.label) is None:
default_next_map[block.label] = blocks[idx + 1].label
+ # SKY-8571: connect conditional branch terminals to the conditional's merge-point successor.
+ resolve_conditional_merge_edges(blocks, label_to_block, default_next_map)
+
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}
@@ -2851,6 +2854,9 @@ class WhileLoopBlock(Block):
if default_next_map.get(block.label) is None:
default_next_map[block.label] = blocks[idx + 1].label
+ # SKY-8571: connect conditional branch terminals to the conditional's merge-point successor.
+ resolve_conditional_merge_edges(blocks, label_to_block, default_next_map)
+
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}
@@ -9552,3 +9558,40 @@ BlockTypeVar = Annotated[BlockSubclasses, Field(discriminator="block_type")]
BranchCriteriaSubclasses = Union[JinjaBranchCriteria, PromptBranchCriteria]
BranchCriteriaTypeVar = Annotated[BranchCriteriaSubclasses, Field(discriminator="criteria_type")]
+
+
+def resolve_conditional_merge_edges(
+ blocks: list[BlockTypeVar],
+ label_to_block: dict[str, BlockTypeVar],
+ default_next_map: dict[str, str | None],
+) -> None:
+ """Point each conditional branch chain's terminal block at the conditional's successor (merge point).
+
+ SKY-8571: iterates to convergence so an outer conditional patched on one pass can let an inner
+ conditional's branch terminals be patched on the next. Mutates default_next_map in place.
+ """
+ changed = True
+ while changed:
+ changed = False
+ for block in blocks:
+ if not isinstance(block, ConditionalBlock):
+ continue
+ successor = default_next_map.get(block.label)
+ if not successor:
+ continue
+ for branch in block.ordered_branches:
+ target = branch.next_block_label
+ if not target or target == successor:
+ continue
+ cur: str | None = target
+ visited: set[str] = set()
+ while cur and cur in label_to_block and cur not in visited:
+ if cur == successor:
+ break
+ visited.add(cur)
+ nxt = default_next_map.get(cur)
+ if nxt is None:
+ default_next_map[cur] = successor
+ changed = True
+ break
+ cur = nxt
diff --git a/skyvern/forge/sdk/workflow/service.py b/skyvern/forge/sdk/workflow/service.py
index 3ceb96eca..63e958481 100644
--- a/skyvern/forge/sdk/workflow/service.py
+++ b/skyvern/forge/sdk/workflow/service.py
@@ -93,6 +93,7 @@ from skyvern.forge.sdk.workflow.models.block import (
WorkflowTriggerBlock,
compute_conditional_scopes,
get_all_blocks,
+ resolve_conditional_merge_edges,
)
from skyvern.forge.sdk.workflow.models.parameter import (
AWSSecretParameter,
@@ -3797,46 +3798,8 @@ class WorkflowService:
if default_next_map.get(block.label) is None:
default_next_map[block.label] = blocks[idx + 1].label
- # SKY-8571: Connect terminal blocks in conditional branch chains to the
- # conditional's successor (merge-point block).
- #
- # Bug scenario: nested conditionals where the inner conditional has no
- # merge-point (next_block_label=null). The outer conditional's branch
- # chain ends at the inner conditional, whose own branches terminate
- # without reconnecting to the outer merge-point.
- #
- # The fix iterates until convergence because patching an outer
- # conditional may give an inner conditional a successor, which in turn
- # lets the inner conditional's branch terminals be patched on the next
- # pass. E.g.:
- # Pass 1: outer_cond patches inner_cond.next → outer_merge
- # Pass 2: inner_cond (now has successor) patches block_57.next → outer_merge
- changed = True
- while changed:
- changed = False
- for block in all_blocks:
- if not isinstance(block, ConditionalBlock):
- continue
- successor = default_next_map.get(block.label)
- if not successor:
- continue
- for branch in block.ordered_branches:
- target = branch.next_block_label
- if not target or target == successor:
- continue
- # Trace the branch chain via default_next_map to find the terminal block.
- cur = target
- visited: set[str] = set()
- while cur and cur in label_to_block and cur not in visited:
- if cur == successor:
- break
- visited.add(cur)
- nxt = default_next_map.get(cur)
- if nxt is None:
- default_next_map[cur] = successor
- changed = True
- break
- cur = nxt
+ # SKY-8571: connect conditional branch terminals to the conditional's merge-point successor.
+ resolve_conditional_merge_edges(all_blocks, label_to_block, default_next_map)
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}
diff --git a/skyvern/forge/sdk/workflow/workflow_definition_converter.py b/skyvern/forge/sdk/workflow/workflow_definition_converter.py
index 5f4ee2c85..49b395316 100644
--- a/skyvern/forge/sdk/workflow/workflow_definition_converter.py
+++ b/skyvern/forge/sdk/workflow/workflow_definition_converter.py
@@ -327,10 +327,8 @@ def convert_workflow_definition(
blocks.append(block)
block_label_mapping[block.label] = block
- # Set the blocks for the workflow definition and derive DAG version metadata
- dag_version = workflow_definition_yaml.version
- if dag_version is None:
- dag_version = 2 if _has_dag_metadata(workflow_definition_yaml.blocks) else 1
+ # version is populated by the WorkflowDefinitionYAML after-validator; `or 1` only narrows int | None.
+ dag_version = workflow_definition_yaml.version or 1
workflow_definition = WorkflowDefinition(
parameters=parameters.values(),
@@ -943,12 +941,3 @@ def _resolve_block_parameters(
) -> list[PARAMETER_TYPE]:
parameter_keys = getattr(block_yaml, "parameter_keys", None)
return [parameters[parameter_key] for parameter_key in parameter_keys] if parameter_keys else []
-
-
-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, WhileLoopBlockYAML)) and _has_dag_metadata(block_yaml.loop_blocks):
- return True
- return False
diff --git a/skyvern/schemas/workflows.py b/skyvern/schemas/workflows.py
index f21da0861..94030b7df 100644
--- a/skyvern/schemas/workflows.py
+++ b/skyvern/schemas/workflows.py
@@ -1243,8 +1243,17 @@ BLOCK_YAML_SUBCLASSES = (
BLOCK_YAML_TYPES = Annotated[BLOCK_YAML_SUBCLASSES, Field(discriminator="block_type")]
+def workflow_definition_has_v2_graph_constructs(blocks: list[BLOCK_YAML_SUBCLASSES]) -> bool:
+ """Whether top-level routing requires version 2: a conditional block or explicit next_block_label.
+
+ Loop interiors are not inspected - `version` describes only top-level routing, and loop bodies are
+ graph-built independently by Block._build_loop_graph regardless of the workflow version.
+ """
+ return any(isinstance(block, ConditionalBlockYAML) or block.next_block_label is not None for block in blocks)
+
+
class WorkflowDefinitionYAML(BaseModel):
- version: int = 1
+ version: int | None = None
parameters: list[PARAMETER_YAML_TYPES]
blocks: list[BLOCK_YAML_TYPES]
finally_block_label: str | None = None
@@ -1269,6 +1278,15 @@ class WorkflowDefinitionYAML(BaseModel):
f"Available labels: {', '.join(labels) if labels else '(none)'}"
)
+ has_v2_graph_constructs = workflow_definition_has_v2_graph_constructs(self.blocks)
+ if self.version is None:
+ self.version = 2 if has_v2_graph_constructs else 1
+ elif self.version < 2 and has_v2_graph_constructs:
+ raise ValueError(
+ "workflow_definition.version must be 2 or greater when using conditional blocks "
+ "or explicit next_block_label routing."
+ )
+
return self
diff --git a/tests/unit/test_workflow_definition_version_inference.py b/tests/unit/test_workflow_definition_version_inference.py
new file mode 100644
index 000000000..cacb1d115
--- /dev/null
+++ b/tests/unit/test_workflow_definition_version_inference.py
@@ -0,0 +1,222 @@
+"""Tests for workflow_definition.version inference and graph validation.
+
+version describes only top-level routing. A definition is v2 when its top-level blocks use a
+conditional or explicit next_block_label; loop interiors are graph-built independently and do not
+promote the top-level version. Conditional branch chains that omit their merge edge are resolved by
+the shared SKY-8571 merge resolver at both the top level and inside loops.
+"""
+
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+
+from skyvern.forge.sdk.workflow.service import WorkflowService
+from skyvern.forge.sdk.workflow.workflow_definition_converter import (
+ convert_workflow_definition,
+)
+from skyvern.schemas.workflows import WorkflowCreateYAMLRequest
+
+_MISSING = object()
+
+
+def _navigation_block(label: str, next_block_label: str | None | object = _MISSING) -> dict[str, object]:
+ block: dict[str, object] = {
+ "block_type": "navigation",
+ "label": label,
+ "navigation_goal": f"Visit {label}",
+ "url": "https://example.com",
+ }
+ if next_block_label is not _MISSING:
+ block["next_block_label"] = next_block_label
+ return block
+
+
+def _conditional_block(label: str, next_block_label: str | None) -> dict[str, object]:
+ return {
+ "block_type": "conditional",
+ "label": label,
+ "branch_conditions": [
+ {
+ "is_default": True,
+ "next_block_label": next_block_label,
+ },
+ ],
+ }
+
+
+def _conditional_block_with_merge(
+ label: str,
+ branch_labels: list[str],
+ merge_label: str,
+) -> dict[str, object]:
+ return {
+ "block_type": "conditional",
+ "label": label,
+ "next_block_label": merge_label,
+ "branch_conditions": [
+ {
+ "is_default": index == len(branch_labels) - 1,
+ "next_block_label": branch_label,
+ **(
+ {}
+ if index == len(branch_labels) - 1
+ else {"criteria": {"criteria_type": "jinja2_template", "expression": "{{ true }}"}}
+ ),
+ }
+ for index, branch_label in enumerate(branch_labels)
+ ],
+ }
+
+
+def _for_loop_block(
+ label: str,
+ loop_blocks: list[dict[str, object]],
+ next_block_label: str | None | object = _MISSING,
+) -> dict[str, object]:
+ block: dict[str, object] = {
+ "block_type": "for_loop",
+ "label": label,
+ "loop_variable_reference": "item",
+ "loop_blocks": loop_blocks,
+ }
+ if next_block_label is not _MISSING:
+ block["next_block_label"] = next_block_label
+ return block
+
+
+def _request_payload(
+ blocks: list[dict[str, object]],
+ version: int | None | object = _MISSING,
+) -> dict[str, object]:
+ workflow_definition: dict[str, object] = {
+ "parameters": [],
+ "blocks": blocks,
+ }
+ if version is not _MISSING:
+ workflow_definition["version"] = version
+ return {
+ "title": "Version inference test",
+ "workflow_definition": workflow_definition,
+ }
+
+
+def _validate_request(
+ blocks: list[dict[str, object]],
+ version: int | None | object = _MISSING,
+) -> WorkflowCreateYAMLRequest:
+ return WorkflowCreateYAMLRequest.model_validate(_request_payload(blocks, version))
+
+
+def test_omitted_version_defaults_to_one_for_sequential_workflows() -> None:
+ """Definitions with no top-level graph constructs remain legacy v1."""
+ request = _validate_request([_navigation_block("first"), _navigation_block("second")])
+ assert request.workflow_definition.version == 1
+
+
+def test_omitted_version_infers_two_for_top_level_conditional() -> None:
+ request = _validate_request([_conditional_block("choose_path", "done"), _navigation_block("done")])
+ assert request.workflow_definition.version == 2
+ converted = convert_workflow_definition(request.workflow_definition, workflow_id="wf_test")
+ assert converted.version == 2
+
+
+def test_omitted_version_infers_two_for_top_level_next_block_label() -> None:
+ request = _validate_request([_navigation_block("first", "second"), _navigation_block("second", None)])
+ assert request.workflow_definition.version == 2
+
+
+def test_nested_only_v2_constructs_keep_top_level_v1() -> None:
+ """A sequential top level stays v1 even when a loop body uses v2 constructs; the blocks are not
+ mutated and the definition is accepted (validation is skipped for v1)."""
+ request = _validate_request(
+ [
+ _for_loop_block(
+ "loop",
+ [
+ _navigation_block("inner_first", "inner_second"),
+ _navigation_block("inner_second", None),
+ ],
+ ),
+ _navigation_block("after_loop"),
+ ]
+ )
+ assert request.workflow_definition.version == 1
+ loop_block, after_loop_block = request.workflow_definition.blocks
+ assert loop_block.next_block_label is None
+ assert after_loop_block.next_block_label is None
+ converted = convert_workflow_definition(request.workflow_definition, workflow_id="wf_test")
+ WorkflowService().validate_workflow_block_graph(converted)
+
+
+def test_conditional_branch_terminals_validate_via_merge_resolution() -> None:
+ """A top-level conditional whose branches omit the merge edge validates: the shared resolver
+ reconnects each branch terminal to the conditional's successor. Blocks are not mutated on parse."""
+ request = _validate_request(
+ [
+ _conditional_block_with_merge("choose_path", ["branch_a", "branch_b"], "merge"),
+ _navigation_block("branch_a"),
+ _navigation_block("branch_b"),
+ _navigation_block("merge"),
+ ]
+ )
+ assert request.workflow_definition.version == 2
+ _, branch_a_block, branch_b_block, merge_block = request.workflow_definition.blocks
+ assert branch_a_block.next_block_label is None
+ assert branch_b_block.next_block_label is None
+ converted = convert_workflow_definition(request.workflow_definition, workflow_id="wf_test")
+ WorkflowService().validate_workflow_block_graph(converted)
+
+
+def test_loop_with_nested_conditional_validates_via_shared_merge_resolution() -> None:
+ """SKY-8571: loop validation uses the same merge resolution as the top-level builder, so a loop
+ body with a conditional whose branch omits the merge edge is not rejected as disconnected."""
+ request = _validate_request(
+ [
+ _navigation_block("start", "loop"),
+ _for_loop_block(
+ "loop",
+ [
+ _conditional_block_with_merge("inner_choice", ["leaf"], "inner_merge"),
+ _navigation_block("leaf"),
+ _navigation_block("inner_merge"),
+ ],
+ ),
+ ]
+ )
+ assert request.workflow_definition.version == 2
+ converted = convert_workflow_definition(request.workflow_definition, workflow_id="wf_test")
+ WorkflowService().validate_workflow_block_graph(converted)
+
+
+ "blocks",
+ [
+ pytest.param([_conditional_block("choose_path", None)], id="conditional"),
+ pytest.param(
+ [_navigation_block("first", "second"), _navigation_block("second", None)],
+ id="next_block_label",
+ ),
+ ],
+)
+def test_explicit_version_one_rejects_top_level_v2_constructs(blocks: list[dict[str, object]]) -> None:
+ """Explicit v1 definitions must not contain top-level v2-only graph constructs."""
+ with pytest.raises(ValidationError, match="version.*2"):
+ _validate_request(blocks, version=1)
+
+
+def test_explicit_version_one_allows_nested_only_constructs() -> None:
+ """A v1 top level is valid even when a loop body uses v2 constructs."""
+ request = _validate_request(
+ [
+ _for_loop_block(
+ "loop",
+ [
+ _navigation_block("inner_first", "inner_second"),
+ _navigation_block("inner_second", None),
+ ],
+ )
+ ],
+ version=1,
+ )
+ assert request.workflow_definition.version == 1