feat: agent takeover, batches

sdk/python/src/donutbrowser/client.py

@@ -1336,6 +1336,9 @@ class RunSession:
         self.remote_debugging_port: Optional[int] = None
         #: Whether the browser actually started headless.
         self.headless: Optional[bool] = None
+        #: Whether a running browser was taken over; the block then leaves it
+        #: open.
+        self.attached: bool = False
         #: A failure while stopping the browser, kept rather than raised when
         #: the block itself was already failing.
         self.cleanup_error: Optional[DonutError] = None
@@ -1358,6 +1361,7 @@ class RunSession:
         self.response = response
         self.remote_debugging_port = response["remote_debugging_port"]
         self.headless = response["headless"]
+        self.attached = bool(response.get("attached", False))
         return self
 
     def __exit__(
@@ -1366,6 +1370,9 @@ class RunSession:
         exc: Optional[BaseException],
         traceback: Optional[TracebackType],
     ) -> bool:
+        if self.attached:
+            # The person had this browser open; it was taken over, not started.
+            return False
         try:
             self.client.kill_profile(self.profile_id)
         except DonutError as failure:

sdk/python/src/donutbrowser/models.py

@@ -315,12 +315,18 @@ class DownloadBrowserResponse(TypedDict):
     status: str
 
 
-class RunProfileResponse(TypedDict):
+class _RunProfileResponseRequired(TypedDict):
     profile_id: str
     remote_debugging_port: int
     headless: bool
 
 
+class RunProfileResponse(_RunProfileResponseRequired, total=False):
+    #: True when the profile was already running and was taken over as it is,
+    #: with no restart. Older apps omit it.
+    attached: bool
+
+
 class RunRemoteResponse(TypedDict):
     profile_id: str
     session_id: str

sdk/python/tests/test_session.py

@@ -90,3 +90,14 @@ def test_the_cdp_url_is_refused_before_the_block(client: DonutClient) -> None:
     session = client.run("p1")
     with pytest.raises(DonutError):
         _ = session.cdp_url
+
+
+def test_a_browser_taken_over_is_left_running(client: DonutClient, fake: FakeDonut) -> None:
+    fake.enqueue_json({**RUN_BODY, "attached": True})
+
+    with client.run("p1") as session:
+        assert session.attached is True
+
+    assert [(sent.method, sent.path) for sent in fake.requests] == [
+        ("POST", "/v1/profiles/p1/run"),
+    ]