Skip to content

Automate browser based workflows with AI

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.py
new file mode 100644
index 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.py
index 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 WorkflowVerification
from skyvern.forge.sdk.core import skyvern_context
from skyvern.forge.sdk.schemas.credentials import Credential
from skyvern.library.skyvern_browser import SkyvernBrowser
+from skyvern.schemas.browser_session_close import BrowserSessionCloseReason
from skyvern.webeye.browser_errors import BrowserCdpConnectionError, BrowserTargetClosedError
from skyvern.webeye.browser_retirement import BrowserOperationRejected, BrowserRetirement, BrowserRetirementReason
from 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 an
unbounded 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) -> BuildTestConnectFailu
installed_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 = None
else:
ctx.browser_session_id = session.persistent_browser_session_id
diff --git a/skyvern/forge/sdk/db/models.py b/skyvern/forge/sdk/db/models.py
index 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.py
index 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 WorkflowRunStatus
from 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 = None
await 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.py
index 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_WORKFLO
from skyvern.forge.sdk.schemas.task_v2 import TaskV2Status
from skyvern.forge.sdk.schemas.tasks import TaskStatus
from skyvern.forge.sdk.workflow.models.workflow import WorkflowRunStatus
+from skyvern.schemas.browser_session_close import BrowserSessionCloseReason
from skyvern.schemas.runs import RunEngine, RunType
from skyvern.services import script_service, task_v2_service
from 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.py
index 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 BaseWorkflowHTTPException
from skyvern.forge.sdk.workflow.models.parameter import ParameterType
from skyvern.forge.sdk.workflow.models.workflow import Workflow
from skyvern.forge.sdk.workflow.workflow_definition_converter import convert_workflow_definition
+from skyvern.schemas.browser_session_close import BrowserSessionCloseReason
from skyvern.schemas.workflows import (
WorkflowCreateYAMLRequest,
WorkflowDefinitionYAML,
@@ -2434,7 +2435,11 @@ async def _new_copilot_chat_post(
metadata = agent_result.browser_ablation_metadata
browser_session_id = metadata.get("browser_session_id") if isinstance(metadata, dict) else None
if 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.py
index 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 StrEnum
from pydantic import BaseModel, ConfigDict, field_validator
from skyvern.forge.sdk.db.utils import deserialize_proxy_location
+from skyvern.schemas.browser_session_close import BrowserSessionCloseReason
from skyvern.schemas.proxy_pinning import validate_proxy_session_id
from 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 = None
close_requested_at: datetime | None = None
cdp_unreachable_at: datetime | None = None
+ close_reason: str | None = None
created_at: datetime
modified_at: datetime
deleted_at: datetime | None = None
diff --git a/skyvern/forge/sdk/workflow/models/block.py b/skyvern/forge/sdk/workflow/models/block.py
index 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 BrowserSessionCloseReason
from skyvern.schemas.runs import RunEngine
from skyvern.schemas.self_heal import HealClassification, HealSkipReason, HealStatus, OutputObligation
from 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.py
index 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 BrowserSessionCloseReason
from skyvern.schemas.proxy_pinning import (
derive_proxy_session_id,
redact_proxy_session_id,
@@ -3865,7 +3866,9 @@ class WorkflowService:
@staticmethod
async 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.py
new file mode 100644
index 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.py
index 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 BrowserSessionCloseReason
from skyvern.schemas.run_enums import RunType
from skyvern.schemas.runs import ProxyLocation, ProxyLocationInput
from 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 it
if 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)
raise
async 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_task
self._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.py
index 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 BrowserSessionCloseReason
from skyvern.schemas.runs import ProxyLocation, ProxyLocationInput
from 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.py
index 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_context
from skyvern.forge.sdk.core.skyvern_context import SkyvernContext
from skyvern.forge.sdk.executor.background_task_executor import BackgroundTaskExecutor
from 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.py
index 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.py
index 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, runtime
from skyvern.forge.sdk.copilot.mcp_adapter import SchemaOverlay
from skyvern.forge.sdk.copilot.runtime import AgentContext, ensure_browser_session, mcp_browser_context, mcp_to_copilot
from skyvern.forge.sdk.copilot.unrecoverable_tool_error import _is_unrecoverable_browser_session_error
+from skyvern.schemas.browser_session_close import BrowserSessionCloseReason
from skyvern.webeye.browser_errors import BrowserCdpConnectionError, BrowserTargetClosedError
from skyvern.webeye.persistent_sessions_manager import BrowserOperation, BrowserRetirement
from 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: pytes
result = 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(monke
with pytest.raises(asyncio.CancelledError):
await task
assert 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 None
monkeypatch.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.py
index 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, patch
import pytest
+from skyvern.schemas.browser_session_close import BrowserSessionCloseReason
from skyvern.webeye import default_persistent_sessions_manager as manager_mod
from skyvern.webeye.default_persistent_sessions_manager import BrowserSession, DefaultPersistentSessionsManager
from 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.asyncio
async 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.py
index 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, patch
import pytest
from skyvern.forge.sdk.workflow.models.workflow import WorkflowRunStatus
+from skyvern.schemas.browser_session_close import BrowserSessionCloseReason
from skyvern.schemas.run_enums import RunType
from skyvern.webeye import default_persistent_sessions_manager as manager_mod
from skyvern.webeye.default_persistent_sessions_manager import BrowserSession, DefaultPersistentSessionsManager
@@ -45,6 +46,7 @@ def _make_manager(uncompleted_sessions: list, owned_ids: list[str] | None = None
db = 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_statu
await 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(unresolvabl
await 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_run
await 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() -> No
await 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.py
index 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, WorkflowParameterType
from skyvern.forge.sdk.workflow.models.workflow import WorkflowRunStatus
+from skyvern.schemas.browser_session_close import BrowserSessionCloseReason
from 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: