Skip to content

Automate browser based workflows with AI

feat(SKY-9328): copilot V2 reuses live debug browser session (backend) (#5709)

Andrew Neilson8dfaea6bdb24
diff --git a/skyvern/forge/sdk/copilot/agent.py b/skyvern/forge/sdk/copilot/agent.py
index d70febfd0..2dc7f069f 100644
--- a/skyvern/forge/sdk/copilot/agent.py
+++ b/skyvern/forge/sdk/copilot/agent.py
@@ -22,11 +22,13 @@ import structlog
import yaml
from pydantic import ValidationError
+from skyvern.forge import app
from skyvern.forge.prompts import prompt_engine
from skyvern.forge.sdk.copilot.block_goal_wrapping import wrap_block_goals
from skyvern.forge.sdk.copilot.context import AgentResult, CopilotContext, StructuredContext
from skyvern.forge.sdk.copilot.output_utils import extract_final_text, parse_final_response
from skyvern.forge.sdk.copilot.tracing_setup import _copilot_model_name, ensure_tracing_initialized, is_tracing_enabled
+from skyvern.forge.sdk.schemas.persistent_browser_sessions import is_final_status
from skyvern.forge.sdk.schemas.workflow_copilot import (
WorkflowCopilotChatHistoryMessage,
)
@@ -42,6 +44,69 @@ WORKFLOW_KNOWLEDGE_BASE_PATH = (
MAX_TURNS = 25
+async def _resolve_live_browser_session_id(
+ chat_request: WorkflowCopilotChatRequest,
+ organization_id: str,
+) -> str | None:
+ """Validate against a debug session for the same (org, workflow_permanent_id);
+ return None on any failure so the caller falls back to auto-create."""
+ requested = chat_request.browser_session_id
+ if not requested:
+ return None
+
+ try:
+ debug_session = await app.DATABASE.debug.get_debug_session_by_browser_session_id(
+ browser_session_id=requested,
+ organization_id=organization_id,
+ )
+ if debug_session is None:
+ LOG.warning(
+ "Copilot received an unknown browser_session_id; ignoring",
+ organization_id=organization_id,
+ requested_session_id=requested,
+ )
+ return None
+ if debug_session.workflow_permanent_id != chat_request.workflow_permanent_id:
+ LOG.warning(
+ "Copilot browser_session_id is bound to a different workflow; ignoring",
+ organization_id=organization_id,
+ requested_session_id=requested,
+ expected_wpid=chat_request.workflow_permanent_id,
+ actual_wpid=debug_session.workflow_permanent_id,
+ )
+ return None
+
+ # Trust the DB row over a CDP probe here — get_browser_state opens a
+ # fresh Playwright connection. ensure_browser_session does the
+ # attachability probe right before use so stale rows still recover.
+ persistent = await app.PERSISTENT_SESSIONS_MANAGER.get_session(requested, organization_id)
+ if persistent is None or is_final_status(persistent.status) or not persistent.browser_address:
+ LOG.warning(
+ "Copilot live browser session is not yet usable; falling back to auto-create",
+ organization_id=organization_id,
+ requested_session_id=requested,
+ status=persistent.status if persistent else None,
+ has_browser_address=bool(persistent.browser_address) if persistent else False,
+ )
+ return None
+
+ LOG.info(
+ "Copilot reusing live browser session",
+ organization_id=organization_id,
+ session_id=requested,
+ )
+ return requested
+ except Exception as exc:
+ LOG.warning(
+ "Copilot live-session validation raised; falling back to auto-create",
+ organization_id=organization_id,
+ requested_session_id=requested,
+ error_type=type(exc).__name__,
+ exc_info=True,
+ )
+ return None
+
+
def _format_chat_history(chat_history: list[WorkflowCopilotChatHistoryMessage]) -> str:
if not chat_history:
return ""
@@ -386,12 +451,14 @@ async def run_copilot_agent(
get_skyvern_mcp_alias_map,
)
+ validated_browser_session_id = await _resolve_live_browser_session_id(chat_request, organization_id)
+
ctx = CopilotContext(
organization_id=organization_id,
workflow_id=chat_request.workflow_id,
workflow_permanent_id=chat_request.workflow_permanent_id,
workflow_yaml=chat_request.workflow_yaml or "",
- browser_session_id=None,
+ browser_session_id=validated_browser_session_id,
stream=stream,
api_key=api_key,
user_message=chat_request.message,
diff --git a/skyvern/forge/sdk/copilot/runtime.py b/skyvern/forge/sdk/copilot/runtime.py
index 9a527c012..3c5e03a95 100644
--- a/skyvern/forge/sdk/copilot/runtime.py
+++ b/skyvern/forge/sdk/copilot/runtime.py
@@ -186,7 +186,29 @@ async def mcp_browser_context(ctx: AgentContext) -> AsyncIterator[None]:
async def ensure_browser_session(ctx: AgentContext) -> dict[str, Any] | None:
"""Create a browser session if needed. Returns None on success, error dict on failure."""
if ctx.browser_session_id:
- return None
+ # Probe attachability — a stale DB row demotes to auto-create here
+ # instead of bubbling up as a "No browser context" tool failure.
+ try:
+ state = await app.PERSISTENT_SESSIONS_MANAGER.get_browser_state(
+ session_id=ctx.browser_session_id,
+ organization_id=ctx.organization_id,
+ )
+ if state and state.browser_context:
+ return None
+ LOG.warning(
+ "Supplied browser_session_id is no longer attachable; auto-creating",
+ session_id=ctx.browser_session_id,
+ organization_id=ctx.organization_id,
+ )
+ except Exception as exc:
+ LOG.warning(
+ "Browser state probe raised for supplied session; auto-creating",
+ session_id=ctx.browser_session_id,
+ organization_id=ctx.organization_id,
+ error_type=type(exc).__name__,
+ exc_info=True,
+ )
+ ctx.browser_session_id = None
session = None
try:
diff --git a/skyvern/forge/sdk/schemas/workflow_copilot.py b/skyvern/forge/sdk/schemas/workflow_copilot.py
index 4c7c5cd94..e130655d5 100644
--- a/skyvern/forge/sdk/schemas/workflow_copilot.py
+++ b/skyvern/forge/sdk/schemas/workflow_copilot.py
@@ -40,6 +40,10 @@ class WorkflowCopilotChatRequest(BaseModel):
workflow_id: str = Field(..., description="Workflow ID (mutable version ID)")
workflow_copilot_chat_id: str | None = Field(None, description="The chat ID to send the message to")
workflow_run_id: str | None = Field(None, description="The workflow run ID to use for the context")
+ browser_session_id: str | None = Field(
+ None,
+ description="Optional persistent browser session ID to reuse instead of creating a new one.",
+ )
message: str = Field(..., description="The message that user sends")
workflow_yaml: str = Field(..., description="Current workflow YAML including unsaved changes")
cancel_token: str | None = Field(
diff --git a/tests/unit/test_copilot_live_session_helper.py b/tests/unit/test_copilot_live_session_helper.py
new file mode 100644
index 000000000..dfeb87d6b
--- /dev/null
+++ b/tests/unit/test_copilot_live_session_helper.py
@@ -0,0 +1,244 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+
+from skyvern.forge import app
+from skyvern.forge.sdk.copilot.agent import _resolve_live_browser_session_id
+from skyvern.forge.sdk.schemas.workflow_copilot import WorkflowCopilotChatRequest
+
+
+def _request(browser_session_id: str | None = None, wpid: str = "wpid-1") -> WorkflowCopilotChatRequest:
+ return WorkflowCopilotChatRequest(
+ workflow_permanent_id=wpid,
+ workflow_id="wf-1",
+ workflow_copilot_chat_id="chat-1",
+ workflow_run_id=None,
+ browser_session_id=browser_session_id,
+ message="hi",
+ workflow_yaml="title: x",
+ )
+
+
+def _running_session(browser_address: str = "wss://example/cdp") -> SimpleNamespace:
+ return SimpleNamespace(status="running", browser_address=browser_address)
+
+
+async def test_no_id_returns_none_and_does_not_call_db(monkeypatch: pytest.MonkeyPatch) -> None:
+ debug_mock = AsyncMock(side_effect=AssertionError("DB must not be touched when no id is supplied"))
+ monkeypatch.setattr(
+ app.DATABASE,
+ "debug",
+ SimpleNamespace(get_debug_session_by_browser_session_id=debug_mock),
+ )
+
+ result = await _resolve_live_browser_session_id(_request(browser_session_id=None), organization_id="org-1")
+
+ assert result is None
+ debug_mock.assert_not_awaited()
+
+
+async def test_unknown_id_falls_back(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr(
+ app.DATABASE,
+ "debug",
+ SimpleNamespace(get_debug_session_by_browser_session_id=AsyncMock(return_value=None)),
+ )
+
+ result = await _resolve_live_browser_session_id(_request(browser_session_id="pbs_unknown"), organization_id="org-1")
+
+ assert result is None
+
+
+async def test_wrong_workflow_falls_back(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr(
+ app.DATABASE,
+ "debug",
+ SimpleNamespace(
+ get_debug_session_by_browser_session_id=AsyncMock(
+ return_value=SimpleNamespace(workflow_permanent_id="wpid-other"),
+ ),
+ ),
+ )
+
+ result = await _resolve_live_browser_session_id(
+ _request(browser_session_id="pbs_foreign", wpid="wpid-1"),
+ organization_id="org-1",
+ )
+
+ assert result is None
+
+
+async def test_persistent_row_missing_falls_back(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr(
+ app.DATABASE,
+ "debug",
+ SimpleNamespace(
+ get_debug_session_by_browser_session_id=AsyncMock(
+ return_value=SimpleNamespace(workflow_permanent_id="wpid-1"),
+ ),
+ ),
+ )
+ monkeypatch.setattr(
+ app,
+ "PERSISTENT_SESSIONS_MANAGER",
+ SimpleNamespace(get_session=AsyncMock(return_value=None)),
+ )
+
+ result = await _resolve_live_browser_session_id(
+ _request(browser_session_id="pbs_unknown_persistent", wpid="wpid-1"),
+ organization_id="org-1",
+ )
+
+ assert result is None
+
+
+async def test_status_in_final_state_falls_back(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr(
+ app.DATABASE,
+ "debug",
+ SimpleNamespace(
+ get_debug_session_by_browser_session_id=AsyncMock(
+ return_value=SimpleNamespace(workflow_permanent_id="wpid-1"),
+ ),
+ ),
+ )
+ monkeypatch.setattr(
+ app,
+ "PERSISTENT_SESSIONS_MANAGER",
+ SimpleNamespace(
+ get_session=AsyncMock(
+ return_value=SimpleNamespace(status="completed", browser_address="wss://example/cdp"),
+ ),
+ ),
+ )
+
+ result = await _resolve_live_browser_session_id(
+ _request(browser_session_id="pbs_done", wpid="wpid-1"),
+ organization_id="org-1",
+ )
+
+ assert result is None
+
+
+async def test_browser_address_unset_falls_back(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr(
+ app.DATABASE,
+ "debug",
+ SimpleNamespace(
+ get_debug_session_by_browser_session_id=AsyncMock(
+ return_value=SimpleNamespace(workflow_permanent_id="wpid-1"),
+ ),
+ ),
+ )
+ monkeypatch.setattr(
+ app,
+ "PERSISTENT_SESSIONS_MANAGER",
+ SimpleNamespace(
+ get_session=AsyncMock(
+ return_value=SimpleNamespace(status="running", browser_address=None),
+ ),
+ ),
+ )
+
+ result = await _resolve_live_browser_session_id(
+ _request(browser_session_id="pbs_booting", wpid="wpid-1"),
+ organization_id="org-1",
+ )
+
+ assert result is None
+
+
+async def test_owned_and_running_returns_id(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr(
+ app.DATABASE,
+ "debug",
+ SimpleNamespace(
+ get_debug_session_by_browser_session_id=AsyncMock(
+ return_value=SimpleNamespace(workflow_permanent_id="wpid-1"),
+ ),
+ ),
+ )
+ monkeypatch.setattr(
+ app,
+ "PERSISTENT_SESSIONS_MANAGER",
+ SimpleNamespace(get_session=AsyncMock(return_value=_running_session())),
+ )
+
+ result = await _resolve_live_browser_session_id(
+ _request(browser_session_id="pbs_live", wpid="wpid-1"),
+ organization_id="org-1",
+ )
+
+ assert result == "pbs_live"
+
+
+async def test_db_exception_falls_back(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr(
+ app.DATABASE,
+ "debug",
+ SimpleNamespace(
+ get_debug_session_by_browser_session_id=AsyncMock(side_effect=RuntimeError("transient DB error")),
+ ),
+ )
+
+ result = await _resolve_live_browser_session_id(_request(browser_session_id="pbs_x"), organization_id="org-1")
+
+ assert result is None
+
+
+async def test_ensure_browser_session_recovers_from_stale_supplied_id(monkeypatch: pytest.MonkeyPatch) -> None:
+ """If `_resolve_live_browser_session_id` returns an id whose DB row is
+ healthy but whose chromium has died, `ensure_browser_session` must
+ auto-create a fresh session rather than short-circuit and let
+ `mcp_browser_context` raise on the first browser tool call."""
+ from skyvern.forge.sdk.copilot import runtime as runtime_module
+ from skyvern.forge.sdk.copilot.context import CopilotContext
+
+ monkeypatch.setattr(runtime_module, "_BROWSER_BOOT_WAIT_SECONDS", 0.1)
+ monkeypatch.setattr(runtime_module, "_BROWSER_BOOT_POLL_INTERVAL_SECONDS", 0.02)
+
+ # First get_browser_state returns a stale row (no browser_context).
+ # After auto-create, the second call returns a healthy state so the
+ # post-create boot wait can complete.
+ fresh_state = SimpleNamespace(browser_context=object())
+ get_browser_state_mock = AsyncMock(side_effect=[SimpleNamespace(browser_context=None), fresh_state])
+ create_session_mock = AsyncMock(return_value=SimpleNamespace(persistent_browser_session_id="pbs_fresh"))
+
+ monkeypatch.setattr(
+ app,
+ "PERSISTENT_SESSIONS_MANAGER",
+ SimpleNamespace(
+ get_browser_state=get_browser_state_mock,
+ create_session=create_session_mock,
+ ),
+ )
+
+ ctx = CopilotContext(
+ organization_id="org-1",
+ workflow_id="wf-1",
+ workflow_permanent_id="wpid-1",
+ workflow_yaml="",
+ browser_session_id="pbs_stale",
+ stream=SimpleNamespace(),
+ api_key="sk-test",
+ user_message="",
+ workflow_copilot_chat_id="chat-1",
+ )
+
+ result = await runtime_module.ensure_browser_session(ctx)
+
+ assert result is None
+ assert ctx.browser_session_id == "pbs_fresh"
+ create_session_mock.assert_awaited_once()