Skip to content

Automate browser based workflows with AI

chore(SKY-9227): prevent Fern SDK drift from breaking workflow block types (#5769)

Marc Kelechava3170bcd9ecb0
diff --git a/skyvern/cli/mcp_tools/_workflow_http.py b/skyvern/cli/mcp_tools/_workflow_http.py
new file mode 100644
index 000000000..361b90047
--- /dev/null
+++ b/skyvern/cli/mcp_tools/_workflow_http.py
@@ -0,0 +1,225 @@
+"""Raw workflow HTTP helpers for MCP tools.
+
+Keep workflow definitions as plain dicts here. Constructing Fern-generated
+workflow/block models in MCP can reject backend-valid block types when the
+vendored SDK is behind the backend enum.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import structlog
+
+from skyvern.client.errors import BadRequestError, NotFoundError
+
+from ._session import get_skyvern
+
+LOG = structlog.get_logger()
+
+_ERROR_DETAIL_LIMIT = 500
+
+PUBLIC_WORKFLOW_ROUTE = "v1/workflows"
+INTERNAL_WORKFLOW_ROUTE = "api/v1/workflows"
+
+
+def coerce_timestamp(value: Any) -> str | None:
+ """Normalize a timestamp coming from either a raw dict or a Fern model."""
+ if value is None:
+ return None
+ if isinstance(value, str):
+ return value
+ isoformat = getattr(value, "isoformat", None)
+ if callable(isoformat):
+ return isoformat()
+ LOG.debug("Unexpected timestamp type in workflow response", value_type=type(value).__name__)
+ return str(value)
+
+
+def extract_error_detail(response: Any) -> str:
+ """Pull a readable detail out of an httpx Response, bounded by _ERROR_DETAIL_LIMIT.
+
+ Truncation is applied uniformly to both JSON-path and non-JSON-path outputs,
+ because a verbose ``detail`` field (e.g., a backend stack trace) can be just
+ as unbounded as an HTML error page.
+ """
+ try:
+ body = response.json()
+ except Exception:
+ detail = str(getattr(response, "text", ""))
+ else:
+ if isinstance(body, dict):
+ detail = str(body.get("detail") or body.get("error") or body)
+ else:
+ detail = str(body)
+ return detail[:_ERROR_DETAIL_LIMIT] if len(detail) > _ERROR_DETAIL_LIMIT else detail
+
+
+def _decode_success_payload(response: Any, *, operation: str) -> Any:
+ """Decode a successful JSON response with operation context for clearer MCP errors."""
+ try:
+ return response.json()
+ except Exception as exc:
+ detail = extract_error_detail(response)
+ suffix = f": {detail}" if detail else ""
+ raise RuntimeError(f"Unexpected {operation} response: failed to decode JSON body{suffix}") from exc
+
+
+async def list_workflows_raw(
+ *,
+ search: str | None,
+ page: int,
+ page_size: int,
+ only_workflows: bool,
+) -> list[dict[str, Any]]:
+ """GET /v1/workflows — returns a list of raw workflow dicts."""
+ skyvern = get_skyvern()
+ params: dict[str, Any] = {
+ "page": page,
+ "page_size": page_size,
+ "only_workflows": only_workflows,
+ }
+ if search is not None:
+ params["search_key"] = search
+ response = await skyvern._client_wrapper.httpx_client.request(
+ PUBLIC_WORKFLOW_ROUTE,
+ method="GET",
+ params=params,
+ )
+ if response.status_code >= 400:
+ raise RuntimeError(f"HTTP {response.status_code}: {extract_error_detail(response)}")
+ payload = _decode_success_payload(response, operation="workflows list")
+ if not isinstance(payload, list):
+ raise RuntimeError(f"Unexpected workflows list payload: {type(payload).__name__}")
+ return payload
+
+
+async def create_workflow_raw(
+ *,
+ json_definition: dict[str, Any] | None,
+ yaml_definition: str | None,
+ folder_id: str | None,
+) -> dict[str, Any]:
+ """POST /v1/workflows — returns the created workflow as a raw dict."""
+ skyvern = get_skyvern()
+ body: dict[str, Any] = {}
+ if json_definition is not None:
+ body["json_definition"] = json_definition
+ if yaml_definition is not None:
+ body["yaml_definition"] = yaml_definition
+ params: dict[str, Any] = {}
+ if folder_id is not None:
+ params["folder_id"] = folder_id
+ response = await skyvern._client_wrapper.httpx_client.request(
+ PUBLIC_WORKFLOW_ROUTE,
+ method="POST",
+ params=params,
+ json=body,
+ )
+ if response.status_code >= 400:
+ raise RuntimeError(f"HTTP {response.status_code}: {extract_error_detail(response)}")
+ payload = _decode_success_payload(response, operation="create_workflow")
+ if not isinstance(payload, dict):
+ raise RuntimeError(f"Unexpected create_workflow payload: {type(payload).__name__}")
+ return payload
+
+
+async def update_workflow_raw(
+ workflow_id: str,
+ *,
+ json_definition: dict[str, Any] | None,
+ yaml_definition: str | None,
+) -> dict[str, Any]:
+ """POST /v1/workflows/{id} — backend update endpoint uses POST, not PUT/PATCH."""
+ skyvern = get_skyvern()
+ body: dict[str, Any] = {}
+ if json_definition is not None:
+ body["json_definition"] = json_definition
+ if yaml_definition is not None:
+ body["yaml_definition"] = yaml_definition
+ response = await skyvern._client_wrapper.httpx_client.request(
+ f"{PUBLIC_WORKFLOW_ROUTE}/{workflow_id}",
+ method="POST",
+ json=body,
+ )
+ if response.status_code == 404:
+ raise NotFoundError(body={"detail": f"Workflow {workflow_id!r} not found"})
+ if response.status_code >= 400:
+ raise RuntimeError(f"HTTP {response.status_code}: {extract_error_detail(response)}")
+ payload = _decode_success_payload(response, operation="update_workflow")
+ if not isinstance(payload, dict):
+ raise RuntimeError(f"Unexpected update_workflow payload: {type(payload).__name__}")
+ return payload
+
+
+async def update_workflow_folder_raw(workflow_id: str, *, folder_id: str | None) -> dict[str, Any]:
+ """PUT /v1/workflows/{id}/folder — returns the updated workflow as a raw dict."""
+ skyvern = get_skyvern()
+ response = await skyvern._client_wrapper.httpx_client.request(
+ f"{PUBLIC_WORKFLOW_ROUTE}/{workflow_id}/folder",
+ method="PUT",
+ json={"folder_id": folder_id},
+ )
+ if response.status_code == 404:
+ raise NotFoundError(body={"detail": f"Workflow {workflow_id!r} not found"})
+ if response.status_code == 400:
+ raise BadRequestError(body={"detail": extract_error_detail(response)})
+ if response.status_code >= 400:
+ raise RuntimeError(f"HTTP {response.status_code}: {extract_error_detail(response)}")
+ payload = _decode_success_payload(response, operation="update_workflow_folder")
+ if not isinstance(payload, dict):
+ raise RuntimeError(f"Unexpected update_workflow_folder payload: {type(payload).__name__}")
+ return payload
+
+
+async def get_workflow_by_id(workflow_id: str, version: int | None = None) -> dict[str, Any]:
+ """GET /api/v1/workflows/{id} — returns a single workflow as a raw dict.
+
+ Uses ``INTERNAL_WORKFLOW_ROUTE`` because the Fern-generated client's public
+ ``get_workflow(id)`` does not expose the ``version`` parameter we rely on
+ for historic-version lookups. Revisit on next Fern regen (see SKY-7807).
+ """
+ skyvern = get_skyvern()
+ params: dict[str, Any] = {}
+ if version is not None:
+ params["version"] = version
+ response = await skyvern._client_wrapper.httpx_client.request(
+ f"{INTERNAL_WORKFLOW_ROUTE}/{workflow_id}",
+ method="GET",
+ params=params,
+ )
+ if response.status_code == 404:
+ raise NotFoundError(body={"detail": f"Workflow {workflow_id!r} not found"})
+ if response.status_code >= 400:
+ raise RuntimeError(f"HTTP {response.status_code}: {extract_error_detail(response)}")
+ payload = _decode_success_payload(response, operation="get_workflow")
+ if not isinstance(payload, dict):
+ raise RuntimeError(f"Unexpected get_workflow payload: {type(payload).__name__}")
+ return payload
+
+
+async def get_workflow_run_status(
+ workflow_run_id: str,
+ *,
+ include_output_details: bool,
+) -> dict[str, Any]:
+ """GET /api/v1/workflows/runs/{id} — returns workflow run detail as a raw dict.
+
+ Uses ``INTERNAL_WORKFLOW_ROUTE`` because the Fern SDK's ``get_run()`` only
+ covers the unified ``/v1/runs/{id}`` surface and doesn't accept
+ ``include_output_details`` for ``wr_`` ids.
+ """
+ skyvern = get_skyvern()
+ response = await skyvern._client_wrapper.httpx_client.request(
+ f"{INTERNAL_WORKFLOW_ROUTE}/runs/{workflow_run_id}",
+ method="GET",
+ params={"include_output_details": include_output_details},
+ )
+ if response.status_code == 404:
+ raise NotFoundError(body={"detail": f"Workflow run {workflow_run_id!r} not found"})
+ if response.status_code >= 400:
+ raise RuntimeError(f"HTTP {response.status_code}: {extract_error_detail(response)}")
+ payload = _decode_success_payload(response, operation="get_workflow_run_status")
+ if not isinstance(payload, dict):
+ raise RuntimeError(f"Unexpected get_workflow_run_status payload: {type(payload).__name__}")
+ return payload
diff --git a/skyvern/cli/mcp_tools/workflow.py b/skyvern/cli/mcp_tools/workflow.py
index 3363f58f2..602cc92c9 100644
--- a/skyvern/cli/mcp_tools/workflow.py
+++ b/skyvern/cli/mcp_tools/workflow.py
@@ -26,6 +26,15 @@ from skyvern.utils.yaml_loader import safe_load_no_dates
from ._common import ErrorCode, Timer, make_error, make_result
from ._session import get_skyvern
from ._validation import validate_folder_id, validate_run_id, validate_workflow_id
+from ._workflow_http import (
+ coerce_timestamp,
+ create_workflow_raw,
+ get_workflow_by_id,
+ get_workflow_run_status,
+ list_workflows_raw,
+ update_workflow_folder_raw,
+ update_workflow_raw,
+)
LOG = structlog.get_logger()
_SUMMARY_TOP_LEVEL_KEY_LIMIT = 8
@@ -33,7 +42,6 @@ _SUMMARY_SCALAR_PREVIEW_LIMIT = 3
_SUMMARY_ARTIFACT_PREVIEW_LIMIT = 4
_SUMMARY_STRING_PREVIEW_LIMIT = 120
_SUMMARY_RECURSION_LIMIT = 10
-_ERROR_DETAIL_LIMIT = 500
_SCREENSHOT_LIST_KEYS = frozenset({"task_screenshots", "workflow_screenshots", "screenshot_urls"})
_SCREENSHOT_ARTIFACT_ID_KEYS = frozenset({"task_screenshot_artifact_ids", "workflow_screenshot_artifact_ids"})
@@ -42,18 +50,6 @@ _SCREENSHOT_ARTIFACT_ID_KEYS = frozenset({"task_screenshot_artifact_ids", "workf
# ---------------------------------------------------------------------------
-def _coerce_timestamp(value: Any) -> str | None:
- if value is None:
- return None
- if isinstance(value, str):
- return value
- isoformat = getattr(value, "isoformat", None)
- if callable(isoformat):
- return isoformat()
- LOG.debug("Unexpected timestamp type in workflow response", value_type=type(value).__name__)
- return str(value)
-
-
def _serialize_workflow(wf: Any) -> dict[str, Any]:
"""Pick the fields we expose from a Workflow.
@@ -71,8 +67,8 @@ def _serialize_workflow(wf: Any) -> dict[str, Any]:
"description": _get_value(wf, "description"),
"is_saved_task": _get_value(wf, "is_saved_task"),
"folder_id": _get_value(wf, "folder_id"),
- "created_at": _coerce_timestamp(_get_value(wf, "created_at")),
- "modified_at": _coerce_timestamp(_get_value(wf, "modified_at")),
+ "created_at": coerce_timestamp(_get_value(wf, "created_at")),
+ "modified_at": coerce_timestamp(_get_value(wf, "modified_at")),
}
for caching_field in ("run_with", "code_version", "adaptive_caching"):
val = _get_value(wf, caching_field)
@@ -391,193 +387,6 @@ def _serialize_run_full(run: Any) -> dict[str, Any]:
return {key: value for key, value in data.items() if value is not None}
-async def _get_workflow_run_status(
- workflow_run_id: str,
- *,
- include_output_details: bool,
-) -> dict[str, Any]:
- skyvern = get_skyvern()
- # The generated SDK only exposes get_run() for /v1/runs/{run_id}; wr_... IDs
- # require the workflow-run detail route until a public SDK helper exists.
- response = await skyvern._client_wrapper.httpx_client.request(
- f"api/v1/workflows/runs/{workflow_run_id}",
- method="GET",
- params={"include_output_details": include_output_details},
- )
- if response.status_code == 404:
- raise NotFoundError(body={"detail": f"Workflow run {workflow_run_id!r} not found"})
- if response.status_code >= 400:
- detail = ""
- try:
- detail = response.json().get("detail", response.text)
- except Exception:
- detail = response.text
- raise RuntimeError(f"HTTP {response.status_code}: {detail}")
- return response.json()
-
-
-async def _get_workflow_by_id(workflow_id: str, version: int | None = None) -> dict[str, Any]:
- """Fetch a single workflow by ID via the Skyvern API.
-
- The Fern-generated client has get_workflows() (list) but no get_workflow(id).
- This helper isolates the private client access so the workaround is contained
- in one place. Replace with ``skyvern.get_workflow(id)`` when the SDK adds it.
-
- Raises NotFoundError on 404, or RuntimeError on other HTTP errors, so callers
- can use the same ``except NotFoundError`` pattern as all other workflow tools.
- """
- skyvern = get_skyvern()
- params: dict[str, Any] = {}
- if version is not None:
- params["version"] = version
- # SKY-7807: Replace with skyvern.get_workflow() when the Fern client adds it.
- response = await skyvern._client_wrapper.httpx_client.request(
- f"api/v1/workflows/{workflow_id}",
- method="GET",
- params=params,
- )
- if response.status_code == 404:
- raise NotFoundError(body={"detail": f"Workflow {workflow_id!r} not found"})
- if response.status_code >= 400:
- detail = ""
- try:
- detail = response.json().get("detail", response.text)
- except Exception:
- detail = response.text
- raise RuntimeError(f"HTTP {response.status_code}: {detail}")
- return response.json()
-
-
-# ---------------------------------------------------------------------------
-# Fern-bypass raw HTTP helpers
-#
-# The vendored Fern SDK ``skyvern/client`` validates Workflow requests and
-# responses through discriminated unions of block variants; any block_type that
-# the client hasn't been regenerated for (e.g. google_sheets_read) blows up the
-# MCP tool before the backend can accept it. These helpers call the backend
-# directly via the underlying httpx client, pass/return plain dicts, and
-# sidestep the drift entirely.
-#
-# The ``v1/workflows`` paths intentionally mirror the generated Fern raw client.
-# The ``api/v1`` workflow routes above are non-Fern/internal routes used only
-# where no public SDK equivalent exists yet.
-# ---------------------------------------------------------------------------
-
-
-def _extract_error_detail(response: Any) -> str:
- try:
- body = response.json()
- except Exception:
- text = str(getattr(response, "text", ""))
- return text[:_ERROR_DETAIL_LIMIT] if len(text) > _ERROR_DETAIL_LIMIT else text
- if isinstance(body, dict):
- return str(body.get("detail") or body.get("error") or body)
- return str(body)
-
-
-async def _list_workflows_raw(
- *,
- search: str | None,
- page: int,
- page_size: int,
- only_workflows: bool,
-) -> list[dict[str, Any]]:
- skyvern = get_skyvern()
- params: dict[str, Any] = {
- "page": page,
- "page_size": page_size,
- "only_workflows": only_workflows,
- }
- if search is not None:
- params["search_key"] = search
- response = await skyvern._client_wrapper.httpx_client.request(
- "v1/workflows",
- method="GET",
- params=params,
- )
- if response.status_code >= 400:
- raise RuntimeError(f"HTTP {response.status_code}: {_extract_error_detail(response)}")
- payload = response.json()
- if not isinstance(payload, list):
- raise RuntimeError(f"Unexpected workflows list payload: {type(payload).__name__}")
- return payload
-
-
-async def _create_workflow_raw(
- *,
- json_definition: dict[str, Any] | None,
- yaml_definition: str | None,
- folder_id: str | None,
-) -> dict[str, Any]:
- skyvern = get_skyvern()
- body: dict[str, Any] = {}
- if json_definition is not None:
- body["json_definition"] = json_definition
- if yaml_definition is not None:
- body["yaml_definition"] = yaml_definition
- params: dict[str, Any] = {}
- if folder_id is not None:
- params["folder_id"] = folder_id
- response = await skyvern._client_wrapper.httpx_client.request(
- "v1/workflows",
- method="POST",
- params=params,
- json=body,
- )
- if response.status_code >= 400:
- raise RuntimeError(f"HTTP {response.status_code}: {_extract_error_detail(response)}")
- payload = response.json()
- if not isinstance(payload, dict):
- raise RuntimeError(f"Unexpected create_workflow payload: {type(payload).__name__}")
- return payload
-
-
-async def _update_workflow_raw(
- workflow_id: str,
- *,
- json_definition: dict[str, Any] | None,
- yaml_definition: str | None,
-) -> dict[str, Any]:
- skyvern = get_skyvern()
- body: dict[str, Any] = {}
- if json_definition is not None:
- body["json_definition"] = json_definition
- if yaml_definition is not None:
- body["yaml_definition"] = yaml_definition
- response = await skyvern._client_wrapper.httpx_client.request(
- f"v1/workflows/{workflow_id}",
- method="POST",
- json=body,
- )
- if response.status_code == 404:
- raise NotFoundError(body={"detail": f"Workflow {workflow_id!r} not found"})
- if response.status_code >= 400:
- raise RuntimeError(f"HTTP {response.status_code}: {_extract_error_detail(response)}")
- payload = response.json()
- if not isinstance(payload, dict):
- raise RuntimeError(f"Unexpected update_workflow payload: {type(payload).__name__}")
- return payload
-
-
-async def _update_workflow_folder_raw(workflow_id: str, *, folder_id: str | None) -> dict[str, Any]:
- skyvern = get_skyvern()
- response = await skyvern._client_wrapper.httpx_client.request(
- f"v1/workflows/{workflow_id}/folder",
- method="PUT",
- json={"folder_id": folder_id},
- )
- if response.status_code == 404:
- raise NotFoundError(body={"detail": f"Workflow {workflow_id!r} not found"})
- if response.status_code == 400:
- raise BadRequestError(body={"detail": _extract_error_detail(response)})
- if response.status_code >= 400:
- raise RuntimeError(f"HTTP {response.status_code}: {_extract_error_detail(response)}")
- payload = response.json()
- if not isinstance(payload, dict):
- raise RuntimeError(f"Unexpected update_workflow_folder payload: {type(payload).__name__}")
- return payload
-
-
def _validate_definition_structure(json_def: dict[str, Any] | None, action: str) -> dict[str, Any] | None:
"""Validate required fields in a JSON workflow definition.
@@ -777,7 +586,7 @@ async def _inject_workflow_update_proxy_default(definition: str, fmt: str, workf
if raw is None or parsed_format is None or "proxy_location" in raw:
return definition
- existing_workflow = await _get_workflow_by_id(workflow_id)
+ existing_workflow = await get_workflow_by_id(workflow_id)
raw["proxy_location"] = existing_workflow.get("proxy_location") or _DEFAULT_MCP_PROXY_LOCATION
return _dump_definition_dict(raw, parsed_format)
@@ -882,7 +691,7 @@ async def _inject_workflow_update_parameters(definition: str, fmt: str, workflow
update_params: list[dict[str, Any]] = wf_def.get("parameters", [])
- existing_workflow = await _get_workflow_by_id(workflow_id)
+ existing_workflow = await get_workflow_by_id(workflow_id)
existing_wf_def = existing_workflow.get("workflow_definition")
if not isinstance(existing_wf_def, dict):
return definition
@@ -1014,7 +823,7 @@ async def skyvern_workflow_list(
search for a workflow by name, or list all workflows for an organization."""
with Timer() as timer:
try:
- workflows = await _list_workflows_raw(
+ workflows = await list_workflows_raw(
search=search,
page=page,
page_size=page_size,
@@ -1054,7 +863,7 @@ async def skyvern_workflow_get(
with Timer() as timer:
try:
- wf_data = await _get_workflow_by_id(workflow_id, version)
+ wf_data = await get_workflow_by_id(workflow_id, version)
timer.mark("sdk")
except NotFoundError:
return make_result(
@@ -1129,7 +938,7 @@ async def skyvern_workflow_create(
with Timer() as timer:
try:
- workflow = await _create_workflow_raw(
+ workflow = await create_workflow_raw(
json_definition=json_def,
yaml_definition=yaml_def,
folder_id=folder_id,
@@ -1213,7 +1022,7 @@ async def skyvern_workflow_update(
with Timer() as timer:
try:
- workflow = await _update_workflow_raw(
+ workflow = await update_workflow_raw(
workflow_id,
json_definition=json_def,
yaml_definition=yaml_def,
@@ -1321,7 +1130,7 @@ async def skyvern_workflow_update_folder(
with Timer() as timer:
try:
- workflow = await _update_workflow_folder_raw(workflow_id, folder_id=folder_id)
+ workflow = await update_workflow_folder_raw(workflow_id, folder_id=folder_id)
timer.mark("sdk")
except NotFoundError:
return make_result(
@@ -1502,7 +1311,7 @@ async def skyvern_workflow_status(
with Timer() as timer:
try:
if run_id.startswith("wr_"):
- run = await _get_workflow_run_status(
+ run = await get_workflow_run_status(
run_id,
include_output_details=verbosity == "full",
)
diff --git a/tests/unit/_mcp_test_helpers.py b/tests/unit/_mcp_test_helpers.py
new file mode 100644
index 000000000..16868d213
--- /dev/null
+++ b/tests/unit/_mcp_test_helpers.py
@@ -0,0 +1,34 @@
+"""Shared helpers for MCP workflow tool tests.
+
+Extracted in SKY-9227 so the four MCP test files that mock ``get_skyvern``
+don't drift in how they patch both ``workflow_tools`` and the
+``_workflow_http`` module introduced by the raw-HTTP centralization.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+import skyvern.cli.mcp_tools.workflow as workflow_tools
+from skyvern.cli.mcp_tools import _workflow_http
+
+
+def patch_skyvern_client(monkeypatch: pytest.MonkeyPatch, fake_client: object) -> None:
+ """Patch ``get_skyvern`` on both ``workflow_tools`` and ``_workflow_http``.
+
+ Each module has its own import-time binding for ``get_skyvern``; tests must
+ redirect both, otherwise the raw-HTTP code path reaches a real client and
+ either errors obscurely (no API key) or makes a stray HTTP call.
+ """
+
+ def _factory() -> object:
+ return fake_client
+
+ monkeypatch.setattr(workflow_tools, "get_skyvern", _factory)
+ monkeypatch.setattr(_workflow_http, "get_skyvern", _factory)
+
+
+def patch_get_workflow_by_id(monkeypatch: pytest.MonkeyPatch, fake_get_workflow_by_id: object) -> None:
+ """Patch workflow lookup in both modules that bind it at import time."""
+ monkeypatch.setattr(workflow_tools, "get_workflow_by_id", fake_get_workflow_by_id)
+ monkeypatch.setattr(_workflow_http, "get_workflow_by_id", fake_get_workflow_by_id)
diff --git a/tests/unit/test_mcp_block_type_parity.py b/tests/unit/test_mcp_block_type_parity.py
index 52ba27a96..7ba6db3d0 100644
--- a/tests/unit/test_mcp_block_type_parity.py
+++ b/tests/unit/test_mcp_block_type_parity.py
@@ -4,18 +4,22 @@ The vendored Fern SDK at ``skyvern/client/`` is regenerated manually. When a
new block type is added to ``skyvern/schemas/workflows.BlockType`` without
regenerating the SDK, MCP read paths that still deserialize through the Fern
``Workflow`` type break (see ``test_mcp_workflow_list_drift``). Even though the
-MCP tools now bypass Fern for Workflow reads, we still want an early warning
-when a regeneration is overdue so downstream clients that *do* use the Fern
-SDK directly stay in sync.
+MCP tools now bypass Fern for Workflow reads (see SKY-9227 and
+the Skyvern Cloud-only ``cloud_docs/fern-sdk/README.md`` runbook), we still
+want an early warning so downstream clients that use the Fern SDK directly stay
+in sync.
This test introspects both Fern discriminated unions and diffs them against
-the backend enum. Known-drifted values are tolerated via an allowlist with a
-Linear tracking pointer to the regeneration task; any NEW drift fails CI.
+the backend enum. Known-drifted values are tolerated via an explicit allowlist
+with per-entry ticket / owner / added_at metadata; any NEW drift fails CI with
+a checklist that points to the regen doc.
"""
from __future__ import annotations
import typing
+from dataclasses import dataclass
+from datetime import date
import pytest
@@ -23,22 +27,95 @@ from skyvern.client.types.workflow_definition_blocks_item import WorkflowDefinit
from skyvern.client.types.workflow_definition_yaml_blocks_item import WorkflowDefinitionYamlBlocksItem
from skyvern.schemas.workflows import BlockType
-# Known drift: block types present in the backend but not yet regenerated into
-# the vendored Fern SDK. Run `fern generate` (or the equivalent Skyvern SDK
-# regen workflow) to resync, then remove the entry here.
-# Tracked follow-up: SKY-9227
-# https://linear.app/skyvern/issue/SKY-9227/prevent-fern-sdk-drift-from-breaking-workflow-block-types
-# Remove this allowlist after the Fern SDK has been regenerated to include
-# these values and downstream `skyvern` PyPI + `@skyvern/client` npm packages
-# are published.
-_KNOWN_DRIFT_ALLOWLIST: frozenset[str] = frozenset(
- {
- "google_sheets_read",
- "google_sheets_write",
- }
+_DOC_POINTER = "Skyvern Cloud-only runbook: cloud_docs/fern-sdk/README.md (not part of OSS sync)"
+
+# The failure message for drift checks IS the new-block-type checklist. That
+# way the guidance only surfaces to devs whose work actually triggers it — no
+# noise on unrelated PRs, impossible to miss on block-type PRs.
+_NEW_BLOCK_TYPE_CHECKLIST = (
+ "A new BlockType addition must satisfy ALL of the following before merge:\n"
+ " 1. Added to `skyvern/schemas/workflows.BlockType` enum.\n"
+ " 2. Added to `skyvern/cli/mcp_tools/blocks.BLOCK_TYPE_MAP` AND `_YAML_CLASS_MAP`.\n"
+ " 3. EITHER regenerate the Fern SDK in a paired PR (link it),\n"
+ " OR add a `BlockDriftEntry` to `_KNOWN_DRIFT_ALLOWLIST` in this file with\n"
+ " populated `ticket`, `owner`, and `added_at` fields.\n"
+ " 4. Tested with MCP `skyvern_workflow_list` / `_create` / `_update` against a\n"
+ " workflow that contains the new block type.\n"
+ " 5. If the block introduces new top-level fields, verify that\n"
+ " `skyvern.cli.mcp_tools.workflow._normalize_json_definition` round-trips\n"
+ " them (unrecognized fields silently drop if the internal schema is stricter\n"
+ " than the API boundary).\n"
+ f"\nSee {_DOC_POINTER} for the full regeneration process, allowlist policy, and"
+ "\nthe decision record on why unknown-block compat lives in MCP, not Fern."
)
+@dataclass(frozen=True)
+class BlockDriftEntry:
+ """An allowlisted backend BlockType that the Fern SDK does not yet know about.
+
+ Every entry must carry a live Linear ticket tracking the regen work and a
+ named owner accountable for clearing the entry at the next Fern regeneration.
+ ``added_at`` is informational only — there is deliberately no time-based
+ staleness failure; entries are cleared at regen time, not by calendar.
+
+ Construction-time ``__post_init__`` enforces non-empty ticket / owner /
+ block_type — a stub-pasted entry fails at module import, not at test time.
+
+ See the Skyvern Cloud-only Fern runbook for the allowlist policy.
+ """
+
+ block_type: str
+ ticket: str
+ owner: str
+ added_at: date
+ notes: str = ""
+
+ def __post_init__(self) -> None:
+ if not self.block_type:
+ raise ValueError("BlockDriftEntry.block_type must be a non-empty backend enum value.")
+ if not self.ticket:
+ raise ValueError(
+ f"BlockDriftEntry({self.block_type!r}).ticket must reference a Linear ticket (e.g. 'SKY-1234'). "
+ f"See {_DOC_POINTER} for the allowlist policy."
+ )
+ if not self.owner:
+ raise ValueError(
+ f"BlockDriftEntry({self.block_type!r}).owner must name an accountable GitHub handle "
+ f"(e.g. '@marc'). See {_DOC_POINTER}."
+ )
+ if not isinstance(self.added_at, date):
+ raise TypeError(
+ f"BlockDriftEntry({self.block_type!r}).added_at must be a datetime.date, "
+ f"got {type(self.added_at).__name__}."
+ )
+
+
+# Allowlist: block types present in the backend but not yet regenerated into
+# the vendored Fern SDK. Run `fern generate` using the Skyvern Cloud-only
+# runbook to resync, then remove the entry here.
+_KNOWN_DRIFT_ALLOWLIST: tuple[BlockDriftEntry, ...] = (
+ BlockDriftEntry(
+ block_type="google_sheets_read",
+ ticket="SKY-9227",
+ owner="@marc",
+ added_at=date(2026, 4, 23),
+ notes="Clears with `google_sheets_write` at the next Fern SDK regeneration.",
+ ),
+ BlockDriftEntry(
+ block_type="google_sheets_write",
+ ticket="SKY-9227",
+ owner="@marc",
+ added_at=date(2026, 4, 23),
+ notes="Clears with `google_sheets_read` at the next Fern SDK regeneration.",
+ ),
+)
+
+
+def _allowlisted_block_types() -> set[str]:
+ return {entry.block_type for entry in _KNOWN_DRIFT_ALLOWLIST}
+
+
def _fern_union_block_types(union_type: typing.Any) -> set[str]:
"""Extract the ``block_type`` Literal value from every variant of a Fern Union."""
values: set[str] = set()
@@ -51,6 +128,17 @@ def _fern_union_block_types(union_type: typing.Any) -> set[str]:
return values
+def _currently_drifted_block_types(
+ backend_values: set[str],
+ fern_blocks: set[str],
+ fern_yaml_blocks: set[str],
+) -> set[str]:
+ missing_in_fern = backend_values - (fern_blocks & fern_yaml_blocks)
+ extra_in_fern = (fern_blocks | fern_yaml_blocks) - backend_values
+ fern_union_mismatch = fern_blocks ^ fern_yaml_blocks
+ return missing_in_fern | extra_in_fern | fern_union_mismatch
+
+
def test_backend_block_types_present_in_fern_unions() -> None:
"""Every BlockType value must be known to both Fern unions (or allowlisted)."""
backend_values = {member.value for member in BlockType}
@@ -59,23 +147,20 @@ def test_backend_block_types_present_in_fern_unions() -> None:
fern_yaml_blocks = _fern_union_block_types(WorkflowDefinitionYamlBlocksItem)
fern_known = fern_blocks & fern_yaml_blocks
- missing_in_fern = backend_values - fern_known - _KNOWN_DRIFT_ALLOWLIST
+ missing_in_fern = backend_values - fern_known - _allowlisted_block_types()
assert not missing_in_fern, (
- "Fern SDK drift detected: the backend `skyvern.schemas.workflows.BlockType` "
- f"has value(s) {sorted(missing_in_fern)!r} that the Fern discriminated unions "
- "(`WorkflowDefinitionBlocksItem` / `WorkflowDefinitionYamlBlocksItem`) do not know. "
- "Run `fern generate` to resync the vendored SDK at skyvern/client/, or add the "
- "value to _KNOWN_DRIFT_ALLOWLIST in this test if the drift is intentional "
- "and tracked."
+ f"Fern SDK drift detected: backend `skyvern.schemas.workflows.BlockType` has "
+ f"value(s) {sorted(missing_in_fern)!r} that the Fern discriminated unions "
+ f"(`WorkflowDefinitionBlocksItem` / `WorkflowDefinitionYamlBlocksItem`) do not know.\n\n"
+ f"{_NEW_BLOCK_TYPE_CHECKLIST}"
)
def test_fern_union_variants_are_subset_of_backend_or_deprecated() -> None:
"""Fern may legitimately retain retired types during a deprecation window.
- This direction is informational: if Fern references a block_type the backend
- no longer emits, we note it but don't fail — clients using a new SDK against
- an older backend is the usual deprecation trajectory.
+ This is intentionally a hard failure unless the drift is allowlisted for
+ one regen cycle; stale entries are then removed by the regen cleanup test.
"""
backend_values = {member.value for member in BlockType}
@@ -83,27 +168,71 @@ def test_fern_union_variants_are_subset_of_backend_or_deprecated() -> None:
fern_yaml_blocks = _fern_union_block_types(WorkflowDefinitionYamlBlocksItem)
extras = (fern_blocks | fern_yaml_blocks) - backend_values
- # Assert parity but allow the allowlist to flex in either direction so a
- # retired block type stays tolerated for one regen cycle.
- unexpected = extras - _KNOWN_DRIFT_ALLOWLIST
+ unexpected = extras - _allowlisted_block_types()
assert not unexpected, (
f"Fern unions reference block_type value(s) {sorted(unexpected)!r} that are "
- "not in the backend BlockType enum. If this is a planned deprecation, add "
- "the value to _KNOWN_DRIFT_ALLOWLIST; otherwise investigate."
+ f"not in the backend BlockType enum. If this is a planned deprecation, add a "
+ f"`BlockDriftEntry` to `_KNOWN_DRIFT_ALLOWLIST` with ticket/owner/added_at; "
+ f"otherwise investigate.\n\n"
+ f"{_NEW_BLOCK_TYPE_CHECKLIST}"
)
def test_allowlist_entries_are_actually_drifted() -> None:
- """Keeps _KNOWN_DRIFT_ALLOWLIST honest: drop stale entries after Fern regen."""
+ """Keeps _KNOWN_DRIFT_ALLOWLIST honest: drop stale entries after Fern regen.
+
+ This is the regen-time cleanliness gate (see the Skyvern Cloud-only Fern
+ runbook post-regeneration steps). Once an entry is no longer drifted because a regen
+ landed, delete it from the allowlist.
+ """
backend_values = {member.value for member in BlockType}
fern_blocks = _fern_union_block_types(WorkflowDefinitionBlocksItem)
fern_yaml_blocks = _fern_union_block_types(WorkflowDefinitionYamlBlocksItem)
- fern_known = fern_blocks & fern_yaml_blocks
- currently_drifted = (backend_values - fern_known) | (fern_blocks ^ fern_yaml_blocks)
- stale_allowlist_entries = _KNOWN_DRIFT_ALLOWLIST - currently_drifted
- assert not stale_allowlist_entries, (
- f"_KNOWN_DRIFT_ALLOWLIST contains stale entries {sorted(stale_allowlist_entries)!r} "
- "that no longer drift. Remove them to keep the allowlist tight."
+ currently_drifted = _currently_drifted_block_types(backend_values, fern_blocks, fern_yaml_blocks)
+ stale = _allowlisted_block_types() - currently_drifted
+ assert not stale, (
+ f"_KNOWN_DRIFT_ALLOWLIST contains stale entries {sorted(stale)!r} that no "
+ f"longer drift. Remove them to keep the allowlist tight. "
+ f"See {_DOC_POINTER} post-regeneration steps."
+ )
+
+
+def test_currently_drifted_block_types_includes_backend_removed_fern_values() -> None:
+ """A retired backend block still present in both Fern unions is real drift."""
+ drifted = _currently_drifted_block_types(
+ backend_values={"navigation"},
+ fern_blocks={"navigation", "retired_block"},
+ fern_yaml_blocks={"navigation", "retired_block"},
)
+
+ assert drifted == {"retired_block"}
+
+
+def test_allowlist_entries_have_required_metadata() -> None:
+ """Belt-and-suspenders: every allowlist entry has non-empty ticket/owner/added_at.
+
+ Primary enforcement is at construction via ``BlockDriftEntry.__post_init__``; this
+ test is a second layer in case a future refactor relaxes the dataclass. See the
+ Skyvern Cloud-only Fern runbook for the allowlist policy.
+ """
+ for entry in _KNOWN_DRIFT_ALLOWLIST:
+ assert entry.block_type, f"allowlist entry missing block_type: {entry!r}"
+ assert entry.ticket, f"{entry.block_type!r}: ticket must reference a Linear ticket"
+ assert entry.owner, f"{entry.block_type!r}: owner must name a GitHub handle"
+ assert isinstance(entry.added_at, date), f"{entry.block_type!r}: added_at must be datetime.date"
+
+
+def test_block_drift_entry_rejects_missing_metadata() -> None:
+ """Construction-time enforcement: empty ticket/owner/block_type must raise."""
+ valid_date = date(2026, 4, 23)
+
+ with pytest.raises(ValueError):
+ BlockDriftEntry(block_type="", ticket="SKY-1234", owner="@someone", added_at=valid_date)
+ with pytest.raises(ValueError):
+ BlockDriftEntry(block_type="foo", ticket="", owner="@someone", added_at=valid_date)
+ with pytest.raises(ValueError):
+ BlockDriftEntry(block_type="foo", ticket="SKY-1234", owner="", added_at=valid_date)
+ with pytest.raises(TypeError):
+ BlockDriftEntry(block_type="foo", ticket="SKY-1234", owner="@someone", added_at="2026-04-23") # type: ignore[arg-type]
diff --git a/tests/unit/test_mcp_folder_tools.py b/tests/unit/test_mcp_folder_tools.py
index 4b45ca45f..06d3a5906 100644
--- a/tests/unit/test_mcp_folder_tools.py
+++ b/tests/unit/test_mcp_folder_tools.py
@@ -9,6 +9,7 @@ import pytest
import skyvern.cli.mcp_tools.folder as folder_tools
import skyvern.cli.mcp_tools.workflow as workflow_tools
from skyvern.client.raw_client import AsyncRawSkyvern, RawSkyvern
+from tests.unit._mcp_test_helpers import patch_skyvern_client as _patch_skyvern_client
def _fake_folder_response() -> SimpleNamespace:
@@ -124,7 +125,7 @@ async def test_workflow_update_folder_calls_sdk(monkeypatch: pytest.MonkeyPatch)
response = SimpleNamespace(status_code=200, json=lambda: payload, text="")
request_mock = AsyncMock(return_value=response)
fake_client = SimpleNamespace(_client_wrapper=SimpleNamespace(httpx_client=SimpleNamespace(request=request_mock)))
- monkeypatch.setattr(workflow_tools, "get_skyvern", lambda: fake_client)
+ _patch_skyvern_client(monkeypatch, fake_client)
result = await workflow_tools.skyvern_workflow_update_folder("wpid_test", "fld_test")
@@ -151,7 +152,7 @@ async def test_workflow_update_folder_surfaces_bad_request(monkeypatch: pytest.M
response = SimpleNamespace(status_code=400, json=lambda: error_payload, text="Folder fld_missing not found")
request_mock = AsyncMock(return_value=response)
fake_client = SimpleNamespace(_client_wrapper=SimpleNamespace(httpx_client=SimpleNamespace(request=request_mock)))
- monkeypatch.setattr(workflow_tools, "get_skyvern", lambda: fake_client)
+ _patch_skyvern_client(monkeypatch, fake_client)
result = await workflow_tools.skyvern_workflow_update_folder("wpid_test", "fld_missing")
diff --git a/tests/unit/test_mcp_script_caching_live.py b/tests/unit/test_mcp_script_caching_live.py
index 8aae3c09a..ce8aa1b5d 100644
--- a/tests/unit/test_mcp_script_caching_live.py
+++ b/tests/unit/test_mcp_script_caching_live.py
@@ -15,9 +15,9 @@ import pytest
from fastmcp import Client
import skyvern.cli.mcp_tools.scripts as script_tools
-import skyvern.cli.mcp_tools.workflow as workflow_tools
from skyvern.cli.mcp_tools import mcp
from skyvern.client.types import ScriptFileCreate
+from tests.unit._mcp_test_helpers import patch_skyvern_client as _patch_skyvern_client
# ---------------------------------------------------------------------------
# Fake API payloads
@@ -361,7 +361,7 @@ async def test_workflow_create_surfaces_caching_fields_via_mcp(monkeypatch):
response = SimpleNamespace(status_code=200, json=lambda: payload, text="")
request_mock = AsyncMock(return_value=response)
fake_client = SimpleNamespace(_client_wrapper=SimpleNamespace(httpx_client=SimpleNamespace(request=request_mock)))
- monkeypatch.setattr(workflow_tools, "get_skyvern", lambda: fake_client)
+ _patch_skyvern_client(monkeypatch, fake_client)
definition = json.dumps(
{
@@ -417,7 +417,7 @@ async def test_workflow_status_shows_script_run_via_mcp(monkeypatch):
httpx_client=SimpleNamespace(request=AsyncMock(return_value=fake_resp)),
),
)
- monkeypatch.setattr(workflow_tools, "get_skyvern", lambda: fake_client)
+ _patch_skyvern_client(monkeypatch, fake_client)
async with Client(mcp) as client:
result = await client.call_tool(
diff --git a/tests/unit/test_mcp_workflow_list_drift.py b/tests/unit/test_mcp_workflow_list_drift.py
index 883ec5e1c..e1d6c7ba3 100644
--- a/tests/unit/test_mcp_workflow_list_drift.py
+++ b/tests/unit/test_mcp_workflow_list_drift.py
@@ -20,8 +20,10 @@ from unittest.mock import AsyncMock, MagicMock
import httpx
import pytest
+from skyvern.cli.mcp_tools import _workflow_http
from skyvern.cli.mcp_tools import workflow as mcp_workflow
from skyvern.client.core.client_wrapper import AsyncClientWrapper
+from tests.unit._mcp_test_helpers import patch_skyvern_client as _patch_skyvern_client
def _make_workflow_dict(workflow_id: str, block_type: str, *, label: str = "step1") -> dict[str, Any]:
@@ -73,7 +75,7 @@ def _patch_skyvern_list_response(
client_wrapper = SimpleNamespace(httpx_client=httpx_client)
fake_skyvern = SimpleNamespace(_client_wrapper=client_wrapper)
- monkeypatch.setattr(mcp_workflow, "get_skyvern", lambda: fake_skyvern)
+ _patch_skyvern_client(monkeypatch, fake_skyvern)
return request_mock
@@ -147,7 +149,7 @@ async def test_raw_list_uses_fern_http_wrapper_auth_headers(monkeypatch: pytest.
httpx_client=base_client,
)
fake_skyvern = SimpleNamespace(_client_wrapper=client_wrapper)
- monkeypatch.setattr(mcp_workflow, "get_skyvern", lambda: fake_skyvern)
+ _patch_skyvern_client(monkeypatch, fake_skyvern)
result = await mcp_workflow.skyvern_workflow_list(only_workflows=True)
@@ -167,9 +169,29 @@ def test_extract_error_detail_truncates_non_json_response_text() -> None:
response.json.side_effect = ValueError("not json")
response.text = "x" * 600
- detail = mcp_workflow._extract_error_detail(response)
+ detail = _workflow_http.extract_error_detail(response)
- assert detail == "x" * 500
+ assert detail == "x" * _workflow_http._ERROR_DETAIL_LIMIT
+
+
+def test_extract_error_detail_truncates_long_json_detail() -> None:
+ """A verbose ``detail`` field (e.g., a backend stack trace) is truncated too."""
+ response = MagicMock()
+ response.json.return_value = {"detail": "x" * 600}
+
+ detail = _workflow_http.extract_error_detail(response)
+
+ assert detail == "x" * _workflow_http._ERROR_DETAIL_LIMIT
+
+
+def test_decode_success_payload_wraps_non_json_response() -> None:
+ """A non-JSON 2xx response should carry operation context, not a bare decoder error."""
+ response = MagicMock()
+ response.json.side_effect = ValueError("not json")
+ response.text = "<html>proxy response</html>"
+
+ with pytest.raises(RuntimeError, match="Unexpected workflows list response"):
+ _workflow_http._decode_success_payload(response, operation="workflows list")
@pytest.mark.asyncio
@@ -182,7 +204,7 @@ async def test_list_surfaces_http_error(monkeypatch: pytest.MonkeyPatch) -> None
request_mock = AsyncMock(return_value=response)
fake_skyvern = SimpleNamespace(_client_wrapper=SimpleNamespace(httpx_client=SimpleNamespace(request=request_mock)))
- monkeypatch.setattr(mcp_workflow, "get_skyvern", lambda: fake_skyvern)
+ _patch_skyvern_client(monkeypatch, fake_skyvern)
result = await mcp_workflow.skyvern_workflow_list()
diff --git a/tests/unit/test_mcp_workflow_route_prefixes.py b/tests/unit/test_mcp_workflow_route_prefixes.py
new file mode 100644
index 000000000..dee6972bb
--- /dev/null
+++ b/tests/unit/test_mcp_workflow_route_prefixes.py
@@ -0,0 +1,132 @@
+"""Guard test for MCP workflow raw-HTTP route prefix choices.
+
+Keeps public vs internal route prefix assignments stable:
+- list / create / update / update_folder → ``v1/workflows`` (public, mirrors the
+ Fern-generated raw client at ``skyvern/client/raw_client.py``).
+- get / run-status → ``api/v1/workflows`` (internal, used only where no public
+ Fern SDK equivalent exists yet).
+
+If you're adding a new MCP workflow raw helper and this test fails, either
+(a) your new helper uses the wrong prefix for its responsibility, or
+(b) this test needs a new assertion entry for the new helper.
+
+See ``cloud_docs/fern-sdk/README.md`` for the rationale behind the split.
+"""
+
+from __future__ import annotations
+
+import ast
+import inspect
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from skyvern.cli.mcp_tools import _workflow_http
+
+
+def capture_request(monkeypatch: pytest.MonkeyPatch) -> MagicMock:
+ """Replace httpx.request with a 200 response.
+
+ The default JSON payload is a dict for dict-returning helpers; list tests
+ override it to ``[]``.
+ """
+ response = MagicMock()
+ response.status_code = 200
+ response.json.return_value = {}
+
+ mock_skyvern = MagicMock()
+ mock_skyvern._client_wrapper = MagicMock()
+ mock_skyvern._client_wrapper.httpx_client = MagicMock()
+ mock_skyvern._client_wrapper.httpx_client.request = AsyncMock(return_value=response)
+
+ monkeypatch.setattr(_workflow_http, "get_skyvern", lambda: mock_skyvern)
+ return mock_skyvern._client_wrapper.httpx_client.request
+
+
+def _route(captured: MagicMock) -> str:
+ """Extract the route string passed as the first positional arg to httpx.request."""
+ assert captured.await_count == 1, "helper must make exactly one HTTP call"
+ return captured.call_args[0][0]
+
+
+async def test_list_workflows_uses_public_route(capture_request: MagicMock) -> None:
+ capture_request.return_value.json.return_value = []
+ await _workflow_http.list_workflows_raw(search=None, page=1, page_size=10, only_workflows=False)
+ assert _route(capture_request) == _workflow_http.PUBLIC_WORKFLOW_ROUTE
+
+
+async def test_create_workflow_uses_public_route(capture_request: MagicMock) -> None:
+ await _workflow_http.create_workflow_raw(
+ json_definition={"title": "x"},
+ yaml_definition=None,
+ folder_id=None,
+ )
+ assert _route(capture_request) == _workflow_http.PUBLIC_WORKFLOW_ROUTE
+
+
+async def test_update_workflow_uses_public_route(capture_request: MagicMock) -> None:
+ await _workflow_http.update_workflow_raw(
+ "wpid_x",
+ json_definition={"title": "x"},
+ yaml_definition=None,
+ )
+ assert _route(capture_request).startswith(_workflow_http.PUBLIC_WORKFLOW_ROUTE + "/")
+
+
+async def test_update_workflow_folder_uses_public_route(capture_request: MagicMock) -> None:
+ await _workflow_http.update_workflow_folder_raw("wpid_x", folder_id=None)
+ assert _route(capture_request).startswith(_workflow_http.PUBLIC_WORKFLOW_ROUTE + "/")
+
+
+async def test_get_workflow_by_id_uses_internal_route(capture_request: MagicMock) -> None:
+ await _workflow_http.get_workflow_by_id("wpid_x")
+ assert _route(capture_request).startswith(_workflow_http.INTERNAL_WORKFLOW_ROUTE + "/")
+
+
+async def test_get_workflow_run_status_uses_internal_route(capture_request: MagicMock) -> None:
+ await _workflow_http.get_workflow_run_status("wr_x", include_output_details=False)
+ assert _route(capture_request).startswith(_workflow_http.INTERNAL_WORKFLOW_ROUTE + "/")
+
+
+def test_prefix_constants_are_stable() -> None:
+ """Lock the string values so a rename doesn't silently invalidate the split."""
+ assert _workflow_http.PUBLIC_WORKFLOW_ROUTE == "v1/workflows"
+ assert _workflow_http.INTERNAL_WORKFLOW_ROUTE == "api/v1/workflows"
+ assert _workflow_http.PUBLIC_WORKFLOW_ROUTE != _workflow_http.INTERNAL_WORKFLOW_ROUTE
+
+
+def test_no_hardcoded_workflow_routes_outside_constants() -> None:
+ """AST guard: every ``v1/...`` or ``api/v1/...`` string literal in _workflow_http.py
+ must be the named constant, not a bypass.
+
+ This catches the case where a future contributor adds a new helper and
+ hardcodes ``"api/v1/workflows/runs/foo"`` instead of using
+ ``INTERNAL_WORKFLOW_ROUTE``. The presence-only tests above only cover the
+ helpers that exist today; this test covers the *shape* of the module.
+ """
+ allowed = {
+ _workflow_http.PUBLIC_WORKFLOW_ROUTE,
+ _workflow_http.INTERNAL_WORKFLOW_ROUTE,
+ }
+ tree = ast.parse(inspect.getsource(_workflow_http))
+ offenders: list[str] = []
+
+ for node in ast.walk(tree):
+ if isinstance(node, ast.Constant) and isinstance(node.value, str):
+ value = node.value
+ if value.startswith(("v1/", "api/v1/")) and value not in allowed:
+ offenders.append(f"line {node.lineno}: {value!r}")
+
+ assert not offenders, (
+ "Hardcoded workflow route literal(s) detected in _workflow_http.py:\n"
+ + "\n".join(f" {o}" for o in offenders)
+ + "\n\nUse PUBLIC_WORKFLOW_ROUTE or INTERNAL_WORKFLOW_ROUTE constants instead. "
+ "See cloud_docs/fern-sdk/README.md."
+ )
diff --git a/tests/unit/test_mcp_workflow_tools.py b/tests/unit/test_mcp_workflow_tools.py
index dcf5cd326..f31e384e2 100644
--- a/tests/unit/test_mcp_workflow_tools.py
+++ b/tests/unit/test_mcp_workflow_tools.py
@@ -10,6 +10,8 @@ from fastmcp import Client
import skyvern.cli.mcp_tools.workflow as workflow_tools
from skyvern.cli.mcp_tools import mcp
+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_response() -> SimpleNamespace:
@@ -73,7 +75,7 @@ def _patch_skyvern_http(
fake_skyvern = SimpleNamespace(
_client_wrapper=SimpleNamespace(httpx_client=SimpleNamespace(request=request_mock)),
)
- monkeypatch.setattr(workflow_tools, "get_skyvern", lambda: fake_skyvern)
+ _patch_skyvern_client(monkeypatch, fake_skyvern)
return request_mock
@@ -190,7 +192,7 @@ async def test_workflow_update_sends_google_sheets_json_definition_as_raw_dict(
},
}
- monkeypatch.setattr(workflow_tools, "_get_workflow_by_id", fake_get_workflow_by_id)
+ _patch_get_workflow_by_id(monkeypatch, fake_get_workflow_by_id)
definition = _google_sheets_definition(block_type)
result = await workflow_tools.skyvern_workflow_update(
@@ -424,7 +426,7 @@ async def test_workflow_update_preserves_existing_proxy_when_omitted(monkeypatch
assert version is None
return {"proxy_location": "RESIDENTIAL_AU"}
- monkeypatch.setattr(workflow_tools, "_get_workflow_by_id", fake_get_workflow_by_id)
+ _patch_get_workflow_by_id(monkeypatch, fake_get_workflow_by_id)
definition = {
"title": "Updated workflow",
@@ -462,7 +464,7 @@ async def test_workflow_update_defaults_proxy_when_existing_is_null(monkeypatch:
assert version is None
return {"proxy_location": None}
- monkeypatch.setattr(workflow_tools, "_get_workflow_by_id", fake_get_workflow_by_id)
+ _patch_get_workflow_by_id(monkeypatch, fake_get_workflow_by_id)
definition = {
"title": "Updated workflow",
@@ -615,7 +617,7 @@ async def test_workflow_status_uses_workflow_run_route_for_wr_ids(monkeypatch: p
get_run=AsyncMock(),
_client_wrapper=SimpleNamespace(httpx_client=SimpleNamespace(request=request)),
)
- monkeypatch.setattr(workflow_tools, "get_skyvern", lambda: fake_client)
+ _patch_skyvern_client(monkeypatch, fake_client)
result = await workflow_tools.skyvern_workflow_status(run_id="wr_heavy")
@@ -645,7 +647,7 @@ async def test_workflow_status_full_preserves_expanded_workflow_details(monkeypa
get_run=AsyncMock(),
_client_wrapper=SimpleNamespace(httpx_client=SimpleNamespace(request=request)),
)
- monkeypatch.setattr(workflow_tools, "get_skyvern", lambda: fake_client)
+ _patch_skyvern_client(monkeypatch, fake_client)
result = await workflow_tools.skyvern_workflow_status(run_id="wr_heavy", verbosity="full")
@@ -682,7 +684,7 @@ async def test_workflow_status_task_runs_still_use_get_run(monkeypatch: pytest.M
queued_at=None,
)
fake_client = SimpleNamespace(get_run=AsyncMock(return_value=task_run))
- monkeypatch.setattr(workflow_tools, "get_skyvern", lambda: fake_client)
+ _patch_skyvern_client(monkeypatch, fake_client)
result = await workflow_tools.skyvern_workflow_status(run_id="tsk_v2_123")
@@ -701,7 +703,7 @@ async def test_workflow_status_summary_via_mcp_client(monkeypatch: pytest.Monkey
get_run=AsyncMock(),
_client_wrapper=SimpleNamespace(httpx_client=SimpleNamespace(request=request)),
)
- monkeypatch.setattr(workflow_tools, "get_skyvern", lambda: fake_client)
+ _patch_skyvern_client(monkeypatch, fake_client)
async with Client(mcp) as client:
result = await client.call_tool("skyvern_workflow_status", {"run_id": "wr_heavy"})
@@ -724,7 +726,7 @@ async def test_workflow_status_full_via_mcp_client(monkeypatch: pytest.MonkeyPat
get_run=AsyncMock(),
_client_wrapper=SimpleNamespace(httpx_client=SimpleNamespace(request=request)),
)
- monkeypatch.setattr(workflow_tools, "get_skyvern", lambda: fake_client)
+ _patch_skyvern_client(monkeypatch, fake_client)
async with Client(mcp) as client:
result = await client.call_tool("skyvern_workflow_status", {"run_id": "wr_heavy", "verbosity": "full"})
@@ -782,7 +784,7 @@ async def test_workflow_update_preserves_credential_parameters_when_omitted(
},
}
- monkeypatch.setattr(workflow_tools, "_get_workflow_by_id", fake_get_workflow_by_id)
+ _patch_get_workflow_by_id(monkeypatch, fake_get_workflow_by_id)
# The update definition includes the workflow parameter but omits the credential parameter
definition = {
@@ -862,7 +864,7 @@ async def test_workflow_update_injects_credential_key_into_block_parameter_keys(
},
}
- monkeypatch.setattr(workflow_tools, "_get_workflow_by_id", fake_get_workflow_by_id)
+ _patch_get_workflow_by_id(monkeypatch, fake_get_workflow_by_id)
# Claude regenerated the login block WITHOUT the credential key in parameter_keys
definition = {
@@ -940,7 +942,7 @@ async def test_workflow_update_injects_credential_key_when_parameter_keys_omitte
},
}
- monkeypatch.setattr(workflow_tools, "_get_workflow_by_id", fake_get_workflow_by_id)
+ _patch_get_workflow_by_id(monkeypatch, fake_get_workflow_by_id)
# Claude regenerated the login block WITHOUT parameter_keys at all
definition = {
@@ -1009,7 +1011,7 @@ async def test_workflow_update_preserves_block_credential_when_param_already_inc
},
}
- monkeypatch.setattr(workflow_tools, "_get_workflow_by_id", fake_get_workflow_by_id)
+ _patch_get_workflow_by_id(monkeypatch, fake_get_workflow_by_id)
# Claude included the credential param but omitted it from the block's parameter_keys
definition = {
@@ -1084,7 +1086,7 @@ async def test_workflow_update_does_not_duplicate_existing_credential_parameter(
},
}
- monkeypatch.setattr(workflow_tools, "_get_workflow_by_id", fake_get_workflow_by_id)
+ _patch_get_workflow_by_id(monkeypatch, fake_get_workflow_by_id)
# The update definition already includes the credential parameter
definition = {
@@ -1155,7 +1157,7 @@ async def test_workflow_update_credential_keys_injected_when_login_block_label_r
},
}
- monkeypatch.setattr(workflow_tools, "_get_workflow_by_id", fake_get_workflow_by_id)
+ _patch_get_workflow_by_id(monkeypatch, fake_get_workflow_by_id)
# Claude renamed the login block from "login_block" to "login"
definition = {
@@ -1227,7 +1229,7 @@ async def test_workflow_update_always_replaces_wrong_credential_id(
},
}
- monkeypatch.setattr(workflow_tools, "_get_workflow_by_id", fake_get_workflow_by_id)
+ _patch_get_workflow_by_id(monkeypatch, fake_get_workflow_by_id)
# Claude includes credential param but with a WRONG credential_id
definition = {
@@ -1304,7 +1306,7 @@ async def test_workflow_update_correct_credential_still_works(
},
}
- monkeypatch.setattr(workflow_tools, "_get_workflow_by_id", fake_get_workflow_by_id)
+ _patch_get_workflow_by_id(monkeypatch, fake_get_workflow_by_id)
# Claude includes credential param correctly AND the block references it
definition = {
@@ -1391,7 +1393,7 @@ async def test_workflow_update_multiple_login_blocks_all_get_credential_keys(
},
}
- monkeypatch.setattr(workflow_tools, "_get_workflow_by_id", fake_get_workflow_by_id)
+ _patch_get_workflow_by_id(monkeypatch, fake_get_workflow_by_id)
# Claude split the workflow into two login blocks with new labels
definition = {
@@ -1480,7 +1482,7 @@ async def test_workflow_update_credential_keys_injected_into_login_block_nested_
},
}
- monkeypatch.setattr(workflow_tools, "_get_workflow_by_id", fake_get_workflow_by_id)
+ _patch_get_workflow_by_id(monkeypatch, fake_get_workflow_by_id)
# Claude renamed the nested login block inside the for_loop
definition = {
@@ -1570,7 +1572,7 @@ async def test_workflow_update_login_block_only_gets_credential_type_keys_not_aw
},
}
- monkeypatch.setattr(workflow_tools, "_get_workflow_by_id", fake_get_workflow_by_id)
+ _patch_get_workflow_by_id(monkeypatch, fake_get_workflow_by_id)
# Claude renamed login block and dropped all parameter info
definition = {
@@ -1662,7 +1664,7 @@ async def test_workflow_update_strips_runtime_fields_from_credential_params(
},
}
- monkeypatch.setattr(workflow_tools, "_get_workflow_by_id", fake_get_workflow_by_id)
+ _patch_get_workflow_by_id(monkeypatch, fake_get_workflow_by_id)
definition = {
"title": "Updated workflow",
@@ -1748,7 +1750,7 @@ async def test_workflow_update_preserves_workflow_credential_id_params_and_injec
},
}
- monkeypatch.setattr(workflow_tools, "_get_workflow_by_id", fake_get_workflow_by_id)
+ _patch_get_workflow_by_id(monkeypatch, fake_get_workflow_by_id)
definition = {
"title": "Updated workflow",
@@ -1840,7 +1842,7 @@ async def test_workflow_update_always_replaces_wrong_workflow_credential_id_defa
},
}
- monkeypatch.setattr(workflow_tools, "_get_workflow_by_id", fake_get_workflow_by_id)
+ _patch_get_workflow_by_id(monkeypatch, fake_get_workflow_by_id)
definition = {
"title": "Updated workflow",
@@ -1915,7 +1917,7 @@ async def test_workflow_update_injects_onepassword_key_into_login_block_paramete
},
}
- monkeypatch.setattr(workflow_tools, "_get_workflow_by_id", fake_get_workflow_by_id)
+ _patch_get_workflow_by_id(monkeypatch, fake_get_workflow_by_id)
definition = {
"title": "Updated workflow",
@@ -1995,7 +1997,7 @@ async def test_workflow_update_injects_bitwarden_login_key_into_login_block_para
},
}
- monkeypatch.setattr(workflow_tools, "_get_workflow_by_id", fake_get_workflow_by_id)
+ _patch_get_workflow_by_id(monkeypatch, fake_get_workflow_by_id)
definition = {
"title": "Updated workflow",
@@ -2072,7 +2074,7 @@ async def test_workflow_update_injects_azure_vault_key_into_login_block_paramete
},
}
- monkeypatch.setattr(workflow_tools, "_get_workflow_by_id", fake_get_workflow_by_id)
+ _patch_get_workflow_by_id(monkeypatch, fake_get_workflow_by_id)
definition = {
"title": "Updated workflow",