browser-handoff 0.1.0__tar.gz

browser_handoff-0.1.0/.gitignore

@@ -0,0 +1,220 @@
+.claude
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

browser_handoff-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 synacktra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

browser_handoff-0.1.0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: browser-handoff
+Version: 0.1.0
+Summary: Pause Playwright automation, hand the browser to a human, resume when they're done.
+Project-URL: Homepage, https://github.com/synacktraa/browser-handoff
+Project-URL: Repository, https://github.com/synacktraa/browser-handoff
+Project-URL: Issues, https://github.com/synacktraa/browser-handoff/issues
+Author-email: Harsh Verma <synacktra.work@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: automation,browser,handoff,human-in-the-loop,intervention,playwright,streaming
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.12
+Requires-Dist: fastapi>=0.115
+Requires-Dist: jinja2>=3.1
+Requires-Dist: playwright>=1.40
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: uvicorn[standard]>=0.32
+Provides-Extra: llm
+Requires-Dist: litellm>=1.0; extra == 'llm'
+Description-Content-Type: text/markdown
+
+# browser-handoff
+
+Pause your browser automation, hand the page to a human, resume when they're done.
+
+When automation hits something only a human should do — login, 2FA, OAuth consent, payment, identity check — `browser-handoff` streams the live browser to an operator over the web, waits for them to finish, then gives control back to your script.
+
+## Install
+
+```bash
+pip install browser-handoff
+```
+
+LLM-based detection (optional): `pip install browser-handoff[llm]`
+
+## 30-second example
+
+```python
+from playwright.async_api import async_playwright
+from browser_handoff import Handoff, Scenario
+from browser_handoff.detection import Detection
+
+handoff = Handoff(
+    scenarios=[
+        Scenario(
+            name="login",
+            trigger=Detection.url(path_contains=["/login"]),
+            complete=Detection.url(path_contains=["/dashboard"]),
+        ),
+    ],
+)
+
+async with async_playwright() as pw:
+    browser = await pw.chromium.launch(headless=False)
+    page = await browser.new_page()
+    await page.goto("https://example.com/start")
+
+    result = await handoff.run(page, timeout=30)
+    if result.was_blocked and not result.timed_out:
+        print(f"Human completed: {result.scenario_name}")
+
+    # Continue automation
+    await page.click("#continue")
+```
+
+## How it works
+
+A `Scenario` is a pair: a `trigger` that says "stop, a human is needed" and a `complete` that says "OK, they're done."
+
+`handoff.run(page, timeout=...)` watches the page for any scenario's trigger. If none fires within `timeout` seconds, it returns `HandoffResult(was_blocked=False)` and your script keeps going. If one fires, it starts a local streaming server, surfaces the URL (printed to logs and pushed to your notifiers), and waits until the matching `complete` condition matches — or until `server.completion_timeout` elapses, in which case the result has `timed_out=True`. `handoff.run` never raises on completion timeout; check the result.
+
+## Scope: what this is *not*
+
+`browser-handoff` is for flows gated by **credentials or session state** — login pages, 2FA prompts, OAuth consent screens, payment forms, identity verification, T&C acceptance.
+
+It is **not** an anti-bot bypass. Sites that fingerprint Playwright/CDP sessions as automation will keep refusing the flow even after a human solves a CAPTCHA, Cloudflare Turnstile, or similar challenge — the session itself is flagged, not the response. If that's your problem, you need an anti-detection browser, not a handoff tool.
+
+## Detection
+
+`Detection` is the factory for conditions:
+
+```python
+Detection.url(host_equals=["accounts.google.com"], path_contains=["/oauth"])
+Detection.element(present=["input[type=password]"], visible=[".consent-modal"], missing=[".user-menu"])
+Detection.content(title_contains=["Sign In"], body_matches=[r"verify.*you"])
+Detection.llm(model="anthropic/claude-sonnet-4-5", condition="Login form is visible")
+```
+
+Combine them:
+
+```python
+Detection.any([d1, d2])    # OR
+Detection.all([d1, d2])    # AND
+Detection.not_(d1)         # NOT
+```
+
+## Notifications
+
+Optional. Each notifier gets the stream URL when a handoff starts.
+
+```python
+from browser_handoff.notifiers import DiscordNotifier, EmailNotifier, SlackNotifier
+
+Handoff(
+    scenarios=[...],
+    notifiers=[
+        SlackNotifier(webhook_url="https://hooks.slack.com/..."),
+        DiscordNotifier(webhook_url="https://discord.com/api/webhooks/..."),
+        EmailNotifier(
+            smtp_host="smtp.gmail.com", smtp_port=587,
+            username="bot@x.com", password="...",
+            to=["ops@x.com"],
+        ),
+    ],
+)
+```
+
+## Server
+
+Defaults to `127.0.0.1:8080` (loopback only) with a 10-minute human-completion budget. Set `host="0.0.0.0"` to expose on the LAN — e.g. for phone access or tunnel forwarding.
+
+```python
+from browser_handoff import ServerConfig
+
+Handoff(
+    scenarios=[...],
+    server=ServerConfig(
+        host="127.0.0.1",                             # "0.0.0.0" to expose on LAN
+        port=8080,
+        public_base="https://my-tunnel.example.com",  # what notifiers link to
+        completion_timeout=600,                       # max human wait (s)
+        jpeg_quality=75,
+        every_nth_frame=1,
+    ),
+)
+```
+
+## Config files
+
+JSON or YAML, with `${VAR}` interpolation:
+
+<table>
+<tr><th>JSON</th><th>YAML</th></tr>
+<tr>
+<td>
+
+```json
+{
+  "scenarios": [{
+    "name": "login",
+    "trigger": {
+      "type": "any",
+      "conditions": [
+        { "type": "url",
+          "path_contains": ["/login"] },
+        { "type": "element",
+          "present": ["input[type=password]"] }
+      ]
+    },
+    "complete": {
+      "type": "not",
+      "condition": {
+        "type": "url",
+        "path_contains": ["/login"]
+      }
+    }
+  }],
+  "server": {
+    "port": 8080,
+    "public_base": "${HANDOFF_URL}"
+  },
+  "notifiers": [
+    { "type": "slack",
+      "webhook_url": "${SLACK_WEBHOOK}" }
+  ]
+}
+```
+
+</td>
+<td>
+
+```yaml
+scenarios:
+  - name: login
+    trigger:
+      type: any
+      conditions:
+        - type: url
+          path_contains: ["/login"]
+        - type: element
+          present: ["input[type=password]"]
+    complete:
+      type: not
+      condition:
+        type: url
+        path_contains: ["/login"]
+
+server:
+  port: 8080
+  public_base: ${HANDOFF_URL}
+
+notifiers:
+  - type: slack
+    webhook_url: ${SLACK_WEBHOOK}
+```
+
+</td>
+</tr>
+</table>
+
+```python
+handoff = Handoff.from_file("handoff.yaml")
+# or: Handoff.from_json(s) / Handoff.from_yaml(s) / Handoff.from_dict(d)
+```
+
+## Examples
+
+See [`examples/claude_oauth_login_handoff.py`](examples/claude_oauth_login_handoff.py) for a working Claude OAuth flow that pairs `browser-handoff` with [`ccauth`](https://github.com/synacktraa/ccauth).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

browser_handoff-0.1.0/README.md

@@ -0,0 +1,201 @@
+# browser-handoff
+
+Pause your browser automation, hand the page to a human, resume when they're done.
+
+When automation hits something only a human should do — login, 2FA, OAuth consent, payment, identity check — `browser-handoff` streams the live browser to an operator over the web, waits for them to finish, then gives control back to your script.
+
+## Install
+
+```bash
+pip install browser-handoff
+```
+
+LLM-based detection (optional): `pip install browser-handoff[llm]`
+
+## 30-second example
+
+```python
+from playwright.async_api import async_playwright
+from browser_handoff import Handoff, Scenario
+from browser_handoff.detection import Detection
+
+handoff = Handoff(
+    scenarios=[
+        Scenario(
+            name="login",
+            trigger=Detection.url(path_contains=["/login"]),
+            complete=Detection.url(path_contains=["/dashboard"]),
+        ),
+    ],
+)
+
+async with async_playwright() as pw:
+    browser = await pw.chromium.launch(headless=False)
+    page = await browser.new_page()
+    await page.goto("https://example.com/start")
+
+    result = await handoff.run(page, timeout=30)
+    if result.was_blocked and not result.timed_out:
+        print(f"Human completed: {result.scenario_name}")
+
+    # Continue automation
+    await page.click("#continue")
+```
+
+## How it works
+
+A `Scenario` is a pair: a `trigger` that says "stop, a human is needed" and a `complete` that says "OK, they're done."
+
+`handoff.run(page, timeout=...)` watches the page for any scenario's trigger. If none fires within `timeout` seconds, it returns `HandoffResult(was_blocked=False)` and your script keeps going. If one fires, it starts a local streaming server, surfaces the URL (printed to logs and pushed to your notifiers), and waits until the matching `complete` condition matches — or until `server.completion_timeout` elapses, in which case the result has `timed_out=True`. `handoff.run` never raises on completion timeout; check the result.
+
+## Scope: what this is *not*
+
+`browser-handoff` is for flows gated by **credentials or session state** — login pages, 2FA prompts, OAuth consent screens, payment forms, identity verification, T&C acceptance.
+
+It is **not** an anti-bot bypass. Sites that fingerprint Playwright/CDP sessions as automation will keep refusing the flow even after a human solves a CAPTCHA, Cloudflare Turnstile, or similar challenge — the session itself is flagged, not the response. If that's your problem, you need an anti-detection browser, not a handoff tool.
+
+## Detection
+
+`Detection` is the factory for conditions:
+
+```python
+Detection.url(host_equals=["accounts.google.com"], path_contains=["/oauth"])
+Detection.element(present=["input[type=password]"], visible=[".consent-modal"], missing=[".user-menu"])
+Detection.content(title_contains=["Sign In"], body_matches=[r"verify.*you"])
+Detection.llm(model="anthropic/claude-sonnet-4-5", condition="Login form is visible")
+```
+
+Combine them:
+
+```python
+Detection.any([d1, d2])    # OR
+Detection.all([d1, d2])    # AND
+Detection.not_(d1)         # NOT
+```
+
+## Notifications
+
+Optional. Each notifier gets the stream URL when a handoff starts.
+
+```python
+from browser_handoff.notifiers import DiscordNotifier, EmailNotifier, SlackNotifier
+
+Handoff(
+    scenarios=[...],
+    notifiers=[
+        SlackNotifier(webhook_url="https://hooks.slack.com/..."),
+        DiscordNotifier(webhook_url="https://discord.com/api/webhooks/..."),
+        EmailNotifier(
+            smtp_host="smtp.gmail.com", smtp_port=587,
+            username="bot@x.com", password="...",
+            to=["ops@x.com"],
+        ),
+    ],
+)
+```
+
+## Server
+
+Defaults to `127.0.0.1:8080` (loopback only) with a 10-minute human-completion budget. Set `host="0.0.0.0"` to expose on the LAN — e.g. for phone access or tunnel forwarding.
+
+```python
+from browser_handoff import ServerConfig
+
+Handoff(
+    scenarios=[...],
+    server=ServerConfig(
+        host="127.0.0.1",                             # "0.0.0.0" to expose on LAN
+        port=8080,
+        public_base="https://my-tunnel.example.com",  # what notifiers link to
+        completion_timeout=600,                       # max human wait (s)
+        jpeg_quality=75,
+        every_nth_frame=1,
+    ),
+)
+```
+
+## Config files
+
+JSON or YAML, with `${VAR}` interpolation:
+
+<table>
+<tr><th>JSON</th><th>YAML</th></tr>
+<tr>
+<td>
+
+```json
+{
+  "scenarios": [{
+    "name": "login",
+    "trigger": {
+      "type": "any",
+      "conditions": [
+        { "type": "url",
+          "path_contains": ["/login"] },
+        { "type": "element",
+          "present": ["input[type=password]"] }
+      ]
+    },
+    "complete": {
+      "type": "not",
+      "condition": {
+        "type": "url",
+        "path_contains": ["/login"]
+      }
+    }
+  }],
+  "server": {
+    "port": 8080,
+    "public_base": "${HANDOFF_URL}"
+  },
+  "notifiers": [
+    { "type": "slack",
+      "webhook_url": "${SLACK_WEBHOOK}" }
+  ]
+}
+```
+
+</td>
+<td>
+
+```yaml
+scenarios:
+  - name: login
+    trigger:
+      type: any
+      conditions:
+        - type: url
+          path_contains: ["/login"]
+        - type: element
+          present: ["input[type=password]"]
+    complete:
+      type: not
+      condition:
+        type: url
+        path_contains: ["/login"]
+
+server:
+  port: 8080
+  public_base: ${HANDOFF_URL}
+
+notifiers:
+  - type: slack
+    webhook_url: ${SLACK_WEBHOOK}
+```
+
+</td>
+</tr>
+</table>
+
+```python
+handoff = Handoff.from_file("handoff.yaml")
+# or: Handoff.from_json(s) / Handoff.from_yaml(s) / Handoff.from_dict(d)
+```
+
+## Examples
+
+See [`examples/claude_oauth_login_handoff.py`](examples/claude_oauth_login_handoff.py) for a working Claude OAuth flow that pairs `browser-handoff` with [`ccauth`](https://github.com/synacktraa/ccauth).
+
+## License
+
+MIT — see [LICENSE](LICENSE).