Skip to content

Automate browser based workflows with AI

feat(mcp): enforce code-only mode on workflow persist path (connector, M4) (#6998)

Marc Kelechavafe84736f319e
diff --git a/skyvern/cli/mcp_tools/workflow.py b/skyvern/cli/mcp_tools/workflow.py
index 0514b34d9..64df10b23 100644
--- a/skyvern/cli/mcp_tools/workflow.py
+++ b/skyvern/cli/mcp_tools/workflow.py
@@ -436,6 +436,56 @@ def _validate_definition_structure(json_def: dict[str, Any] | None, action: str)
return None
+def _extract_workflow_blocks(definition: dict[str, Any]) -> list[Any]:
+ block_lists: list[list[Any]] = []
+ top_level_blocks = definition.get("blocks")
+ if isinstance(top_level_blocks, list):
+ block_lists.append(top_level_blocks)
+
+ workflow_definition = definition.get("workflow_definition")
+ if isinstance(workflow_definition, dict):
+ workflow_blocks = workflow_definition.get("blocks")
+ if isinstance(workflow_blocks, list) and workflow_blocks is not top_level_blocks:
+ block_lists.append(workflow_blocks)
+
+ return [block for blocks in block_lists for block in blocks]
+
+
+def _validate_code_only_workflow_blocks(definition: dict[str, Any], action: str) -> dict[str, Any] | None:
+ blocks = _extract_workflow_blocks(definition)
+ if not blocks:
+ return None
+
+ # Preserve the lightweight-install constraint; copilot helpers require server-only deps.
+ from skyvern.forge.sdk.copilot.tools.banned_blocks import ( # noqa: PLC0415
+ collect_code_only_banned_items,
+ )
+
+ banned_items = collect_code_only_banned_items(blocks)
+ if not banned_items:
+ return None
+
+ labels = ", ".join(sorted({label for label, _ in banned_items}))
+ types = ", ".join(sorted({block_type for _, block_type in banned_items}))
+ return make_result(
+ action,
+ ok=False,
+ error=make_error(
+ ErrorCode.INVALID_INPUT,
+ f"Block type(s) {types} are not allowed in code-only mode (offending labels: {labels})",
+ "In code-only mode, use a `code` block for durable browser/page work instead of "
+ "task/navigation/extraction/etc.",
+ ),
+ )
+
+
+def _validate_code_only_definition(definition: str, fmt: str, action: str) -> dict[str, Any] | None:
+ raw, _ = _load_definition_dict(definition, fmt)
+ if raw is None:
+ return None
+ return _validate_code_only_workflow_blocks(raw, action)
+
+
_CODE_V2_DEFAULTS: dict[str, Any] = {
"code_version": 2,
"run_with": "agent",
@@ -1289,6 +1339,13 @@ async def skyvern_workflow_create(
str, Field(description="Definition format: 'json', 'yaml', or 'auto' (tries JSON first, falls back to YAML)")
] = "auto",
folder_id: Annotated[str | None, "Folder ID (fld_...) to organize the workflow in"] = None,
+ code_only: Annotated[
+ bool,
+ Field(
+ description="When true, structurally reject non-code browser/page block types before persisting "
+ "(code-only mode)"
+ ),
+ ] = False,
) -> dict[str, Any]:
"""Create a reusable, versioned workflow from a YAML or JSON definition. For multi-page automations,
scheduling, and repeated runs — not one-off trials (use skyvern_run_task for those).
@@ -1333,6 +1390,13 @@ async def skyvern_workflow_create(
if err := _validate_definition_structure(json_def, "skyvern_workflow_create"):
return err
+ if code_only:
+ if json_def is not None:
+ if err := _validate_code_only_workflow_blocks(json_def, "skyvern_workflow_create"):
+ return err
+ elif err := _validate_code_only_definition(definition, format, "skyvern_workflow_create"):
+ return err
+
with Timer() as timer:
try:
workflow = await create_workflow_raw(
@@ -1368,6 +1432,13 @@ async def skyvern_workflow_update(
format: Annotated[ # noqa: A002
str, Field(description="Definition format: 'json', 'yaml', or 'auto'")
] = "auto",
+ code_only: Annotated[
+ bool,
+ Field(
+ description="When true, structurally reject non-code browser/page block types before persisting "
+ "(code-only mode)"
+ ),
+ ] = False,
) -> dict[str, Any]:
"""Update an existing workflow's definition. Use when you need to modify a workflow's blocks,
parameters, or configuration. Creates a new version of the workflow."""
@@ -1385,6 +1456,10 @@ async def skyvern_workflow_update(
),
)
+ if code_only:
+ if err := _validate_code_only_definition(definition, format, "skyvern_workflow_update"):
+ return err
+
param_warnings: list[str] = []
try:
definition = await _inject_workflow_update_proxy_default(definition, format, workflow_id)
diff --git a/tests/unit/test_workflow_persist_code_only.py b/tests/unit/test_workflow_persist_code_only.py
new file mode 100644
index 000000000..f9852d91c
--- /dev/null
+++ b/tests/unit/test_workflow_persist_code_only.py
@@ -0,0 +1,231 @@
+from __future__ import annotations
+
+import json
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+
+import skyvern.cli.mcp_tools.workflow as workflow_tools
+from tests.unit._mcp_test_helpers import patch_get_workflow_by_id as _patch_get_workflow_by_id
+from tests.unit._mcp_test_helpers import patch_skyvern_client as _patch_skyvern_client
+
+
+def _fake_workflow_dict(**overrides: object) -> dict[str, object]:
+ data: dict[str, object] = {
+ "workflow_permanent_id": "wpid_test",
+ "workflow_id": "wf_test",
+ "title": "Example Workflow",
+ "version": 1,
+ "status": "published",
+ "description": None,
+ "is_saved_task": False,
+ "folder_id": None,
+ "created_at": "2026-04-23T10:00:00+00:00",
+ "modified_at": "2026-04-23T10:00:00+00:00",
+ }
+ data.update(overrides)
+ return data
+
+
+def _patch_skyvern_http(monkeypatch: pytest.MonkeyPatch) -> AsyncMock:
+ response = SimpleNamespace(
+ status_code=200,
+ json=lambda: _fake_workflow_dict(),
+ text=json.dumps(_fake_workflow_dict()),
+ )
+ request_mock = AsyncMock(return_value=response)
+ fake_skyvern = SimpleNamespace(
+ _client_wrapper=SimpleNamespace(httpx_client=SimpleNamespace(request=request_mock)),
+ )
+ _patch_skyvern_client(monkeypatch, fake_skyvern)
+ return request_mock
+
+
+def _patch_existing_workflow(monkeypatch: pytest.MonkeyPatch) -> AsyncMock:
+ existing_workflow = {
+ "proxy_location": "RESIDENTIAL",
+ "workflow_definition": {
+ "parameters": [],
+ "blocks": [],
+ },
+ }
+ get_workflow_by_id = AsyncMock(return_value=existing_workflow)
+ _patch_get_workflow_by_id(monkeypatch, get_workflow_by_id)
+ return get_workflow_by_id
+
+
+def _navigation_block(**overrides: object) -> dict[str, object]:
+ block: dict[str, object] = {
+ "block_type": "navigation",
+ "label": "visit_page",
+ "url": "https://example.com",
+ "navigation_goal": "Open the page",
+ }
+ block.update(overrides)
+ return block
+
+
+def _code_block() -> dict[str, object]:
+ return {
+ "block_type": "code",
+ "label": "visit_in_code",
+ "code": 'await page.goto("https://example.com")\nreturn {"ok": True}',
+ }
+
+
+def _workflow_definition(blocks: list[object], **overrides: object) -> dict[str, object]:
+ definition: dict[str, object] = {
+ "title": "Code only workflow",
+ "workflow_definition": {
+ "parameters": [],
+ "blocks": blocks,
+ },
+ }
+ definition.update(overrides)
+ return definition
+
+
+def _assert_code_only_rejection(result: dict[str, object], *, label: str) -> None:
+ assert result["ok"] is False
+ error = result["error"]
+ assert isinstance(error, dict)
+ assert error["code"] == workflow_tools.ErrorCode.INVALID_INPUT
+ assert "not allowed in code-only mode" in str(error["message"])
+ assert label in str(error["message"])
+ assert "use a `code` block" in str(error["hint"])
+
+
+async def test_workflow_create_rejects_navigation_block_in_code_only_mode(monkeypatch: pytest.MonkeyPatch) -> None:
+ request_mock = _patch_skyvern_http(monkeypatch)
+ definition = _workflow_definition([_navigation_block()])
+
+ result = await workflow_tools.skyvern_workflow_create(
+ definition=json.dumps(definition),
+ format="json",
+ code_only=True,
+ )
+
+ _assert_code_only_rejection(result, label="visit_page")
+ request_mock.assert_not_awaited()
+
+
+async def test_workflow_create_defaults_code_only_off_and_persists_navigation(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ request_mock = _patch_skyvern_http(monkeypatch)
+ definition = _workflow_definition([_navigation_block()])
+
+ result = await workflow_tools.skyvern_workflow_create(definition=json.dumps(definition), format="json")
+
+ assert result["ok"] is True, result
+ request_mock.assert_awaited_once()
+
+
+async def test_workflow_create_accepts_code_block_in_code_only_mode(monkeypatch: pytest.MonkeyPatch) -> None:
+ request_mock = _patch_skyvern_http(monkeypatch)
+ definition = _workflow_definition([_code_block()])
+
+ result = await workflow_tools.skyvern_workflow_create(
+ definition=json.dumps(definition),
+ format="json",
+ code_only=True,
+ )
+
+ assert result["ok"] is True, result
+ request_mock.assert_awaited_once()
+
+
+async def test_workflow_create_rejects_task_block_nested_in_loop_in_code_only_mode(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ request_mock = _patch_skyvern_http(monkeypatch)
+ definition = _workflow_definition(
+ [
+ {
+ "block_type": "for_loop",
+ "label": "for_each_item",
+ "loop_over_parameter_key": "items",
+ "loop_blocks": [
+ {
+ "block_type": "task",
+ "label": "legacy_task",
+ "url": "https://example.com",
+ "navigation_goal": "Open the page",
+ }
+ ],
+ }
+ ]
+ )
+
+ result = await workflow_tools.skyvern_workflow_create(
+ definition=json.dumps(definition),
+ format="json",
+ code_only=True,
+ )
+
+ _assert_code_only_rejection(result, label="legacy_task")
+ request_mock.assert_not_awaited()
+
+
+async def test_workflow_create_rejects_label_less_navigation_block_in_code_only_mode(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ request_mock = _patch_skyvern_http(monkeypatch)
+ navigation_block = _navigation_block()
+ navigation_block.pop("label")
+ definition = _workflow_definition([navigation_block])
+
+ result = await workflow_tools.skyvern_workflow_create(
+ definition=json.dumps(definition),
+ format="json",
+ code_only=True,
+ )
+
+ _assert_code_only_rejection(result, label="(unlabeled)")
+ request_mock.assert_not_awaited()
+
+
+async def test_workflow_update_rejects_navigation_block_in_code_only_mode(monkeypatch: pytest.MonkeyPatch) -> None:
+ request_mock = _patch_skyvern_http(monkeypatch)
+ get_workflow_by_id = _patch_existing_workflow(monkeypatch)
+ definition = _workflow_definition([_navigation_block()])
+
+ result = await workflow_tools.skyvern_workflow_update(
+ workflow_id="wpid_test",
+ definition=json.dumps(definition),
+ format="json",
+ code_only=True,
+ )
+
+ _assert_code_only_rejection(result, label="visit_page")
+ request_mock.assert_not_awaited()
+ get_workflow_by_id.assert_not_awaited()
+
+
+async def test_workflow_update_accepts_code_block_in_code_only_mode(monkeypatch: pytest.MonkeyPatch) -> None:
+ request_mock = _patch_skyvern_http(monkeypatch)
+ _patch_existing_workflow(monkeypatch)
+ definition = _workflow_definition(
+ [_code_block()],
+ proxy_location="RESIDENTIAL",
+ run_sequentially=True,
+ sequential_key="code-only",
+ )
+
+ result = await workflow_tools.skyvern_workflow_update(
+ workflow_id="wpid_test",
+ definition=json.dumps(definition),
+ format="json",
+ code_only=True,
+ )
+
+ assert result["ok"] is True, result
+ request_mock.assert_awaited_once()