oneshot-python 0.37.0__tar.gz → 0.39.0__tar.gz

{oneshot_python-0.37.0 → oneshot_python-0.39.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: oneshot-python
-Version: 0.37.0
+Version: 0.39.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.37.0 → oneshot_python-0.39.0}/README.md

@@ -244,7 +244,7 @@ except LinkedInConnectRequiredError:
 
 Account reads stop offering reconnect after confirming upstream deletion.
 Missing accounts are excluded from the active list; `include_revoked=True`
-lets you inspect their `deleted_upstream` status and `reconnect_required=False`.
+lets you inspect their `connection_deleted` status and `reconnect_required=False`.
 Authentication failures and timeouts remain ordinary errors and do not instruct
 the consumer to create a new connection.
 
@@ -315,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+
@@ -324,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.37.0 → oneshot_python-0.39.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.37.0 → oneshot_python-0.39.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.37.0 → oneshot_python-0.39.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,13 +60,13 @@ try:
 
     SDK_VERSION = _pkg_version("oneshot-python")
 except Exception:  # pragma: no cover - editable/source runs without dist metadata
-    SDK_VERSION = "0.37.0"
+    SDK_VERSION = "0.39.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)$")
+_DURABLE_ADMISSION_ENDPOINT = re.compile(r"(lookup/person-(profile|email|email-status)|lookup/place-permits|physical-mail/send)$")
 _CHAIN_ID = 8453
 _USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
 
