oneshot-python 0.36.0__tar.gz → 0.38.0__tar.gz

{oneshot_python-0.36.0 → oneshot_python-0.38.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: oneshot-python
-Version: 0.36.0
+Version: 0.38.0
 Summary: Core Python SDK for the OneShot API — HTTP client with x402 payment handling — 48 tools
 License-Expression: MIT
 Requires-Python: >=3.10

{oneshot_python-0.36.0 → oneshot_python-0.38.0}/README.md

@@ -194,6 +194,7 @@ print(goal["goal_id"])
 # Observe
 status = client.get_compute_goal(goal["goal_id"])
 tasks = client.get_compute_tasks(goal["goal_id"])
+outputs = client.get_compute_outputs(goal["goal_id"])  # what the tasks produced; read one with get_compute_output(goal_id, key)
 budget = client.get_compute_budget(goal["goal_id"])
 
 # Top up a recurring goal (paid)
@@ -212,7 +213,7 @@ Every method has an `a*` async mirror (`acompute`, `aget_compute_goal`, …).
 
 ### Physical mail
 
-`client.physical_mail` supports U.S. letters and 4×6 postcards through `upload_artwork`, `validate_address`, `preview`, `get_quote`, `approve`, `send`, `get_order`, `recover`, and `cancel`. Async variants prefix the method with `a`. Review each proof and price, then call `approve(..., approved=True)` explicitly. Persist `idempotency_key` before sending. `recover(key)` retrieves the original order without a second charge. Postal delivery does not prove the letter was read; paid receipts and fulfillment events are separate. Lob credentials stay on OneShot's server.
+`client.physical_mail` supports U.S. letters and 4×6 postcards through `upload_artwork`, `validate_address`, `preview`, `get_quote`, `approve`, `send`, `get_order`, `recover`, and `cancel`. Async variants prefix the method with `a`. Review each proof and price, then call `approve(..., approved=True)` explicitly. Persist `idempotency_key` before sending. `recover(key)` retrieves the original order without a second charge. Postal delivery does not prove the letter was read; paid receipts and fulfillment events are separate. Mail provider credentials stay on OneShot's server.
 
 ### Account login and 2FA (0.24.0+)
 
@@ -314,6 +315,16 @@ client.hunts.leaderboard()    # public predictor leaderboard
 
 Async variants prefix the method with `a` (`alist`, `astatus`, `apredict`, `acapture`, `acollection`, `aleaderboard`). `list`/`status`/`collection`/`leaderboard` are free reads and work for both wallet and access-token sessions. `predict`/`capture` debit a stake and require Soul Hunt's wallet-signed write proof, which an access-token (credits-only) session cannot produce — those two raise `ValidationError` locally rather than reaching the network. The client never forwards the OneShot bearer token to Soul Hunt; only the wallet address and, for wallet sessions, the signed `x-agent-proof` go out.
 
+## Declared routes and inbox methods (#1273)
+
+Every route in the API registry states an agent tool. The ones without a typed method are in the lookup
+manifest and reached with `call_lookup(name, **fields)`, for example `call_lookup("company_filings", cik="320193")`
+(`acall_lookup` for async): a free route is a signed
+call, a paid one goes through `call_tool` and its quote. LangChain and GAME build their tools from the same
+manifest. The inbox, SMS inbox and notification routes also have methods: `inbox`, `inbox_get`, `sms_inbox`,
+`sms_inbox_get`, `notifications`, `mark_notification_read`, `mark_all_notifications_read` (each with an `a`
+async form).
+
 ## Requirements
 
 - Python 3.10+
@@ -323,7 +334,7 @@ Async variants prefix the method with `a` (`alist`, `astatus`, `apredict`, `acap
 ## Links
 
 - [Documentation](https://docs.oneshotagent.com/sdk/installation#install-via-pip-python)
-- [LangChain integration](https://pypi.org/project/langchain-oneshot/): 48 tools as LangChain BaseTool
+- [LangChain integration](https://pypi.org/project/langchain-oneshot/): 48 tools plus the lookup tools as LangChain BaseTool
 - [GAME plugin](https://pypi.org/project/game-plugin-oneshot/): Virtuals Protocol integration
 - [TypeScript SDK](https://www.npmjs.com/package/@oneshot-agent/sdk)
 - [MCP Server](https://www.npmjs.com/package/@oneshot-agent/mcp-server)

{oneshot_python-0.36.0 → oneshot_python-0.38.0}/oneshot/__init__.py

@@ -39,9 +39,11 @@ from oneshot._types import (
     DomainPoolStatusResult,
 )
 from oneshot.client import OneShotClient
+from oneshot.lookup import lookup_tools
 from oneshot.x402 import sign_payment_authorization
 
 __all__ = [
+    "lookup_tools",
     "PhysicalMail", "PostalAddress", "MailQuote", "MailOrder",
     "OneShotClient",
     "OneShotError",

{oneshot_python-0.36.0 → oneshot_python-0.38.0}/oneshot/_types.py

@@ -127,6 +127,7 @@ class ComputeCancelResult(TypedDict, total=False):
     goal_id: str
     status: str
     remaining_budget: str
+    message: str
 
 
 class ComputeTaskResponseResult(TypedDict, total=False):

{oneshot_python-0.36.0 → oneshot_python-0.38.0}/oneshot/client.py

@@ -44,6 +44,7 @@ from oneshot._types import (
     DomainPoolListResult,
     DomainPoolStatusResult,
 )
+from oneshot.lookup import PAID_PRICING, find_lookup_tool, lookup_query, lookup_request
 from oneshot.x402 import (
     build_zero_cost_authorization,
     encode_payment_header,
@@ -59,11 +60,13 @@ try:
 
     SDK_VERSION = _pkg_version("oneshot-python")
 except Exception:  # pragma: no cover - editable/source runs without dist metadata
-    SDK_VERSION = "0.36.0"
+    SDK_VERSION = "0.38.0"
 
 _BASE_URL = "https://win.oneshotagent.com"
 _HUNT_BASE_URL = "https://api.soulhunt.ai"
 _ACCESS_TOKEN_RE = re.compile(r"^oneshot_[0-9a-f]{64}$")
+# Endpoints whose admission reads a "submit"-scoped agent proof (same list as the TypeScript SDK).
+_DURABLE_ADMISSION_ENDPOINT = re.compile(r"(enrich/(profile|email)|verify/email|physical-mail/send)$")
 _CHAIN_ID = 8453
 _USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
 
@@ -72,6 +75,7 @@ _USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
 _POLL_BACKOFF = (0.3, 0.6, 1.0, 2.0)  # seconds
 _POLL_RETRY_BASE = 2.0  # seconds, transient-error retry backoff base
 _MAX_POLL_RETRIES = 3
+_BUILD_TRANSPORT_KWARGS = ("max_cost", "timeout_sec", "wait", "approval_id", "idempotency_key")
 
 
 def _build_email_payload(
@@ -157,6 +161,24 @@ def _parse_policy_rejection(resp: Any) -> Optional[OneShotError]:
     return None
 
 
+def _parse_invalid_proof(resp: Any) -> Optional[tuple[str, str]]:
+    """``(reason, message)`` when ``resp`` is the API's 401 ``invalid_proof`` refusal (#1437), else None."""
+    if resp.status_code != 401:
+        return None
+    try:
+        data = resp.json()
+    except Exception:  # noqa: BLE001 - non-JSON body
+        return None
+    if not isinstance(data, dict) or data.get("error") != "invalid_proof":
+        return None
+    reason = data.get("reason")
+    message = data.get("message")
+    return (
+        reason if isinstance(reason, str) else "invalid",
+        message if isinstance(message, str) else "The agent proof could not be verified.",
+    )
+
+
 def _parse_budget_rejection(resp: Any) -> Optional[BudgetExceededError]:
     """Map a 403 ``budget_exceeded`` body onto :class:`BudgetExceededError`.
 
@@ -631,6 +653,24 @@ class OneShotClient:
             self._log(f"Failed to sign read proof (continuing without): {e}")
         return headers
 
+    def _prove_wallet(self, headers: dict[str, str], endpoint: str) -> dict[str, str]:
+        """Add a signed agent proof to a paid-call leg that carries no signed
+        payment. The API spends an agent's credits, and shows them on a quote,
+        only for a caller that has proven it holds the wallet: ``X-Agent-ID``
+        alone is a public address. A leg with a real payment signature needs
+        none. The endpoints with durable admission read a ``submit`` proof.
+        An access-token session is already bound to its agent. A signing
+        failure is logged and the leg goes without, so the call is priced as
+        if the agent held no credits."""
+        if self._access_token:
+            return headers
+        scope = "submit" if _DURABLE_ADMISSION_ENDPOINT.search(endpoint) else "write"
+        try:
+            headers["x-agent-proof"] = sign_read_proof(self._private_key, self.address, scope=scope)
+        except Exception as e:  # noqa: BLE001
+            self._log(f"Failed to sign agent proof (continuing without; credits will not be used): {e}")
+        return headers
+
     def _write_headers(self, domain_name: str = "OneShot Agent Auth") -> dict[str, str]:
         """Like ``_read_headers`` but with a ``write``-scoped proof, for the
         signed mutation routes (budgets). The server enforces the proof on
@@ -646,6 +686,29 @@ class OneShotClient:
         if self.debug:
             print(f"[OneShot] {msg}")
 
+    async def _post_proved(self, client: httpx.AsyncClient, url: str, build_headers: Any, payload: dict[str, Any]) -> Any:
+        """POST a leg that proves the wallet. ``build_headers`` returns the headers
+        with a freshly signed proof each time it is called.
+
+        The API refuses a request whose proof it rejected, saying why (#1437). A
+        proof outside its window or sent twice is cured by signing a new one, so
+        the leg is sent again once. Any other reason, or a second refusal, is
+        raised with the reason. Nothing is paid in answer to this refusal.
+        """
+        resp = await client.post(url, headers=build_headers(), json=payload)
+        refusal = _parse_invalid_proof(resp)
+        if refusal is None:
+            return resp
+        reason, message = refusal
+        if reason in ("expired", "already_used"):
+            self._log(f"Wallet proof refused ({reason}); signing a new proof and retrying once")
+            resp = await client.post(url, headers=build_headers(), json=payload)
+            refusal = _parse_invalid_proof(resp)
+            if refusal is None:
+                return resp
+            reason, message = refusal
+        raise OneShotError(f"The API refused the wallet proof ({reason}): {message}")
+
     async def aensure_budgets_synced(self) -> None:
         """Push ``budgets`` / ``alert_email`` to the server once (async).
 
@@ -754,6 +817,44 @@ class OneShotClient:
             )
         )
 
+    def call_lookup(self, name: str, /, **params: Any) -> Any:
+        """Call a lookup tool by its manifest name, e.g. ``call_lookup("company_filings", cik="320193")``.
+
+        The tool's name is positional only, so a tool whose own input is called
+        ``name`` can be given it: ``call_lookup("company_legal_identifier", name="Apple Inc.")``.
+
+        Sends the params through :meth:`call_tool`. Params that are ``None`` are
+        left out. An unknown name raises ``ValidationError``; see
+        :func:`oneshot.lookup.lookup_tools` for the names.
+        """
+        entry = find_lookup_tool(name)
+        method, pricing, path, payload = lookup_request(entry, params)
+        if pricing in PAID_PRICING:
+            return self.call_tool(path, payload)
+        return asyncio.get_event_loop().run_until_complete(self._acall_free_lookup(method, path, payload))
+
+    async def acall_lookup(self, name: str, /, **params: Any) -> Any:
+        """Async form of :meth:`call_lookup`, sent through :meth:`acall_tool`."""
+        entry = find_lookup_tool(name)
+        method, pricing, path, payload = lookup_request(entry, params)
+        if pricing in PAID_PRICING:
+            return await self.acall_tool(path, payload)
+        return await self._acall_free_lookup(method, path, payload)
+
+    async def _acall_free_lookup(self, method: str, path: str, payload: dict[str, Any]) -> Any:
+        """A route with no payment of its own (a goal read or control, an inbox, a notification, a number or
+        account setting): a GET sends the params as the query, the other methods are write-scoped signed calls;
+        the ``{"success", "data"}`` envelope is stripped as the compute methods do."""
+        if method == "GET":
+            return self._unwrap_data(await self.acall_free_get(path, lookup_query(payload) or None))
+        if method == "PATCH":
+            return self._unwrap_data(await self.acall_free_patch(path, payload, scope="write"))
+        if method == "PUT":
+            return self._unwrap_data(await self.acall_free_put(path, payload))
+        if method == "DELETE":
+            return self._unwrap_data(await self.acall_free_delete(path, scope="write"))
+        return self._unwrap_data(await self.acall_free_post(path, payload, scope="write"))
+
     def wait_for_result(
         self,
         request_id: str,
@@ -850,10 +951,16 @@ class OneShotClient:
             # before they ever get to the 402 dance unless x-quote-id rides
             # on this very first attempt, so an already-obtained quote_id
             # must be sent from the start, not just on the paid retry.
-            initial_headers = self._with_approval(self._headers(max_cost=max_cost, idempotency_key=idempotency_key), approval_id)
-            if quote_id:
-                initial_headers["x-quote-id"] = quote_id
-            resp = await client.post(url, headers=initial_headers, json=payload)
+            initial_headers_base = self._with_approval(self._headers(max_cost=max_cost, idempotency_key=idempotency_key), approval_id)
+
+            def _initial_headers() -> dict[str, str]:
+                headers = dict(initial_headers_base)
+                self._prove_wallet(headers, endpoint)
+                if quote_id:
+                    headers["x-quote-id"] = quote_id
+                return headers
+
+            resp = await self._post_proved(client, url, _initial_headers, payload)
 
             # The spend-budget gate rejects at quote time (403) so nothing is
             # signed; surface it as the typed error.
@@ -981,13 +1088,21 @@ class OneShotClient:
                     resource=parsed_req.get("resource"),
                     extensions=parsed_req.get("extensions"),
                 )
-                headers = {
+                zero_cost_base = {
                     **self._with_approval(self._headers(max_cost=max_cost, idempotency_key=idempotency_key), approval_id),
                     "payment-signature": encode_payment_header(auth),
                 }
-                if quote_id:
-                    headers["x-quote-id"] = quote_id
-                resp2 = await client.post(url, headers=headers, json=payload)
+
+                def _zero_cost_headers() -> dict[str, str]:
+                    # The zero-cost authorization is an unsigned stub, so this leg
+                    # still has to prove the wallet for the credits to be spent.
+                    headers = dict(zero_cost_base)
+                    self._prove_wallet(headers, endpoint)
+                    if quote_id:
+                        headers["x-quote-id"] = quote_id
+                    return headers
+
+                resp2 = await self._post_proved(client, url, _zero_cost_headers, payload)
             else:
                 auth = sign_payment_authorization(
                     private_key=self._private_key,
@@ -1368,6 +1483,32 @@ class OneShotClient:
         """List tasks under a goal. Async."""
         return self._unwrap_data(await self.acall_free_get(f"/v1/compute/{goal_id}/tasks"))
 
+    def get_compute_outputs(self, goal_id: str) -> Any:
+        """List what a goal produced: the files its sandbox tasks left and the
+        tool results too large for a task row. The goal's short answer is
+        ``result`` on ``get_compute_goal``. Blocking."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.aget_compute_outputs(goal_id)
+        )
+
+    async def aget_compute_outputs(self, goal_id: str) -> Any:
+        """List what a goal produced. Async."""
+        return self._unwrap_data(await self.acall_free_get(f"/v1/compute/{goal_id}/outputs"))
+
+    def get_compute_output(self, goal_id: str, key: str) -> Any:
+        """Read one output of a goal by the ``key`` from ``get_compute_outputs``
+        (or a task's ``outputs``). ``content`` is None when the output was too
+        large to keep (``readable`` False). Blocking."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.aget_compute_output(goal_id, key)
+        )
+
+    async def aget_compute_output(self, goal_id: str, key: str) -> Any:
+        """Read one output of a goal. Async."""
+        # The key is a path: keep its slashes, escape everything else.
+        path = "/".join(quote(part, safe="") for part in key.split("/"))
+        return self._unwrap_data(await self.acall_free_get(f"/v1/compute/{goal_id}/outputs/{path}"))
+
     def get_compute_budget(self, goal_id: str) -> Any:
         """Get budget breakdown. Blocking."""
         return asyncio.get_event_loop().run_until_complete(
@@ -1379,7 +1520,12 @@ class OneShotClient:
         return self._unwrap_data(await self.acall_free_get(f"/v1/compute/{goal_id}/budget"))
 
     def cancel_compute_goal(self, goal_id: str, reason: Optional[str] = None) -> Any:
-        """Cancel a goal; remaining budget is credited. Blocking."""
+        """Cancel a goal; remaining budget is credited. Blocking.
+
+        When reservations are still in flight the server answers 202 and the
+        refund is deferred: the result then has ``status == "pending_settlement"``
+        (no exception is raised).
+        """
         return asyncio.get_event_loop().run_until_complete(
             self.acancel_compute_goal(goal_id, reason)
         )
@@ -1387,11 +1533,17 @@ class OneShotClient:
     async def acancel_compute_goal(
         self, goal_id: str, reason: Optional[str] = None
     ) -> Any:
-        """Cancel a goal; remaining budget is credited. Async."""
+        """Cancel a goal; remaining budget is credited. Async.
+
+        A 202 ``pending_settlement`` answer is returned as a result, not raised.
+        """
         payload: dict[str, Any] = {"reason": reason} if reason is not None else {}
-        return self._unwrap_data(
+        result = self._unwrap_data(
             await self.acall_free_post(f"/v1/compute/{goal_id}/cancel", payload, scope="write")
         )
+        if isinstance(result, dict) and result.get("status") == "pending_settlement":
+            result = {"goal_id": goal_id, **{k: v for k, v in result.items() if k != "success"}}
+        return result
 
     def respond_to_compute_task(
         self,
@@ -1460,7 +1612,11 @@ class OneShotClient:
         )
 
     async def afund_compute_goal(self, goal_id: str, amount: float) -> Any:
-        """Top up budget on a recurring goal. Quote+pay (x402) via `acall_tool`."""
+        """Top up budget on a recurring goal, or on any goal that ended with
+        ``end_reason == "budget_exhausted"`` (it is set back to ``active`` and woken, keeping
+        its tasks and workspace). Other endings and passed deadlines are refused; a refund
+        still settling answers a retryable ``refund_pending`` (409). Quote+pay (x402) via
+        `acall_tool`."""
         if not amount or amount <= 0:
             raise ValidationError("amount must be a positive number", "amount")
         return await self.acall_tool(
@@ -1949,29 +2105,29 @@ class OneShotClient:
         """Enrich a company from domain, name, LinkedIn URL, or ticker. Async."""
         return await self.acall_tool("/v1/tools/enrich/company", kwargs)
 
-    def local_search(self, **kwargs: Any) -> Any:
+    def business_find(self, **kwargs: Any) -> Any:
         """Discover local businesses (restaurants, contractors, practices) by category/keywords x location. Blocking."""
-        return self.call_tool("/v1/tools/local/search", kwargs)
+        return self.call_tool("/v1/tools/find/business", kwargs)
 
-    async def alocal_search(self, **kwargs: Any) -> Any:
+    async def abusiness_find(self, **kwargs: Any) -> Any:
         """Discover local businesses (restaurants, contractors, practices) by category/keywords x location. Async."""
-        return await self.acall_tool("/v1/tools/local/search", kwargs)
+        return await self.acall_tool("/v1/tools/find/business", kwargs)
 
-    def local_resolve(self, name: str, **kwargs: Any) -> Any:
+    def business_resolve(self, name: str, **kwargs: Any) -> Any:
         """Resolve a business name + one locating field (address/city/postal_code/phone) to its domain, phone, status. Blocking."""
-        return self.call_tool("/v1/tools/local/resolve", {"name": name, **kwargs})
+        return self.call_tool("/v1/tools/resolve/business", {"name": name, **kwargs})
 
-    async def alocal_resolve(self, name: str, **kwargs: Any) -> Any:
+    async def abusiness_resolve(self, name: str, **kwargs: Any) -> Any:
         """Resolve a business name + one locating field (address/city/postal_code/phone) to its domain, phone, status. Async."""
-        return await self.acall_tool("/v1/tools/local/resolve", {"name": name, **kwargs})
+        return await self.acall_tool("/v1/tools/resolve/business", {"name": name, **kwargs})
 
-    def gov_solicitations(self, naics: list[str], **kwargs: Any) -> Any:
+    def record_solicitations_find(self, naics: list[str], **kwargs: Any) -> Any:
         """Federal Sources Sought / Presolicitation notices (SAM.gov) by NAICS code with the contracting officer's contact. Result carries `data_as_of` (snapshot behind the rows). Blocking."""
-        return self.call_tool("/v1/tools/gov/solicitations", {"naics": naics, **kwargs})
+        return self.call_tool("/v1/tools/find/record-solicitations", {"naics": naics, **kwargs})
 
-    async def agov_solicitations(self, naics: list[str], **kwargs: Any) -> Any:
+    async def arecord_solicitations_find(self, naics: list[str], **kwargs: Any) -> Any:
         """Federal Sources Sought / Presolicitation notices (SAM.gov) by NAICS code with the contracting officer's contact. Result carries `data_as_of` (snapshot behind the rows). Async."""
-        return await self.acall_tool("/v1/tools/gov/solicitations", {"naics": naics, **kwargs})
+        return await self.acall_tool("/v1/tools/find/record-solicitations", {"naics": naics, **kwargs})
 
     def find_email(self, company_domain: str, *, full_name: Optional[str] = None, first_name: Optional[str] = None, last_name: Optional[str] = None, **kwargs: Any) -> Any:
         """Find a person's email address. Blocking."""
@@ -2077,6 +2233,16 @@ class OneShotClient:
         """Build a website. Async."""
         return await self.acall_tool("/v1/tools/build", {"product": product, **kwargs})
 
+    def update_build(self, build_id: str, changes: str, **kwargs: Any) -> Any:
+        """Apply natural-language changes to an existing build (same route as build). Blocking."""
+        transport = {k: kwargs.pop(k) for k in _BUILD_TRANSPORT_KWARGS if k in kwargs}
+        return self.call_tool("/v1/tools/build", {"build_id": build_id, "changes": changes, **kwargs}, **transport)
+
+    async def aupdate_build(self, build_id: str, changes: str, **kwargs: Any) -> Any:
+        """Apply natural-language changes to an existing build (same route as build). Async."""
+        transport = {k: kwargs.pop(k) for k in _BUILD_TRANSPORT_KWARGS if k in kwargs}
+        return await self.acall_tool("/v1/tools/build", {"build_id": build_id, "changes": changes, **kwargs}, **transport)
+
     def get_balance(self) -> dict:
         """Get unified balance (on-chain USDC + credits). Blocking."""
         return self.call_free_get("/v1/tools/balance")
@@ -2085,6 +2251,69 @@ class OneShotClient:
         """Get unified balance (on-chain USDC + credits). Async."""
         return await self.acall_free_get("/v1/tools/balance")
 
+    # Inboxes and notifications (#1273). Free signed reads and writes of the agent's own data.
+
+    @staticmethod
+    def _inbox_params(**values: Any) -> Optional[dict[str, str]]:
+        params = {k: ("true" if v is True else "false" if v is False else str(v)) for k, v in values.items() if v is not None}
+        return params or None
+
+    def inbox(self, *, since: Optional[str] = None, limit: Optional[int] = None, include_body: Optional[bool] = None) -> Any:
+        """List emails received by the agent, newest first. Free. Blocking."""
+        return self.call_free_get("/v1/tools/inbox", self._inbox_params(since=since, limit=limit, include_body=include_body))
+
+    async def ainbox(self, *, since: Optional[str] = None, limit: Optional[int] = None, include_body: Optional[bool] = None) -> Any:
+        """List emails received by the agent, newest first. Free. Async."""
+        return await self.acall_free_get("/v1/tools/inbox", self._inbox_params(since=since, limit=limit, include_body=include_body))
+
+    def inbox_get(self, email_id: str) -> Any:
+        """One received email with its body and attachments. Free. Blocking."""
+        return self.call_free_get(f"/v1/tools/inbox/{quote(email_id, safe='')}")
+
+    async def ainbox_get(self, email_id: str) -> Any:
+        """One received email with its body and attachments. Free. Async."""
+        return await self.acall_free_get(f"/v1/tools/inbox/{quote(email_id, safe='')}")
+
+    def sms_inbox(self, *, since: Optional[str] = None, limit: Optional[int] = None, from_number: Optional[str] = None) -> Any:
+        """List text messages received by the agent. Free. Blocking."""
+        return self.call_free_get("/v1/tools/sms/inbox", self._inbox_params(since=since, limit=limit, **{"from": from_number}))
+
+    async def asms_inbox(self, *, since: Optional[str] = None, limit: Optional[int] = None, from_number: Optional[str] = None) -> Any:
+        """List text messages received by the agent. Free. Async."""
+        return await self.acall_free_get("/v1/tools/sms/inbox", self._inbox_params(since=since, limit=limit, **{"from": from_number}))
+
+    def sms_inbox_get(self, message_id: str) -> Any:
+        """One received text message. Free. Blocking."""
+        return self.call_free_get(f"/v1/tools/sms/inbox/{quote(message_id, safe='')}")
+
+    async def asms_inbox_get(self, message_id: str) -> Any:
+        """One received text message. Free. Async."""
+        return await self.acall_free_get(f"/v1/tools/sms/inbox/{quote(message_id, safe='')}")
+
+    def notifications(self, *, unread: Optional[bool] = None, limit: Optional[int] = None) -> Any:
+        """List the agent's notifications (job completions, failures, budget warnings). Free. Blocking."""
+        return self.call_free_get("/v1/tools/notifications", self._inbox_params(unread=unread, limit=limit))
+
+    async def anotifications(self, *, unread: Optional[bool] = None, limit: Optional[int] = None) -> Any:
+        """List the agent's notifications (job completions, failures, budget warnings). Free. Async."""
+        return await self.acall_free_get("/v1/tools/notifications", self._inbox_params(unread=unread, limit=limit))
+
+    def mark_notification_read(self, notification_id: str) -> Any:
+        """Mark one notification as read. Free. Blocking."""
+        return self.call_free_patch(f"/v1/tools/notifications/{quote(notification_id, safe='')}/read", scope="write")
+
+    async def amark_notification_read(self, notification_id: str) -> Any:
+        """Mark one notification as read. Free. Async."""
+        return await self.acall_free_patch(f"/v1/tools/notifications/{quote(notification_id, safe='')}/read", scope="write")
+
+    def mark_all_notifications_read(self) -> Any:
+        """Mark every notification as read. Free. Blocking."""
+        return self.call_free_patch("/v1/tools/notifications/read-all", scope="write")
+
+    async def amark_all_notifications_read(self) -> Any:
+        """Mark every notification as read. Free. Async."""
+        return await self.acall_free_patch("/v1/tools/notifications/read-all", scope="write")
+
     # `pause`/`resume` sit behind the API's paidEndpointLimiter (a rate limiter,
     # not a price) — no x402 quote, so they use `call_free_post`, not `call_tool`.
 
@@ -2118,7 +2347,7 @@ class OneShotClient:
 
     async def apause_domain(self, domain: str) -> DomainPoolStatusResult:
         """Take a domain out of rotation without releasing it. Async."""
-        return await self.acall_free_post(self._domain_action_path(domain, "pause"))
+        return await self.acall_free_post(self._domain_action_path(domain, "pause"), scope="write")
 
     def resume_domain(self, domain: str) -> DomainPoolStatusResult:
         """Put a paused domain back into rotation. Blocking."""
@@ -2130,7 +2359,7 @@ class OneShotClient:
         Reputation pauses (`pause_reason='low_reputation'`) auto-recover once the
         domain is warmed again; a manual pause needs this call.
         """
-        return await self.acall_free_post(self._domain_action_path(domain, "resume"))
+        return await self.acall_free_post(self._domain_action_path(domain, "resume"), scope="write")
 
     @staticmethod
     def _domain_action_path(domain: str, action: str) -> str: