scalebrowser 0.3.0__tar.gz → 0.4.0__tar.gz

{scalebrowser-0.3.0 → scalebrowser-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: scalebrowser
-Version: 0.3.0
+Version: 0.4.0
 Summary: Official Python SDK for the Scalebrowser daemon — typed REST client + direct-CDP driver (nodriver-style).
 Project-URL: Homepage, https://scalebrowser.net
 Project-URL: Documentation, https://scalebrowser.net
@@ -27,7 +27,7 @@ Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
 Description-Content-Type: text/markdown
 
-# scalebrowser — Python SDK
+# scalebrowser: the Python SDK
 
 Official Python SDK for the [Scalebrowser](https://scalebrowser.net) daemon: a
 typed REST client **plus a direct-CDP driver** (nodriver-style) for the
@@ -89,43 +89,43 @@ asyncio.run(main())
 Every `/v1` endpoint is a typed method on the client, under the same name in
 both the sync and the async client:
 
-- **Profiles** — `list_profiles`, `get_profile`, `create_profile`,
+- **Profiles**: `list_profiles`, `get_profile`, `create_profile`,
   `update_profile`, `delete_profile`, `start_profile`, `stop_profile`
-- **Bulk** — `bulk_create_profiles`, `bulk_start`, `bulk_stop`, `bulk_delete`,
+- **Bulk**: `bulk_create_profiles`, `bulk_start`, `bulk_stop`, `bulk_delete`,
   `bulk_assign_proxy`
-- **Groups / Presets** — `list_groups`/`create_group`/`get_group`/`update_group`/`delete_group`,
+- **Groups / Presets**: `list_groups`/`create_group`/`get_group`/`update_group`/`delete_group`,
   `list_presets`/`create_preset`/`get_preset`/`update_preset`/`delete_preset`,
   `get_persona_constraints`. A preset is `config` (what the profiles do:
   `geo_mode`, `proxy_id`, …) plus `constraints` (what they are: `country`, which
   pins the persona's language, timezone and voices). Both are typed
   (`PresetConfig` / `PresetConstraints`) and the daemon refuses an unknown key
-  with a 400 — read the valid regions from `get_persona_constraints()` rather than
+  with a 400, so read the valid regions from `get_persona_constraints()` rather than
   hardcoding them.
-- **Proxies** — `list_proxies`/`create_proxy`/`get_proxy`/`update_proxy`/`delete_proxy`/`check_proxy`,
+- **Proxies**: `list_proxies`/`create_proxy`/`get_proxy`/`update_proxy`/`delete_proxy`/`check_proxy`,
   plus `check_proxy_config` (probe a config before saving it; pass `id` to reuse
   an existing proxy's stored credentials)
-- **Extensions** — `list_extensions`, `attach_extension`, `detach_extension`,
+- **Extensions**: `list_extensions`, `attach_extension`, `detach_extension`,
   plus the daemon-wide library (`upload_extension`, `get_library_extension`,
   `delete_library_extension`). An attached package IS loaded into the browser at
   launch, under the canonical Web-Store id its own key derives
-- **Credentials** — `list_credentials`, `put_credential`, `reveal_credential`
+- **Credentials**: `list_credentials`, `put_credential`, `reveal_credential`
   (needs the vault password), `export_credentials`, `import_credentials`
-- **Cookies** — `reveal_cookies`, the one route a cookie VALUE leaves through,
+- **Cookies**: `reveal_cookies`, the one route a cookie VALUE leaves through,
   behind the same vault password
-- **Sessions** — `export_session`, `import_session`
-- **Mailboxes** — `list_inboxes`, `create_inbox`, `update_inbox`, `delete_inbox`,
-  `get_inbox_bindings`, `bind_inbox`, `unbind_inbox` — where a profile's
+- **Sessions**: `export_session`, `import_session`
+- **Mailboxes**: `list_inboxes`, `create_inbox`, `update_inbox`, `delete_inbox`,
+  `get_inbox_bindings`, `bind_inbox`, `unbind_inbox`, which is where a profile's
   confirmation codes arrive
-- **Passkeys** — `list_passkeys`, `delete_passkey`. Metadata only: the private
+- **Passkeys**: `list_passkeys`, `delete_passkey`. Metadata only: the private
   key has no field and no endpoint
-- **Agent runs** — `list_runs`, `get_run`, `list_run_steps`, `get_run_shot`,
+- **Agent runs**: `list_runs`, `get_run`, `list_run_steps`, `get_run_shot`,
   `get_activity`. Read-only, all of it
-- **Interruptions** — `list_interruption_locks`, `set_interruption_lock`,
+- **Interruptions**: `list_interruption_locks`, `set_interruption_lock`,
   `list_interruption_rules`, `set_interruption_rule`,
-  `delete_interruption_rule` — who may answer when the browser asks something
-- **Artifacts** — `put_artifact` (hand the daemon a file to upload later),
+  `delete_interruption_rule`: who may answer when the browser asks something
+- **Artifacts**: `put_artifact` (hand the daemon a file to upload later),
   `get_artifact` (fetch a screenshot, download or saved PDF as bytes)
-- **Input / Metrics / Account / Events** — `send_input`, `get_metrics`,
+- **Input / Metrics / Account / Events**: `send_input`, `get_metrics`,
   `get_account`, `health`, `ready`, `events()`
 
 ```python
@@ -134,19 +134,19 @@ async for event in sb_async.events():        # SSE lifecycle stream (Bearer-auth
 ```
 
 Errors map the daemon contract: `ApiError(status, code, message)` with codes
-`4001–4010` (`ApiError.is_auth_error` for 401 / 4010); `NetworkError` when the
+`4001–4012` (`ApiError.is_auth_error` for 401 / 4010); `NetworkError` when the
 daemon is unreachable; `CdpError` for protocol-level failures.
 
 ## Direct-CDP driver
 
 `CdpSession` (async) / `SyncCdpSession` give you:
 
-- `send(method, params)` — any CDP command, awaited by `id`
-- `navigate(url)`, `evaluate(expr, isolated=False)` — **never** calls
+- `send(method, params)`: any CDP command, awaited by `id`
+- `navigate(url)`, `evaluate(expr, isolated=False)`, which **never** call
   `Runtime.enable` (a detection leak); isolated worlds via
   `create_isolated_world()`
-- `on(method, cb)` / `events()` — subscribe to CDP events
-- `humanize_move/click/type/scroll` — humanized OS-level input via the daemon
+- `on(method, cb)` / `events()`: subscribe to CDP events
+- `humanize_move/click/type/scroll`: humanized OS-level input via the daemon
 
 ## Tests
 
@@ -159,8 +159,14 @@ SCALEBROWSER_E2E=1 pytest tests/test_e2e.py   # against a real daemon
 ## Contract assumptions
 
 - Default base URL `http://127.0.0.1:8787`; Bearer token always.
+- **The CDP endpoint is guarded by the OS user, not by that token.** The engine's
+  DevTools port has no authentication of its own: it answers a bogus bearer with
+  `200`, measured, so the engine drops any connection whose peer process runs as
+  a different user. Nothing to configure and nothing to pass: your process is the
+  one that started the profile, so it is on the allowed side. A helper running as
+  another account will not get in, by design.
 - The trusted-input body beyond `{action, humanize}` (coordinates, `button`,
-  `delta_x/y`, `text`) is an SDK convention — see `cdp.py`.
+  `delta_x/y`, `text`) is an SDK convention; see `cdp.py`.
 - Two endpoints are optional and answer 404 on a daemon without them, which the
   SDK treats as information rather than as an error: `get_metrics()` then derives
   running counts from profile state, and `get_account()` returns

{scalebrowser-0.3.0 → scalebrowser-0.4.0}/README.md

@@ -1,4 +1,4 @@
-# scalebrowser — Python SDK
+# scalebrowser: the Python SDK
 
 Official Python SDK for the [Scalebrowser](https://scalebrowser.net) daemon: a
 typed REST client **plus a direct-CDP driver** (nodriver-style) for the
@@ -60,43 +60,43 @@ asyncio.run(main())
 Every `/v1` endpoint is a typed method on the client, under the same name in
 both the sync and the async client:
 
-- **Profiles** — `list_profiles`, `get_profile`, `create_profile`,
+- **Profiles**: `list_profiles`, `get_profile`, `create_profile`,
   `update_profile`, `delete_profile`, `start_profile`, `stop_profile`
-- **Bulk** — `bulk_create_profiles`, `bulk_start`, `bulk_stop`, `bulk_delete`,
+- **Bulk**: `bulk_create_profiles`, `bulk_start`, `bulk_stop`, `bulk_delete`,
   `bulk_assign_proxy`
-- **Groups / Presets** — `list_groups`/`create_group`/`get_group`/`update_group`/`delete_group`,
+- **Groups / Presets**: `list_groups`/`create_group`/`get_group`/`update_group`/`delete_group`,
   `list_presets`/`create_preset`/`get_preset`/`update_preset`/`delete_preset`,
   `get_persona_constraints`. A preset is `config` (what the profiles do:
   `geo_mode`, `proxy_id`, …) plus `constraints` (what they are: `country`, which
   pins the persona's language, timezone and voices). Both are typed
   (`PresetConfig` / `PresetConstraints`) and the daemon refuses an unknown key
-  with a 400 — read the valid regions from `get_persona_constraints()` rather than
+  with a 400, so read the valid regions from `get_persona_constraints()` rather than
   hardcoding them.
-- **Proxies** — `list_proxies`/`create_proxy`/`get_proxy`/`update_proxy`/`delete_proxy`/`check_proxy`,
+- **Proxies**: `list_proxies`/`create_proxy`/`get_proxy`/`update_proxy`/`delete_proxy`/`check_proxy`,
   plus `check_proxy_config` (probe a config before saving it; pass `id` to reuse
   an existing proxy's stored credentials)
-- **Extensions** — `list_extensions`, `attach_extension`, `detach_extension`,
+- **Extensions**: `list_extensions`, `attach_extension`, `detach_extension`,
   plus the daemon-wide library (`upload_extension`, `get_library_extension`,
   `delete_library_extension`). An attached package IS loaded into the browser at
   launch, under the canonical Web-Store id its own key derives
-- **Credentials** — `list_credentials`, `put_credential`, `reveal_credential`
+- **Credentials**: `list_credentials`, `put_credential`, `reveal_credential`
   (needs the vault password), `export_credentials`, `import_credentials`
-- **Cookies** — `reveal_cookies`, the one route a cookie VALUE leaves through,
+- **Cookies**: `reveal_cookies`, the one route a cookie VALUE leaves through,
   behind the same vault password
-- **Sessions** — `export_session`, `import_session`
-- **Mailboxes** — `list_inboxes`, `create_inbox`, `update_inbox`, `delete_inbox`,
-  `get_inbox_bindings`, `bind_inbox`, `unbind_inbox` — where a profile's
+- **Sessions**: `export_session`, `import_session`
+- **Mailboxes**: `list_inboxes`, `create_inbox`, `update_inbox`, `delete_inbox`,
+  `get_inbox_bindings`, `bind_inbox`, `unbind_inbox`, which is where a profile's
   confirmation codes arrive
-- **Passkeys** — `list_passkeys`, `delete_passkey`. Metadata only: the private
+- **Passkeys**: `list_passkeys`, `delete_passkey`. Metadata only: the private
   key has no field and no endpoint
-- **Agent runs** — `list_runs`, `get_run`, `list_run_steps`, `get_run_shot`,
+- **Agent runs**: `list_runs`, `get_run`, `list_run_steps`, `get_run_shot`,
   `get_activity`. Read-only, all of it
-- **Interruptions** — `list_interruption_locks`, `set_interruption_lock`,
+- **Interruptions**: `list_interruption_locks`, `set_interruption_lock`,
   `list_interruption_rules`, `set_interruption_rule`,
-  `delete_interruption_rule` — who may answer when the browser asks something
-- **Artifacts** — `put_artifact` (hand the daemon a file to upload later),
+  `delete_interruption_rule`: who may answer when the browser asks something
+- **Artifacts**: `put_artifact` (hand the daemon a file to upload later),
   `get_artifact` (fetch a screenshot, download or saved PDF as bytes)
-- **Input / Metrics / Account / Events** — `send_input`, `get_metrics`,
+- **Input / Metrics / Account / Events**: `send_input`, `get_metrics`,
   `get_account`, `health`, `ready`, `events()`
 
 ```python
@@ -105,19 +105,19 @@ async for event in sb_async.events():        # SSE lifecycle stream (Bearer-auth
 ```
 
 Errors map the daemon contract: `ApiError(status, code, message)` with codes
-`4001–4010` (`ApiError.is_auth_error` for 401 / 4010); `NetworkError` when the
+`4001–4012` (`ApiError.is_auth_error` for 401 / 4010); `NetworkError` when the
 daemon is unreachable; `CdpError` for protocol-level failures.
 
 ## Direct-CDP driver
 
 `CdpSession` (async) / `SyncCdpSession` give you:
 
-- `send(method, params)` — any CDP command, awaited by `id`
-- `navigate(url)`, `evaluate(expr, isolated=False)` — **never** calls
+- `send(method, params)`: any CDP command, awaited by `id`
+- `navigate(url)`, `evaluate(expr, isolated=False)`, which **never** call
   `Runtime.enable` (a detection leak); isolated worlds via
   `create_isolated_world()`
-- `on(method, cb)` / `events()` — subscribe to CDP events
-- `humanize_move/click/type/scroll` — humanized OS-level input via the daemon
+- `on(method, cb)` / `events()`: subscribe to CDP events
+- `humanize_move/click/type/scroll`: humanized OS-level input via the daemon
 
 ## Tests
 
@@ -130,8 +130,14 @@ SCALEBROWSER_E2E=1 pytest tests/test_e2e.py   # against a real daemon
 ## Contract assumptions
 
 - Default base URL `http://127.0.0.1:8787`; Bearer token always.
+- **The CDP endpoint is guarded by the OS user, not by that token.** The engine's
+  DevTools port has no authentication of its own: it answers a bogus bearer with
+  `200`, measured, so the engine drops any connection whose peer process runs as
+  a different user. Nothing to configure and nothing to pass: your process is the
+  one that started the profile, so it is on the allowed side. A helper running as
+  another account will not get in, by design.
 - The trusted-input body beyond `{action, humanize}` (coordinates, `button`,
-  `delta_x/y`, `text`) is an SDK convention — see `cdp.py`.
+  `delta_x/y`, `text`) is an SDK convention; see `cdp.py`.
 - Two endpoints are optional and answer 404 on a daemon without them, which the
   SDK treats as information rather than as an error: `get_metrics()` then derives
   running counts from profile state, and `get_account()` returns

{scalebrowser-0.3.0 → scalebrowser-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "scalebrowser"
-version = "0.3.0"
+version = "0.4.0"
 description = "Official Python SDK for the Scalebrowser daemon — typed REST client + direct-CDP driver (nodriver-style)."
 readme = "README.md"
 requires-python = ">=3.10"

{scalebrowser-0.3.0 → scalebrowser-0.4.0}/src/scalebrowser/__init__.py

@@ -1,4 +1,4 @@
-"""Scalebrowser — official Python SDK.
+"""Scalebrowser: the official Python SDK.
 
 Typed REST client + a direct-CDP driver (nodriver-style, **not** Playwright) for
 the self-hosted Scalebrowser daemon.
@@ -111,6 +111,7 @@ from .models import (
     StartProfileBody,
     StartProfileResult,
     StopProfileResult,
+    TakeoverResult,
     UpdateProfileBody,
     UpdateProxyBody,
     WebGl,
@@ -207,6 +208,7 @@ __all__ = [
     "StartProfileBody",
     "StartProfileResult",
     "StopProfileResult",
+    "TakeoverResult",
     "BulkCreateBody",
     "BulkIdsBody",
     "BulkAssignProxyBody",

{scalebrowser-0.3.0 → scalebrowser-0.4.0}/src/scalebrowser/_sync.py

@@ -2,7 +2,7 @@
 
 A single background daemon thread runs an asyncio loop; the sync client and CDP
 session drive the async implementations through it via
-``run_coroutine_threadsafe``. There is no duplicated endpoint logic — every call
+``run_coroutine_threadsafe``. There is no duplicated endpoint logic: every call
 forwards to :class:`AsyncScalebrowserClient` / :class:`CdpSession`.
 """
 
@@ -161,7 +161,7 @@ class SyncCdpSession:
 
 
 class ScalebrowserClient:
-    """Synchronous client — mirrors :class:`AsyncScalebrowserClient` one-to-one."""
+    """Synchronous client; mirrors :class:`AsyncScalebrowserClient` one-to-one."""
 
     def __init__(
         self,
@@ -229,7 +229,7 @@ class ScalebrowserClient:
         sort: Optional[str] = None,
         order: Optional[str] = None,
     ) -> dict[str, Any]:
-        """Every id matching the filters, unpaged — what "act on all matches" needs."""
+        """Every id matching the filters, unpaged: what "act on all matches" needs."""
         return self._portal.run(
             self._async.list_profile_ids(group=group, state=state, q=q, sort=sort, order=order)
         )

{scalebrowser-0.3.0 → scalebrowser-0.4.0}/src/scalebrowser/cdp.py

@@ -1,10 +1,10 @@
-"""Direct-CDP driver (nodriver-style) over websockets — **not** a Playwright /
+"""Direct-CDP driver (nodriver-style) over websockets, and **not** a Playwright /
 Puppeteer control plane (DEC-006 / AC-FP-005).
 
 ``start`` returns a ``cdp_ws`` endpoint; we connect with our own minimal CDP
 client: send/await commands by ``id`` over a single multiplexed socket, demux
 events, attach to page targets (``flatten``), and create isolated worlds. We
-deliberately never call ``Runtime.enable`` (a documented detection leak — the
+deliberately never call ``Runtime.enable`` (a documented detection leak: the
 svebaa ``console.*`` + proxy-chain bypass); ``Runtime.evaluate`` works without it.
 
 The ``humanize_*`` helpers route to the daemon trusted-input endpoint
@@ -140,7 +140,7 @@ class _Connection:
         for callback in (*self._listeners.get(event["method"], ()), *self._listeners.get("*", ())):
             try:
                 callback(event)
-            except Exception:  # noqa: BLE001 — a bad listener must not kill the reader
+            except Exception:  # noqa: BLE001, a bad listener must not kill the reader
                 pass
         for queue in self._queues:
             queue.put_nowait(event)
@@ -410,7 +410,7 @@ async def connect_cdp(
         headers["Authorization"] = f"Bearer {token}"
     try:
         ws = await ws_connect(cdp_ws, additional_headers=headers, max_size=None)
-    except Exception as exc:  # noqa: BLE001 — normalize handshake/transport failures
+    except Exception as exc:  # noqa: BLE001, normalize handshake/transport failures
         raise NetworkError(f"Could not connect to CDP endpoint {cdp_ws}.", exc) from exc
 
     connection = _Connection(ws)

{scalebrowser-0.3.0 → scalebrowser-0.4.0}/src/scalebrowser/client.py

@@ -1,4 +1,4 @@
-"""The async Scalebrowser client — typed REST surface + a direct-CDP entry point.
+"""The async Scalebrowser client: typed REST surface plus a direct-CDP entry point.
 
 Every endpoint path is defined here exactly once, so endpoint drift is a
 one-file change (the transport in ``_http.py`` is the only other HTTP-aware
@@ -49,6 +49,7 @@ from .models import (
     SessionImportBody,
     StartProfileResult,
     StopProfileResult,
+    TakeoverResult,
     UpdatePresetBody,
     UpdateProfileBody,
     UpdateProxyBody,
@@ -73,12 +74,19 @@ from .models_identity import (
     PutInboxBody,
     RevealCookiesBody,
     RevealCookiesResult,
+    SecretDeleteResult,
+    SecretListResult,
+    SecretPatchBody,
+    SecretRow,
+    SecretRunBody,
+    SecretRunResult,
+    SecretScrubResult,
 )
 from .models_runs import ActivitySnapshot, AgentRun
 
 DEFAULT_BASE_URL = "http://127.0.0.1:8787"
 
-#: Mirrors ``CapacityConfig::default()`` — used by the metrics fallback.
+#: Mirrors ``CapacityConfig::default()``; used by the metrics fallback.
 DEFAULT_CAPACITY_MAX_CONCURRENT = 64
 DEFAULT_CAPACITY_RAM_BUDGET_MB = 24_576
 
@@ -145,7 +153,7 @@ class AsyncScalebrowserClient:
 
         ``sort`` (``created_at`` | ``name`` | ``runtime_state`` | ``last_open_at``)
         and ``order`` (``asc`` | ``desc``) are applied by the DAEMON over the whole
-        filtered set — sorting a fetched page would order a minority of a paged
+        filtered set, because sorting a fetched page would order a minority of a paged
         fleet while looking authoritative.
         """
         data = await self._t.get(
@@ -188,6 +196,16 @@ class AsyncScalebrowserClient:
         data = await self._t.post(f"/v1/profiles/{_q(profile_id)}/stop", {})
         return StopProfileResult.model_validate(data)
 
+    async def takeover_profile(self, profile_id: str) -> TakeoverResult:
+        """Ask for a profile that is open on another machine of this account.
+
+        Closes nothing here and nothing there: the control plane revokes the
+        holder's right, and the holder closes its own browser at its next
+        heartbeat. Start only after this answered ``free``.
+        """
+        data = await self._t.post(f"/v1/profiles/{_q(profile_id)}/takeover", {})
+        return TakeoverResult.model_validate(data)
+
     # ── bulk (PRD §D2) ───────────────────────────────────────────────────────
 
     async def bulk_create_profiles(
@@ -213,7 +231,7 @@ class AsyncScalebrowserClient:
         sort: Optional[str] = None,
         order: Optional[str] = None,
     ) -> dict[str, Any]:
-        """Every id matching the filters, unpaged — what "act on all matches" needs.
+        """Every id matching the filters, unpaged: what "act on all matches" needs.
 
         ``list_profiles`` is paged, so acting on "everything" from it only ever
         covers the page that was fetched. This costs one request and carries no
@@ -342,7 +360,7 @@ class AsyncScalebrowserClient:
     async def check_proxy_config(
         self, body: Union[CheckProxyConfigBody, Mapping[str, Any]]
     ) -> ProxyCheckResult:
-        """Probe a proxy config WITHOUT persisting it — validate before committing."""
+        """Probe a proxy config WITHOUT persisting it: validate before committing."""
         data = await self._t.post("/v1/proxies/check", _payload(body))
         return ProxyCheckResult.model_validate(data)
 
@@ -367,12 +385,12 @@ class AsyncScalebrowserClient:
     # Stored logins, so an agent can sign a profile into a platform WITHOUT ever
     # holding the password: the daemon decrypts and types it. Only
     # :meth:`reveal_credential` and the bundle calls return plaintext, and all of
-    # them need the vault password — the bearer token alone is not enough, because
+    # them need the vault password; the bearer token alone is not enough, because
     # the MCP agent layer authenticates with exactly the same one.
     #
     # ``platform`` is whatever you have: the service's domain ("discord.com"),
     # its name ("Discord") or a host under it ("www.discord.com"). The daemon
-    # resolves all of them to ONE key — the registrable domain — and every
+    # resolves all of them to ONE key (the registrable domain), and every
     # response echoes that key, so a later :meth:`delete_credential` addresses
     # the same row. Pass a whole sign-in URL only to the MCP tools: here the
     # platform is a path segment, and a "/" in it is refused rather than read
@@ -392,20 +410,30 @@ class AsyncScalebrowserClient:
         password: str | None = None,
         totp_secret: str | None = None,
         login_url: str | None = None,
+        binding_mode: str | None = None,
+        binding_value: str | None = None,
+        field_bound: bool | None = None,
     ) -> CredentialMeta:
         """Store or update one login.
 
-        An omitted secret keeps its stored value rather than clearing it — an edit
+        An omitted secret keeps its stored value rather than clearing it, because an edit
         form never saw the password in the clear, so it cannot resend one. Delete
         the row to remove a credential. ``totp_secret`` may be pasted exactly as a
         site presents it (grouped, lower case); it is normalised and test-decoded
         by the daemon, so a broken key is refused here rather than mid-login.
+
+        The three binding arguments say WHERE this login may be typed. Omitting
+        them leaves the binding as it is, so changing a password never silently
+        widens one.
         """
         body = {
             "username": username,
             "password": password,
             "totp_secret": totp_secret,
             "login_url": login_url,
+            "binding_mode": binding_mode,
+            "binding_value": binding_value,
+            "field_bound": field_bound,
         }
         data = await self._t.request(
             "PUT",
@@ -435,7 +463,7 @@ class AsyncScalebrowserClient:
 
         ``password`` is deliberately separate from the vault password: a backup
         gets handed to another machine, and that must not also hand over access to
-        this daemon. It is the answer to a lost master key — a daemon-generated
+        this daemon. It is the answer to a lost master key: a daemon-generated
         password exists nowhere else.
         """
         data = await self._t.post(
@@ -472,7 +500,7 @@ class AsyncScalebrowserClient:
     #
     # Upload a ``.crx``; the daemon lifts its public key out of the CRX header and
     # writes it into the unpacked ``manifest.json``, so every profile loads the
-    # package under its CANONICAL Web-Store id. A key-less package is refused — it
+    # package under its CANONICAL Web-Store id. A key-less package is refused, since it
     # would take a path-derived id, identical across the fleet.
 
     async def list_library_extensions(self) -> list[Extension]:
@@ -501,7 +529,7 @@ class AsyncScalebrowserClient:
     async def delete_library_extension_version(self, ext_id: str, version: str) -> None:
         """Remove ONE stocked version.
 
-        Assignments survive — they name the extension, not the version — unless
+        Assignments survive, because they name the extension and not the version, unless
         this was the last version, in which case they go with it.
         """
         await self._t.delete(f"/v1/extensions/{_q(ext_id)}/{_q(version)}")
@@ -607,7 +635,7 @@ class AsyncScalebrowserClient:
     async def list_run_steps(
         self, run_id: str, *, limit: Optional[int] = None, offset: Optional[int] = None
     ) -> list[RunStep]:
-        """A run's steps, oldest first — the order they happened in."""
+        """A run's steps, oldest first: the order they happened in."""
         data = await self._t.get(
             f"/v1/runs/{_q(run_id)}/steps", params={"limit": limit, "offset": offset}
         )
@@ -676,6 +704,66 @@ class AsyncScalebrowserClient:
         """
         await self._t.delete(f"/v1/profiles/{_q(profile_id)}/passkeys/{_q(credential_id)}")
 
+    # ── secret layer ─────────────────────────────────────────────────────────
+    #
+    # Values a profile holds that no agent ever reads. Nothing here returns a
+    # value, and that is not an oversight: ``run_with_secrets`` starts the
+    # command INSIDE the daemon precisely so that no route has to hand plaintext
+    # out.
+
+    async def list_secrets(self, profile_id: str) -> SecretListResult:
+        """The entries this profile keeps, with the placeholder for each."""
+        return SecretListResult.model_validate(
+            await self._t.get(f"/v1/profiles/{_q(profile_id)}/secrets")
+        )
+
+    async def update_secret(
+        self, profile_id: str, secret_id: str, body: Union[SecretPatchBody, Mapping[str, Any]]
+    ) -> SecretRow:
+        """Change a title, a binding, or the state. Never the label."""
+        return SecretRow.model_validate(
+            await self._t.patch(
+                f"/v1/profiles/{_q(profile_id)}/secrets/{_q(secret_id)}", _payload(body)
+            )
+        )
+
+    async def delete_secret(self, profile_id: str, secret_id: str) -> SecretDeleteResult:
+        """Delete an entry. The reply names the runs it appeared in."""
+        return SecretDeleteResult.model_validate(
+            await self._t.delete(f"/v1/profiles/{_q(profile_id)}/secrets/{_q(secret_id)}")
+        )
+
+    async def scrub_text(self, profile_id: str, text: str) -> SecretScrubResult:
+        """Filter a text you hold against this profile's values.
+
+        The call exists because censoring only makes sense where a MODEL is
+        reading: your own code is not, and a placeholder in the middle of it
+        would break parsing. So the daemon offers the filter rather than
+        applying it to a channel it does not own.
+        """
+        return SecretScrubResult.model_validate(
+            await self._t.post(f"/v1/profiles/{_q(profile_id)}/secrets/scrub", {"text": text})
+        )
+
+    async def run_with_secrets(
+        self, profile_id: str, body: Union[SecretRunBody, Mapping[str, Any]]
+    ) -> SecretRunResult:
+        """Run a command with named values in its environment.
+
+        The daemon starts the child, so no value crosses a socket.
+        """
+        return SecretRunResult.model_validate(
+            await self._t.post(f"/v1/profiles/{_q(profile_id)}/secrets/run", _payload(body))
+        )
+
+    async def get_secret_layer(self) -> dict[str, Any]:
+        """Is the secret layer on? It is by default."""
+        return await self._t.get("/v1/secret-layer") or {}
+
+    async def set_secret_layer(self, enabled: bool) -> dict[str, Any]:
+        """Turn the secret layer on or off for the whole daemon."""
+        return await self._t.post("/v1/secret-layer", {"enabled": enabled}) or {}
+
     # ── interruptions ────────────────────────────────────────────────────────
 
     async def list_interruption_locks(self) -> InterruptionLockView:
@@ -726,7 +814,7 @@ class AsyncScalebrowserClient:
         return ArtifactPutResult.model_validate(result)
 
     async def get_artifact(self, artifact_id: str) -> ArtifactBytes:
-        """Fetch one artifact's bytes — a screenshot, a download, a saved PDF.
+        """Fetch one artifact's bytes: a screenshot, a download, a saved PDF.
 
         A miss is a plain 404 whether the id never existed, expired, or belonged
         to a released lease: the caller's next move is the same in all three.
@@ -772,7 +860,7 @@ class AsyncScalebrowserClient:
         return HealthStatus.model_validate(await self._t.get("/health"))
 
     async def ready(self) -> ReadyStatus:
-        """"Can it serve?" Local facts only — the control plane is not consulted."""
+        """"Can it serve?" Local facts only; the control plane is not consulted."""
         return ReadyStatus.model_validate(await self._t.get("/health/ready"))
 
     # ── events (SSE) ─────────────────────────────────────────────────────────

{scalebrowser-0.3.0 → scalebrowser-0.4.0}/src/scalebrowser/errors.py

@@ -1,6 +1,6 @@
 """Typed SDK errors and the daemon's stable numeric error codes.
 
-The daemon returns error bodies shaped ``{ "code": <4001-4010>, "message": "…" }``
+The daemon returns error bodies shaped ``{ "code": <4001-4012>, "message": "…" }``
 with the HTTP status from ``core::Error::http_status()`` (docs/features/api.md, SPEC §5).
 """
 
@@ -26,6 +26,16 @@ class ErrorCode:
     # is to stop a running browser anywhere or upgrade the plan.
     CONCURRENCY_LIMIT: Final = 4008
     UNAUTHORIZED: Final = 4010
+    # No account is connected to this machine, so nothing may run (DEC-014).
+    # Distinct from UNAUTHORIZED (4010 = the daemon's own bearer token is wrong, so
+    # re-read the token): 4011 means the machine needs to be signed in, and no token
+    # a client holds can substitute for that. Connect it in the desktop app.
+    NOT_SIGNED_IN: Final = 4011
+    # This ONE profile is open on another machine of the same account (DEC-015).
+    # Distinct from CONCURRENCY_LIMIT (4008 = the plan is full, buy more or free any
+    # browser): the caller's move here costs nothing. Close it on that machine, or
+    # take it over from the app running there.
+    PROFILE_IN_USE: Final = 4012
 
 
 _CODE_LABELS: Final[dict[int, str]] = {
@@ -37,6 +47,8 @@ _CODE_LABELS: Final[dict[int, str]] = {
     4006: "Profile already running",
     4008: "Concurrent-browser limit reached (subscription-wide)",
     4010: "Unauthorized",
+    4011: "No account connected to this machine",
+    4012: "This profile is open on another machine",
 }
 
 
@@ -53,7 +65,7 @@ class ApiError(ScalebrowserError):
     """A transport/contract error from the daemon REST API.
 
     Carries the HTTP ``status`` and the daemon's numeric ``code`` so callers can
-    branch on auth failures or specific business errors (4001-4010).
+    branch on auth failures or specific business errors (4001-4012).
     """
 
     def __init__(
@@ -81,7 +93,7 @@ class ApiError(ScalebrowserError):
 
 
 class NetworkError(ScalebrowserError):
-    """A network-level failure — the daemon was unreachable (no HTTP response)."""
+    """A network-level failure: the daemon was unreachable (no HTTP response)."""
 
     def __init__(self, message: str, cause: Optional[BaseException] = None) -> None:
         super().__init__(message)