@@ -74,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(
@@ -159,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`.
 
@@ -666,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).
 
@@ -774,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,
@@ -870,11 +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)
-            self._prove_wallet(initial_headers, endpoint)
-            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.
@@ -1002,16 +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),
                 }
-                # The zero-cost authorization is an unsigned stub, so this leg
-                # still has to prove the wallet for the credits to be spent.
-                self._prove_wallet(headers, endpoint)
-                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,
@@ -1429,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)
         )
@@ -1437,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,
@@ -1510,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(
@@ -1967,63 +2073,63 @@ class OneShotClient:
         approval_id = kwargs.pop("approval_id", None)
         return await self.acall_tool("/v1/tools/sms/send", {"message": message, "to_number": to_number, **kwargs}, approval_id=approval_id)
 
-    def people_search(self, **kwargs: Any) -> Any:
+    def person_find(self, **kwargs: Any) -> Any:
         """Search for people by job title, company, etc. Blocking."""
-        return self.call_tool("/v1/tools/research/people", kwargs)
+        return self.call_tool("/v1/tools/find/person", kwargs)
 
-    async def apeople_search(self, **kwargs: Any) -> Any:
+    async def aperson_find(self, **kwargs: Any) -> Any:
         """Search for people by job title, company, etc. Async."""
-        return await self.acall_tool("/v1/tools/research/people", kwargs)
+        return await self.acall_tool("/v1/tools/find/person", kwargs)
 
-    def enrich_profile(self, **kwargs: Any) -> Any:
+    def person_profile(self, **kwargs: Any) -> Any:
         """Enrich a person's profile from LinkedIn URL, email, or name. Blocking."""
-        return self.call_tool("/v1/tools/enrich/profile", kwargs)
+        return self.call_tool("/v1/tools/lookup/person-profile", kwargs)
 
-    async def aenrich_profile(self, **kwargs: Any) -> Any:
+    async def aperson_profile(self, **kwargs: Any) -> Any:
         """Enrich a person's profile from LinkedIn URL, email, or name. Async."""
-        return await self.acall_tool("/v1/tools/enrich/profile", kwargs)
+        return await self.acall_tool("/v1/tools/lookup/person-profile", kwargs)
 
-    def company_search(self, **kwargs: Any) -> Any:
+    def company_find(self, **kwargs: Any) -> Any:
         """Search for companies by name, domain, industry, location, size, etc. Blocking."""
-        return self.call_tool("/v1/tools/research/company", kwargs)
+        return self.call_tool("/v1/tools/find/company", kwargs)
 
-    async def acompany_search(self, **kwargs: Any) -> Any:
+    async def acompany_find(self, **kwargs: Any) -> Any:
         """Search for companies by name, domain, industry, location, size, etc. Async."""
-        return await self.acall_tool("/v1/tools/research/company", kwargs)
+        return await self.acall_tool("/v1/tools/find/company", kwargs)
 
-    def enrich_company(self, **kwargs: Any) -> Any:
+    def company_profile(self, **kwargs: Any) -> Any:
         """Enrich a company from domain, name, LinkedIn URL, or ticker. Blocking."""
-        return self.call_tool("/v1/tools/enrich/company", kwargs)
+        return self.call_tool("/v1/tools/lookup/company-profile", kwargs)
 
-    async def aenrich_company(self, **kwargs: Any) -> Any:
+    async def acompany_profile(self, **kwargs: Any) -> Any:
         """Enrich a company from domain, name, LinkedIn URL, or ticker. Async."""
-        return await self.acall_tool("/v1/tools/enrich/company", kwargs)
+        return await self.acall_tool("/v1/tools/lookup/company-profile", 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:
+    def person_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."""
         payload: dict[str, Any] = {"company_domain": company_domain, **kwargs}
         if full_name:
@@ -2032,9 +2138,9 @@ class OneShotClient:
             payload["first_name"] = first_name
         if last_name:
             payload["last_name"] = last_name
-        return self.call_tool("/v1/tools/enrich/email", payload)
+        return self.call_tool("/v1/tools/lookup/person-email", payload)
 
-    async def afind_email(self, company_domain: str, *, full_name: Optional[str] = None, first_name: Optional[str] = None, last_name: Optional[str] = None, **kwargs: Any) -> Any:
+    async def aperson_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. Async."""
         payload: dict[str, Any] = {"company_domain": company_domain, **kwargs}
         if full_name:
@@ -2043,63 +2149,63 @@ class OneShotClient:
             payload["first_name"] = first_name
         if last_name:
             payload["last_name"] = last_name
-        return await self.acall_tool("/v1/tools/enrich/email", payload)
+        return await self.acall_tool("/v1/tools/lookup/person-email", payload)
 
-    def verify_email(self, email: str) -> Any:
+    def person_email_status(self, email: str) -> Any:
         """Verify email deliverability. Blocking."""
-        return self.call_tool("/v1/tools/verify/email", {"email": email})
+        return self.call_tool("/v1/tools/lookup/person-email-status", {"email": email})
 
-    async def averify_email(self, email: str) -> Any:
+    async def aperson_email_status(self, email: str) -> Any:
         """Verify email deliverability. Async."""
-        return await self.acall_tool("/v1/tools/verify/email", {"email": email})
+        return await self.acall_tool("/v1/tools/lookup/person-email-status", {"email": email})
 
-    def deep_research_person(self, **kwargs: Any) -> Any:
+    def person_dossier(self, **kwargs: Any) -> Any:
         """Deep research on a person. Blocking."""
-        return self.call_tool("/v1/tools/research/person", kwargs)
+        return self.call_tool("/v1/tools/lookup/person-dossier", kwargs)
 
-    async def adeep_research_person(self, **kwargs: Any) -> Any:
+    async def aperson_dossier(self, **kwargs: Any) -> Any:
         """Deep research on a person. Async."""
-        return await self.acall_tool("/v1/tools/research/person", kwargs)
+        return await self.acall_tool("/v1/tools/lookup/person-dossier", kwargs)
 
-    def social_profiles(self, **kwargs: Any) -> Any:
+    def person_social_accounts(self, **kwargs: Any) -> Any:
         """Discover social media profiles. Blocking."""
-        return self.call_tool("/v1/tools/research/social", kwargs)
+        return self.call_tool("/v1/tools/lookup/person-social-accounts", kwargs)
 
-    async def asocial_profiles(self, **kwargs: Any) -> Any:
+    async def aperson_social_accounts(self, **kwargs: Any) -> Any:
         """Discover social media profiles. Async."""
-        return await self.acall_tool("/v1/tools/research/social", kwargs)
+        return await self.acall_tool("/v1/tools/lookup/person-social-accounts", kwargs)
 
-    def article_search(self, name: str, company: str, **kwargs: Any) -> Any:
+    def person_articles(self, name: str, company: str, **kwargs: Any) -> Any:
         """Find articles by or about a person. Blocking."""
-        return self.call_tool("/v1/tools/research/articles", {"name": name, "company": company, **kwargs})
+        return self.call_tool("/v1/tools/lookup/person-articles", {"name": name, "company": company, **kwargs})
 
-    async def aarticle_search(self, name: str, company: str, **kwargs: Any) -> Any:
+    async def aperson_articles(self, name: str, company: str, **kwargs: Any) -> Any:
         """Find articles by or about a person. Async."""
-        return await self.acall_tool("/v1/tools/research/articles", {"name": name, "company": company, **kwargs})
+        return await self.acall_tool("/v1/tools/lookup/person-articles", {"name": name, "company": company, **kwargs})
 
-    def person_newsfeed(self, social_media_url: str, **kwargs: Any) -> Any:
+    def person_posts(self, social_media_url: str, **kwargs: Any) -> Any:
         """Get recent social posts from a person. Blocking."""
-        return self.call_tool("/v1/tools/research/newsfeed", {"social_media_url": social_media_url, **kwargs})
+        return self.call_tool("/v1/tools/lookup/person-posts", {"social_media_url": social_media_url, **kwargs})
 
-    async def aperson_newsfeed(self, social_media_url: str, **kwargs: Any) -> Any:
+    async def aperson_posts(self, social_media_url: str, **kwargs: Any) -> Any:
         """Get recent social posts from a person. Async."""
-        return await self.acall_tool("/v1/tools/research/newsfeed", {"social_media_url": social_media_url, **kwargs})
+        return await self.acall_tool("/v1/tools/lookup/person-posts", {"social_media_url": social_media_url, **kwargs})
 
     def person_interests(self, **kwargs: Any) -> Any:
         """Analyze a person's interests from their digital footprint. Blocking."""
-        return self.call_tool("/v1/tools/research/interests", kwargs)
+        return self.call_tool("/v1/tools/lookup/person-interests", kwargs)
 
     async def aperson_interests(self, **kwargs: Any) -> Any:
         """Analyze a person's interests from their digital footprint. Async."""
-        return await self.acall_tool("/v1/tools/research/interests", kwargs)
+        return await self.acall_tool("/v1/tools/lookup/person-interests", kwargs)
 
-    def person_interactions(self, social_media_url: str, **kwargs: Any) -> Any:
+    def person_followers(self, social_media_url: str, **kwargs: Any) -> Any:
         """Get a person's social interactions. Blocking."""
-        return self.call_tool("/v1/tools/research/interactions", {"social_media_url": social_media_url, **kwargs})
+        return self.call_tool("/v1/tools/lookup/person-followers", {"social_media_url": social_media_url, **kwargs})
 
-    async def aperson_interactions(self, social_media_url: str, **kwargs: Any) -> Any:
+    async def aperson_followers(self, social_media_url: str, **kwargs: Any) -> Any:
         """Get a person's social interactions. Async."""
-        return await self.acall_tool("/v1/tools/research/interactions", {"social_media_url": social_media_url, **kwargs})
+        return await self.acall_tool("/v1/tools/lookup/person-followers", {"social_media_url": social_media_url, **kwargs})
 
     def commerce_search(self, query: str, *, limit: int = 10, **kwargs: Any) -> Any:
         """Search for products. Blocking."""
@@ -2127,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")
@@ -2135,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`.
 
@@ -2336,8 +2515,8 @@ class OneShotClient:
     @staticmethod
     def _is_phones_pending(result: Any) -> bool:
         """Detects whether a result is awaiting Apollo's async phone-reveal
-        webhook. Tolerates two shapes: the unwrapped result ``{phones_pending}``
-        and the deep_research_person wrapper ``{result: {phones_pending}}``.
+        webhook. Accepts legacy flat results and person_dossier's
+        ``result.profile.data.phones_pending``.
 
         Mirrors the TS SDK's _isPhonesPending — kept in lockstep so the worker
         contract works for both SDKs.
@@ -2349,6 +2528,10 @@ class OneShotClient:
         inner = result.get("result")
         if isinstance(inner, dict) and inner.get("phones_pending") is True:
             return True
+        profile = inner.get("profile") if isinstance(inner, dict) else None
+        data = profile.get("data") if isinstance(profile, dict) else None
+        if isinstance(data, dict) and data.get("phones_pending") is True:
+            return True
         return False
 
     async def _poll_for_phones(