Automate browser based workflows with AI
Python aiapiautomationbrowserbrowser-automationcomputergptllmplaywrightpowerautomatepuppeteerpythonrpaseleniumvisionworkflow
Record why a browser session was closed so an aborted one is not counted as completed (#8399)
Aaron Perez1126ec96fdad
diff --git a/alembic/versions/2026_09_02_1919-ac35398557c1_add_close_reason_to_persistent_browser_sessions.py b/alembic/versions/2026_09_02_1919-ac35398557c1_add_close_reason_to_persistent_browser_sessions.pynew file mode 100644index 000000000..d29291895--- /dev/null+++ b/alembic/versions/2026_09_02_1919-ac35398557c1_add_close_reason_to_persistent_browser_sessions.py@@ -0,0 +1,34 @@+"""add close_reason to persistent_browser_sessions++Revision ID: ac35398557c1+Revises: e29e30deaac9+Create Date: 2026-09-02T19:19:51.612058+00:00++"""++from typing import Sequence, Union++import sqlalchemy as sa++from alembic import op++# revision identifiers, used by Alembic.+revision: str = "ac35398557c1"+down_revision: Union[str, None] = "e29e30deaac9"+branch_labels: Union[str, Sequence[str], None] = None+depends_on: Union[str, Sequence[str], None] = None+++def upgrade() -> None:+ op.execute("SET lock_timeout = '5s';")+ op.add_column(+ "persistent_browser_sessions",+ sa.Column("close_reason", sa.String(), nullable=True),+ )+ op.execute("RESET lock_timeout;")+++def downgrade() -> None:+ op.execute("SET lock_timeout = '5s';")+ op.drop_column("persistent_browser_sessions", "close_reason")+ op.execute("RESET lock_timeout;")diff --git a/skyvern/forge/sdk/copilot/runtime.py b/skyvern/forge/sdk/copilot/runtime.pyindex 217003a47..4c889fb8a 100644--- a/skyvern/forge/sdk/copilot/runtime.py+++ b/skyvern/forge/sdk/copilot/runtime.py@@ -47,6 +47,7 @@ from skyvern.forge.sdk.copilot.verification_evidence import WorkflowVerificationfrom skyvern.forge.sdk.core import skyvern_contextfrom skyvern.forge.sdk.schemas.credentials import Credentialfrom skyvern.library.skyvern_browser import SkyvernBrowser+from skyvern.schemas.browser_session_close import BrowserSessionCloseReasonfrom skyvern.webeye.browser_errors import BrowserCdpConnectionError, BrowserTargetClosedErrorfrom skyvern.webeye.browser_retirement import BrowserOperationRejected, BrowserRetirement, BrowserRetirementReasonfrom skyvern.webeye.browser_state import BrowserState@@ -929,12 +930,17 @@ async def resolve_persistent_browser_state(return await asyncio.shield(_abandonable_browser_state_resolve(session_id, organization_id))-async def close_browser_session_quietly(organization_id: str, session_id: str) -> None:+async def close_browser_session_quietly(+ organization_id: str,+ session_id: str,+ *,+ reason: BrowserSessionCloseReason = BrowserSessionCloseReason.aborted,+) -> None:"""Bounded: the session-manager backend is often the reason we are closing at all, so anunbounded close could hang the request."""try:await asyncio.wait_for(- app.PERSISTENT_SESSIONS_MANAGER.close_session(organization_id, session_id),+ app.PERSISTENT_SESSIONS_MANAGER.close_session(organization_id, session_id, reason=reason),timeout=_SESSION_CLEANUP_TIMEOUT_SECONDS,)except Exception:@@ -1291,7 +1297,11 @@ async def _provision_browser_session(ctx: AgentContext) -> BuildTestConnectFailuinstalled_session_id=ctx.browser_session_id,organization_id=ctx.organization_id,)- await close_browser_session_quietly(ctx.organization_id, session.persistent_browser_session_id)+ await close_browser_session_quietly(+ ctx.organization_id,+ session.persistent_browser_session_id,+ reason=BrowserSessionCloseReason.user_requested,+ )session = Noneelse:ctx.browser_session_id = session.persistent_browser_session_iddiff --git a/skyvern/forge/sdk/db/models.py b/skyvern/forge/sdk/db/models.pyindex 4ec391792..5cf64cf29 100644--- a/skyvern/forge/sdk/db/models.py+++ b/skyvern/forge/sdk/db/models.py@@ -1424,6 +1424,8 @@ class PersistentBrowserSessionModel(Base):# workflow's cancellation to ride a throttled heartbeat. Write-once: it marks the first request.close_requested_at = Column(DateTime, nullable=True)cdp_unreachable_at = Column(DateTime, nullable=True)+ # A BrowserSessionCloseReason, write-once; NULL when the session timed out, failed, or predates the column.+ close_reason = Column(String, nullable=True)# Retained, unwritten column: the asynchronous-create contract that populated it was reverted,# and dropping it would rewrite a hot table for no gain. Keep it in sync with `alembic check`.provisioning_deadline_at = Column(DateTime, nullable=True)diff --git a/skyvern/forge/sdk/db/repositories/browser_sessions.py b/skyvern/forge/sdk/db/repositories/browser_sessions.pyindex 4aa17da92..8ed97bc6a 100644--- a/skyvern/forge/sdk/db/repositories/browser_sessions.py+++ b/skyvern/forge/sdk/db/repositories/browser_sessions.py@@ -37,6 +37,7 @@ from skyvern.forge.sdk.schemas.persistent_browser_sessions import (Extensions,PersistentBrowserSession,PersistentBrowserType,+ resolve_terminal_status,)from skyvern.forge.sdk.workflow.models.workflow import WorkflowRunStatusfrom skyvern.schemas.proxy_pinning import generate_proxy_session_id, parse_proxy_location_input@@ -846,6 +847,23 @@ class BrowserSessionsRepository(BaseRepository):)await session.commit()+ @db_operation("record_persistent_browser_session_close_reason")+ async def record_persistent_browser_session_close_reason(+ self, session_id: str, organization_id: str, close_reason: str+ ) -> None:+ """Write-once like close_requested_at, and only while the row is open: the reason that started+ the teardown is the one that explains it, and a row that ended on its own keeps NULL."""+ async with self.Session() as session:+ await session.execute(+ update(PersistentBrowserSessionModel)+ .where(PersistentBrowserSessionModel.persistent_browser_session_id == session_id)+ .where(PersistentBrowserSessionModel.organization_id == organization_id)+ .where(PersistentBrowserSessionModel.deleted_at.is_(None))+ .where(PersistentBrowserSessionModel.completed_at.is_(None))+ .values(close_reason=func.coalesce(PersistentBrowserSessionModel.close_reason, close_reason))+ )+ await session.commit()+@db_operation("is_persistent_browser_session_close_requested")async def is_persistent_browser_session_close_requested(self, session_id: str, organization_id: str) -> bool:"""Whether a close has been requested. Narrow single-column read: the session activity calls@@ -965,7 +983,9 @@ class BrowserSessionsRepository(BaseRepository):raise NotFoundError(f"PersistentBrowserSession {browser_session_id} not found")if status:- persistent_browser_session.status = status+ persistent_browser_session.status = resolve_terminal_status(+ status, persistent_browser_session.close_reason+ )if status in FINAL_STATUSES:# A session that has reached a final status is no longer producing downloads, so the# producer key must not survive it even when the caller omits completed_at.@@ -1253,7 +1273,9 @@ class BrowserSessionsRepository(BaseRepository):if persistent_browser_session.completed_at:return PersistentBrowserSession.model_validate(persistent_browser_session)persistent_browser_session.completed_at = naive_utc_now()- persistent_browser_session.status = "completed"+ persistent_browser_session.status = resolve_terminal_status(+ "completed", persistent_browser_session.close_reason+ )persistent_browser_session.download_run_id = Noneawait session.commit()await session.refresh(persistent_browser_session)diff --git a/skyvern/forge/sdk/executor/background_task_executor.py b/skyvern/forge/sdk/executor/background_task_executor.pyindex c5c1a5973..aa5e4b4fa 100644--- a/skyvern/forge/sdk/executor/background_task_executor.py+++ b/skyvern/forge/sdk/executor/background_task_executor.py@@ -17,6 +17,7 @@ from skyvern.forge.sdk.schemas.persistent_browser_sessions import FORCED_WORKFLOfrom skyvern.forge.sdk.schemas.task_v2 import TaskV2Statusfrom skyvern.forge.sdk.schemas.tasks import TaskStatusfrom skyvern.forge.sdk.workflow.models.workflow import WorkflowRunStatus+from skyvern.schemas.browser_session_close import BrowserSessionCloseReasonfrom skyvern.schemas.runs import RunEngine, RunTypefrom skyvern.services import script_service, task_v2_servicefrom skyvern.utils.files import initialize_skyvern_state_file@@ -166,6 +167,7 @@ class BackgroundTaskExecutor(AsyncExecutor):await app.PERSISTENT_SESSIONS_MANAGER.close_session(organization.organization_id,workflow_run.browser_session_id,+ reason=BrowserSessionCloseReason.aborted,)except Exception:LOG.exception(diff --git a/skyvern/forge/sdk/routes/workflow_copilot.py b/skyvern/forge/sdk/routes/workflow_copilot.pyindex 7d542596b..52ebde462 100644--- a/skyvern/forge/sdk/routes/workflow_copilot.py+++ b/skyvern/forge/sdk/routes/workflow_copilot.py@@ -108,6 +108,7 @@ from skyvern.forge.sdk.workflow.exceptions import BaseWorkflowHTTPExceptionfrom skyvern.forge.sdk.workflow.models.parameter import ParameterTypefrom skyvern.forge.sdk.workflow.models.workflow import Workflowfrom skyvern.forge.sdk.workflow.workflow_definition_converter import convert_workflow_definition+from skyvern.schemas.browser_session_close import BrowserSessionCloseReasonfrom skyvern.schemas.workflows import (WorkflowCreateYAMLRequest,WorkflowDefinitionYAML,@@ -2434,7 +2435,11 @@ async def _new_copilot_chat_post(metadata = agent_result.browser_ablation_metadatabrowser_session_id = metadata.get("browser_session_id") if isinstance(metadata, dict) else Noneif isinstance(browser_session_id, str) and browser_session_id:- await close_browser_session_quietly(organization.organization_id, browser_session_id)+ await close_browser_session_quietly(+ organization.organization_id,+ browser_session_id,+ reason=BrowserSessionCloseReason.user_requested,+ )return FastAPIEventSourceStream.create(request, stream_handler)diff --git a/skyvern/forge/sdk/schemas/persistent_browser_sessions.py b/skyvern/forge/sdk/schemas/persistent_browser_sessions.pyindex 0576202e1..1cafb5652 100644--- a/skyvern/forge/sdk/schemas/persistent_browser_sessions.py+++ b/skyvern/forge/sdk/schemas/persistent_browser_sessions.py@@ -5,6 +5,7 @@ from enum import StrEnumfrom pydantic import BaseModel, ConfigDict, field_validatorfrom skyvern.forge.sdk.db.utils import deserialize_proxy_location+from skyvern.schemas.browser_session_close import BrowserSessionCloseReasonfrom skyvern.schemas.proxy_pinning import validate_proxy_session_idfrom skyvern.schemas.runs import ProxyLocationInput@@ -29,6 +30,13 @@ def is_final_status(status: str | None) -> bool:return status in FINAL_STATUSES+def resolve_terminal_status(status: str, close_reason: str | None) -> str:+ """A close requested as an abort lands on failed; every other terminal write keeps what it asked for."""+ if status == PersistentBrowserSessionStatus.completed and close_reason == BrowserSessionCloseReason.aborted:+ return PersistentBrowserSessionStatus.failed.value+ return status++def export_profile_storage_id(*,session_id: str,@@ -98,6 +106,7 @@ class PersistentBrowserSession(BaseModel):last_activity_at: datetime | None = Noneclose_requested_at: datetime | None = Nonecdp_unreachable_at: datetime | None = None+ close_reason: str | None = Nonecreated_at: datetimemodified_at: datetimedeleted_at: datetime | None = Nonediff --git a/skyvern/forge/sdk/workflow/models/block.py b/skyvern/forge/sdk/workflow/models/block.pyindex b83d0ce72..538f94bb2 100644--- a/skyvern/forge/sdk/workflow/models/block.py+++ b/skyvern/forge/sdk/workflow/models/block.py@@ -226,6 +226,7 @@ from skyvern.forge.sdk.workflow.secret_encryption import (is_encrypted_secret,is_full_template_reference,)+from skyvern.schemas.browser_session_close import BrowserSessionCloseReasonfrom skyvern.schemas.runs import RunEnginefrom skyvern.schemas.self_heal import HealClassification, HealSkipReason, HealStatus, OutputObligationfrom skyvern.schemas.workflows import (@@ -15575,7 +15576,13 @@ class WorkflowTriggerBlock(Block):if created_fresh_session and resolved_browser_session_id:try:await app.PERSISTENT_SESSIONS_MANAGER.close_session(- organization_id, resolved_browser_session_id+ organization_id,+ resolved_browser_session_id,+ reason=(+ BrowserSessionCloseReason.user_requested+ if success+ else BrowserSessionCloseReason.aborted+ ),)except Exception:LOG.warning(diff --git a/skyvern/forge/sdk/workflow/service.py b/skyvern/forge/sdk/workflow/service.pyindex e91ae1b9f..e8b70db0d 100644--- a/skyvern/forge/sdk/workflow/service.py+++ b/skyvern/forge/sdk/workflow/service.py@@ -203,6 +203,7 @@ from skyvern.forge.sdk.workflow.status_mapping import (TASK_STATUS_MAP,)from skyvern.forge.sdk.workflow.workflow_definition_converter import convert_workflow_definition+from skyvern.schemas.browser_session_close import BrowserSessionCloseReasonfrom skyvern.schemas.proxy_pinning import (derive_proxy_session_id,redact_proxy_session_id,@@ -3865,7 +3866,9 @@ class WorkflowService:@staticmethodasync def _close_reused_session_best_effort(*, organization_id: str, session_id: str) -> None:try:- await app.PERSISTENT_SESSIONS_MANAGER.close_session(organization_id, session_id)+ await app.PERSISTENT_SESSIONS_MANAGER.close_session(+ organization_id, session_id, reason=BrowserSessionCloseReason.aborted+ )except Exception:LOG.warning("Failed to close unusable reused browser session",diff --git a/skyvern/schemas/browser_session_close.py b/skyvern/schemas/browser_session_close.pynew file mode 100644index 000000000..52d6b8042--- /dev/null+++ b/skyvern/schemas/browser_session_close.py@@ -0,0 +1,15 @@+"""A leaf module with no Skyvern imports: copilot and workflow-service modules name a close reason+from inside the import cycle that ``persistent_browser_sessions`` reaches through ``db.utils``."""++from enum import StrEnum+++class BrowserSessionCloseReason(StrEnum):+ """Persisted on the session row, so every member stays low-cardinality and free of session,+ run, or customer identifiers."""++ user_requested = "user_requested"+ expired = "expired"+ orphaned = "orphaned"+ shutdown = "shutdown"+ aborted = "aborted"diff --git a/skyvern/webeye/default_persistent_sessions_manager.py b/skyvern/webeye/default_persistent_sessions_manager.pyindex 6741aa14c..ed9372c99 100644--- a/skyvern/webeye/default_persistent_sessions_manager.py+++ b/skyvern/webeye/default_persistent_sessions_manager.py@@ -30,6 +30,7 @@ from skyvern.forge.sdk.schemas.persistent_browser_sessions import (is_final_status,)from skyvern.forge.sdk.streaming.registries import stream_tombstone_holds_session_lease+from skyvern.schemas.browser_session_close import BrowserSessionCloseReasonfrom skyvern.schemas.run_enums import RunTypefrom skyvern.schemas.runs import ProxyLocation, ProxyLocationInputfrom skyvern.webeye.browser_state import BrowserState@@ -741,7 +742,7 @@ class DefaultPersistentSessionsManager(PersistentSessionsManager):raise# Session doesn't exist, has started, is completed, or is stuck — close itif session is None or session.completed_at is None:- await self.close_session(organization_id, session_id)+ await self.close_session(organization_id, session_id, reason=BrowserSessionCloseReason.expired)raiseasync def seconds_until_fixed_deadline(self, session_id: str, organization_id: str) -> float | None:@@ -975,7 +976,13 @@ class DefaultPersistentSessionsManager(PersistentSessionsManager):_release_cdp_port(browser_session.cdp_port)return True- async def _close_session(self, organization_id: str, browser_session_id: str) -> None:+ async def _close_session(+ self,+ organization_id: str,+ browser_session_id: str,+ *,+ reason: BrowserSessionCloseReason = BrowserSessionCloseReason.user_requested,+ ) -> None:released = await self._release_local_browser_session(organization_id, browser_session_id)if not released:LOG.info(@@ -984,16 +991,33 @@ class DefaultPersistentSessionsManager(PersistentSessionsManager):session_id=browser_session_id,)+ try:+ await self.database.browser_sessions.record_persistent_browser_session_close_reason(+ browser_session_id, organization_id, reason.value+ )+ except Exception:+ LOG.warning(+ "Failed to record the close reason; the row will close on its terminal default",+ organization_id=organization_id,+ session_id=browser_session_id,+ exc_info=True,+ )await self.database.browser_sessions.close_persistent_browser_session(browser_session_id, organization_id)if settings.BROWSER_STREAMING_MODE == "cdp":await self.database.browser_sessions.archive_browser_session_address(browser_session_id, organization_id)- async def close_session(self, organization_id: str, browser_session_id: str) -> None:+ async def close_session(+ self,+ organization_id: str,+ browser_session_id: str,+ *,+ reason: BrowserSessionCloseReason = BrowserSessionCloseReason.user_requested,+ ) -> None:"""Close a session while retaining cleanup ownership if its caller is cancelled."""cleanup_key = (organization_id, browser_session_id)cleanup_task = self._close_cleanup_tasks.get(cleanup_key)if cleanup_task is None:- cleanup_task = asyncio.create_task(self._close_session(organization_id, browser_session_id))+ cleanup_task = asyncio.create_task(self._close_session(organization_id, browser_session_id, reason=reason))self._close_cleanup_tasks[cleanup_key] = cleanup_taskself._retain_background_task(cleanup_task)@@ -1008,7 +1032,11 @@ class DefaultPersistentSessionsManager(PersistentSessionsManager):"""Close all browser sessions for an organization."""browser_sessions = await self.database.browser_sessions.get_active_persistent_browser_sessions(organization_id)for browser_session in browser_sessions:- await self.close_session(organization_id, browser_session.persistent_browser_session_id)+ await self.close_session(+ organization_id,+ browser_session.persistent_browser_session_id,+ reason=BrowserSessionCloseReason.shutdown,+ )async def cleanup_stale_sessions(self) -> None:"""Close sessions left active by a previous process."""@@ -1137,7 +1165,11 @@ class DefaultPersistentSessionsManager(PersistentSessionsManager):organization_id=db_session.organization_id,)try:- await self.close_session(db_session.organization_id, db_session.persistent_browser_session_id)+ await self.close_session(+ db_session.organization_id,+ db_session.persistent_browser_session_id,+ reason=BrowserSessionCloseReason.expired,+ )except Exception:LOG.exception("Failed to reap expired persistent browser session",@@ -1228,5 +1260,9 @@ class DefaultPersistentSessionsManager(PersistentSessionsManager):if cls.instance:active_sessions = await cls.instance.database.browser_sessions.get_all_active_persistent_browser_sessions()for db_session in active_sessions:- await cls.instance.close_session(db_session.organization_id, db_session.persistent_browser_session_id)+ await cls.instance.close_session(+ db_session.organization_id,+ db_session.persistent_browser_session_id,+ reason=BrowserSessionCloseReason.shutdown,+ )LOG.info("PersistentSessionsManager is closed")diff --git a/skyvern/webeye/persistent_sessions_manager.py b/skyvern/webeye/persistent_sessions_manager.pyindex ad95d9d58..81d28f032 100644--- a/skyvern/webeye/persistent_sessions_manager.py+++ b/skyvern/webeye/persistent_sessions_manager.py@@ -13,6 +13,7 @@ from skyvern.forge.sdk.schemas.persistent_browser_sessions import (PersistentBrowserSession,PersistentBrowserType,)+from skyvern.schemas.browser_session_close import BrowserSessionCloseReasonfrom skyvern.schemas.runs import ProxyLocation, ProxyLocationInputfrom skyvern.webeye.browser_retirement import (BrowserOperationRejected,@@ -271,8 +272,14 @@ class PersistentSessionsManager(Protocol):"""...- async def close_session(self, organization_id: str, browser_session_id: str) -> None:- """Close a specific browser session."""+ async def close_session(+ self,+ organization_id: str,+ browser_session_id: str,+ *,+ reason: BrowserSessionCloseReason = BrowserSessionCloseReason.user_requested,+ ) -> None:+ """Close a specific browser session; ``reason`` is recorded on its row, and an abort lands it on failed."""...async def close_all_sessions(self, organization_id: str) -> None:diff --git a/tests/unit/test_background_task_executor.py b/tests/unit/test_background_task_executor.pyindex 8ce6ca1a4..0ddb26226 100644--- a/tests/unit/test_background_task_executor.py+++ b/tests/unit/test_background_task_executor.py@@ -11,6 +11,7 @@ from skyvern.forge.sdk.core import skyvern_contextfrom skyvern.forge.sdk.core.skyvern_context import SkyvernContextfrom skyvern.forge.sdk.executor.background_task_executor import BackgroundTaskExecutorfrom skyvern.forge.sdk.schemas.persistent_browser_sessions import FORCED_WORKFLOW_SESSION_RUNNABLE_TYPE+from skyvern.schemas.browser_session_close import BrowserSessionCloseReason@pytest.mark.asyncio@@ -254,7 +255,7 @@ async def test_execute_workflow_closes_forced_session_before_credential_fence(block_outputs=None,)- close_session.assert_awaited_once_with("org_test", "pbs_forced")+ close_session.assert_awaited_once_with("org_test", "pbs_forced", reason=BrowserSessionCloseReason.aborted)executor._schedule.assert_not_called()diff --git a/tests/unit/test_copilot_diagnosis_repair_contract.py b/tests/unit/test_copilot_diagnosis_repair_contract.pyindex 5c6400724..7e078fdd9 100644--- a/tests/unit/test_copilot_diagnosis_repair_contract.py+++ b/tests/unit/test_copilot_diagnosis_repair_contract.py@@ -3030,7 +3030,7 @@ async def test_post_run_inspect_does_not_close_the_session_it_landed_on(closed: list[str] = []class _Sessions:- async def close_session(self, *, organization_id: str, browser_session_id: str) -> None:+ async def close_session(self, *, organization_id: str, browser_session_id: str, **_: object) -> None:closed.append(browser_session_id)monkeypatch.setattr("skyvern.forge.app.PERSISTENT_SESSIONS_MANAGER", _Sessions(), raising=False)diff --git a/tests/unit/test_copilot_runtime.py b/tests/unit/test_copilot_runtime.pyindex 13502d604..f82e20cf8 100644--- a/tests/unit/test_copilot_runtime.py+++ b/tests/unit/test_copilot_runtime.py@@ -29,6 +29,7 @@ from skyvern.forge.sdk.copilot import mcp_adapter, runtimefrom skyvern.forge.sdk.copilot.mcp_adapter import SchemaOverlayfrom skyvern.forge.sdk.copilot.runtime import AgentContext, ensure_browser_session, mcp_browser_context, mcp_to_copilotfrom skyvern.forge.sdk.copilot.unrecoverable_tool_error import _is_unrecoverable_browser_session_error+from skyvern.schemas.browser_session_close import BrowserSessionCloseReasonfrom skyvern.webeye.browser_errors import BrowserCdpConnectionError, BrowserTargetClosedErrorfrom skyvern.webeye.persistent_sessions_manager import BrowserOperation, BrowserRetirementfrom tests.unit.test_copilot_secret_scrub import _make_server@@ -280,7 +281,40 @@ async def test_ensure_browser_session_times_out_and_cleans_up(monkeypatch: pytesresult = await ensure_browser_session(ctx)assert result == {"ok": False, "error": "Failed to create browser session"}assert ctx.browser_session_id is None- mock_manager.close_session.assert_awaited_once_with("org_1", "bs_2")+ mock_manager.close_session.assert_awaited_once_with("org_1", "bs_2", reason=BrowserSessionCloseReason.aborted)+++async def test_a_duplicate_session_from_a_creation_race_closes_cleanly(monkeypatch: pytest.MonkeyPatch) -> None:+ # SKY-15022: the loser of a create race closes a healthy browser it never used; that is not an abort.+ import skyvern.forge.sdk.copilot.runtime as runtime++ ctx = _make_ctx()+ loser = MagicMock()+ loser.persistent_browser_session_id = "bs_loser"++ async def _create(**_kwargs: object) -> MagicMock:+ ctx.browser_session_id = "bs_winner"+ return loser++ ready_state = MagicMock()+ ready_state.browser_context = _FakeBrowserContext()+ mock_manager = MagicMock()+ mock_manager.create_session = AsyncMock(side_effect=_create)+ mock_manager.get_browser_state = AsyncMock(return_value=ready_state)+ mock_manager.close_session = AsyncMock()+ mock_app = MagicMock()+ mock_app.PERSISTENT_SESSIONS_MANAGER = mock_manager+ monkeypatch.setattr(runtime, "app", mock_app)+ monkeypatch.setattr(runtime, "_BROWSER_BOOT_POLL_INTERVAL_SECONDS", 0.0)++ result = await ensure_browser_session(ctx)++ assert result is None+ assert ctx.browser_session_id == "bs_winner"+ mock_manager.close_session.assert_awaited_once_with(+ "org_1", "bs_loser", reason=BrowserSessionCloseReason.user_requested+ )@pytest.mark.asyncio@@ -309,7 +343,9 @@ async def test_cancelled_browser_boot_closes_the_partially_created_session(monkewith pytest.raises(asyncio.CancelledError):await taskassert ctx.browser_session_id is None- mock_manager.close_session.assert_awaited_once_with("org_1", "bs_cancelled_boot")+ mock_manager.close_session.assert_awaited_once_with(+ "org_1", "bs_cancelled_boot", reason=BrowserSessionCloseReason.aborted+ )@pytest.mark.asyncio@@ -591,7 +627,7 @@ def _install_dispatch_stack(monkeypatch.setattr(runtime, "register_copilot_session", MagicMock())monkeypatch.setattr(runtime, "unregister_copilot_session", MagicMock())- async def _close(_organization_id: str, _session_id: str) -> None:+ async def _close(_organization_id: str, _session_id: str, **_kwargs: object) -> None:return Nonemonkeypatch.setattr(runtime, "close_browser_session_quietly", _close)diff --git a/tests/unit/test_default_persistent_sessions_manager_close.py b/tests/unit/test_default_persistent_sessions_manager_close.pyindex c2b2db66c..7c407a032 100644--- a/tests/unit/test_default_persistent_sessions_manager_close.py+++ b/tests/unit/test_default_persistent_sessions_manager_close.py@@ -4,6 +4,7 @@ from unittest.mock import ANY, AsyncMock, MagicMock, patchimport pytest+from skyvern.schemas.browser_session_close import BrowserSessionCloseReasonfrom skyvern.webeye import default_persistent_sessions_manager as manager_modfrom skyvern.webeye.default_persistent_sessions_manager import BrowserSession, DefaultPersistentSessionsManagerfrom skyvern.webeye.persistent_sessions_manager import PBS_TASK_RUNNABLE_TYPE@@ -69,6 +70,7 @@ def manager() -> DefaultPersistentSessionsManager:db.browser_sessions.get_persistent_browser_session = AsyncMock()db.browser_sessions.close_persistent_browser_session = AsyncMock()db.browser_sessions.archive_browser_session_address = AsyncMock()+ db.browser_sessions.record_persistent_browser_session_close_reason = AsyncMock()return DefaultPersistentSessionsManager(database=db)@@ -157,6 +159,28 @@ async def test_close_session_exports_and_closes_for_matching_org()+async def test_close_session_records_the_reason_before_closing_the_row(+ manager: DefaultPersistentSessionsManager,+) -> None:+ """SKY-15022: the row close resolves its terminal status from the recorded reason."""+ events: list[str] = []+ manager.database.browser_sessions.record_persistent_browser_session_close_reason = AsyncMock(+ side_effect=lambda *_: events.append("reason")+ )+ manager.database.browser_sessions.close_persistent_browser_session = AsyncMock(+ side_effect=lambda *_: events.append("close")+ )++ with patch.object(manager_mod.settings, "BROWSER_STREAMING_MODE", "vnc"):+ await manager.close_session("org_owner", "pbs_aborted", reason=BrowserSessionCloseReason.aborted)++ manager.database.browser_sessions.record_persistent_browser_session_close_reason.assert_awaited_once_with(+ "pbs_aborted", "org_owner", "aborted"+ )+ assert events == ["reason", "close"]++@pytest.mark.asyncioasync def test_cancelled_close_retains_browser_and_port_cleanup(manager: DefaultPersistentSessionsManager,diff --git a/tests/unit/test_persistent_session_reaper.py b/tests/unit/test_persistent_session_reaper.pyindex 15d09816e..59875c3b1 100644--- a/tests/unit/test_persistent_session_reaper.py+++ b/tests/unit/test_persistent_session_reaper.py@@ -10,6 +10,7 @@ from unittest.mock import AsyncMock, MagicMock, patchimport pytestfrom skyvern.forge.sdk.workflow.models.workflow import WorkflowRunStatus+from skyvern.schemas.browser_session_close import BrowserSessionCloseReasonfrom skyvern.schemas.run_enums import RunTypefrom skyvern.webeye import default_persistent_sessions_manager as manager_modfrom skyvern.webeye.default_persistent_sessions_manager import BrowserSession, DefaultPersistentSessionsManager@@ -45,6 +46,7 @@ def _make_manager(uncompleted_sessions: list, owned_ids: list[str] | None = Nonedb = MagicMock()db.browser_sessions = MagicMock()db.browser_sessions.get_uncompleted_persistent_browser_sessions = AsyncMock(return_value=uncompleted_sessions)+ db.browser_sessions.record_persistent_browser_session_close_reason = AsyncMock()db.workflow_runs = MagicMock()db.tasks = MagicMock()# Default: the owning run row is gone (stale). Tests that need a live/terminal owner override this.@@ -118,7 +120,7 @@ async def test_reaps_only_sessions_past_timeout_and_grace() -> None:await manager.reap_expired_sessions()- manager.close_session.assert_awaited_once_with("org_test", "pbs_expired")+ manager.close_session.assert_awaited_once_with("org_test", "pbs_expired", reason=BrowserSessionCloseReason.expired)@pytest.mark.asyncio@@ -218,7 +220,7 @@ async def test_reaps_expired_session_whose_owning_run_is_terminal(terminal_statuawait manager.reap_expired_sessions()- manager.close_session.assert_awaited_once_with("org_test", "pbs_stuck")+ manager.close_session.assert_awaited_once_with("org_test", "pbs_stuck", reason=BrowserSessionCloseReason.expired)manager.database.workflow_runs.get_workflow_run.assert_awaited_once_with(workflow_run_id="wr_dead",organization_id="org_test",@@ -243,7 +245,7 @@ async def test_reaps_expired_session_whose_owning_run_is_missing() -> None:await manager.reap_expired_sessions()- manager.close_session.assert_awaited_once_with("org_test", "pbs_orphan")+ manager.close_session.assert_awaited_once_with("org_test", "pbs_orphan", reason=BrowserSessionCloseReason.expired)@pytest.mark.asyncio@@ -288,7 +290,9 @@ async def test_reaps_expired_session_with_unresolvable_runnable_type(unresolvablawait manager.reap_expired_sessions()- manager.close_session.assert_awaited_once_with("org_test", "pbs_unresolvable")+ manager.close_session.assert_awaited_once_with(+ "org_test", "pbs_unresolvable", reason=BrowserSessionCloseReason.expired+ )# No per-type liveness semantics were invented: neither known-owner lookup was attempted.manager.database.workflow_runs.get_workflow_run.assert_not_awaited()manager.database.tasks.get_task.assert_not_awaited()@@ -366,7 +370,7 @@ async def test_reaps_expired_session_once_its_lease_is_released(browser_manager:browser_manager._persistent_session_leases.pop("s_done")await manager.reap_expired_sessions()- manager.close_session.assert_awaited_once_with("org_test", "pbs_released")+ manager.close_session.assert_awaited_once_with("org_test", "pbs_released", reason=BrowserSessionCloseReason.expired)@pytest.mark.asyncio@@ -391,7 +395,7 @@ async def test_lease_does_not_protect_a_session_owned_by_a_terminal_workflow_runawait manager.reap_expired_sessions()- manager.close_session.assert_awaited_once_with("org_test", "pbs_wr_dead")+ manager.close_session.assert_awaited_once_with("org_test", "pbs_wr_dead", reason=BrowserSessionCloseReason.expired)@pytest.mark.asyncio@@ -499,7 +503,9 @@ async def test_reap_pass_survives_close_failure_without_dropping_session() -> Noawait manager.reap_expired_sessions() # must not raise- manager.close_session.assert_awaited_once_with("org_test", "pbs_flaky_close")+ manager.close_session.assert_awaited_once_with(+ "org_test", "pbs_flaky_close", reason=BrowserSessionCloseReason.expired+ )@pytest.mark.asyncio@@ -559,7 +565,9 @@ async def test_reclaims_cdp_connect_request_level_session_after_run_dies() -> No):await manager.reap_expired_sessions()- manager.close_session.assert_awaited_once_with("org_test", "pbs_request_level")+ manager.close_session.assert_awaited_once_with(+ "org_test", "pbs_request_level", reason=BrowserSessionCloseReason.expired+ )manager.database.workflow_runs.get_workflow_run.assert_awaited_once_with(workflow_run_id="wr_request_level",organization_id="org_test",diff --git a/tests/unit/workflow/test_workflow_trigger_block.py b/tests/unit/workflow/test_workflow_trigger_block.pyindex 07de74c3c..964758cb1 100644--- a/tests/unit/workflow/test_workflow_trigger_block.py+++ b/tests/unit/workflow/test_workflow_trigger_block.py@@ -25,6 +25,7 @@ from skyvern.forge.sdk.workflow.models.block import ()from skyvern.forge.sdk.workflow.models.parameter import OutputParameter, WorkflowParameter, WorkflowParameterTypefrom skyvern.forge.sdk.workflow.models.workflow import WorkflowRunStatus+from skyvern.schemas.browser_session_close import BrowserSessionCloseReasonfrom skyvern.schemas.workflows import BlockType@@ -644,7 +645,9 @@ async def test_sync_trigger_closes_fresh_session_when_fence_fires() -> None:mock_app.WORKFLOW_SERVICE.execute_workflow.assert_not_awaited()mock_app.WORKFLOW_SERVICE.mark_workflow_run_as_failed_if_not_final.assert_awaited_once()assert captured["success"] is False- mock_app.PERSISTENT_SESSIONS_MANAGER.close_session.assert_awaited_once_with("org_parent", "pbs_fresh")+ mock_app.PERSISTENT_SESSIONS_MANAGER.close_session.assert_awaited_once_with(+ "org_parent", "pbs_fresh", reason=BrowserSessionCloseReason.aborted+ )@pytest.mark.asyncio@@ -667,7 +670,9 @@ async def test_sync_trigger_closes_fresh_session_when_setup_raises() -> None:mock_app, captured = await _run_sync_trigger_fence(block, created_session_id="pbs_fresh", setup_raises=True)assert captured["success"] is False- mock_app.PERSISTENT_SESSIONS_MANAGER.close_session.assert_awaited_once_with("org_parent", "pbs_fresh")+ mock_app.PERSISTENT_SESSIONS_MANAGER.close_session.assert_awaited_once_with(+ "org_parent", "pbs_fresh", reason=BrowserSessionCloseReason.aborted+ )class TestBlockMetadata: