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

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: oneshot-python
-Version: 0.23.1
+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

{oneshot_python-0.23.1 → 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)
@@ -205,3 +205,12 @@ 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.23.1 → 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.23.1 → 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.23.1"
+    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:
@@ -505,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:
@@ -540,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.
@@ -597,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:
@@ -732,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)
@@ -1052,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
@@ -1061,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."""
@@ -1160,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(
@@ -1186,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})
@@ -1556,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.23.1 → oneshot_python-0.24.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "oneshot-python"
-version = "0.23.1"
+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"

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.23.1 → oneshot_python-0.24.0}/uv.lock

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

oneshot_python-0.23.1/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")