portacode 2.2.20.dev6__tar.gz → 2.2.20.dev7__tar.gz

{portacode-2.2.20.dev6 → portacode-2.2.20.dev7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: portacode
-Version: 2.2.20.dev6
+Version: 2.2.20.dev7
 Summary: Device agent for the AI platform that builds, tests, deploys, and operates real software
 Home-page: https://portacode.com/
 Author: Meena Erian

{portacode-2.2.20.dev6 → portacode-2.2.20.dev7}/portacode/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.2.20.dev6'
-__version_tuple__ = version_tuple = (2, 2, 20, 'dev6')
+__version__ = version = '2.2.20.dev7'
+__version_tuple__ = version_tuple = (2, 2, 20, 'dev7')
 
 __commit_id__ = commit_id = None

{portacode-2.2.20.dev6 → portacode-2.2.20.dev7}/portacode/connection/handlers/README.md

@@ -43,6 +43,18 @@ The handler system consists of:
    - Provides system resource information
    - Returns CPU, memory, and disk usage data
 
+### Browser Handlers (`browser_handlers.py`)
+
+1. **`BrowserConfigHandler`** - `browser_config`
+   - Reads or atomically persists runtime-user browser viewport and recording dimensions
+   - Returns `browser_config_response`; the same effective values appear in `system_info.info.browser_config`
+
+2. **`BrowserRunHandler`** - `browser_run`
+   - Runs up to 30 Playwright navigation, interaction, assertion, read, bounded DOM, and screenshot steps in a named persistent profile
+   - Applies saved dimensions unless the request supplies per-run overrides and returns `browser_run_response`
+   - Returns screenshots inline, a device-side `video_path` for recordings, and uses the standard chunk framing for large responses
+   - Adds polished cursor, pacing, focus, ripple, typing, and desktop zoom effects only while recording video; non-recorded automation stays fast
+
 ## Adding New Handlers
 
 ### 1. Asynchronous Handlers

{portacode-2.2.20.dev6 → portacode-2.2.20.dev7}/portacode/connection/handlers/WEBSOCKET_PROTOCOL.md

@@ -119,6 +119,8 @@ This document describes the complete protocol for communicating with devices thr
     - [`terminal_exec`](#terminal_exec)
   - [System Actions](#system-actions)
     - [`system_info`](#system_info)
+    - [`browser_config`](#browser_config)
+    - [`browser_run`](#browser_run)
     - [`update_portacode_cli`](#update_portacode_cli)
     - [`clock_sync_request`](#clock_sync_request)
   - [File Actions](#file-actions)
@@ -171,6 +173,8 @@ This document describes the complete protocol for communicating with devices thr
     - [`terminal_list`](#terminal_list-event)
   - [System Events](#system-events)
     - [`system_info`](#system_info-event)
+    - [`browser_config_response`](#browser_config_response)
+    - [`browser_run_response`](#browser_run_response)
     - [`update_portacode_response`](#update_portacode_response)
     - [`clock_sync_response`](#clock_sync_response)
   - [File Events](#file-events)
@@ -429,6 +433,96 @@ This action does not require any payload fields.
 
 *   On success, the device will respond with a [`system_info`](#system_info-event) event.
 
+### `browser_config`
+
+Reads or atomically updates the runtime user's persistent browser dimensions.
+Handled by [`BrowserConfigHandler`](./browser_handlers.py). Omitting `config`
+performs a read without changing the saved values.
+
+**Payload Fields:**
+
+*   `config` (object, optional): Sections to merge into the saved configuration.
+    *   `viewport` (object, optional): `width` and/or `height` for browser pages.
+    *   `video` (object, optional): `width` and/or `height` for recordings.
+*   Every supplied dimension must be an integer from 240 through 1920. Unknown
+    sections and fields are rejected.
+
+**Responses:**
+
+*   On success, the device responds with
+    [`browser_config_response`](#browser_config_response).
+*   The resulting configuration is also reported at
+    `system_info.info.browser_config` and becomes the default for later runs.
+
+Example read:
+
+```json
+{"cmd":"browser_config"}
+```
+
+Example update:
+
+```json
+{
+  "cmd": "browser_config",
+  "config": {
+    "viewport": {"width": 390, "height": 844},
+    "video": {"width": 390, "height": 844}
+  }
+}
+```
+
+### `browser_run`
+
+Runs a bounded Playwright batch in a persistent, runtime-user-scoped Chromium
+profile. Handled by [`BrowserRunHandler`](./browser_handlers.py). A safe logical
+`session_id` preserves cookies and local storage between calls.
+
+**Payload Fields:**
+
+*   `session_id` (string, optional): Profile name containing only letters,
+    numbers, dot, dash, or underscore; defaults to `default`.
+*   `start_url` (string, optional): Initial page to load.
+*   `steps` (array, optional): At most 30 ordered operations: `goto`, `click`,
+    `fill`, `press`, `select`, `check`, `uncheck`, `wait`, `assert`, `read`,
+    `dom`, or `screenshot`. Locators support CSS (`css` or `selector`) and the
+    semantic `role`/`name`, `label`, `text`, and `testid` forms, with optional
+    `nth`. A `dom` step returns bounded `outerHTML` for `selector` (or `body`),
+    with `max_chars` clamped to 200–20000.
+*   `timeout_ms` (integer, optional): Per-operation timeout, clamped to
+    250–30000 milliseconds.
+*   `viewport` (object, optional): Per-run `width`/`height` override. Missing
+    fields retain the saved viewport values; dimensions must be 240–1920.
+*   `video` (object, optional): Per-run recording-size override with the same
+    merge and dimension rules. It does not enable recording by itself.
+*   `record_video` (boolean, optional): Record the run and return its device-side
+    path. Recorded runs have a 180-second action deadline.
+*   `final_screenshot` (boolean, optional): Capture the final viewport; defaults
+    to true.
+*   `screenshot_on_failure` (boolean, optional): Capture the viewport at a failed
+    step; defaults to true.
+*   `image_quality` (integer, optional): JPEG quality, clamped to 30–85.
+
+Saved `browser_config` values are applied first and per-run `viewport`/`video`
+fields override them. Screenshots use the active viewport; a `full_page`
+screenshot may be taller than it. Recordings always keep the configured video
+frame size and aspect ratio.
+
+When video recording is enabled, the device automatically adds presentation
+pacing: a virtual cursor, smooth movement and scrolling, target highlighting,
+click ripples, human-paced non-password typing, pauses, and desktop zoom. This
+layer is intentionally disabled for non-recorded automation, so screenshots,
+DOM inspection, reads, assertions, and ordinary browser use remain fast.
+
+**Responses:**
+
+*   The device responds with
+    [`browser_run_response`](#browser_run_response), including failures that
+    have a useful failure screenshot.
+*   Large responses use the standard chunk envelope with `browser_chunked=true`;
+    concatenate `chunk_content` in chunk order and parse the resulting JSON as
+    the ordinary response.
+
 ### `setup_proxmox_infra`
 
 Configures a Proxmox node for Portacode infrastructure usage (API token validation, automatic storage/template detection, bridge/NAT setup, and connectivity verification). Handled by [`ConfigureProxmoxInfraHandler`](./proxmox_infra.py).
@@ -1419,6 +1513,9 @@ Provides system information in response to a `system_info` action. Handled by [`
                 *   `available` (boolean): True when Playwright knows an executable path.
                 *   `executable_path` (string|null): Absolute path to the browser binary when known.
         *   `error` (string|null): Any warning message captured while probing Playwright.
+    *   `browser_config` (object): Persistent defaults used by browser automation:
+        *   `viewport` (object): Browser page `width` and `height` in pixels.
+        *   `video` (object): Recorded video `width` and `height` in pixels.
     *   `proxmox` (object): Detection hints for Proxmox VE nodes:
         *   `is_proxmox_node` (boolean): True when Proxmox artifacts (e.g., `/etc/proxmox-release`) exist.
         *   `version` (string|null): Raw contents of `/etc/proxmox-release` when readable.
@@ -2141,23 +2238,37 @@ Confirms the result of a git commit operation.
 *   `error` (string, optional): Error message if the operation failed.
 *   `commit_hash` (string, optional): The SHA hash of the new commit if successful.
 
-### Client Session Events
+### <a name="browser_config_response"></a>`browser_config_response`
 
-### `browser_run`
+Returns the complete effective configuration after a `browser_config` read or
+update.
+
+*   `config` (object): `viewport` and `video` objects, each containing integer
+    `width` and `height` values.
+
+### <a name="browser_run_response"></a>`browser_run_response`
 
-Runs a bounded Playwright action batch in a persistent, runtime-user-scoped
-Chromium profile. `session_id` is a safe logical name, never a filesystem path.
-The handler accepts at most 30 `steps`; supported operations are `goto`,
-`click`, `fill`, `press`, `select`, `check`, `uncheck`, `wait`, `assert`, and
-`screenshot`. Selectors may use CSS or the semantic `role`/`name`, `label`,
-`text`, and `testid` forms. Optional recording is stored below the runtime
-user's Portacode browser data directory and returned as `video_path`; recording
-bytes are not placed on the control channel.
-
-The `browser_run_response` contains compact per-step outcomes, final URL/title,
-bounded JPEG screenshots encoded as base64, and an optional absolute recording
-path. `success` describes protocol execution while `ok` describes whether all
-browser steps passed, allowing a failure screenshot to reach the caller.
+Returns the browser batch result.
+
+*   `success` (boolean): True only when every browser step passed.
+*   `ok` (boolean): Playwright batch result; currently equivalent to `success`.
+*   `session_id` (string): Profile used for the run.
+*   `steps` (array): Compact outcomes with step index `i`, `op`, `ok`, and an
+    optional returned `value` or bounded `error`.
+*   `url` and `title` (string, success only): Final page identity.
+*   `screenshots` (array): JPEG captures with `step`, base64 `data`,
+    `mime_type`, and optional `failure=true`.
+*   `video_path` (string, recorded runs): Absolute path on the device. Video
+    bytes are not sent over the control channel.
+*   `error` (string, failed runs): Bounded failure detail. A failed run remains
+    a normal `browser_run_response` with `success=false`, preserving completed
+    step results and any failure screenshot.
+
+For chunked responses, each envelope also contains `browser_chunked=true`, a
+shared `transfer_id`, chunk metadata, and `chunk_content` holding a slice of the
+serialized complete response.
+
+### Client Session Events
 
 ### <a name="request_client_sessions"></a>`request_client_sessions`
 

{portacode-2.2.20.dev6 → portacode-2.2.20.dev7}/portacode/connection/handlers/browser_handlers.py

@@ -490,6 +490,24 @@ class BrowserRunHandler(AsyncHandler):
         if playwright_js := _playwright_js_package():
             env["PORTACODE_PLAYWRIGHT_JS"] = playwright_js
         argv = wrap_argv_for_user([_node_executable(), "-e", _RUNNER], user, login=False)
+        existing_worker = _WORKERS.get((user, session_id))
+        session_is_live = bool(
+            existing_worker
+            and (existing_worker.process is None or existing_worker.process.returncode is None)
+        )
+        if not message.get("start_url") and not session_is_live:
+            return {
+                "event": "browser_run_response",
+                "success": False,
+                "ok": False,
+                "session_id": session_id,
+                "error": (
+                    f"Browser session {session_id!r} is not active. "
+                    "Provide start_url to create or restore it."
+                ),
+                "screenshots": [],
+                "steps": [],
+            }
         worker = await _worker_for(
             user=user, session_id=session_id, argv=argv, env=env,
         )

{portacode-2.2.20.dev6 → portacode-2.2.20.dev7}/portacode/connection/handlers/test_browser_handlers.py

@@ -95,7 +95,7 @@ class BrowserRunHandlerTests(unittest.IsolatedAsyncioTestCase):
     async def test_reuses_worker_for_same_runtime_user_and_session(self):
         worker = AsyncMock()
         worker.run.return_value = {"ok": True, "steps": [], "screenshots": []}
-        message = {"session_id": "safe", "steps": [], "final_screenshot": False}
+        message = {"session_id": "safe", "start_url": "about:blank", "steps": [], "final_screenshot": False}
         with (
             patch.object(browser_handlers, "get_default_runtime_user", return_value="tester"),
             patch.object(browser_handlers, "get_runtime_user_home", return_value="/tmp"),
@@ -138,11 +138,27 @@ class BrowserRunHandlerTests(unittest.IsolatedAsyncioTestCase):
             patch.object(browser_handlers, "_worker_for", AsyncMock(return_value=worker)),
         ):
             result = await self.handler.execute(
-                {"session_id": "failure", "steps": [], "final_screenshot": False}
+                {"session_id": "failure", "start_url": "about:blank", "steps": [], "final_screenshot": False}
             )
         self.assertFalse(result["success"])
         self.assertEqual(result["error"], "expected text")
 
+    async def test_missing_session_requires_start_url(self):
+        browser_handlers._WORKERS.clear()
+        with (
+            patch.object(browser_handlers, "get_default_runtime_user", return_value="tester"),
+            patch.object(browser_handlers, "get_runtime_user_home", return_value="/tmp"),
+            patch.object(browser_handlers, "mkdir_with_owner"),
+            patch.object(browser_handlers, "wrap_argv_for_user", return_value=["node"]),
+            patch.object(browser_handlers, "_node_path", AsyncMock(return_value="/modules")),
+            patch.object(browser_handlers, "_node_executable", return_value="/bundled/node"),
+            patch.object(browser_handlers, "_playwright_js_package", return_value=None),
+        ):
+            result = await self.handler.execute({"session_id": "lost", "steps": []})
+        self.assertFalse(result["success"])
+        self.assertIn("Provide start_url", result["error"])
+        self.assertEqual(result["screenshots"], [])
+
     async def test_worker_registry_separates_users_and_sessions(self):
         browser_handlers._WORKERS.clear()
         first = await browser_handlers._worker_for(
@@ -240,8 +256,8 @@ class BrowserRunHandlerTests(unittest.IsolatedAsyncioTestCase):
             patch.object(browser_handlers, "_playwright_js_package", return_value=None),
             patch.object(browser_handlers, "_worker_for", AsyncMock(return_value=worker)),
         ):
-            await self.handler.execute({"session_id":"fast","steps":[],"record_video":False})
-            await self.handler.execute({"session_id":"demo","steps":[],"record_video":True})
+            await self.handler.execute({"session_id":"fast","start_url":"about:blank","steps":[],"record_video":False})
+            await self.handler.execute({"session_id":"demo","start_url":"about:blank","steps":[],"record_video":True})
         self.assertFalse(worker.run.await_args_list[0].args[0]["demo"])
         self.assertTrue(worker.run.await_args_list[1].args[0]["demo"])
 
@@ -267,6 +283,7 @@ class BrowserRunHandlerTests(unittest.IsolatedAsyncioTestCase):
             })
             await self.handler.execute({
                 "session_id": "mobile", "steps": [], "record_video": True,
+                "start_url": "about:blank",
                 "final_screenshot": False,
             })
             saved = json.loads(
@@ -294,6 +311,7 @@ class BrowserRunHandlerTests(unittest.IsolatedAsyncioTestCase):
         ):
             await self.handler.execute({
                 "session_id": "override", "steps": [], "record_video": True,
+                "start_url": "about:blank",
                 "viewport": {"width": 430}, "video": {"height": 932},
             })
         run_config = worker.run.await_args.args[0]

{portacode-2.2.20.dev6 → portacode-2.2.20.dev7}/portacode.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: portacode
-Version: 2.2.20.dev6
+Version: 2.2.20.dev7
 Summary: Device agent for the AI platform that builds, tests, deploys, and operates real software
 Home-page: https://portacode.com/
 Author: Meena Erian