oya-browser 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ """oya-browser: real browsers for AI agents, from Python.
2
+
3
+ from oya_browser import Oya
4
+
5
+ with Oya() as oya, oya.browser.start() as browser:
6
+ browser.goto("https://example.com")
7
+ print(browser.ask("What is the page title?"))
8
+
9
+ With browser-use (pip install "oya-browser[browser-use]"):
10
+
11
+ agent = Agent(task, llm, browser=browser.for_browser_use())
12
+ """
13
+
14
+ from .browser import AsyncBrowser, Browser
15
+ from .client import AsyncOya, Oya
16
+ from .errors import OyaError
17
+ from .file import MAX_FILE_BYTES, file
18
+ from .run import AsyncRun, Run
19
+
20
+ __all__ = ["MAX_FILE_BYTES", "AsyncBrowser", "AsyncOya", "AsyncRun", "Browser", "Oya", "OyaError", "Run", "file"]
21
+ __version__ = "0.2.0"
@@ -0,0 +1,41 @@
1
+ """What Browser and AsyncBrowser share: what a browser knows about itself, its links, and the browser-use hand-off."""
2
+
3
+ from typing import Any
4
+
5
+ from . import _ops as ops
6
+ from ._http import AsyncHttp, Http
7
+
8
+ NO_CDP = "This browser has no CDP endpoint (its provider does not offer one), so browser-use cannot drive it."
9
+
10
+
11
+ def browser_use(cdp_url: str | None) -> Any:
12
+ """A browser_use.Browser on `cdp_url`; browser-use is an optional extra, imported only when asked for."""
13
+ if not cdp_url:
14
+ raise ValueError(NO_CDP)
15
+ try:
16
+ from browser_use import Browser as BrowserUseBrowser
17
+ except ImportError as e:
18
+ raise ImportError('browser-use is not installed: pip install "oya-browser[browser-use]"') from e
19
+ return BrowserUseBrowser(cdp_url=cdp_url)
20
+
21
+
22
+ class BrowserBase:
23
+ """What every browser knows about itself."""
24
+
25
+ def __init__(self, http: Http | AsyncHttp, info: dict[str, Any], auto_captcha: bool) -> None:
26
+ self.id: str = info["id"]
27
+ self.provider: str = info.get("provider") or "cdp"
28
+ self.persona: str = info.get("persona") or "default"
29
+ self.cdp_url: str | None = info.get("cdpUrl")
30
+ """Where Playwright, Puppeteer or browser-use connect; single use, see fresh_cdp_url()."""
31
+ self.reused: bool = info.get("reused") is True
32
+ """True when start() handed over a browser that was already running, such as the desktop app."""
33
+ self._auto_captcha = auto_captcha
34
+ self._base_url = http.origin.base_url
35
+
36
+ def live_view_url(self) -> str:
37
+ """Watch it work: the console, opened on this browser. Carries no credential; frames are live_stream_url()."""
38
+ return ops.live_view_url(self._base_url, self.id)
39
+
40
+ def __repr__(self) -> str:
41
+ return f"<{type(self).__name__} {self.id} on {self.provider}>"
oya_browser/_config.py ADDED
@@ -0,0 +1,83 @@
1
+ """Where the key and the address come from: the option, then OYA_API_KEY / OYA_BASE_URL, then ~/.oya/config.json.
2
+
3
+ The same order as the TypeScript SDK and the `oya` CLI, so a key saved by `oya login` works here unchanged.
4
+ A saved key is only used for the deployment it was saved for, so a staging key never goes to production.
5
+ """
6
+
7
+ import json
8
+ import os
9
+ from dataclasses import dataclass
10
+ from pathlib import Path
11
+ from urllib.parse import urlsplit
12
+
13
+ from ._constants import DEFAULT_BASE_URL, JSON_INDENT, PRIVATE_DIR, PRIVATE_FILE
14
+
15
+ NO_KEY = "No API key. Get one at https://oyabrowser.com, then set OYA_API_KEY or pass api_key=..."
16
+
17
+
18
+ @dataclass(frozen=True)
19
+ class Origin:
20
+ """The key and the address the client calls."""
21
+
22
+ api_key: str
23
+ base_url: str
24
+
25
+
26
+ def config_file() -> Path:
27
+ """The CLI's config file: OYA_CONFIG_HOME, else ~/.oya, then config.json."""
28
+ return Path(os.environ.get("OYA_CONFIG_HOME") or str(Path.home() / ".oya")) / "config.json"
29
+
30
+
31
+ def _saved() -> dict[str, str]:
32
+ """The CLI's saved config, or nothing when there is none or it does not parse."""
33
+ try:
34
+ data = json.loads(config_file().read_text())
35
+ except (OSError, ValueError):
36
+ return {}
37
+ return {k: v for k, v in data.items() if isinstance(v, str)} if isinstance(data, dict) else {}
38
+
39
+
40
+ def _host(url: str) -> str:
41
+ """The deployment a URL belongs to: its host, port included."""
42
+ return urlsplit(url).netloc
43
+
44
+
45
+ def save_key(api_key: str, base_url: str) -> bool:
46
+ """Saves a key where `oya login` would, unless one is there already, owner-only; True when it wrote."""
47
+ if _saved().get("apiKey"):
48
+ return False
49
+ path = config_file()
50
+ path.parent.mkdir(mode=PRIVATE_DIR, parents=True, exist_ok=True)
51
+ text = json.dumps({**_saved(), "apiKey": api_key, "baseUrl": base_url}, indent=JSON_INDENT)
52
+ _write_private(path, text)
53
+ return True
54
+
55
+
56
+ def _write_private(path: Path, text: str) -> None:
57
+ """Writes `text` to `path` readable by its owner only, whatever was there before.
58
+
59
+ Opening the file itself with O_TRUNC would keep the mode of a file that already exists (a config left
60
+ world-readable stays so) and would follow a symlink planted at the path. So the key goes to a new file,
61
+ created exclusively and not through a link, and is renamed over the config in one step.
62
+ """
63
+ tmp = path.with_name(f".{path.name}.{os.getpid()}.tmp")
64
+ fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0), PRIVATE_FILE)
65
+ try:
66
+ with os.fdopen(fd, "w") as f:
67
+ f.write(text)
68
+ os.replace(tmp, path)
69
+ except BaseException:
70
+ tmp.unlink(missing_ok=True)
71
+ raise
72
+
73
+
74
+ def resolve(api_key: str | None = None, base_url: str | None = None) -> Origin:
75
+ """The key and address to use; raises without a key."""
76
+ saved = _saved()
77
+ address = (base_url or os.environ.get("OYA_BASE_URL") or saved.get("baseUrl") or DEFAULT_BASE_URL).rstrip("/")
78
+ saved_base = saved.get("baseUrl", DEFAULT_BASE_URL)
79
+ saved_key = saved.get("apiKey") if _host(saved_base) == _host(address) else None
80
+ key = (api_key or os.environ.get("OYA_API_KEY") or saved_key or "").strip()
81
+ if not key:
82
+ raise ValueError(NO_KEY)
83
+ return Origin(api_key=key, base_url=address)
@@ -0,0 +1,68 @@
1
+ """Every number the SDK uses, by name, in seconds: the same budgets as the TypeScript SDK's constants.ts."""
2
+
3
+ DEFAULT_BASE_URL = "https://oyabrowser.com"
4
+ """The hosted control plane, used when no option, environment variable or saved config names one."""
5
+
6
+ DEFAULT_TIMEOUT_S = 60.0
7
+ """A plain API call."""
8
+ START_TIMEOUT_S = 120.0
9
+ """Starting a browser: the start call itself, before any wait for a cloud browser to dial in."""
10
+ READY_TIMEOUT_S = 120.0
11
+ """How long a starting cloud browser has to dial in."""
12
+ READY_POLL_S = 2.0
13
+ """How often the fleet is checked while a cloud browser is starting."""
14
+ NAVIGATE_TIMEOUT_S = 120.0
15
+ """A navigation, which waits for the page to load."""
16
+ CHALLENGE_TIMEOUT_S = 180.0
17
+ """Solving a CAPTCHA or completing MFA."""
18
+ AGENT_TIMEOUT_S = 600.0
19
+ """An agent task or a playbook replay; the server keeps the connection alive meanwhile."""
20
+ PLAYBOOK_TIMEOUT_S = 120.0
21
+ """Saving a playbook."""
22
+ STOP_TIMEOUT_S = 60.0
23
+ """Stopping a browser, which destroys a cloud sandbox."""
24
+ WAIT_FOR_DEFAULT_S = 30.0
25
+ """How long wait_for() waits for a selector by default."""
26
+ WAIT_FOR_GRACE_S = 5.0
27
+ """Extra request time on top of wait_for()'s own timeout, so the server answers first."""
28
+ MS_PER_SECOND = 1000
29
+ """The API takes wait_for()'s timeout in milliseconds."""
30
+ AIMED_SCROLL_AMOUNT = 500
31
+ """Pixels an aimed scroll (scroll(at=...)) moves when no amount is given."""
32
+ SHARE_EXPIRES_S = 3600
33
+ """How long a share_url() link works by default."""
34
+ RUN_POLL_S = 2.0
35
+ """How often a submitted run is polled by default."""
36
+ MAX_RUN_POLL_ERRORS = 5
37
+ """Failed polls in a row before a run is reported as failed."""
38
+ DESKTOP_TIMEOUT_S = 300.0
39
+ """How long desktop.connect() waits for a person to click Connect (and allow the keychain prompt)."""
40
+ DESKTOP_PROVIDER = "oya-desktop"
41
+ """The provider the server names the Oya desktop app by."""
42
+ DESKTOP_DOWNLOAD_URL = "https://oyabrowser.com/#download"
43
+ """Where the desktop app is downloaded."""
44
+ BYTES_PER_MB = 1_048_576
45
+ """Bytes in a megabyte, for file limits and messages."""
46
+ MAX_FILE_MB = 10
47
+ """Largest task file: bigger and the server would refuse the body anyway."""
48
+ PRIVATE_FILE = 0o600
49
+ """Owner read and write only: the saved config holds a key."""
50
+ PRIVATE_DIR = 0o700
51
+ """~/.oya, created owner-only, so no other user can list or replace the key file in it."""
52
+ JSON_INDENT = 2
53
+ """Indent of the saved config, as `oya login` writes it."""
54
+
55
+ STATUS_UNKNOWN = 0
56
+ """A failure that was not an HTTP answer, such as a run that could not be polled."""
57
+ STATUS_NOT_FOUND = 404
58
+ """A session not recorded yet, which is fine while a browser starts."""
59
+ STATUS_CONFLICT = 409
60
+ """A browser whose creation ended."""
61
+ STATUS_UNPROCESSABLE = 422
62
+ """A command that ran and failed."""
63
+ STATUS_SERVER_ERROR = 500
64
+ """An agent failure reported without a status."""
65
+ STATUS_GATEWAY_TIMEOUT = 504
66
+ """A browser that did not dial in before its budget ran out."""
67
+ STATUS_BAD_REQUEST_FLOOR = 400
68
+ """Responses from here up are errors."""
oya_browser/_http.py ADDED
@@ -0,0 +1,89 @@
1
+ """The one HTTP path every call takes, sync and async: the same headers, timeouts and error handling for both.
2
+
3
+ Errors come back as OyaError with the server's message, so a caller reads "Browser abc not found", not a status code.
4
+ """
5
+
6
+ from typing import Any
7
+ from urllib.parse import quote
8
+
9
+ import httpx
10
+
11
+ from ._config import Origin
12
+ from ._constants import DEFAULT_TIMEOUT_S, STATUS_BAD_REQUEST_FLOOR
13
+ from .errors import OyaError
14
+
15
+ USER_AGENT = "oya-browser-python"
16
+
17
+
18
+ def segment(value: object, field: str = "id") -> str:
19
+ """One path segment, encoded; refused when it is empty or would change the path ("/", "." or "..")."""
20
+ if not isinstance(value, str) or not value:
21
+ raise ValueError(f"{field} must be a non-empty string, not {value!r}")
22
+ if "/" in value or value in (".", ".."):
23
+ raise ValueError(f"{field} must be a single path segment, not {value!r}")
24
+ return quote(value, safe="")
25
+
26
+
27
+ def _headers(origin: Origin, extra: dict[str, str] | None) -> dict[str, str]:
28
+ """The key, the client name, and any per-call headers."""
29
+ return {"Authorization": f"Bearer {origin.api_key}", "User-Agent": USER_AGENT, **(extra or {})}
30
+
31
+
32
+ def _parsed(response: httpx.Response, call: str) -> Any:
33
+ """The JSON body, or an OyaError carrying the server's message when the call failed."""
34
+ try:
35
+ body: Any = response.json() if response.content else None
36
+ except ValueError:
37
+ body = response.text
38
+ if response.status_code >= STATUS_BAD_REQUEST_FLOOR:
39
+ message = body.get("error") if isinstance(body, dict) else None
40
+ raise OyaError(message or f"{call} failed ({response.status_code})", response.status_code, body)
41
+ return body
42
+
43
+
44
+ class Http:
45
+ """Synchronous calls to the control plane."""
46
+
47
+ def __init__(self, origin: Origin, client: httpx.Client | None = None, headers: dict[str, str] | None = None):
48
+ self.origin = origin
49
+ self._client = client or httpx.Client(base_url=origin.base_url)
50
+ self._extra = headers
51
+
52
+ def with_headers(self, headers: dict[str, str]) -> "Http":
53
+ """The same client sending `headers` on every call too."""
54
+ return Http(self.origin, self._client, {**(self._extra or {}), **headers})
55
+
56
+ def request(self, method: str, path: str, body: Any = None, timeout: float = DEFAULT_TIMEOUT_S, **kw: Any) -> Any:
57
+ """One call; returns the parsed JSON body."""
58
+ headers = _headers(self.origin, {**(self._extra or {}), **kw.get("headers", {})})
59
+ response = self._client.request(method, path, json=body, headers=headers, timeout=timeout)
60
+ return _parsed(response, f"{method} {path}")
61
+
62
+ def close(self) -> None:
63
+ """Closes the connection pool."""
64
+ self._client.close()
65
+
66
+
67
+ class AsyncHttp:
68
+ """Asynchronous calls to the control plane."""
69
+
70
+ def __init__(self, origin: Origin, client: httpx.AsyncClient | None = None, headers: dict[str, str] | None = None):
71
+ self.origin = origin
72
+ self._client = client or httpx.AsyncClient(base_url=origin.base_url)
73
+ self._extra = headers
74
+
75
+ def with_headers(self, headers: dict[str, str]) -> "AsyncHttp":
76
+ """The same client sending `headers` on every call too."""
77
+ return AsyncHttp(self.origin, self._client, {**(self._extra or {}), **headers})
78
+
79
+ async def request(
80
+ self, method: str, path: str, body: Any = None, timeout: float = DEFAULT_TIMEOUT_S, **kw: Any
81
+ ) -> Any:
82
+ """One call; returns the parsed JSON body."""
83
+ headers = _headers(self.origin, {**(self._extra or {}), **kw.get("headers", {})})
84
+ response = await self._client.request(method, path, json=body, headers=headers, timeout=timeout)
85
+ return _parsed(response, f"{method} {path}")
86
+
87
+ async def aclose(self) -> None:
88
+ """Closes the connection pool."""
89
+ await self._client.aclose()
@@ -0,0 +1,36 @@
1
+ """The base of every namespace whose methods are one call each (oya.personas, oya.control, ...).
2
+
3
+ One class serves both clients: on Oya a method returns the answer, on AsyncOya the same method returns an awaitable
4
+ of it. Each call is written once, so the sync and async surfaces cannot drift apart.
5
+ """
6
+
7
+ from typing import Any
8
+
9
+ from ._http import AsyncHttp, Http
10
+ from ._ops import Call
11
+
12
+
13
+ def _picked(result: Any, pick: str | None) -> Any:
14
+ """The answer, or the one field of it a list endpoint wraps its items in."""
15
+ return result.get(pick) if pick and isinstance(result, dict) else result
16
+
17
+
18
+ class Namespace:
19
+ """One call per method, sync or async depending on the client that built it."""
20
+
21
+ def __init__(self, http: Http | AsyncHttp) -> None:
22
+ self._http = http
23
+
24
+ @property
25
+ def _is_async(self) -> bool:
26
+ return isinstance(self._http, AsyncHttp)
27
+
28
+ def _do(self, call: Call, pick: str | None = None) -> Any:
29
+ """Makes the call; on AsyncOya returns a coroutine to await."""
30
+ if isinstance(self._http, AsyncHttp):
31
+ return self._ado(self._http, call, pick)
32
+ return _picked(self._http.request(call.method, call.path, call.body, call.timeout, headers=call.headers), pick)
33
+
34
+ @staticmethod
35
+ async def _ado(http: AsyncHttp, call: Call, pick: str | None) -> Any:
36
+ return _picked(await http.request(call.method, call.path, call.body, call.timeout, headers=call.headers), pick)
oya_browser/_ops.py ADDED
@@ -0,0 +1,196 @@
1
+ """Every browser call written once, as data: the sync and async Browser only differ in whether they await.
2
+
3
+ Paths, bodies and timeouts match the TypeScript SDK's browser.ts call for call.
4
+ """
5
+
6
+ import uuid
7
+ from dataclasses import dataclass, field
8
+ from typing import Any
9
+ from urllib.parse import quote
10
+
11
+ from ._constants import (
12
+ AGENT_TIMEOUT_S,
13
+ AIMED_SCROLL_AMOUNT,
14
+ CHALLENGE_TIMEOUT_S,
15
+ DEFAULT_TIMEOUT_S,
16
+ MS_PER_SECOND,
17
+ NAVIGATE_TIMEOUT_S,
18
+ PLAYBOOK_TIMEOUT_S,
19
+ STATUS_CONFLICT,
20
+ STATUS_SERVER_ERROR,
21
+ STATUS_UNPROCESSABLE,
22
+ STOP_TIMEOUT_S,
23
+ WAIT_FOR_GRACE_S,
24
+ )
25
+ from ._http import segment
26
+ from .errors import OyaError
27
+
28
+ LANE_HEADER = "X-Oya-Agent"
29
+ """A desktop browser handed to start() gives each lane a tab of its own, so the person keeps theirs."""
30
+
31
+
32
+ def sdk_lane() -> str:
33
+ """A lane name of this SDK's own, unique per Browser object."""
34
+ return f"sdk-{uuid.uuid4()}"
35
+
36
+
37
+ @dataclass(frozen=True)
38
+ class Call:
39
+ """One HTTP call: method, path, JSON body and time budget."""
40
+
41
+ method: str
42
+ path: str
43
+ body: Any = None
44
+ timeout: float = DEFAULT_TIMEOUT_S
45
+ headers: dict[str, str] = field(default_factory=dict)
46
+
47
+
48
+ def command(browser_id: str, action: str, params: dict[str, Any], timeout: float = DEFAULT_TIMEOUT_S) -> Call:
49
+ """A browser command, such as navigate, analyze, click or type."""
50
+ return Call("POST", f"/api/browsers/{segment(browser_id)}/command", {"action": action, "params": params}, timeout)
51
+
52
+
53
+ def command_data(result: Any, action: str) -> Any:
54
+ """A command's data; a command that ran and failed raises."""
55
+ if isinstance(result, dict) and result.get("ok") is False:
56
+ raise OyaError(result.get("error") or f"{action} failed", STATUS_UNPROCESSABLE, result)
57
+ return result.get("data") if isinstance(result, dict) else result
58
+
59
+
60
+ def agent_answer(result: Any) -> dict[str, Any]:
61
+ """An agent answer; the server sends 200 up front to keep long runs alive, so failures arrive in the body."""
62
+ if not isinstance(result, dict):
63
+ raise OyaError("The agent sent no answer", STATUS_SERVER_ERROR, result)
64
+ if result.get("error"):
65
+ raise OyaError(str(result["error"]), int(result.get("status") or STATUS_SERVER_ERROR), result)
66
+ return result
67
+
68
+
69
+ def element(element_id: int | str) -> dict[str, Any]:
70
+ """The params that address an element by its id from analyze()."""
71
+ try:
72
+ number = int(element_id)
73
+ except (TypeError, ValueError):
74
+ raise ValueError(f"element ids come from analyze(); {element_id!r} is not one") from None
75
+ return {"element_id": number, "selector": f'[data-ac-id="{number}"]'}
76
+
77
+
78
+ def navigate(browser_id: str, url: str) -> Call:
79
+ """Opens `url` and waits for it to load."""
80
+ return command(browser_id, "navigate", {"url": url}, NAVIGATE_TIMEOUT_S)
81
+
82
+
83
+ def wait_for(browser_id: str, selector: str, timeout_s: float) -> Call:
84
+ """Waits until `selector` matches."""
85
+ params = {"selector": selector, "timeout": int(timeout_s * MS_PER_SECOND)}
86
+ return command(browser_id, "wait", params, timeout_s + WAIT_FOR_GRACE_S)
87
+
88
+
89
+ def challenge(browser_id: str, kind: str) -> Call:
90
+ """Solves a CAPTCHA ("captcha") or completes MFA ("mfa")."""
91
+ return Call("POST", f"/api/browsers/{segment(browser_id)}/{kind}", {}, CHALLENGE_TIMEOUT_S)
92
+
93
+
94
+ def ask(browser_id: str, prompt: str, data: Any, secrets: Any, schema: Any = None) -> Call:
95
+ """A task in plain language; with `schema`, the answer comes back as data in that shape."""
96
+ body: dict[str, Any] = {"messages": [{"role": "user", "content": prompt}], "data": data, "secrets": secrets}
97
+ if schema is not None:
98
+ body["schema"] = schema
99
+ return Call("POST", f"/api/browsers/{segment(browser_id)}/chat", body, AGENT_TIMEOUT_S)
100
+
101
+
102
+ def to_playbook(browser_id: str, name: str) -> Call:
103
+ """Saves the last ask() on this browser as a named playbook."""
104
+ return Call("POST", f"/api/browsers/{segment(browser_id)}/playbooks", {"name": name}, PLAYBOOK_TIMEOUT_S)
105
+
106
+
107
+ def play(browser_id: str, name: str, data: Any, auto_heal: bool) -> Call:
108
+ """Replays a playbook with no model in the loop."""
109
+ path = f"/api/browsers/{segment(browser_id)}/playbooks/{segment(name, 'name')}/play"
110
+ return Call("POST", path, {"variables": data or {}, "autoHeal": auto_heal}, AGENT_TIMEOUT_S)
111
+
112
+
113
+ def stop(browser_id: str, reused: bool) -> Call:
114
+ """Stops a browser this SDK started; for one it borrowed (a person's desktop), ends only its own lane."""
115
+ action = "lane/end" if reused else "stop"
116
+ return Call("POST", f"/api/browsers/{segment(browser_id)}/{action}", {}, STOP_TIMEOUT_S)
117
+
118
+
119
+ def scroll(direction: str, amount: int | None, at: tuple[int, int] | None = None) -> dict[str, Any]:
120
+ """Scroll params; `amount` left out scrolls about a screen.
121
+
122
+ With `at`, the wheel is aimed at that (x, y) point, an inner scroller such as a results panel, as one wheel
123
+ event: drivers only honour x/y in that mode, and it moves AIMED_SCROLL_AMOUNT pixels when no amount is given.
124
+ """
125
+ if at is None:
126
+ return {"direction": direction} if amount is None else {"direction": direction, "amount": amount}
127
+ x, y = at
128
+ return {
129
+ "direction": direction,
130
+ "amount": AIMED_SCROLL_AMOUNT if amount is None else amount,
131
+ "x": x,
132
+ "y": y,
133
+ "smooth": False,
134
+ }
135
+
136
+
137
+ def active_url(tabs: list[dict[str, Any]]) -> str:
138
+ """The active tab's URL, or empty when there is none."""
139
+ return next((str(t.get("url") or "") for t in tabs if t.get("active")), "")
140
+
141
+
142
+ def handle_dialog(browser_id: str, accept: bool, prompt_text: str | None) -> Call:
143
+ """Answers a confirm() or prompt() holding the page."""
144
+ params: dict[str, Any] = {"accept": accept}
145
+ if prompt_text is not None:
146
+ params["prompt_text"] = prompt_text
147
+ return command(browser_id, "handle_dialog", params)
148
+
149
+
150
+ def open_tab(browser_id: str, url: str | None) -> Call:
151
+ """Opens a tab, at `url` when given; it may load a page, so it gets a navigation's budget."""
152
+ return command(browser_id, "open_tab", {} if url is None else {"url": url}, NAVIGATE_TIMEOUT_S)
153
+
154
+
155
+ def assert_captcha_cleared(result: dict[str, Any]) -> None:
156
+ """After captcha="auto": a CAPTCHA still on screen needs a person, so goto() raises 409 rather than go on."""
157
+ if not result.get("present") or result.get("solved") or result.get("invisible"):
158
+ return
159
+ message = result.get("error") or "CAPTCHA needs attention. Call solve_captcha() again or open the live view."
160
+ raise OyaError(str(message), STATUS_CONFLICT, result)
161
+
162
+
163
+ def session(browser_id: str, action: str) -> Call:
164
+ """A control-plane call on this browser's session: "ticket" for the live stream, "share" for a link."""
165
+ return Call("POST", f"/api/control/sessions/{segment(browser_id)}/{action}", {})
166
+
167
+
168
+ def share(browser_id: str, control: bool, expires_in_s: int) -> Call:
169
+ """Mints a credential scoped to this one browser, for a share link."""
170
+ body = {"control": control, "expiresIn": expires_in_s}
171
+ return Call("POST", f"/api/control/sessions/{segment(browser_id)}/share", body)
172
+
173
+
174
+ def live_stream_url(base_url: str, browser_id: str, ticket: str) -> str:
175
+ """The SSE frame stream; EventSource cannot set headers, so the single-use ticket rides in the query."""
176
+ return f"{base_url}/api/live/{segment(browser_id)}?ticket={quote(ticket, safe='')}"
177
+
178
+
179
+ def share_link(base_url: str, browser_id: str, credential: dict[str, Any]) -> dict[str, Any]:
180
+ """The public live-view link; the token rides in the fragment, so no server log or Referer sees it."""
181
+ url = f"{base_url}/live/{segment(browser_id)}#t={quote(str(credential['token']), safe='')}"
182
+ return {"url": url, "id": credential["id"], "expiresAt": credential.get("expiresAt")}
183
+
184
+
185
+ def live_view_url(base_url: str, browser_id: str) -> str:
186
+ """The console deep link: carries no credential, unlike a stream URL with the key in it would."""
187
+ return f"{base_url}/dashboard/?browser={quote(browser_id, safe='')}"
188
+
189
+
190
+ def submit(browser_id: str, prompt: str | None, playbook: str | None, values: dict[str, Any]) -> Call:
191
+ """Starts a prompt or a playbook as a background run; exactly one of the two."""
192
+ if (prompt is None) == (playbook is None):
193
+ raise ValueError("submit() takes a prompt or playbook=..., exactly one")
194
+ task = {"prompt": prompt} if prompt is not None else {"playbook": playbook}
195
+ body = {**task, **{k: v for k, v in values.items() if v is not None}}
196
+ return Call("POST", f"/api/browsers/{segment(browser_id)}/runs", body)
@@ -0,0 +1,95 @@
1
+ """What a submitted run's poll means, written once for Run and AsyncRun.
2
+
3
+ A poll is a new attention request, the result, or the failure. Same rules as the TypeScript SDK's run-watch.ts.
4
+ """
5
+
6
+ import logging
7
+ from collections.abc import Callable
8
+ from dataclasses import dataclass
9
+ from typing import Any
10
+ from urllib.parse import urljoin
11
+
12
+ from ._constants import MAX_RUN_POLL_ERRORS, STATUS_SERVER_ERROR, STATUS_UNKNOWN
13
+ from ._http import segment
14
+ from ._ops import Call
15
+ from .errors import OyaError
16
+
17
+ log = logging.getLogger("oya_browser")
18
+
19
+ Callback = Callable[[Any], Any]
20
+
21
+
22
+ @dataclass(frozen=True)
23
+ class Callbacks:
24
+ """What a run fires: on_success(result), on_failure(OyaError), on_human_attention(request), on_healed(result)."""
25
+
26
+ on_success: Callback | None = None
27
+ on_failure: Callback | None = None
28
+ on_human_attention: Callback | None = None
29
+ on_healed: Callback | None = None
30
+
31
+
32
+ @dataclass
33
+ class Step:
34
+ """One poll's meaning: a new attention request to report, and the result or failure once the run ended."""
35
+
36
+ attention: dict[str, Any] | None = None
37
+ result: dict[str, Any] | None = None
38
+ failure: OyaError | None = None
39
+
40
+
41
+ @dataclass
42
+ class Watch:
43
+ """What the loop carries between polls."""
44
+
45
+ base_url: str
46
+ respond: Callable[..., Any]
47
+ seen: str | None = None
48
+ errors: int = 0
49
+
50
+ def failed_poll(self, error: Exception) -> OyaError | None:
51
+ """None while polls fail now and then; the failure once MAX_RUN_POLL_ERRORS have failed in a row."""
52
+ self.errors += 1
53
+ if self.errors < MAX_RUN_POLL_ERRORS:
54
+ return None
55
+ return error if isinstance(error, OyaError) else OyaError(str(error), STATUS_UNKNOWN)
56
+
57
+ def step(self, info: dict[str, Any]) -> Step:
58
+ """Reads one successful poll; the attention request is reported once, however often it is polled."""
59
+ self.errors = 0
60
+ step = Step(attention=self._attention(info))
61
+ if info.get("status") == "succeeded":
62
+ step.result = info.get("result") or {}
63
+ elif info.get("status") == "failed":
64
+ status = info.get("errorStatus") or STATUS_SERVER_ERROR
65
+ step.failure = OyaError(info.get("error") or "Run failed", int(status), info)
66
+ return step
67
+
68
+ def _attention(self, info: dict[str, Any]) -> dict[str, Any] | None:
69
+ request = info.get("attention")
70
+ if info.get("status") != "needs_attention" or not request or request.get("id") == self.seen:
71
+ return None
72
+ self.seen = request.get("id")
73
+ link = request.get("liveViewUrl")
74
+ return {**request, "liveViewUrl": urljoin(self.base_url, link) if link else link, "respond": self.respond}
75
+
76
+
77
+ def fire(callback: Callback | None, value: Any) -> Any:
78
+ """Calls a caller's callback; one that raises is logged, never allowed to break the loop."""
79
+ if callback is None:
80
+ return None
81
+ try:
82
+ return callback(value)
83
+ except Exception:
84
+ log.exception("run callback raised")
85
+ return None
86
+
87
+
88
+ def status_call(run_id: str) -> Call:
89
+ """The run's current state."""
90
+ return Call("GET", f"/api/runs/{segment(run_id)}")
91
+
92
+
93
+ def respond_call(run_id: str, response: str) -> Call:
94
+ """Answers the open attention request."""
95
+ return Call("POST", f"/api/runs/{segment(run_id)}/respond", {"response": response})