Skip to content

Automate browser based workflows with AI

feat(SKY-12217): heal-episodes read API + query index + dedupe semantics (#7414)

pedrohsdb4e87f3f03e82
diff --git a/alembic/versions/2026_07_14_1836-2b8e37d98d97_add_heal_episode_workflow_block_label_index.py b/alembic/versions/2026_07_14_1836-2b8e37d98d97_add_heal_episode_workflow_block_label_index.py
new file mode 100644
index 000000000..e65b1a4fc
--- /dev/null
+++ b/alembic/versions/2026_07_14_1836-2b8e37d98d97_add_heal_episode_workflow_block_label_index.py
@@ -0,0 +1,42 @@
+"""add heal episode workflow block label index
+
+Revision ID: 2b8e37d98d97
+Revises: a0d23605c574
+Create Date: 2026-07-14T18:36:13.734497+00:00
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "2b8e37d98d97"
+down_revision: Union[str, None] = "a0d23605c574"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+ with op.get_context().autocommit_block():
+ op.execute("SET statement_timeout = '24h';")
+ op.execute("""
+ CREATE INDEX CONCURRENTLY IF NOT EXISTS he_org_wpid_block_label_index
+ ON heal_episodes (organization_id, workflow_permanent_id, block_label, created_at)
+ """)
+ op.execute("DROP INDEX CONCURRENTLY IF EXISTS he_org_wrid_index")
+ op.execute("""
+ CREATE INDEX CONCURRENTLY IF NOT EXISTS he_org_wrid_created_at_index
+ ON heal_episodes (organization_id, workflow_run_id, created_at)
+ """)
+ op.execute("RESET statement_timeout;")
+
+
+def downgrade() -> None:
+ with op.get_context().autocommit_block():
+ op.execute("DROP INDEX CONCURRENTLY IF EXISTS he_org_wrid_created_at_index")
+ op.execute("""
+ CREATE INDEX CONCURRENTLY IF NOT EXISTS he_org_wrid_index
+ ON heal_episodes (organization_id, workflow_run_id)
+ """)
+ op.execute("DROP INDEX CONCURRENTLY IF EXISTS he_org_wpid_block_label_index")
diff --git a/skyvern/forge/sdk/copilot/heal_content_sanitization.py b/skyvern/forge/sdk/copilot/heal_content_sanitization.py
index d36200379..b90701c15 100644
--- a/skyvern/forge/sdk/copilot/heal_content_sanitization.py
+++ b/skyvern/forge/sdk/copilot/heal_content_sanitization.py
@@ -72,7 +72,9 @@ def _sanitize_string_leaves(node: Any) -> Any:
def build_heal_episode_detail(episode: HealEpisode) -> HealEpisodeDetail:
return HealEpisodeDetail(
- **episode.model_dump(exclude={"block_code", "block_prompt", "failure_message", "block_steps"}),
+ **episode.model_dump(
+ exclude={"organization_id", "block_code", "block_prompt", "failure_message", "block_steps"}
+ ),
sanitized_block_code=sanitize_heal_content(episode.block_code),
sanitized_block_prompt=sanitize_heal_content(episode.block_prompt),
sanitized_failure_message=sanitize_heal_content(episode.failure_message),
diff --git a/skyvern/forge/sdk/db/models.py b/skyvern/forge/sdk/db/models.py
index 0854a8753..e6bb93103 100644
--- a/skyvern/forge/sdk/db/models.py
+++ b/skyvern/forge/sdk/db/models.py
@@ -1756,8 +1756,9 @@ class HealEpisodeModel(Base):
__tablename__ = "heal_episodes"
__table_args__ = (
Index("he_org_wpid_index", "organization_id", "workflow_permanent_id", "created_at"),
+ Index("he_org_wpid_block_label_index", "organization_id", "workflow_permanent_id", "block_label", "created_at"),
Index("he_org_created_at_index", "organization_id", "created_at"),
- Index("he_org_wrid_index", "organization_id", "workflow_run_id"),
+ Index("he_org_wrid_created_at_index", "organization_id", "workflow_run_id", "created_at"),
)
heal_episode_id = Column(String, primary_key=True, default=generate_heal_episode_id)
diff --git a/skyvern/forge/sdk/db/repositories/self_heal.py b/skyvern/forge/sdk/db/repositories/self_heal.py
index 6f9a5e056..aefe1ffed 100644
--- a/skyvern/forge/sdk/db/repositories/self_heal.py
+++ b/skyvern/forge/sdk/db/repositories/self_heal.py
@@ -100,6 +100,49 @@ class SelfHealRepository(BaseRepository):
episodes = (await session.scalars(query.order_by(order).limit(limit))).all()
return [HealEpisode.model_validate(episode) for episode in episodes]
+ @db_operation("get_heal_episodes_for_workflow")
+ async def get_heal_episodes_for_workflow(
+ self,
+ organization_id: str,
+ workflow_permanent_id: str,
+ block_label: str | None = None,
+ status: str | None = None,
+ limit: int = 50,
+ offset: int = 0,
+ ) -> list[HealEpisode]:
+ async with self.Session() as session:
+ query = select(HealEpisodeModel).where(
+ HealEpisodeModel.organization_id == organization_id,
+ HealEpisodeModel.workflow_permanent_id == workflow_permanent_id,
+ )
+ if block_label is not None:
+ query = query.where(HealEpisodeModel.block_label == block_label)
+ if status is not None:
+ query = query.where(HealEpisodeModel.status == status)
+
+ episodes = (
+ await session.scalars(
+ query.order_by(HealEpisodeModel.created_at.desc(), HealEpisodeModel.heal_episode_id.desc())
+ .limit(max(1, min(limit, 200)))
+ .offset(max(offset, 0))
+ )
+ ).all()
+ return [HealEpisode.model_validate(episode) for episode in episodes]
+
+ @db_operation("get_heal_episodes_for_run")
+ async def get_heal_episodes_for_run(self, organization_id: str, workflow_run_id: str) -> list[HealEpisode]:
+ async with self.Session() as session:
+ query = select(HealEpisodeModel).where(
+ HealEpisodeModel.organization_id == organization_id,
+ HealEpisodeModel.workflow_run_id == workflow_run_id,
+ )
+ episodes = (
+ await session.scalars(
+ query.order_by(HealEpisodeModel.created_at.asc(), HealEpisodeModel.heal_episode_id.asc())
+ )
+ ).all()
+ return [HealEpisode.model_validate(episode) for episode in episodes]
+
@db_operation("create_heal_proposal")
async def create_heal_proposal(
self,
diff --git a/skyvern/forge/sdk/routes/__init__.py b/skyvern/forge/sdk/routes/__init__.py
index 90143348a..d8c4f8495 100644
--- a/skyvern/forge/sdk/routes/__init__.py
+++ b/skyvern/forge/sdk/routes/__init__.py
@@ -11,6 +11,7 @@ from skyvern.forge.sdk.routes import run_blocks # noqa: F401
from skyvern.forge.sdk.routes import runtime_config # noqa: F401
from skyvern.forge.sdk.routes import scripts # noqa: F401
from skyvern.forge.sdk.routes import sdk # noqa: F401
+from skyvern.forge.sdk.routes import self_heal # noqa: F401
from skyvern.forge.sdk.routes import webhooks # noqa: F401
from skyvern.forge.sdk.routes import workflow_schedules # noqa: F401
from skyvern.forge.sdk.routes.streaming import cdp_input # noqa: F401
diff --git a/skyvern/forge/sdk/routes/self_heal.py b/skyvern/forge/sdk/routes/self_heal.py
new file mode 100644
index 000000000..ec52e23ac
--- /dev/null
+++ b/skyvern/forge/sdk/routes/self_heal.py
@@ -0,0 +1,59 @@
+import structlog
+from fastapi import Depends, Query
+from pydantic import BaseModel
+
+from skyvern.forge import app
+from skyvern.forge.sdk.routes.routers import base_router
+from skyvern.forge.sdk.schemas.organizations import Organization
+from skyvern.forge.sdk.services import org_auth_service
+from skyvern.schemas.self_heal import HealEpisodeView, HealStatus, RunHealSummary, summarize_run_heals
+
+LOG = structlog.get_logger()
+
+
+class RunHealEpisodesResponse(BaseModel):
+ episodes: list[HealEpisodeView]
+ summary: RunHealSummary
+
+
+@base_router.get(
+ "/workflows/{workflow_permanent_id}/heal_episodes",
+ response_model=list[HealEpisodeView],
+ include_in_schema=False,
+)
+async def get_workflow_heal_episodes(
+ workflow_permanent_id: str,
+ block_label: str | None = None,
+ status: HealStatus | None = None,
+ limit: int = Query(default=50, ge=1, le=200),
+ offset: int = Query(default=0, ge=0),
+ organization: Organization = Depends(org_auth_service.get_current_org),
+) -> list[HealEpisodeView]:
+ episodes = await app.DATABASE.self_heal.get_heal_episodes_for_workflow(
+ organization_id=organization.organization_id,
+ workflow_permanent_id=workflow_permanent_id,
+ block_label=block_label,
+ status=status,
+ limit=limit,
+ offset=offset,
+ )
+ return [HealEpisodeView.from_episode(episode) for episode in episodes]
+
+
+@base_router.get(
+ "/runs/{workflow_run_id}/heal_episodes",
+ response_model=RunHealEpisodesResponse,
+ include_in_schema=False,
+)
+async def get_run_heal_episodes(
+ workflow_run_id: str,
+ organization: Organization = Depends(org_auth_service.get_current_org),
+) -> RunHealEpisodesResponse:
+ episodes = await app.DATABASE.self_heal.get_heal_episodes_for_run(
+ organization_id=organization.organization_id,
+ workflow_run_id=workflow_run_id,
+ )
+ return RunHealEpisodesResponse(
+ episodes=[HealEpisodeView.from_episode(episode) for episode in episodes],
+ summary=summarize_run_heals(episodes),
+ )
diff --git a/skyvern/schemas/self_heal.py b/skyvern/schemas/self_heal.py
index f611bcd9b..e5b22c216 100644
--- a/skyvern/schemas/self_heal.py
+++ b/skyvern/schemas/self_heal.py
@@ -74,10 +74,7 @@ class HealEpisode(BaseModel):
class HealEpisodeView(BaseModel):
- model_config = ConfigDict(from_attributes=True)
-
heal_episode_id: str
- organization_id: str
workflow_permanent_id: str
workflow_id: str
workflow_run_id: str
@@ -86,7 +83,6 @@ class HealEpisodeView(BaseModel):
engine: str
status: HealStatus
skip_reason: HealSkipReason | None = None
- block_steps: list | dict | None = None
snapshot_available: bool = False
convergence_eligible: bool = False
parameter_binding_keys: list[str] | dict | None = None
@@ -103,11 +99,89 @@ class HealEpisodeView(BaseModel):
created_at: datetime
modified_at: datetime
+ @classmethod
+ def from_episode(cls, episode: HealEpisode) -> HealEpisodeView:
+ return cls(
+ heal_episode_id=episode.heal_episode_id,
+ workflow_permanent_id=episode.workflow_permanent_id,
+ workflow_id=episode.workflow_id,
+ workflow_run_id=episode.workflow_run_id,
+ workflow_run_block_id=episode.workflow_run_block_id,
+ block_label=episode.block_label,
+ engine=episode.engine,
+ status=episode.status,
+ skip_reason=episode.skip_reason,
+ snapshot_available=episode.snapshot_available,
+ convergence_eligible=episode.convergence_eligible,
+ parameter_binding_keys=episode.parameter_binding_keys,
+ exception_class=episode.exception_class,
+ failing_line=episode.failing_line,
+ matched_step_index=episode.matched_step_index,
+ escalation_task_id=episode.escalation_task_id,
+ wall_clock_ms=episode.wall_clock_ms,
+ action_count=episode.action_count,
+ output_obligation=episode.output_obligation,
+ dom_snapshot_artifact_id=episode.dom_snapshot_artifact_id,
+ scout_transcript_artifact_id=episode.scout_transcript_artifact_id,
+ screenshot_artifact_id=episode.screenshot_artifact_id,
+ created_at=episode.created_at,
+ modified_at=episode.modified_at,
+ )
+
class HealEpisodeDetail(HealEpisodeView):
sanitized_block_code: str | None = None
sanitized_block_prompt: str | None = None
sanitized_failure_message: str | None = None
+ block_steps: list | dict | None = None
+
+
+def resolve_block_outcome(
+ episodes: list[HealEpisode],
+) -> Literal["healed", "unverified", "failed", "skipped", "none"]:
+ statuses = {episode.status for episode in episodes}
+ if HealStatus.fired_completed in statuses:
+ return "healed"
+ if HealStatus.fired_unverified in statuses:
+ return "unverified"
+ if HealStatus.fired_failed in statuses:
+ return "failed"
+ if HealStatus.skipped in statuses:
+ return "skipped"
+ return "none"
+
+
+class RunHealSummary(BaseModel):
+ blocks_healed: int
+ blocks_outcome_risk: list[str]
+ blocks_with_heal_attempt: int
+
+
+def summarize_run_heals(episodes: list[HealEpisode]) -> RunHealSummary:
+ episodes_by_block: dict[str, list[HealEpisode]] = {}
+ for episode in episodes:
+ episodes_by_block.setdefault(episode.block_label, []).append(episode)
+
+ blocks_healed = 0
+ blocks_outcome_risk: list[str] = []
+ for block_label, block_episodes in episodes_by_block.items():
+ outcome = resolve_block_outcome(block_episodes)
+ if outcome == "healed":
+ blocks_healed += 1
+ continue
+ if outcome not in {"unverified", "failed"}:
+ continue
+ if any(
+ episode.output_obligation in {OutputObligation.observed, OutputObligation.vestigial}
+ for episode in block_episodes
+ ):
+ blocks_outcome_risk.append(block_label)
+
+ return RunHealSummary(
+ blocks_healed=blocks_healed,
+ blocks_outcome_risk=sorted(blocks_outcome_risk),
+ blocks_with_heal_attempt=len(episodes_by_block),
+ )
class WorkflowHealProposal(BaseModel):
diff --git a/tests/unit/forge/sdk/db/test_self_heal_repository.py b/tests/unit/forge/sdk/db/test_self_heal_repository.py
index 4462e75fd..ed8b12468 100644
--- a/tests/unit/forge/sdk/db/test_self_heal_repository.py
+++ b/tests/unit/forge/sdk/db/test_self_heal_repository.py
@@ -6,6 +6,8 @@ a Postgres error in production (see scripts.py/tasks.py's use of the same
sanitize_postgres_text helper) rather than being caught here.
"""
+from datetime import datetime, timedelta
+
import pytest
import pytest_asyncio
from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
@@ -14,6 +16,36 @@ from skyvern.forge.sdk.db.models import Base, HealEpisodeModel, WorkflowHealProp
from skyvern.forge.sdk.db.repositories.self_heal import SelfHealRepository
ORG_A = "o_aaaaaaaaaaaaaaa"
+ORG_B = "o_bbbbbbbbbbbbbbb"
+
+
+def _heal_episode_model(
+ *,
+ heal_episode_id: str | None = None,
+ organization_id: str = ORG_A,
+ workflow_permanent_id: str = "wpid_1",
+ workflow_id: str = "w_1",
+ workflow_run_id: str = "wr_1",
+ workflow_run_block_id: str = "wrb_1",
+ block_label: str = "block_1",
+ status: str = "fired_failed",
+ created_at: datetime,
+) -> HealEpisodeModel:
+ model_kwargs: dict[str, str | datetime] = {
+ "organization_id": organization_id,
+ "workflow_permanent_id": workflow_permanent_id,
+ "workflow_id": workflow_id,
+ "workflow_run_id": workflow_run_id,
+ "workflow_run_block_id": workflow_run_block_id,
+ "block_label": block_label,
+ "engine": "code",
+ "status": status,
+ "created_at": created_at,
+ "modified_at": created_at,
+ }
+ if heal_episode_id is not None:
+ model_kwargs["heal_episode_id"] = heal_episode_id
+ return HealEpisodeModel(**model_kwargs)
@pytest_asyncio.fixture
@@ -103,3 +135,188 @@ async def test_update_heal_proposal_status_compare_and_set(repo_and_session) ->
)
assert adopted is not None
assert adopted.status == "adopted"
+
+
+async def test_get_heal_episodes_for_workflow_filters_and_paginates(repo_and_session) -> None:
+ repo, session_factory = repo_and_session
+ now = datetime(2026, 1, 1, 0, 0, 0)
+ async with session_factory() as session:
+ session.add_all(
+ [
+ _heal_episode_model(
+ workflow_run_id="wr_target",
+ workflow_run_block_id="wrb_a",
+ block_label="block_x",
+ status="fired_failed",
+ created_at=now,
+ ),
+ _heal_episode_model(
+ workflow_run_id="wr_target",
+ workflow_run_block_id="wrb_b",
+ block_label="block_x",
+ status="fired_completed",
+ created_at=now + timedelta(minutes=1),
+ ),
+ _heal_episode_model(
+ workflow_run_id="wr_target",
+ workflow_run_block_id="wrb_c",
+ block_label="block_y",
+ status="fired_failed",
+ created_at=now + timedelta(minutes=2),
+ ),
+ _heal_episode_model(
+ workflow_permanent_id="wpid_other",
+ workflow_run_id="wr_target",
+ workflow_run_block_id="wrb_d",
+ block_label="block_x",
+ status="fired_failed",
+ created_at=now + timedelta(minutes=3),
+ ),
+ _heal_episode_model(
+ organization_id=ORG_B,
+ workflow_run_id="wr_target",
+ workflow_run_block_id="wrb_e",
+ block_label="block_x",
+ status="fired_failed",
+ created_at=now + timedelta(minutes=4),
+ ),
+ ]
+ )
+ await session.commit()
+
+ all_for_workflow = await repo.get_heal_episodes_for_workflow(
+ organization_id=ORG_A,
+ workflow_permanent_id="wpid_1",
+ )
+ assert [episode.workflow_run_block_id for episode in all_for_workflow] == ["wrb_c", "wrb_b", "wrb_a"]
+
+ block_filtered = await repo.get_heal_episodes_for_workflow(
+ organization_id=ORG_A,
+ workflow_permanent_id="wpid_1",
+ block_label="block_x",
+ )
+ assert [episode.workflow_run_block_id for episode in block_filtered] == ["wrb_b", "wrb_a"]
+
+ status_filtered = await repo.get_heal_episodes_for_workflow(
+ organization_id=ORG_A,
+ workflow_permanent_id="wpid_1",
+ status="fired_failed",
+ )
+ assert [episode.workflow_run_block_id for episode in status_filtered] == ["wrb_c", "wrb_a"]
+
+ paginated = await repo.get_heal_episodes_for_workflow(
+ organization_id=ORG_A,
+ workflow_permanent_id="wpid_1",
+ limit=2,
+ offset=1,
+ )
+ assert [episode.workflow_run_block_id for episode in paginated] == ["wrb_b", "wrb_a"]
+
+ clamped = await repo.get_heal_episodes_for_workflow(
+ organization_id=ORG_A,
+ workflow_permanent_id="wpid_1",
+ limit=-5,
+ )
+ assert [episode.workflow_run_block_id for episode in clamped] == ["wrb_c"]
+
+
+async def test_get_heal_episodes_for_run_returns_created_at_ascending(repo_and_session) -> None:
+ repo, session_factory = repo_and_session
+ now = datetime(2026, 2, 1, 0, 0, 0)
+ async with session_factory() as session:
+ session.add_all(
+ [
+ _heal_episode_model(
+ workflow_run_id="wr_ordered",
+ workflow_run_block_id="wrb_late",
+ created_at=now + timedelta(minutes=2),
+ ),
+ _heal_episode_model(
+ workflow_run_id="wr_ordered",
+ workflow_run_block_id="wrb_early",
+ created_at=now,
+ ),
+ _heal_episode_model(
+ workflow_run_id="wr_ordered",
+ workflow_run_block_id="wrb_middle",
+ created_at=now + timedelta(minutes=1),
+ ),
+ _heal_episode_model(
+ workflow_run_id="wr_other",
+ workflow_run_block_id="wrb_other",
+ created_at=now + timedelta(minutes=3),
+ ),
+ ]
+ )
+ await session.commit()
+
+ episodes = await repo.get_heal_episodes_for_run(organization_id=ORG_A, workflow_run_id="wr_ordered")
+ assert [episode.workflow_run_block_id for episode in episodes] == ["wrb_early", "wrb_middle", "wrb_late"]
+
+
+async def test_get_heal_episodes_for_workflow_uses_heal_episode_id_tiebreaker(repo_and_session) -> None:
+ repo, session_factory = repo_and_session
+ now = datetime(2026, 3, 1, 0, 0, 0)
+ async with session_factory() as session:
+ session.add_all(
+ [
+ _heal_episode_model(
+ heal_episode_id="he_001",
+ workflow_run_block_id="wrb_1",
+ created_at=now,
+ ),
+ _heal_episode_model(
+ heal_episode_id="he_003",
+ workflow_run_block_id="wrb_3",
+ created_at=now,
+ ),
+ _heal_episode_model(
+ heal_episode_id="he_002",
+ workflow_run_block_id="wrb_2",
+ created_at=now,
+ ),
+ ]
+ )
+ await session.commit()
+
+ episodes = await repo.get_heal_episodes_for_workflow(
+ organization_id=ORG_A,
+ workflow_permanent_id="wpid_1",
+ )
+ assert [episode.heal_episode_id for episode in episodes] == ["he_003", "he_002", "he_001"]
+
+
+async def test_get_heal_episodes_for_run_uses_heal_episode_id_tiebreaker(repo_and_session) -> None:
+ repo, session_factory = repo_and_session
+ now = datetime(2026, 4, 1, 0, 0, 0)
+ async with session_factory() as session:
+ session.add_all(
+ [
+ _heal_episode_model(
+ heal_episode_id="he_003",
+ workflow_run_id="wr_tie",
+ workflow_run_block_id="wrb_3",
+ created_at=now,
+ ),
+ _heal_episode_model(
+ heal_episode_id="he_001",
+ workflow_run_id="wr_tie",
+ workflow_run_block_id="wrb_1",
+ created_at=now,
+ ),
+ _heal_episode_model(
+ heal_episode_id="he_002",
+ workflow_run_id="wr_tie",
+ workflow_run_block_id="wrb_2",
+ created_at=now,
+ ),
+ ]
+ )
+ await session.commit()
+
+ episodes = await repo.get_heal_episodes_for_run(organization_id=ORG_A, workflow_run_id="wr_tie")
+ assert [episode.heal_episode_id for episode in episodes] == ["he_001", "he_002", "he_003"]
diff --git a/tests/unit/forge/sdk/db/test_self_heal_schema.py b/tests/unit/forge/sdk/db/test_self_heal_schema.py
index a10ee737c..f8554ae22 100644
--- a/tests/unit/forge/sdk/db/test_self_heal_schema.py
+++ b/tests/unit/forge/sdk/db/test_self_heal_schema.py
@@ -1,13 +1,23 @@
from __future__ import annotations
-import ast
+from datetime import datetime
from pathlib import Path
import pytest
+from alembic.config import Config
+from alembic.script import ScriptDirectory
from skyvern.forge.sdk.db.id import generate_heal_episode_id, generate_heal_proposal_id
from skyvern.forge.sdk.db.models import HealEpisodeModel, WorkflowHealProposalModel
-from skyvern.schemas.self_heal import HealEpisodeDetail
+from skyvern.schemas.self_heal import (
+ HealEpisode,
+ HealEpisodeDetail,
+ HealEpisodeView,
+ HealStatus,
+ OutputObligation,
+ resolve_block_outcome,
+ summarize_run_heals,
+)
def test_heal_episode_and_heal_proposal_id_prefixes() -> None:
@@ -27,26 +37,95 @@ def test_heal_episode_and_heal_proposal_model_shapes() -> None:
def test_heal_migration_chains_from_current_head() -> None:
- # alembic/ does not sync to the OSS repo; skip there instead of failing on the missing file.
- migration_path = (
- Path(__file__).resolve().parents[5]
- / "alembic"
- / "versions"
- / "2026_07_08_0935-a1c4d9e7b2f1_add_heal_episodes_and_proposals.py"
- )
- if not migration_path.exists():
+ repo_root = Path(__file__).resolve().parents[5]
+ alembic_ini_path = repo_root / "alembic.ini"
+ script_location = repo_root / "alembic"
+ if not alembic_ini_path.exists() or not script_location.exists():
pytest.skip("alembic migrations are not part of this checkout")
- module = ast.parse(migration_path.read_text())
- down_revisions = [
- node.value.value
- for node in module.body
- if isinstance(node, ast.AnnAssign)
- and isinstance(node.target, ast.Name)
- and node.target.id == "down_revision"
- and isinstance(node.value, ast.Constant)
- ]
-
- assert down_revisions == ["5a7c9d1e2f34"]
+
+ config = Config(str(alembic_ini_path))
+ config.set_main_option("script_location", str(script_location))
+ script = ScriptDirectory.from_config(config)
+
+ heads = script.get_heads()
+ assert heads == ["2b8e37d98d97"]
+
+ revision = script.get_revision("2b8e37d98d97")
+ assert revision is not None
+ # down_revision is re-pointed to main's head on every rebase (migration-rebase policy);
+ # assert the parent resolves to a real revision instead of pinning a specific hash.
+ assert revision.down_revision is not None
+ assert script.get_revision(revision.down_revision) is not None
+
+
+def _episode(
+ *,
+ block_label: str,
+ status: HealStatus,
+ output_obligation: OutputObligation | None = None,
+ workflow_run_block_id: str = "wrb_1",
+) -> HealEpisode:
+ now = datetime(2026, 1, 1, 0, 0, 0)
+ return HealEpisode(
+ heal_episode_id=f"he_{block_label}_{workflow_run_block_id}",
+ organization_id="o_1",
+ workflow_permanent_id="wpid_1",
+ workflow_id="w_1",
+ workflow_run_id="wr_1",
+ workflow_run_block_id=workflow_run_block_id,
+ block_label=block_label,
+ engine="code",
+ status=status,
+ output_obligation=output_obligation,
+ created_at=now,
+ modified_at=now,
+ )
+
+
+ ("episodes", "expected"),
+ [
+ ([HealStatus.fired_completed, HealStatus.fired_failed], "healed"),
+ ([HealStatus.fired_unverified, HealStatus.skipped], "unverified"),
+ ([HealStatus.fired_failed, HealStatus.skipped], "failed"),
+ ([HealStatus.skipped], "skipped"),
+ ([], "none"),
+ ],
+)
+def test_resolve_block_outcome_precedence(episodes: list[HealStatus], expected: str) -> None:
+ assert resolve_block_outcome([_episode(block_label="block", status=status) for status in episodes]) == expected
+
+
+def test_summarize_run_heals_counts_and_risk_with_obligation() -> None:
+ summary = summarize_run_heals(
+ [
+ _episode(block_label="block_healed", status=HealStatus.fired_completed),
+ _episode(
+ block_label="block_unverified_risk",
+ status=HealStatus.fired_unverified,
+ output_obligation=OutputObligation.observed,
+ ),
+ _episode(
+ block_label="block_failed_no_obligation",
+ status=HealStatus.fired_failed,
+ output_obligation=OutputObligation.none,
+ ),
+ _episode(
+ block_label="block_failed_risk",
+ status=HealStatus.fired_failed,
+ output_obligation=OutputObligation.vestigial,
+ ),
+ ]
+ )
+
+ assert summary.blocks_healed == 1
+ assert summary.blocks_with_heal_attempt == 4
+ assert summary.blocks_outcome_risk == ["block_failed_risk", "block_unverified_risk"]
+
+
+def test_heal_episode_view_excludes_secret_fields() -> None:
+ forbidden = {"block_prompt", "block_code", "failure_message"}
+ assert forbidden.isdisjoint(HealEpisodeView.model_fields.keys())
def test_heal_episode_detail_exposes_only_sanitized_free_text_fields() -> None:
diff --git a/tests/unit/forge/sdk/routes/test_self_heal_routes.py b/tests/unit/forge/sdk/routes/test_self_heal_routes.py
new file mode 100644
index 000000000..c2cd9fde2
--- /dev/null
+++ b/tests/unit/forge/sdk/routes/test_self_heal_routes.py
@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+from datetime import datetime
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+import skyvern.forge.sdk.routes.self_heal # noqa: F401
+from skyvern.forge import app as forge_app
+from skyvern.forge.sdk.routes import routers as routers_module
+from skyvern.forge.sdk.services import org_auth_service
+from skyvern.schemas.self_heal import HealEpisode, HealEpisodeView, HealStatus, OutputObligation
+
+ORG_ID = "org_self_heal"
+
+
+def _episode(
+ *,
+ heal_episode_id: str,
+ workflow_run_block_id: str,
+ block_label: str,
+ status: HealStatus,
+ workflow_permanent_id: str = "wpid_1",
+ workflow_run_id: str = "wr_1",
+ output_obligation: OutputObligation | None = None,
+) -> HealEpisode:
+ now = datetime(2026, 1, 1, 0, 0, 0)
+ return HealEpisode(
+ heal_episode_id=heal_episode_id,
+ organization_id=ORG_ID,
+ workflow_permanent_id=workflow_permanent_id,
+ workflow_id="w_1",
+ workflow_run_id=workflow_run_id,
+ workflow_run_block_id=workflow_run_block_id,
+ block_label=block_label,
+ engine="code",
+ status=status,
+ output_obligation=output_obligation,
+ created_at=now,
+ modified_at=now,
+ )
+
+
+def _build_client(monkeypatch) -> tuple[TestClient, AsyncMock, AsyncMock]:
+ async def _fake_org() -> SimpleNamespace:
+ return SimpleNamespace(organization_id=ORG_ID)
+
+ get_for_workflow = AsyncMock()
+ get_for_run = AsyncMock()
+ monkeypatch.setattr(forge_app.DATABASE.self_heal, "get_heal_episodes_for_workflow", get_for_workflow)
+ monkeypatch.setattr(forge_app.DATABASE.self_heal, "get_heal_episodes_for_run", get_for_run)
+
+ fastapi_app = FastAPI()
+ fastapi_app.dependency_overrides[org_auth_service.get_current_org] = _fake_org
+ fastapi_app.include_router(routers_module.base_router, prefix="/v1")
+ return TestClient(fastapi_app), get_for_workflow, get_for_run
+
+
+def test_get_workflow_heal_episodes_filters_to_caller_org_and_view_shape(monkeypatch) -> None:
+ client, get_for_workflow, _ = _build_client(monkeypatch)
+
+ async def _repo_call(**kwargs):
+ assert kwargs["organization_id"] == ORG_ID
+ assert kwargs["workflow_permanent_id"] == "wpid_target"
+ return [
+ _episode(
+ heal_episode_id="he_2",
+ workflow_run_block_id="wrb_2",
+ block_label="block_b",
+ status=HealStatus.fired_completed,
+ workflow_permanent_id="wpid_target",
+ ),
+ _episode(
+ heal_episode_id="he_1",
+ workflow_run_block_id="wrb_1",
+ block_label="block_a",
+ status=HealStatus.fired_failed,
+ workflow_permanent_id="wpid_target",
+ ),
+ ]
+
+ get_for_workflow.side_effect = _repo_call
+
+ response = client.get("/v1/workflows/wpid_target/heal_episodes")
+
+ assert response.status_code == 200
+ body = response.json()
+ assert len(body) == 2
+ assert {item["workflow_run_block_id"] for item in body} == {"wrb_1", "wrb_2"}
+
+ expected_keys = set(HealEpisodeView.model_fields.keys())
+ for item in body:
+ assert set(item.keys()) == expected_keys
+ assert "block_code" not in item
+ assert "block_prompt" not in item
+ assert "failure_message" not in item
+
+
+def test_get_workflow_heal_episodes_invalid_status_returns_422(monkeypatch) -> None:
+ client, get_for_workflow, _ = _build_client(monkeypatch)
+
+ response = client.get("/v1/workflows/wpid_target/heal_episodes", params={"status": "invalid_status"})
+
+ assert response.status_code == 422
+ get_for_workflow.assert_not_awaited()
+
+
+def test_get_run_heal_episodes_returns_episodes_and_summary(monkeypatch) -> None:
+ client, _, get_for_run = _build_client(monkeypatch)
+ get_for_run.return_value = [
+ _episode(
+ heal_episode_id="he_1",
+ workflow_run_block_id="wrb_a",
+ block_label="block_a",
+ status=HealStatus.fired_completed,
+ workflow_run_id="wr_target",
+ ),
+ _episode(
+ heal_episode_id="he_2",
+ workflow_run_block_id="wrb_b",
+ block_label="block_b",
+ status=HealStatus.fired_failed,
+ workflow_run_id="wr_target",
+ output_obligation=OutputObligation.observed,
+ ),
+ ]
+
+ response = client.get("/v1/runs/wr_target/heal_episodes")
+
+ assert response.status_code == 200
+ body = response.json()
+ assert set(body.keys()) == {"episodes", "summary"}
+ assert len(body["episodes"]) == 2
+ assert set(body["summary"].keys()) == {
+ "blocks_healed",
+ "blocks_outcome_risk",
+ "blocks_with_heal_attempt",
+ }
+ assert body["summary"]["blocks_healed"] == 1
+ assert body["summary"]["blocks_with_heal_attempt"] == 2
+ assert body["summary"]["blocks_outcome_risk"] == ["block_b"]