oneshot-python 0.20.2__tar.gz → 0.24.0__tar.gz

{oneshot_python-0.20.2 → oneshot_python-0.24.0}/.gitignore

@@ -1,5 +1,6 @@
 # Dependencies
 node_modules
+packages/mcp-server/node_modules/
 .pnp
 .pnp.js
 

{oneshot_python-0.20.2 → oneshot_python-0.24.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: oneshot-python
-Version: 0.20.2
-Summary: Core Python SDK for the OneShot API — HTTP client with x402 payment handling
+Version: 0.24.0
+Summary: Core Python SDK for the OneShot API — HTTP client with x402 payment handling — 35 tools
 License-Expression: MIT
 Requires-Python: >=3.10
 Requires-Dist: eth-account>=0.13.0

{oneshot_python-0.20.2 → oneshot_python-0.24.0}/README.md

@@ -192,7 +192,7 @@ Every method has an `a*` async mirror (`acompute`, `aget_compute_goal`, …).
 ## Links
 
 - [Documentation](https://docs.oneshotagent.com/sdk/installation#install-via-pip-python)
-- [LangChain integration](https://pypi.org/project/langchain-oneshot/) — 34 tools as LangChain BaseTool
+- [LangChain integration](https://pypi.org/project/langchain-oneshot/) — 35 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)
@@ -201,3 +201,16 @@ Every method has an `a*` async mirror (`acompute`, `aget_compute_goal`, …).
 ## License
 
 MIT
+
+### 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 creating another charge. Postal delivery does not prove readership; paid receipts and fulfillment events remain separate. Lob credentials stay on OneShot's server.
+
+
+### Account login and 2FA (0.24.0+)
+
+Use `create_browser_profile(name)`, then `start_browser_profile_setup(profile_id, login_url)`. Poll `get_browser_profile_setup(profile_id)` until `status` is `idle`, and show the private `live_url` to the user. The live browser currently uses the Browser-Use domain. The user enters their credentials and completes 2FA there; after they finish, call `finish_browser_profile_setup(profile_id)` to save the session. Async variants use an `a` prefix.
+
+Finish inspects cookie metadata in a fresh browser before navigation, without returning values. Later `browser(profile_id=..., task=...)` calls reuse the saved profile; verify site authentication with a read before relying on it. Setup expires after 15 minutes, with abandoned-session cleanup by the lifecycle sweep; the profile is retained for reconnection. Never log private live URLs or put credentials/codes in task prompts.
+
+Alternatively, `create_browser_profile(name, cookies=[...])` or `storage_state={...}` imports cookies and localStorage. The legacy browser `secrets` field is rejected, and `max_steps` must be an integer from 25 through 100. Failed `JobError`s expose `code` and `partial_result`. Browser `cost` is provider cost; `billed_cost` is the reconciled customer charge, or null while pending.

{oneshot_python-0.20.2 → oneshot_python-0.24.0}/oneshot/__init__.py

@@ -1,5 +1,7 @@
 """oneshot-python — Core Python SDK for the OneShot API."""
 
+from oneshot.physical_mail import PhysicalMail, PostalAddress, MailQuote, MailOrder
+
 from oneshot._errors import (
     BudgetExceededError,
     BudgetSyncError,
@@ -34,6 +36,7 @@ from oneshot.client import OneShotClient
 from oneshot.x402 import sign_payment_authorization
 
 __all__ = [
+    "PhysicalMail", "PostalAddress", "MailQuote", "MailOrder",
     "OneShotClient",
     "OneShotError",
     "ToolError",

{oneshot_python-0.20.2 → oneshot_python-0.24.0}/oneshot/_errors.py

@@ -44,10 +44,12 @@ class PaymentError(OneShotError):
 class JobError(OneShotError):
     """Async job completed with an error."""
 
-    def __init__(self, message: str, job_id: str, job_error: str) -> None:
+    def __init__(self, message: str, job_id: str, job_error: str, code: str | None = None, partial_result: dict | None = None) -> None:
         super().__init__(message)
         self.job_id = job_id
         self.job_error = job_error
+        self.code = code
+        self.partial_result = partial_result
 
 
 class JobTimeoutError(OneShotError):

{oneshot_python-0.20.2 → oneshot_python-0.24.0}/oneshot/client.py

@@ -51,7 +51,7 @@ try:
 
     SDK_VERSION = _pkg_version("oneshot-python")
 except Exception:  # pragma: no cover - editable/source runs without dist metadata
-    SDK_VERSION = "0.20.2"
+    SDK_VERSION = "0.24.0"
 
 # ---------------------------------------------------------------------------
 # Environment configuration
@@ -95,13 +95,26 @@ def _build_email_payload(
             raise ValidationError("to is required unless reply_to_email_id is set", "to")
         if not subject:
             raise ValidationError("subject is required unless reply_to_email_id is set", "subject")
-    mailbox = from_mailbox or "agent"
-    domain = from_domain or "oneshotagent.com"
+    # Rotation mode: when the caller passes neither from_domain nor
+    # from_mailbox, omit from_address entirely so the server picks from the
+    # agent's domain pool (mirrors the TS SDK's rotation contract). Pinning
+    # from_mailbox alone has no domain to attach it to — "oneshotagent.com"
+    # is OneShot's own domain and no agent can send from it — so that
+    # combination is a client-side error rather than a guaranteed
+    # domain_not_owned rejection from the server.
     payload: dict[str, Any] = {
-        "from_address": f"{mailbox}@{domain}",
         "body": body,
         **extra,
     }
+    if from_domain:
+        mailbox = from_mailbox or "agent"
+        payload["from_address"] = f"{mailbox}@{from_domain}"
+    elif from_mailbox:
+        raise ValidationError(
+            "from_mailbox was pinned without from_domain. Pass from_domain (a domain you own) as well, "
+            "or omit both to rotate across your warmed domains.",
+            "from_domain",
+        )
     if to is not None:
         payload["to_address"] = to
     if subject is not None:
@@ -313,6 +326,11 @@ class OneShotClient:
             headers["X-Max-Cost-USDC"] = str(max_cost)
         return headers
 
+    @property
+    def physical_mail(self):
+        from oneshot.physical_mail import PhysicalMail
+        return PhysicalMail(self)
+
     def _read_headers(self) -> dict[str, str]:
         """Auth headers plus a signed EIP-712 read proof (x-agent-proof) for the
         free READ routes (inbox, sms inbox, notifications, balance, browser
@@ -500,11 +518,17 @@ class OneShotClient:
         wait: bool = True,
         wait_for_phones: bool = False,
         phone_timeout_sec: int = 360,
+        quote_id: Optional[str] = None,
     ) -> Any:
         """Execute a paid tool call (async). Handles the full x402 flow.
 
         With ``wait=False`` a queued job is returned as
         ``{"request_id": ..., "status": ...}`` instead of being polled.
+
+        Pass ``quote_id`` when the caller already obtained a quote for this
+        exact request (e.g. ``/email/send`` after ``/email/quote``) — it rides
+        on the ``x-quote-id`` header from the very first attempt, since
+        quote-based routes reject before the 402 dance even starts without it.
         """
         memo = payload.get("memo")
         if memo is not None:
@@ -535,8 +559,15 @@ class OneShotClient:
         await self.aensure_budgets_synced()
 
         async with httpx.AsyncClient(timeout=httpx.Timeout(120.0)) as client:
-            # Step 1 — Initial POST (expect 402 for paid tools)
-            resp = await client.post(url, headers=self._headers(max_cost=max_cost), json=payload)
+            # Step 1 — Initial POST (expect 402 for paid tools). Quote-based
+            # routes (e.g. /email/send) reject with 400 quote_id_required
+            # 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._headers(max_cost=max_cost)
+            if quote_id:
+                initial_headers["x-quote-id"] = quote_id
+            resp = await client.post(url, headers=initial_headers, json=payload)
 
             # The spend-budget gate rejects at quote time (403) so nothing is
             # signed; surface it as the typed error.
@@ -592,7 +623,12 @@ class OneShotClient:
             quote_data = resp.json()
             payment_request = quote_data["payment_request"]
             context = quote_data.get("context", {})
-            quote_id = context.get("quote_id")
+            # Self-quoting tools (voice/sms/browser/compute) mint a fresh
+            # quote_id in this same 402's context; quote-then-send tools
+            # (email/send) already had one supplied by the caller and don't
+            # get one echoed back here — keep it rather than clobbering it
+            # with None, or the paid retry below loses x-quote-id entirely.
+            quote_id = context.get("quote_id") or quote_id
 
             total = context.get("total") or context.get("pricing", {}).get("total")
             if max_cost is not None and total is not None:
@@ -727,7 +763,7 @@ class OneShotClient:
     ) -> Any:
         """POST to a free endpoint (async)."""
         url = f"{self.base_url}{endpoint}"
-        async with httpx.AsyncClient(timeout=httpx.Timeout(30.0)) as client:
+        async with httpx.AsyncClient(timeout=httpx.Timeout(150.0 if endpoint.startswith("/v1/tools/browser/profiles") else 30.0)) as client:
             resp = await client.post(url, headers=self._read_headers(), json=payload or {})
             if not resp.is_success:
                 raise ToolError(f"POST {endpoint} failed", resp.status_code, resp.text)
@@ -1047,6 +1083,10 @@ class OneShotClient:
         timeout_sec: int = 300,
     ) -> Any:
         """Run a browser automation task. Async."""
+        if secrets is not None:
+            raise ValueError("Browser secrets are unsupported; import cookies or storage_state into a profile")
+        if max_steps is not None and (type(max_steps) is not int or not 25 <= max_steps <= 100):
+            raise ValueError("max_steps must be an integer between 25 and 100")
         payload: dict[str, Any] = {"task": task}
         if output_schema is not None:
             payload["output_schema"] = output_schema
@@ -1056,21 +1096,53 @@ class OneShotClient:
             payload["allowed_domains"] = allowed_domains
         if profile_id is not None:
             payload["profile_id"] = profile_id
-        if secrets is not None:
-            payload["secrets"] = secrets
         if max_steps is not None:
             payload["max_steps"] = max_steps
         return await self.acall_tool(
             "/v1/tools/browser", payload, max_cost=max_cost, timeout_sec=timeout_sec,
         )
 
-    def create_browser_profile(self, name: str) -> dict:
+    def create_browser_profile(self, name: str, *, cookies: Optional[list] = None, storage_state: Optional[dict] = None) -> dict:
         """Create a persistent browser profile. Blocking."""
-        return self.call_free_post("/v1/tools/browser/profiles", {"name": name})
-
-    async def acreate_browser_profile(self, name: str) -> dict:
+        if cookies is not None and storage_state is not None:
+            raise ValueError("Provide cookies or storage_state, not both")
+        payload = {"name": name}
+        if cookies is not None:
+            payload["cookies"] = cookies
+        if storage_state is not None:
+            payload["storage_state"] = storage_state
+        return self.call_free_post("/v1/tools/browser/profiles", payload)
+
+    async def acreate_browser_profile(self, name: str, *, cookies: Optional[list] = None, storage_state: Optional[dict] = None) -> dict:
         """Create a persistent browser profile. Async."""
-        return await self.acall_free_post("/v1/tools/browser/profiles", {"name": name})
+        if cookies is not None and storage_state is not None:
+            raise ValueError("Provide cookies or storage_state, not both")
+        payload = {"name": name}
+        if cookies is not None:
+            payload["cookies"] = cookies
+        if storage_state is not None:
+            payload["storage_state"] = storage_state
+        return await self.acall_free_post("/v1/tools/browser/profiles", payload)
+
+    def start_browser_profile_setup(self, profile_id: str, start_url: str) -> dict:
+        """Open login/2FA live view. Do not log the returned live_url."""
+        return self.call_free_post(f"/v1/tools/browser/profiles/{quote(profile_id, safe='')}/setup/start", {"start_url": start_url})
+
+    async def astart_browser_profile_setup(self, profile_id: str, start_url: str) -> dict:
+        return await self.acall_free_post(f"/v1/tools/browser/profiles/{quote(profile_id, safe='')}/setup/start", {"start_url": start_url})
+
+    def get_browser_profile_setup(self, profile_id: str) -> dict:
+        return self.call_free_post(f"/v1/tools/browser/profiles/{quote(profile_id, safe='')}/setup/status", {})
+
+    async def aget_browser_profile_setup(self, profile_id: str) -> dict:
+        return await self.acall_free_post(f"/v1/tools/browser/profiles/{quote(profile_id, safe='')}/setup/status", {})
+
+    def finish_browser_profile_setup(self, profile_id: str) -> dict:
+        """Save after human login/2FA; inspect saved cookies before navigation."""
+        return self.call_free_post(f"/v1/tools/browser/profiles/{quote(profile_id, safe='')}/setup/finish", {})
+
+    async def afinish_browser_profile_setup(self, profile_id: str) -> dict:
+        return await self.acall_free_post(f"/v1/tools/browser/profiles/{quote(profile_id, safe='')}/setup/finish", {})
 
     def list_browser_profiles(self) -> list:
         """List all browser profiles. Blocking."""
@@ -1155,9 +1227,13 @@ class OneShotClient:
         ``mailbox_mode == 'mailbox'``, and read ``mailbox_provisioning_fee`` on
         the quote for the exact amount before paying.
         """
-        return self.call_tool(
-            "/v1/tools/email/send",
-            _build_email_payload(to, subject, body, from_domain, from_mailbox, from_name, kwargs, reply_to_email_id=reply_to_email_id, mailbox_mode=mailbox_mode),
+        return asyncio.get_event_loop().run_until_complete(
+            self.aemail(
+                to, subject, body,
+                from_domain=from_domain, from_mailbox=from_mailbox, from_name=from_name,
+                reply_to_email_id=reply_to_email_id, mailbox_mode=mailbox_mode,
+                **kwargs,
+            )
         )
 
     async def aemail(
@@ -1181,12 +1257,53 @@ class OneShotClient:
 
         ``mailbox_mode`` ('relay' | 'mailbox', default 'relay') selects how a
         domain sends — see ``email()`` for details.
+
+        Quotes before sending — mirrors the TS SDK (``index.ts`` ``email()``).
+        ``/v1/tools/email/send`` requires an ``x-quote-id`` from a prior
+        ``/v1/tools/email/quote`` call and 400s without one, and rotation mode
+        (both ``from_domain``/``from_mailbox`` omitted) is decided at quote
+        time and locked server-side for the matching send — so quoting first
+        is not optional, it's the only way rotation (or any send) works.
         """
+        # max_cost/timeout_sec are transport options for acall_tool, not
+        # send-body fields — pull them out of kwargs before they reach
+        # _build_email_payload, or they'd ride along in the JSON body (which
+        # the server's Zod schema silently drops) instead of driving the
+        # X-Max-Cost-USDC header + local budget check and the poll timeout.
+        max_cost = kwargs.pop("max_cost", None)
+        timeout_sec = kwargs.pop("timeout_sec", 120)
+
+        # Quote payload mirrors the TS SDK's quote body: no from_name/extra
+        # kwargs (attachments, idempotencyKey, etc. are send-only concerns).
+        quote_payload = _build_email_payload(
+            to, subject, body, from_domain, from_mailbox, None, {},
+            reply_to_email_id=reply_to_email_id, mailbox_mode=mailbox_mode,
+        )
+        quote = await self.acall_tool(
+            "/v1/tools/email/quote", quote_payload, max_cost=max_cost,
+        )
+        quote_id = quote.get("quote_id") if isinstance(quote, dict) else None
+        quoted_from_address = quote.get("from_address") if isinstance(quote, dict) else None
+
+        send_payload = _build_email_payload(
+            to, subject, body, from_domain, from_mailbox, from_name, kwargs,
+            reply_to_email_id=reply_to_email_id, mailbox_mode=mailbox_mode,
+        )
+        # Replay the quote-locked/rotated address explicitly. The server
+        # already replays it from the quote row when from_address is absent,
+        # but sending it back is harmless and mirrors the TS SDK
+        # (index.ts:425,431) so a future /send-without-quote revision keeps
+        # working unchanged.
+        resolved_from_address = send_payload.get("from_address") or quoted_from_address
+        if resolved_from_address:
+            send_payload["from_address"] = resolved_from_address
+
         return await self.acall_tool(
-            "/v1/tools/email/send",
-            _build_email_payload(to, subject, body, from_domain, from_mailbox, from_name, kwargs, reply_to_email_id=reply_to_email_id, mailbox_mode=mailbox_mode),
+            "/v1/tools/email/send", send_payload, quote_id=quote_id,
+            max_cost=max_cost, timeout_sec=timeout_sec,
         )
 
+
     def voice(self, objective: str, target_number: str, **kwargs: Any) -> Any:
         """Make an AI voice call. Blocking."""
         return self.call_tool("/v1/tools/voice/call", {"objective": objective, "target_number": target_number, **kwargs})
@@ -1235,6 +1352,30 @@ 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:
+        """Discover local businesses (restaurants, contractors, practices) by category/keywords x location. Blocking."""
+        return self.call_tool("/v1/tools/local/search", kwargs)
+
+    async def alocal_search(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)
+
+    def local_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})
+
+    async def alocal_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})
+
+    def gov_solicitations(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})
+
+    async def agov_solicitations(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})
+
     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."""
         payload: dict[str, Any] = {"company_domain": company_domain, **kwargs}
@@ -1527,6 +1668,7 @@ class OneShotClient:
                         f"Job failed: {job.get('error', 'Unknown')}",
                         request_id,
                         str(job.get("error", "Unknown")),
+                        code=job.get("error_code"), partial_result=job.get("result"),
                     )
 
                 retries = 0

oneshot_python-0.24.0/oneshot/physical_mail.py

@@ -0,0 +1,168 @@
+"""Physical mail: explicit approval, durable recovery, independent fulfillment."""
+from __future__ import annotations
+from typing import Any, Literal, TypedDict
+import math
+import httpx
+from oneshot.x402 import sign_read_proof, parse_payment_required, sign_payment_authorization, encode_payment_header
+from oneshot._errors import OneShotError
+
+class _PostalAddressRequired(TypedDict):
+    name: str
+    address_line1: str
+    address_city: str
+    address_state: str
+    address_zip: str
+
+class PostalAddress(_PostalAddressRequired, total=False):
+    address_line2: str
+    address_country: Literal['US']
+
+class MailQuote(TypedDict):
+    quote_id: str
+    input_hash: str
+    status: Literal['rendering', 'ready']
+    total_usdc: str | None
+    expires_at: str
+    preview: dict[str, Any]
+    input: dict[str, Any]
+    service_fee_usdc: str | None
+    approval_id: str | None
+    delivery_proves_readership: Literal[False]
+
+class MailOrder(TypedDict):
+    order_id: str
+    quote_id: str
+    receipt_id: str
+    order_status: str
+    payment_status: str
+    fulfillment_status: str
+    total_usdc: str
+    cancellation_requested: bool
+    cancellation_error: str | None
+    cancel_before: str | None
+    refunded_at: str | None
+    signed_receipt: Any
+    events: list[dict[str, Any]]
+    idempotency_key: str
+    delivery_proves_readership: Literal[False]
+
+class PhysicalMail:
+    def __init__(self, client: Any):
+        self.client = client
+
+    async def _request(self, path: str, method: str = 'POST', body: Any = None, *, mime: str | None = None, key: str | None = None, max_cost: float | None = None) -> Any:
+        c = self.client
+        scope = 'read' if method == 'GET' else 'submit' if path == '/send' else 'write'
+        def headers() -> dict[str, str]:
+            h = c._headers(max_cost=max_cost)
+            h['x-agent-proof'] = sign_read_proof(c._private_key, c.address, scope=scope)
+            if key:
+                h['Idempotency-Key'] = key
+            if mime:
+                h['Content-Type'] = mime
+            return h
+        if path == '/send':
+            await c.aensure_budgets_synced()
+        async with httpx.AsyncClient(timeout=60.0) as transport:
+            kwargs = {'content': body} if mime else {'json': body}
+            url = f'{c.base_url}/v1/tools/physical-mail{path}'
+            response = await transport.request(method, url, headers=headers(), **kwargs)
+            if response.status_code == 402 and path == '/send':
+                parsed = parse_payment_required(response.headers.get('payment-required'))
+                accepted = parsed['accepted']
+                payment = response.json()['payment_request']
+                charge = str(int(accepted['amount']) / 1_000_000)
+                c._assert_within_budget(charge)
+                if max_cost is not None and float(charge) > max_cost:
+                    raise OneShotError('Physical mail quote exceeds max_cost')
+                auth = sign_payment_authorization(private_key=c._private_key, from_address=c.address,
+                    to_address=payment['recipient'], amount=charge, token_address=payment['token_address'],
+                    chain_id=payment['chain_id'], network=accepted['network'], accepted=accepted,
+                    resource=parsed.get('resource'), extensions=parsed.get('extensions'))
+                h = headers()  # Proof nonces are single use, including the unpaid leg.
+                h['payment-signature'] = encode_payment_header(auth)
+                response = await transport.post(url, headers=h, json=body)
+            response.raise_for_status()
+            return response.json()
+
+    async def aupload_artwork(self, data: bytes, mime: str) -> dict[str, str]:
+        return await self._request('/assets', body=data, mime=mime)
+
+    async def avalidate_address(self, address: PostalAddress) -> dict[str, Any]:
+        return await self._request('/validate-address', body=address)
+
+    async def apreview(self, mail_input: dict[str, Any]) -> MailQuote:
+        return await self._request('/preview', body=mail_input)
+
+    async def aget_quote(self, quote_id: str) -> MailQuote:
+        from urllib.parse import quote
+        return await self._request(f'/quotes/{quote(quote_id, safe="")}', 'GET')
+
+    async def aapprove(self, *, quote_id: str, input_hash: str, total_usdc: str, approved: Literal[True]) -> dict[str, str]:
+        if approved is not True:
+            raise ValueError('Explicit mailpiece approval required')
+        return await self._request('/approve', body=dict(quote_id=quote_id, input_hash=input_hash, total_usdc=total_usdc, approved=True))
+
+    async def asend(self, *, quote_id: str, approval_id: str, idempotency_key: str, max_cost: float | None = None, memo: str | None = None, decision_context: dict[str, Any] | None = None) -> MailOrder:
+        if max_cost is not None and (not math.isfinite(max_cost) or max_cost <= 0):
+            raise ValueError('Physical mail max_cost must be finite and positive')
+        if not idempotency_key or not approval_id:
+            raise ValueError('Persist an idempotency key and explicitly approve the quote before sending')
+        body: dict[str, Any] = dict(quote_id=quote_id, approval_id=approval_id)
+        if memo is not None:
+            body['memo'] = memo
+        if decision_context is not None:
+            body['decisionContext'] = decision_context
+        try:
+            return await self._request('/send', body=body, key=idempotency_key, max_cost=max_cost)
+        except Exception as error:
+            error.idempotency_key = idempotency_key  # type: ignore[attr-defined]
+            raise
+
+    async def aget_order(self, order_id: str) -> MailOrder:
+        from urllib.parse import quote
+        return await self._request(f'/orders/{quote(order_id, safe="")}', 'GET')
+
+    async def arecover(self, key: str) -> MailOrder:
+        from urllib.parse import quote
+        return await self._request(f'/orders/recover?key={quote(key, safe="")}', 'GET')
+
+    async def acancel(self, order_id: str) -> MailOrder:
+        from urllib.parse import quote
+        return await self._request(f'/orders/{quote(order_id, safe="")}/cancel', body={})
+
+    def upload_artwork(self, *args: Any, **kwargs: Any) -> Any:
+        import asyncio
+        return asyncio.get_event_loop().run_until_complete(self.aupload_artwork(*args, **kwargs))
+
+    def validate_address(self, *args: Any, **kwargs: Any) -> Any:
+        import asyncio
+        return asyncio.get_event_loop().run_until_complete(self.avalidate_address(*args, **kwargs))
+
+    def preview(self, *args: Any, **kwargs: Any) -> Any:
+        import asyncio
+        return asyncio.get_event_loop().run_until_complete(self.apreview(*args, **kwargs))
+
+    def get_quote(self, *args: Any, **kwargs: Any) -> Any:
+        import asyncio
+        return asyncio.get_event_loop().run_until_complete(self.aget_quote(*args, **kwargs))
+
+    def approve(self, *args: Any, **kwargs: Any) -> Any:
+        import asyncio
+        return asyncio.get_event_loop().run_until_complete(self.aapprove(*args, **kwargs))
+
+    def send(self, *args: Any, **kwargs: Any) -> Any:
+        import asyncio
+        return asyncio.get_event_loop().run_until_complete(self.asend(*args, **kwargs))
+
+    def get_order(self, *args: Any, **kwargs: Any) -> Any:
+        import asyncio
+        return asyncio.get_event_loop().run_until_complete(self.aget_order(*args, **kwargs))
+
+    def recover(self, *args: Any, **kwargs: Any) -> Any:
+        import asyncio
+        return asyncio.get_event_loop().run_until_complete(self.arecover(*args, **kwargs))
+
+    def cancel(self, *args: Any, **kwargs: Any) -> Any:
+        import asyncio
+        return asyncio.get_event_loop().run_until_complete(self.acancel(*args, **kwargs))

{oneshot_python-0.20.2 → oneshot_python-0.24.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "oneshot-python"
-version = "0.20.2"
-description = "Core Python SDK for the OneShot API — HTTP client with x402 payment handling"
+version = "0.24.0"
+description = "Core Python SDK for the OneShot API — HTTP client with x402 payment handling — 35 tools"
 readme = {text = "Core Python SDK for the OneShot API", content-type = "text/plain"}
 license = "MIT"
 requires-python = ">=3.10"

oneshot_python-0.24.0/tests/test_browser.py

@@ -0,0 +1,57 @@
+"""Browser credentials bypass paid task prose; invalid requests fail locally."""
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+from oneshot.client import OneShotClient
+from oneshot._errors import JobError
+
+TEST_PRIVATE_KEY = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize('options', [{'secrets': {}}, {'max_steps': 3}, {'max_steps': 25.5}, {'max_steps': True}])
+async def test_invalid_task_never_calls_paid_endpoint(options):
+    client = OneShotClient(TEST_PRIVATE_KEY)
+    client.acall_tool = AsyncMock()
+    with pytest.raises(ValueError):
+        await client.abrowser('Read heading', **options)
+    client.acall_tool.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_import_uses_profile_endpoint_and_rejects_ambiguous_state():
+    client = OneShotClient(TEST_PRIVATE_KEY)
+    client.acall_free_post = AsyncMock(return_value={'id': 'profile'})
+    state = {'cookies': [], 'origins': []}
+    assert await client.acreate_browser_profile('test', storage_state=state) == {'id': 'profile'}
+    client.acall_free_post.assert_awaited_once_with('/v1/tools/browser/profiles', {'name': 'test', 'storage_state': state})
+    with pytest.raises(ValueError):
+        await client.acreate_browser_profile('test', cookies=[], storage_state=state)
+
+
+@pytest.mark.asyncio
+async def test_failed_poll_preserves_partial_browser_result():
+    client = OneShotClient(TEST_PRIVATE_KEY)
+    partial = {'cost': .1, 'steps': [{'number': 1, 'goal': 'Browser action', 'url': 'https://example.com'}]}
+    response = MagicMock(is_success=True, status_code=200)
+    response.json.return_value = {'status': 'failed', 'error_message': 'Browser timeout', 'error_code': 'browser_timeout', 'result': partial}
+    http = MagicMock()
+    http.get = AsyncMock(return_value=response)
+    with pytest.raises(JobError) as caught:
+        await client._poll_job(http, 'request', 10)
+    assert caught.value.code == 'browser_timeout'
+    assert caught.value.partial_result == partial
+
+
+@pytest.mark.asyncio
+async def test_interactive_setup_uses_free_authenticated_operations():
+    client = OneShotClient(TEST_PRIVATE_KEY)
+    client.acall_free_post = AsyncMock(return_value={'status': 'idle'})
+    await client.astart_browser_profile_setup('profile', 'https://example.com/login')
+    await client.aget_browser_profile_setup('profile')
+    await client.afinish_browser_profile_setup('profile')
+    assert [(call.args[0],call.args[1]) for call in client.acall_free_post.await_args_list] == [
+        ('/v1/tools/browser/profiles/profile/setup/start', {'start_url':'https://example.com/login'}),
+        ('/v1/tools/browser/profiles/profile/setup/status', {}),
+        ('/v1/tools/browser/profiles/profile/setup/finish', {}),
+    ]

oneshot_python-0.24.0/tests/test_email_payload.py

@@ -0,0 +1,282 @@
+"""Tests for the email payload construction in OneShotClient.
+
+Verifies that email()/aemail() send the API's field convention
+(from_address + to_address), build from_address from from_mailbox/from_domain
+when a domain is pinned, omit from_address entirely to trigger server-side
+rotation when both are omitted, reject a from_mailbox pinned without
+from_domain, and forward the optional from_name display name.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+import pytest
+
+from oneshot._errors import ValidationError
+from oneshot.client import OneShotClient, _build_email_payload
+
+TEST_PRIVATE_KEY = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"
+REPLY_ID = "4fa85f64-5717-4562-b3fc-2c963f66afa6"
+
+
+@pytest.fixture(autouse=True)
+def _fresh_event_loop():
+    """Give every test in this module its own event loop.
+
+    The sync surface (``email()``) bridges to ``aemail()`` via
+    ``asyncio.get_event_loop().run_until_complete(...)``. pytest-asyncio
+    clears the current event loop after each async test, which otherwise
+    breaks any *sync* test — mocked or not — that happens to run afterward
+    in the same session ("There is no current event loop in thread
+    'MainThread'"). Without this fixture the suite's pass/fail would depend
+    on test collection order, which is exactly the kind of environment-
+    dependent test this correction round was asked to avoid introducing.
+    """
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    yield
+    loop.close()
+
+
+# ── _build_email_payload (pure) ───────────────────────────────────────────
+
+def test_payload_omits_from_address_when_no_from_knobs_given():
+    # Rotation mode: matches the TS SDK's contract — never fabricate
+    # `agent@oneshotagent.com`. The server picks a domain from the agent's
+    # own pool and the caller replays whatever the quote returns.
+    p = _build_email_payload("r@x.com", "S", "B", None, None, None, {})
+    assert p == {
+        "to_address": "r@x.com",
+        "subject": "S",
+        "body": "B",
+    }
+    assert "from_address" not in p
+
+
+def test_payload_uses_mailbox_domain_and_name():
+    p = _build_email_payload("r@x.com", "S", "B", "acme.com", "jane", "Jane Doe", {})
+    assert p["from_address"] == "jane@acme.com"
+    assert p["from_name"] == "Jane Doe"
+
+
+def test_payload_from_domain_alone_defaults_mailbox_to_agent():
+    p = _build_email_payload("r@x.com", "S", "B", "acme.com", None, None, {})
+    assert p["from_address"] == "agent@acme.com"
+
+
+def test_payload_from_mailbox_without_from_domain_raises():
+    # No default domain to fall back to — oneshotagent.com is OneShot's own
+    # domain and no agent can send from it. This must be a client-side
+    # ValidationError naming from_domain, never a fabricated address.
+    with pytest.raises(ValidationError, match="from_domain"):
+        _build_email_payload("r@x.com", "S", "B", None, "jane", None, {})
+
+
+def test_payload_omits_empty_from_name():
+    p = _build_email_payload("r@x.com", "S", "B", None, None, "", {})
+    assert "from_name" not in p
+
+
+def test_payload_passes_extra_kwargs():
+    p = _build_email_payload("r@x.com", "S", "B", None, None, None, {"wait": True})
+    assert p["wait"] is True
+
+
+def test_payload_forwards_mailbox_mode():
+    # mailbox_mode is an explicit keyword-only param, forwarded into the send body so
+    # the API's per-domain provider override + fee logic sees it.
+    p = _build_email_payload("r@x.com", "S", "B", "acme.com", None, None, {}, mailbox_mode="mailbox")
+    assert p["mailbox_mode"] == "mailbox"
+
+
+def test_payload_omits_mailbox_mode_when_absent():
+    p = _build_email_payload("r@x.com", "S", "B", "acme.com", None, None, {})
+    assert "mailbox_mode" not in p
+
+
+# ── reply threading (reply_to_email_id) ───────────────────────────────────
+
+def test_reply_payload_omits_to_and_subject_when_derivable():
+    # Replying: to/subject may be omitted; server derives them.
+    p = _build_email_payload(None, None, "B", None, None, None, {}, reply_to_email_id=REPLY_ID)
+    assert p["reply_to_email_id"] == REPLY_ID
+    assert p["body"] == "B"
+    assert "to_address" not in p
+    assert "subject" not in p
+
+
+def test_reply_payload_keeps_explicit_to_and_subject():
+    p = _build_email_payload("r@x.com", "Custom", "B", None, None, None, {}, reply_to_email_id=REPLY_ID)
+    assert p["reply_to_email_id"] == REPLY_ID
+    assert p["to_address"] == "r@x.com"
+    assert p["subject"] == "Custom"
+
+
+def test_non_reply_requires_to():
+    with pytest.raises(ValidationError):
+        _build_email_payload(None, "S", "B", None, None, None, {})
+
+
+def test_non_reply_requires_subject():
+    with pytest.raises(ValidationError):
+        _build_email_payload("r@x.com", None, "B", None, None, None, {})
+
+
+def test_reply_does_not_require_to_or_subject():
+    # Should not raise even though to and subject are None.
+    _build_email_payload(None, None, "B", None, None, None, {}, reply_to_email_id=REPLY_ID)
+
+
+# ── email()/aemail() quote-then-send flow ──────────────────────────────────
+#
+# email()/aemail() now quote before sending (mirrors the TS SDK's
+# email/quote -> email/send flow in libs/agent-sdk/src/index.ts). These tests
+# stub acall_tool itself (the real HTTP/x402 transport) so they exercise the
+# actual two-request flow end-to-end, instead of stopping at the payload
+# builder — the gap that let a Python send hard-fail with 400
+# missing_from_address in production while the mocked-call_tool tests still
+# passed.
+
+def _capturing_client(
+    quote_from_address: str | None = None,
+    quote_extra: dict | None = None,
+) -> tuple[OneShotClient, list[dict]]:
+    """A client whose acall_tool is stubbed to capture both the /email/quote
+    and /email/send calls it makes, without touching the network."""
+    c = OneShotClient(TEST_PRIVATE_KEY)
+    calls: list[dict] = []
+
+    async def fake_acall_tool(endpoint, payload, **kwargs):
+        calls.append({
+            "endpoint": endpoint,
+            "payload": dict(payload),
+            "quote_id": kwargs.get("quote_id"),
+            "max_cost": kwargs.get("max_cost"),
+            "timeout_sec": kwargs.get("timeout_sec"),
+        })
+        if endpoint.endswith("/email/quote"):
+            resp: dict[str, Any] = {"total_cost": "0.01", "quote_id": "quote_test_1"}
+            if quote_from_address:
+                resp["from_address"] = quote_from_address
+            if quote_extra:
+                resp.update(quote_extra)
+            return resp
+        return {"request_id": "r1", "status": "completed"}
+
+    c.acall_tool = fake_acall_tool  # type: ignore[method-assign]
+    return c, calls
+
+
+def _find(calls: list[dict], suffix: str) -> dict:
+    for call in calls:
+        if call["endpoint"].endswith(suffix):
+            return call
+    raise AssertionError(f"no call to endpoint ending in {suffix!r} among {[c['endpoint'] for c in calls]}")
+
+
+@pytest.mark.asyncio
+async def test_aemail_rotation_quotes_before_send_and_replays_picked_address():
+    # Rotation mode (no from_domain/from_mailbox): from_address must be
+    # omitted on the quote so the server picks a domain from the agent's own
+    # pool, and the picked address must be replayed on /send — otherwise
+    # /send 400s with missing_from_address (apps/api-service's
+    # /email/send resolves from_address only from an explicit param, a
+    # quote-locked address, or a reply target).
+    c, calls = _capturing_client(quote_from_address="agent@picked.com")
+    await c.aemail("r@x.com", "Hi", "Body")
+
+    quote = _find(calls, "/email/quote")
+    send = _find(calls, "/email/send")
+    assert "from_address" not in quote["payload"]
+    assert send["payload"]["from_address"] == "agent@picked.com"
+    assert send["payload"]["to_address"] == "r@x.com"
+    # /email/send requires x-quote-id from the very first attempt (the API
+    # 400s quote_id_required / "Quote ID required" otherwise) — acall_tool
+    # must receive the quote's id so it can set the header on every attempt.
+    assert send["quote_id"] == "quote_test_1"
+
+
+def test_email_sends_correct_contract():
+    c, calls = _capturing_client()
+    c.email("r@x.com", "Hi", "Body", from_mailbox="jane", from_domain="acme.com", from_name="Jane Doe")
+    quote = _find(calls, "/email/quote")
+    send = _find(calls, "/email/send")
+    assert quote["payload"]["from_address"] == "jane@acme.com"
+    assert send["payload"]["from_address"] == "jane@acme.com"
+    assert send["payload"]["to_address"] == "r@x.com"
+    assert send["payload"]["from_name"] == "Jane Doe"
+    # from_name is a display-only field for the send, not part of pricing —
+    # mirrors the TS SDK quote body, which never sends it either.
+    assert "from_name" not in quote["payload"]
+    assert send["quote_id"] == "quote_test_1"
+
+
+def test_email_reply_forwards_reply_id_without_to_subject():
+    c, calls = _capturing_client(quote_from_address="agent@picked.com")
+    c.email(reply_to_email_id=REPLY_ID, body="Thanks!")
+    quote = _find(calls, "/email/quote")
+    send = _find(calls, "/email/send")
+    for call in (quote, send):
+        assert call["payload"]["reply_to_email_id"] == REPLY_ID
+        assert call["payload"]["body"] == "Thanks!"
+        assert "to_address" not in call["payload"]
+        assert "subject" not in call["payload"]
+
+
+def test_email_without_to_or_reply_id_raises():
+    c, calls = _capturing_client()
+    with pytest.raises(ValidationError):
+        c.email(body="orphan body")
+    assert calls == []  # fails before any network call — quote or send
+
+
+def test_email_from_mailbox_without_from_domain_raises():
+    # Public email() surface, not just the pure _build_email_payload helper:
+    # pinning from_mailbox alone must fail client-side naming from_domain,
+    # never send agent@oneshotagent.com — checked before quoting, so no
+    # network call is made at all.
+    c, calls = _capturing_client()
+    with pytest.raises(ValidationError, match="from_domain"):
+        c.email("r@x.com", "Hi", "Body", from_mailbox="jane")
+    assert calls == []
+
+
+# ── max_cost / timeout_sec forwarding (finding PRRT_kwDOQhndvM6gpNlg) ──────
+#
+# aemail() takes max_cost/timeout_sec via **kwargs alongside genuine send-body
+# extras (attachments, idempotencyKey, ...). Before this fix they fell straight
+# through to _build_email_payload and rode along in the JSON body — never
+# reaching acall_tool, so the X-Max-Cost-USDC header + local budget check never
+# fired on the quote or send call, and the poll used the 120s default no
+# matter what the caller asked for.
+
+@pytest.mark.asyncio
+async def test_aemail_forwards_max_cost_and_timeout_to_transport_not_body():
+    c, calls = _capturing_client(quote_from_address="agent@picked.com")
+    await c.aemail("r@x.com", "Hi", "Body", max_cost=0.05, timeout_sec=30)
+
+    quote = _find(calls, "/email/quote")
+    send = _find(calls, "/email/send")
+    # Reached acall_tool as transport options...
+    assert quote["max_cost"] == 0.05
+    assert send["max_cost"] == 0.05
+    assert send["timeout_sec"] == 30
+    # ...and did NOT leak into the JSON payload either call sends.
+    assert "max_cost" not in quote["payload"]
+    assert "max_cost" not in send["payload"]
+    assert "timeout_sec" not in quote["payload"]
+    assert "timeout_sec" not in send["payload"]
+
+
+@pytest.mark.asyncio
+async def test_aemail_default_timeout_sec_is_120_when_unset():
+    c, calls = _capturing_client(quote_from_address="agent@picked.com")
+    await c.aemail("r@x.com", "Hi", "Body")
+
+    send = _find(calls, "/email/send")
+    assert send["timeout_sec"] == 120
+    quote = _find(calls, "/email/quote")
+    assert quote["max_cost"] is None
+

oneshot_python-0.24.0/tests/test_physical_mail.py

@@ -0,0 +1,43 @@
+import pytest
+from unittest.mock import AsyncMock, MagicMock
+from oneshot.physical_mail import PhysicalMail
+
+@pytest.mark.asyncio
+async def test_preview_and_approval_do_not_send():
+    mail = PhysicalMail(MagicMock())
+    mail._request = AsyncMock(return_value={})
+    await mail.apreview({'artwork': {'kind': 'letter', 'file': 'asset'}})
+    assert mail._request.call_args.args[0] == '/preview'
+    with pytest.raises(ValueError):
+        await mail.aapprove(quote_id='q', input_hash='h', total_usdc='1.05', approved=False)
+    await mail.aapprove(quote_id='q', input_hash='h', total_usdc='1.05', approved=True)
+    assert mail._request.call_args.args[0] == '/approve'
+
+@pytest.mark.asyncio
+async def test_send_preserves_key_and_approval_and_recovery_does_not_send():
+    mail = PhysicalMail(MagicMock())
+    mail._request = AsyncMock(return_value={})
+    with pytest.raises(ValueError):
+        await mail.asend(quote_id='q', approval_id='a', idempotency_key='')
+    await mail.asend(quote_id='q', approval_id='a', idempotency_key='durable', max_cost=1.05)
+    assert mail._request.call_args.kwargs['key'] == 'durable'
+    assert mail._request.call_args.kwargs['body'] == {'quote_id': 'q', 'approval_id': 'a'}
+    await mail.arecover('a/b')
+    assert mail._request.call_args.args == ('/orders/recover?key=a%2Fb', 'GET')
+
+@pytest.mark.asyncio
+async def test_transport_error_carries_recovery_key():
+    mail = PhysicalMail(MagicMock())
+    mail._request = AsyncMock(side_effect=TimeoutError())
+    with pytest.raises(TimeoutError) as caught:
+        await mail.asend(quote_id='q', approval_id='a', idempotency_key='persisted')
+    assert caught.value.idempotency_key == 'persisted'
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize('max_cost', [0, -1, float('nan'), float('inf')])
+async def test_invalid_caps_never_submit(max_cost):
+    mail = PhysicalMail(MagicMock())
+    mail._request = AsyncMock()
+    with pytest.raises(ValueError, match='finite and positive'):
+        await mail.asend(quote_id='q', approval_id='a', idempotency_key='key', max_cost=max_cost)
+    mail._request.assert_not_called()

{oneshot_python-0.20.2 → oneshot_python-0.24.0}/uv.lock

@@ -549,7 +549,7 @@ wheels = [
 
 [[package]]
 name = "oneshot-python"
-version = "0.14.0"
+version = "0.24.0"
 source = { editable = "." }
 dependencies = [
     { name = "eth-account" },

oneshot_python-0.20.2/tests/test_email_payload.py

@@ -1,138 +0,0 @@
-"""Tests for the email payload construction in OneShotClient.
-
-Verifies that email()/aemail() send the API's field convention
-(from_address + to_address), build from_address from from_mailbox/from_domain,
-and forward the optional from_name display name.
-"""
-
-from __future__ import annotations
-
-from unittest.mock import AsyncMock, MagicMock
-
-import pytest
-
-from oneshot._errors import ValidationError
-from oneshot.client import OneShotClient, _build_email_payload
-
-TEST_PRIVATE_KEY = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"
-REPLY_ID = "4fa85f64-5717-4562-b3fc-2c963f66afa6"
-
-
-# ── _build_email_payload (pure) ───────────────────────────────────────────
-
-def test_payload_defaults_to_agent_mailbox():
-    p = _build_email_payload("r@x.com", "S", "B", None, None, None, {})
-    assert p == {
-        "from_address": "agent@oneshotagent.com",
-        "to_address": "r@x.com",
-        "subject": "S",
-        "body": "B",
-    }
-
-
-def test_payload_uses_mailbox_domain_and_name():
-    p = _build_email_payload("r@x.com", "S", "B", "acme.com", "jane", "Jane Doe", {})
-    assert p["from_address"] == "jane@acme.com"
-    assert p["from_name"] == "Jane Doe"
-
-
-def test_payload_omits_empty_from_name():
-    p = _build_email_payload("r@x.com", "S", "B", None, None, "", {})
-    assert "from_name" not in p
-
-
-def test_payload_passes_extra_kwargs():
-    p = _build_email_payload("r@x.com", "S", "B", None, None, None, {"wait": True})
-    assert p["wait"] is True
-
-
-def test_payload_forwards_mailbox_mode():
-    # mailbox_mode is an explicit keyword-only param, forwarded into the send body so
-    # the API's per-domain provider override + fee logic sees it.
-    p = _build_email_payload("r@x.com", "S", "B", "acme.com", None, None, {}, mailbox_mode="mailbox")
-    assert p["mailbox_mode"] == "mailbox"
-
-
-def test_payload_omits_mailbox_mode_when_absent():
-    p = _build_email_payload("r@x.com", "S", "B", "acme.com", None, None, {})
-    assert "mailbox_mode" not in p
-
-
-# ── reply threading (reply_to_email_id) ───────────────────────────────────
-
-def test_reply_payload_omits_to_and_subject_when_derivable():
-    # Replying: to/subject may be omitted; server derives them.
-    p = _build_email_payload(None, None, "B", None, None, None, {}, reply_to_email_id=REPLY_ID)
-    assert p["reply_to_email_id"] == REPLY_ID
-    assert p["body"] == "B"
-    assert "to_address" not in p
-    assert "subject" not in p
-
-
-def test_reply_payload_keeps_explicit_to_and_subject():
-    p = _build_email_payload("r@x.com", "Custom", "B", None, None, None, {}, reply_to_email_id=REPLY_ID)
-    assert p["reply_to_email_id"] == REPLY_ID
-    assert p["to_address"] == "r@x.com"
-    assert p["subject"] == "Custom"
-
-
-def test_non_reply_requires_to():
-    with pytest.raises(ValidationError):
-        _build_email_payload(None, "S", "B", None, None, None, {})
-
-
-def test_non_reply_requires_subject():
-    with pytest.raises(ValidationError):
-        _build_email_payload("r@x.com", None, "B", None, None, None, {})
-
-
-def test_reply_does_not_require_to_or_subject():
-    # Should not raise even though to and subject are None.
-    _build_email_payload(None, None, "B", None, None, None, {}, reply_to_email_id=REPLY_ID)
-
-
-# ── email() delegation ────────────────────────────────────────────────────
-
-def _client() -> OneShotClient:
-    c = OneShotClient(TEST_PRIVATE_KEY)
-    c.call_tool = MagicMock(return_value={"request_id": "r1"})  # type: ignore[method-assign]
-    return c
-
-
-def test_email_sends_correct_contract():
-    c = _client()
-    c.email("r@x.com", "Hi", "Body", from_mailbox="jane", from_domain="acme.com", from_name="Jane Doe")
-    endpoint, payload = c.call_tool.call_args[0]
-    assert endpoint == "/v1/tools/email/send"
-    assert payload["from_address"] == "jane@acme.com"
-    assert payload["to_address"] == "r@x.com"
-    assert payload["from_name"] == "Jane Doe"
-
-
-@pytest.mark.asyncio
-async def test_aemail_sends_correct_contract():
-    c = OneShotClient(TEST_PRIVATE_KEY)
-    c.acall_tool = AsyncMock(return_value={"request_id": "r2"})  # type: ignore[method-assign]
-    await c.aemail("r@x.com", "Hi", "Body")
-    endpoint, payload = c.acall_tool.call_args[0]
-    assert endpoint == "/v1/tools/email/send"
-    assert payload["from_address"] == "agent@oneshotagent.com"
-    assert payload["to_address"] == "r@x.com"
-    assert "from_name" not in payload
-
-
-def test_email_reply_forwards_reply_id_without_to_subject():
-    c = _client()
-    c.email(reply_to_email_id=REPLY_ID, body="Thanks!")
-    endpoint, payload = c.call_tool.call_args[0]
-    assert endpoint == "/v1/tools/email/send"
-    assert payload["reply_to_email_id"] == REPLY_ID
-    assert payload["body"] == "Thanks!"
-    assert "to_address" not in payload
-    assert "subject" not in payload
-
-
-def test_email_without_to_or_reply_id_raises():
-    c = _client()
-    with pytest.raises(ValidationError):
-        c.email(body="orphan body")