feat: expose a public failure and retry contract for browser-action errors (#232)

Skyvern-AI/rustwright-cloud#221

---------

Co-authored-by: suchintan <3853670+suchintan@users.noreply.github.com>

Author: suchintan

CHANGELOG.md

@@ -7,6 +7,7 @@ All notable user-facing changes to Rustwright are documented in this file.
 ### Changed
 
 - Verified support for standard CPython 3.9 through 3.14 and CPython 3.15.0rc1. Python 3.15 support remains pre-release, and CI tracks 3.15-dev until GA.
+- Added a public failure and retry contract for browser actions. Rust, Python, and MCP callers can inspect the failure phase, target kind, command-write status, and retry safety. A tracked input command with unknown delivery now raises `UnknownOutcomeError` in Python and is never reported as safe to retry. Other bindings keep their existing error types and receive a clear diagnostic message.
 
 ## [0.2.0] - 2026-08-03
 

bindings/CONTRACT.md

@@ -103,6 +103,8 @@ the same OS thread and copy the borrowed UTF-8 message into language-owned
 memory. It is NULL when no error is recorded and is valid only until the next
 Rustwright ABI call on that thread. Never free it.
 
+`rw_last_error()` is diagnostic prose, not a machine-readable taxonomy; bindings must not parse it to decide whether to retry.
+
 `rw_browser_ws_endpoint` and `rw_page_target_id` return NULL on failure and set
 the same last-error slot. All ABI entry points catch Rust panics; no unwind is
 allowed to cross the C boundary.

docs/PARITY.md

@@ -731,8 +731,8 @@ The package-root inventory below comes from `rustwright.__all__`; sync and async
 
 | Module | Matching Playwright exports | Playwright exports | Missing | Rustwright-only/extra |
 | --- | ---: | ---: | ---: | ---: |
-| `sync_api` | 50 | 55 | 5 | 8 |
-| `async_api` | 51 | 55 | 4 | 8 |
+| `sync_api` | 50 | 55 | 5 | 9 |
+| `async_api` | 51 | 55 | 4 | 9 |
 
 Missing sync exports: `FormData`, `ScreencastFrame`, `ScreencastSize`, `Selectors`, `VirtualCredential`.
 
@@ -760,6 +760,7 @@ Missing async exports: `FormData`, `ScreencastFrame`, `ScreencastSize`, `Virtual
 | `Response` | yes | yes |
 | `TargetClosedError` | no | no |
 | `TimeoutError` | yes | yes |
+| `UnknownOutcomeError` | yes | yes |
 | `Video` | yes | yes |
 | `async_playwright` | no | yes |
 | `backend_marker` | yes | yes |
@@ -776,6 +777,7 @@ Missing async exports: `FormData`, `ScreencastFrame`, `ScreencastSize`, `Virtual
 - OOPIF support is new. Cross-origin frame locator actions work in covered cases, but non-main-frame remote `JSHandle` follow-up operations remain a gap, and drag, screenshot, and bounding-box behavior in OOPIFs is not yet claimed as full parity.
 - Anti-bot and stealth behavior is partial. Rustwright suppresses some common automation signals, but recent public fingerprint checks were only clean on about 2 of 4 targets. Rustwright does not promise undetectability.
 - Drop-in compatibility import names are intended to be opt-in for the public alpha. The final compatibility-mode API is being finalized separately.
+- `UnknownOutcomeError` is a Rustwright safety extension. Compatibility shims intentionally do not export it.
 - The implementation still has large monolithic files. A module split is planned before beta.
 
 ## Node.js subset

docs/api-surface/playwright-async-api.json

@@ -1817,11 +1817,14 @@
       "StorageState",
       "StorageStateCookie",
       "TimeoutError",
+      "UnknownOutcomeError",
       "ViewportSize",
       "async_playwright",
       "expect"
     ],
-    "extra": [],
+    "extra": [
+      "UnknownOutcomeError"
+    ],
     "missing": {},
     "reference": [
       "APIResponseAssertions",
@@ -1856,7 +1859,7 @@
   },
   "reference_module": "playwright.async_api",
   "summary": {
-    "extra_members": 0,
+    "extra_members": 1,
     "missing_classes": 0,
     "missing_members": 0,
     "signature_diffs": 0,

docs/api-surface/playwright-async-api.md

@@ -4,6 +4,6 @@
 - Candidate: `rustwright.async_api`
 - Missing classes: `0`
 - Missing members: `0`
-- Extra members: `0`
+- Extra members: `1`
 - Unclassified missing members: `0`
 - Signature diffs: `0`

docs/api-surface/playwright-sync-api.json

@@ -1817,11 +1817,14 @@
       "StorageState",
       "StorageStateCookie",
       "TimeoutError",
+      "UnknownOutcomeError",
       "ViewportSize",
       "expect",
       "sync_playwright"
     ],
-    "extra": [],
+    "extra": [
+      "UnknownOutcomeError"
+    ],
     "missing": {},
     "reference": [
       "APIResponseAssertions",
@@ -1856,7 +1859,7 @@
   },
   "reference_module": "playwright.sync_api",
   "summary": {
-    "extra_members": 0,
+    "extra_members": 1,
     "missing_classes": 0,
     "missing_members": 0,
     "signature_diffs": 0,

docs/api-surface/playwright-sync-api.md

@@ -4,6 +4,6 @@
 - Candidate: `rustwright.sync_api`
 - Missing classes: `0`
 - Missing members: `0`
-- Extra members: `0`
+- Extra members: `1`
 - Unclassified missing members: `0`
 - Signature diffs: `0`