Skip to content

Automate browser based workflows with AI

Reap orphaned upstream browser sessions from outside the process that holds them (SKY-13158) (#7821)

Aaron Perezf7dd9b86bf43
diff --git a/alembic/versions/2026_07_28_2230-b0941c6bd241_partial_index_for_the_vendor_held_session_lease_sweep_sky_13158.py b/alembic/versions/2026_07_28_2230-b0941c6bd241_partial_index_for_the_vendor_held_session_lease_sweep_sky_13158.py
new file mode 100644
index 000000000..74964e599
--- /dev/null
+++ b/alembic/versions/2026_07_28_2230-b0941c6bd241_partial_index_for_the_vendor_held_session_lease_sweep_sky_13158.py
@@ -0,0 +1,50 @@
+"""Partial index for the vendor-held session lease sweep (SKY-13158)
+
+Revision ID: b0941c6bd241
+Revises: ff4452dc827f
+Create Date: 2026-07-28T22:30:03.274576+00:00
+
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "b0941c6bd241"
+down_revision: Union[str, None] = "ff4452dc827f"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+_INDEX_NAME = "idx_pbs_vendor_held_lease"
+_TABLE = "persistent_browser_sessions"
+_PARTIAL_WHERE = (
+ "upstream_cdp_url IS NOT NULL AND browser_address IS NULL AND completed_at IS NULL AND deleted_at IS NULL"
+)
+
+
+def upgrade() -> None:
+ with op.get_context().autocommit_block():
+ op.execute("SET statement_timeout = '1h';")
+ op.create_index(
+ _INDEX_NAME,
+ _TABLE,
+ ["last_activity_at", "started_at"],
+ unique=False,
+ postgresql_concurrently=True,
+ postgresql_where=sa.text(_PARTIAL_WHERE),
+ if_not_exists=True,
+ )
+ op.execute("RESET statement_timeout;")
+
+
+def downgrade() -> None:
+ with op.get_context().autocommit_block():
+ op.drop_index(
+ _INDEX_NAME,
+ table_name=_TABLE,
+ postgresql_concurrently=True,
+ if_exists=True,
+ )
diff --git a/skyvern/forge/sdk/db/models.py b/skyvern/forge/sdk/db/models.py
index 6360a65dc..937bc4ecb 100644
--- a/skyvern/forge/sdk/db/models.py
+++ b/skyvern/forge/sdk/db/models.py
@@ -1299,6 +1299,22 @@ class PersistentBrowserSessionModel(Base):
"status",
desc("created_at"),
),
+ # The orphan sweep (SKY-13158) is deliberately cross-organization, so it matches neither
+ # index above. The partial predicate is what does the work: it restricts the index to live
+ # vendor-held rows, a small subset, which is why plain column keys are enough even though
+ # the sweep orders by COALESCE(last_activity_at, started_at).
+ # Do NOT "fix" the keys to that COALESCE expression: alembic cannot reliably compare
+ # expression-based indexes, so an expression key here reads as drift and fails `alembic
+ # check`. Its postgresql_where is never compared, so the partial predicate is safe.
+ Index(
+ "idx_pbs_vendor_held_lease",
+ "last_activity_at",
+ "started_at",
+ postgresql_where=text(
+ "upstream_cdp_url IS NOT NULL AND browser_address IS NULL "
+ "AND completed_at IS NULL AND deleted_at IS NULL"
+ ),
+ ),
)
persistent_browser_session_id = Column(String, primary_key=True, default=generate_persistent_browser_session_id)
diff --git a/skyvern/forge/sdk/db/repositories/browser_sessions.py b/skyvern/forge/sdk/db/repositories/browser_sessions.py
index 99bd29098..518c36491 100644
--- a/skyvern/forge/sdk/db/repositories/browser_sessions.py
+++ b/skyvern/forge/sdk/db/repositories/browser_sessions.py
@@ -53,6 +53,11 @@ _VISIBLE_TO_CUSTOMER = or_(
PersistentBrowserSessionModel.browser_address.isnot(None),
)
+_VENDOR_HELD = and_(
+ PersistentBrowserSessionModel.upstream_cdp_url.isnot(None),
+ PersistentBrowserSessionModel.browser_address.is_(None),
+)
+
class BrowserSessionsRepository(BaseRepository):
"""Database operations for browser profiles and persistent browser sessions."""
@@ -697,6 +702,38 @@ class BrowserSessionsRepository(BaseRepository):
await session.refresh(browser_session)
return PersistentBrowserSession.model_validate(browser_session)
+ @db_operation("get_stale_vendor_held_browser_sessions")
+ async def get_stale_vendor_held_browser_sessions(
+ self,
+ *,
+ stale_before: datetime,
+ limit: int,
+ ) -> list[PersistentBrowserSession]:
+ """Vendor-held rows whose proxy lease has aged past ``stale_before``, oldest first.
+
+ The lease is ``last_activity_at`` — the proxy restamps it while it relays client commands,
+ so it ages by itself the moment the owning process stops, whether that was graceful or a
+ SIGKILL. ``started_at`` covers a session that died before its first relayed command. When
+ both are NULL the COALESCE comparison is NULL and the row is excluded: a row that cannot be
+ dated is never reaped.
+ """
+ async with self.Session() as session:
+ lease_at = func.coalesce(
+ PersistentBrowserSessionModel.last_activity_at,
+ PersistentBrowserSessionModel.started_at,
+ )
+ query = (
+ select(PersistentBrowserSessionModel)
+ .filter(_VENDOR_HELD)
+ .filter_by(deleted_at=None, completed_at=None)
+ .filter(PersistentBrowserSessionModel.status.not_in(FINAL_STATUSES))
+ .filter(lease_at < stale_before)
+ .order_by(lease_at)
+ .limit(limit)
+ )
+ rows = (await session.scalars(query)).all()
+ return [PersistentBrowserSession.model_validate(row) for row in rows]
+
@db_operation("get_persistent_browser_session_unscoped")
async def get_persistent_browser_session_unscoped(self, session_id: str) -> PersistentBrowserSession | None:
"""Primary-key read without organization scoping, for trusted internal session
diff --git a/skyvern/forge/sdk/schemas/persistent_browser_sessions.py b/skyvern/forge/sdk/schemas/persistent_browser_sessions.py
index b549f451d..58543b007 100644
--- a/skyvern/forge/sdk/schemas/persistent_browser_sessions.py
+++ b/skyvern/forge/sdk/schemas/persistent_browser_sessions.py
@@ -77,6 +77,10 @@ class PersistentBrowserSession(BaseModel):
# BrowserSessionResponse.from_browser_session is the allowlist that enforces the former.
upstream_cdp_url: str | None = None
browser_vendor: str | None = None
+ # The upstream provider's own id for this browser. Server-side only, under the same allowlist
+ # as the two fields above. It is the sole handle for terminating a session out of band, so the
+ # orphan reaper reads it off the row after the process that created the session is gone.
+ browser_id: str | None = None
status: str | None = None
timeout_minutes: int | None = None
proxy_location: ProxyLocationInput = None
diff --git a/tests/unit/webeye/test_browser_session_response.py b/tests/unit/webeye/test_browser_session_response.py
index 7bcd36b21..6deff8a26 100644
--- a/tests/unit/webeye/test_browser_session_response.py
+++ b/tests/unit/webeye/test_browser_session_response.py
@@ -42,6 +42,7 @@ async def test_browser_session_response_never_exposes_upstream_routing_fields()
browser_address="wss://proxy.example/pbs_123/token/devtools/browser/test",
upstream_cdp_url="ws://10.0.0.7:9222/devtools/browser/test",
browser_vendor="websocket",
+ browser_id="upstream-session-cafebabe",
created_at=now,
modified_at=now,
)
@@ -54,7 +55,7 @@ async def test_browser_session_response_never_exposes_upstream_routing_fields()
response = await BrowserSessionResponse.from_browser_session(session)
serialized = response.model_dump_json()
- for leaked in ("10.0.0.7", "upstream_cdp_url", "browser_vendor"):
+ for leaked in ("10.0.0.7", "upstream_cdp_url", "browser_vendor", "browser_id", "upstream-session-cafebabe"):
assert leaked not in serialized
assert response.browser_address == "wss://proxy.example/pbs_123/token/devtools/browser/test"