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

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

@@ -90,3 +90,6 @@ output/
 
 # Claude Code agent metadata (lockfile + local settings)
 .claude/
+
+# generated by scripts/deploy-blog-generator.sh
+scripts/humanizer.vendored.ts

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

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

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

@@ -66,6 +66,43 @@ Read endpoints (inbox, SMS inbox, notifications, balance, browser profiles) retu
 
 This is automatic — no extra code beyond `private_key`. **Requires `oneshot-python >= 0.17.0`.** Older versions keep working until the API enables enforcement, after which they must send a valid `x-agent-proof`.
 
+## Spend Budgets
+
+Cap what the agent can spend so a runaway loop can't drain the wallet overnight:
+
+```python
+client = OneShotClient(
+    "0x...",
+    budgets={
+        "daily": 50,            # max USDC per UTC day
+        "per_transaction": 5,   # max USDC for any single call
+        "alert_at": 0.8,        # warn at 80% of daily
+        "pause_at": 1.0,        # stop paying at 100%
+    },
+    alert_email="you@example.com",
+)
+```
+
+Unlike `max_cost` (a per-call client-side check), budgets are **enforced server-side** against your receipt ledger. The config is synced once before your first paid call, so the daily figure is a true per-agent total — shared across every process and restart using the same wallet.
+
+At `alert_at` you get a `budget_warning` notification (in-app via `/v1/tools/notifications`, plus email if set). At `pause_at` paid calls raise `BudgetExceededError` until the window resets at the next UTC midnight:
+
+```python
+from oneshot import BudgetExceededError
+
+try:
+    client.research(topic="...")
+except BudgetExceededError as e:
+    print(f"{e.reason} budget hit — ${e.spent} spent, resumes {e.resets_at}")
+
+client.get_budgets()
+# {"daily_usdc": 50, "spent_today_usdc": "41.20", "pct_used": 0.824, "resets_at": "..."}
+```
+
+Omit `budgets` to leave whatever is stored server-side untouched — agents without a budget are unlimited. **Requires `oneshot-python >= 0.20.0`.**
+
+The sync **fails closed**: if the budget can't be confirmed with the server, the paid call raises `BudgetSyncError` and is not made (retried on the next call). An invalid config (`daily=-1`, `alert_at=2`) raises `ValidationError` at construction.
+
 ## Configuration
 
 ```python

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

@@ -1,6 +1,8 @@
 """oneshot-python — Core Python SDK for the OneShot API."""
 
 from oneshot._errors import (
+    BudgetExceededError,
+    BudgetSyncError,
     ContentBlockedError,
     EmergencyNumberError,
     JobError,
@@ -11,6 +13,8 @@ from oneshot._errors import (
     ValidationError,
 )
 from oneshot._types import (
+    AgentBudgetConfig,
+    AgentBudgetStatus,
     ComputeBudgetStatus,
     ComputeCancelResult,
     ComputeFundResult,
@@ -34,12 +38,16 @@ __all__ = [
     "OneShotError",
     "ToolError",
     "PaymentError",
+    "BudgetExceededError",
+    "BudgetSyncError",
     "JobError",
     "JobTimeoutError",
     "ValidationError",
     "ContentBlockedError",
     "EmergencyNumberError",
     "sign_payment_authorization",
+    "AgentBudgetConfig",
+    "AgentBudgetStatus",
     "ComputeSchedule",
     "ComputeGoalResult",
     "ComputeGoalStatus",

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

@@ -81,3 +81,49 @@ class EmergencyNumberError(OneShotError):
     def __init__(self, message: str, blocked_number: str) -> None:
         super().__init__(message)
         self.blocked_number = blocked_number
+
+
+class BudgetExceededError(OneShotError):
+    """The agent's own spend budget stopped this call (HTTP 403 ``budget_exceeded``).
+
+    Distinct from :class:`PaymentError`: nothing was signed and nothing was
+    charged. A retry cannot succeed until the daily window resets
+    (``resets_at``) or the budget is raised — which is why the server answers
+    403 rather than 402. ``reason`` is ``"daily"`` when cumulative UTC-day
+    spend would cross the budget, or ``"per_transaction"`` when this single
+    call is larger than the per-call cap.
+
+    Mirrors ``BudgetExceededError`` in ``libs/agent-sdk/src/errors.ts``.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        reason: str,
+        cap: float | None = None,
+        spent: float | None = None,
+        charge: float | None = None,
+        resets_at: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.reason = reason
+        self.cap = cap
+        self.spent = spent
+        self.charge = charge
+        self.resets_at = resets_at
+
+
+class BudgetSyncError(OneShotError):
+    """The configured spend budget could not be confirmed with the server, so
+    the paid call was NOT made.
+
+    Budgets are enforced server-side; if the sync fails (network error, 5xx,
+    rate limit, rejected config) proceeding would silently drop the guardrail
+    the developer configured. The sync is retried on the next paid call.
+    ``status`` is the HTTP status when the server answered, else None.
+    """
+
+    def __init__(self, message: str, status: int | None = None, body: str | None = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.body = body

{oneshot_python-0.19.0 → oneshot_python-0.20.2}/oneshot/_types.py

@@ -181,6 +181,12 @@ class DomainPoolEntry(TypedDict, total=False):
 
     domain: str
     default_from: str
+    # 'mailbox' = a real mailbox is provisioned per address, so every address not
+    # already active in addresses[] bills the one-time mailbox_provisioning_fee on
+    # its first send — the canonical default_from included. 'relay' = header-only,
+    # no per-address fee. A property of the DOMAIN, fixed at setup: omitting
+    # mailbox_mode on a quote does not make the send relay.
+    mailbox_mode: str  # relay | mailbox
     addresses: list[DomainAddressEntry]
     pool_status: str  # active | paused | removed
     warmup_state: str  # warming | warmed | degraded
@@ -227,3 +233,37 @@ __all__ = [
     "DomainPoolListResult",
     "DomainPoolStatusResult",
 ]
+
+
+# ── Agent spend budgets ──────────────────────────────────────────────────
+
+
+class AgentBudgetConfig(TypedDict, total=False):
+    """Spend budget passed to ``OneShotClient(budgets=...)``.
+
+    Mirrors ``AgentBudgetConfig`` in TS (snake_case here; camelCase keys are
+    accepted too and normalised). Synced to the server once, before the first
+    paid call, and enforced there against the receipt ledger.
+    """
+
+    daily: float
+    """Max USDC per UTC day."""
+    per_transaction: float
+    """Max USDC for any single call."""
+    alert_at: float
+    """Fraction of ``daily`` that triggers a ``budget_warning`` (default 0.8)."""
+    pause_at: float
+    """Fraction of ``daily`` at which paid calls stop (default 1.0)."""
+
+
+class AgentBudgetStatus(TypedDict):
+    """Live utilization from ``GET /v1/agents/me/budgets``. Mirrors ``AgentBudgetStatus`` in TS."""
+
+    daily_usdc: Optional[float]
+    per_transaction_usdc: Optional[float]
+    alert_at: Optional[float]
+    pause_at: Optional[float]
+    spent_today_usdc: str
+    remaining_usdc: Optional[str]
+    pct_used: Optional[float]
+    resets_at: str

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

@@ -8,6 +8,7 @@ GET/POST for free endpoints.
 from __future__ import annotations
 
 import asyncio
+import math
 import json
 import time
 from decimal import Decimal
@@ -18,6 +19,8 @@ import httpx
 from eth_account import Account
 
 from oneshot._errors import (
+    BudgetExceededError,
+    BudgetSyncError,
     ContentBlockedError,
     EmergencyNumberError,
     JobError,
@@ -28,6 +31,8 @@ from oneshot._errors import (
     ValidationError,
 )
 from oneshot._types import (
+    AgentBudgetConfig,
+    AgentBudgetStatus,
     DomainPoolListResult,
     DomainPoolStatusResult,
 )
@@ -46,7 +51,7 @@ try:
 
     SDK_VERSION = _pkg_version("oneshot-python")
 except Exception:  # pragma: no cover - editable/source runs without dist metadata
-    SDK_VERSION = "0.19.0"
+    SDK_VERSION = "0.20.2"
 
 # ---------------------------------------------------------------------------
 # Environment configuration
@@ -56,7 +61,10 @@ _BASE_URL = "https://win.oneshotagent.com"
 _CHAIN_ID = 8453
 _USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
 
-_POLL_INTERVAL = 2.0  # seconds
+# Poll cadence for GET /v1/requests/{id}: fast first checks (most jobs finish in
+# a few seconds), settling at 2s. Index = number of polls already made.
+_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
 
 
@@ -107,6 +115,39 @@ def _build_email_payload(
     return payload
 
 
+def _parse_budget_rejection(resp: Any) -> Optional[BudgetExceededError]:
+    """Map a 403 ``budget_exceeded`` body onto :class:`BudgetExceededError`.
+
+    Lets callers catch "my own budget stopped this" separately from an auth
+    failure or a payment rejection. Returns None for any other response so the
+    caller falls back to ``ToolError``.
+    """
+    if resp.status_code != 403:
+        return None
+    try:
+        data = resp.json()
+    except Exception:  # noqa: BLE001 - non-JSON body
+        return None
+    if not isinstance(data, dict) or data.get("error") != "budget_exceeded":
+        return None
+    b = data.get("budget") or {}
+
+    def _num(v: Any) -> float | None:
+        try:
+            return float(v) if v is not None else None
+        except (TypeError, ValueError):
+            return None
+
+    return BudgetExceededError(
+        data.get("message") or "Agent spend budget exceeded",
+        "per_transaction" if b.get("reason") == "per_transaction" else "daily",
+        cap=_num(b.get("cap")),
+        spent=_num(b.get("spent")),
+        charge=_num(b.get("charge")),
+        resets_at=b.get("resets_at"),
+    )
+
+
 def _parse_payment_rejection(resp: Any) -> Optional[PaymentError]:
     """Build a ``PaymentError`` from a 402 that names its own cause.
 
@@ -183,6 +224,44 @@ def _resolve_charge_amount(accepted: Any, payment_request: dict[str, Any]) -> st
     return from_header
 
 
+_BUDGET_KEY_ALIASES = {
+    "perTransaction": "per_transaction",
+    "alertAt": "alert_at",
+    "pauseAt": "pause_at",
+}
+
+
+def _normalize_budgets(budgets: Optional[AgentBudgetConfig]) -> Optional[dict[str, float]]:
+    """Accept the TS camelCase keys too; keep only known, numeric fields."""
+    if not budgets:
+        return None
+    out: dict[str, float] = {}
+    for k, v in budgets.items():
+        key = _BUDGET_KEY_ALIASES.get(k, k)
+        # Validate here, at construction, what the server would reject — a
+        # typo'd cap must never silently become "no cap" on the first call.
+        # That includes a typo'd KEY: `{"daliy": 50}` used to normalise to
+        # "no budget" and skip the sync entirely.
+        if key not in ("daily", "per_transaction", "alert_at", "pause_at"):
+            raise ValidationError(f"budgets.{k} is not a recognized field", f"budgets.{k}")
+        if v is None:
+            continue
+        if isinstance(v, bool):  # float(True) == 1.0 would pass as a real cap
+            raise ValidationError(f"budgets.{key} must be a number", f"budgets.{key}")
+        try:
+            value = float(v)
+        except (TypeError, ValueError):
+            raise ValidationError(f"budgets.{key} must be a number", f"budgets.{key}") from None
+        if not math.isfinite(value):
+            raise ValidationError(f"budgets.{key} must be finite", f"budgets.{key}")
+        if key in ("daily", "per_transaction") and value <= 0:
+            raise ValidationError(f"budgets.{key} must be positive", f"budgets.{key}")
+        if key in ("alert_at", "pause_at") and not 0 < value <= 1:
+            raise ValidationError(f"budgets.{key} must be in (0, 1]", f"budgets.{key}")
+        out[key] = value
+    return out or None
+
+
 class OneShotClient:
     """Synchronous + async HTTP client for the OneShot API.
 
@@ -196,13 +275,22 @@ class OneShotClient:
         *,
         base_url: Optional[str] = None,
         debug: bool = False,
+        budgets: Optional[AgentBudgetConfig] = None,
+        alert_email: Optional[str] = None,
     ) -> None:
         self.base_url = base_url or _BASE_URL
         self.chain_id: int = _CHAIN_ID
         self.usdc_address: str = _USDC_ADDRESS
         self.debug = debug
 
-        # Derive wallet address from private key
+        # Spend budget: synced to the server once, before the first paid call,
+        # and enforced there against the receipt ledger. Omit to leave whatever
+        # is stored server-side untouched (no budget = unlimited).
+        self._budgets = _normalize_budgets(budgets)
+        self._alert_email = alert_email
+        self._budget_synced = False
+        self._budget_sync_lock: Optional[asyncio.Lock] = None
+
         self._private_key = private_key
         acct = Account.from_key(private_key)
         self.address: str = acct.address
@@ -239,10 +327,93 @@ class OneShotClient:
             self._log(f"Failed to sign read proof (continuing without): {e}")
         return headers
 
+    def _write_headers(self) -> dict[str, str]:
+        """Like ``_read_headers`` but with a ``write``-scoped proof, for the
+        signed mutation routes (budgets). The server enforces the proof on
+        those routes outright — there is no log-only fallback — so a signing
+        failure here is surfaced rather than swallowed."""
+        headers = self._headers()
+        headers["x-agent-proof"] = sign_read_proof(self._private_key, self.address, scope="write")
+        return headers
+
     def _log(self, msg: str) -> None:
         if self.debug:
             print(f"[OneShot] {msg}")
 
+    # ------------------------------------------------------------------
+    # Spend budget
+    # ------------------------------------------------------------------
+
+    async def aensure_budgets_synced(self) -> None:
+        """Push ``budgets`` / ``alert_email`` to the server once (async).
+
+        Called at the top of every paid call so the server-side gate knows the
+        budget on the very first request — including for a brand-new wallet,
+        which the budget route registers. Guarded by a lock so concurrent
+        first calls issue one PUT.
+
+        FAILS CLOSED: if the server can't confirm the budget (network error,
+        5xx, 429, rejected config) this raises :class:`BudgetSyncError` and the
+        paid call is not made — proceeding would silently drop the guardrail
+        the developer configured. ``_budget_synced`` is set only on success,
+        so the next paid call retries.
+        """
+        if self._budget_synced or (self._budgets is None and self._alert_email is None):
+            return
+        if self._budget_sync_lock is None:
+            self._budget_sync_lock = asyncio.Lock()
+        async with self._budget_sync_lock:
+            if self._budget_synced:
+                return
+            body: dict[str, Any] = dict(self._budgets or {})
+            if self._alert_email is not None:
+                body["alert_email"] = self._alert_email
+            try:
+                url = f"{self.base_url}/v1/agents/me/budgets"
+                async with httpx.AsyncClient(timeout=httpx.Timeout(30.0)) as client:
+                    resp = await client.put(url, headers=self._write_headers(), json=body)
+            except Exception as e:  # noqa: BLE001
+                self._log(f"Budget sync failed ({e}) — paid call refused until the budget is confirmed")
+                raise BudgetSyncError(f"Could not sync spend budget (network): {e}") from e
+            if not resp.is_success:
+                self._log(f"Budget sync rejected ({resp.status_code}) — paid call refused")
+                raise BudgetSyncError(
+                    f"Could not sync spend budget ({resp.status_code}): {resp.text}",
+                    status=resp.status_code,
+                    body=resp.text,
+                )
+            self._budget_synced = True
+            self._log("Budget synced")
+
+    def _assert_within_budget(self, total: Any) -> None:
+        """Local fast-fail on the per-transaction cap — no round-trip for an
+        oversized call. The server enforces the same cap (and the daily one,
+        which needs the ledger) regardless of client; this mirrors the
+        ``max_cost`` SDK-checks/server-enforces split."""
+        cap = (self._budgets or {}).get("per_transaction")
+        if not cap or cap <= 0:
+            return
+        try:
+            amount = float(total)
+        except (TypeError, ValueError):
+            return
+        if amount > cap:
+            raise BudgetExceededError(
+                f"Quote ${total} exceeds this agent's per-transaction budget of ${cap}",
+                "per_transaction",
+                cap=cap,
+                charge=amount,
+            )
+
+    def get_budgets(self) -> AgentBudgetStatus:
+        """Current spend budget and today's utilization. Blocking."""
+        return asyncio.get_event_loop().run_until_complete(self.aget_budgets())
+
+    async def aget_budgets(self) -> AgentBudgetStatus:
+        """Current spend budget and today's utilization. Async."""
+        body = await self.acall_free_get("/v1/agents/me/budgets")
+        return body.get("data", body) if isinstance(body, dict) else body
+
     # ------------------------------------------------------------------
     # Paid tool flow  (POST -> 402 -> sign -> POST w/ payment -> poll)
     # ------------------------------------------------------------------
@@ -254,11 +425,16 @@ class OneShotClient:
         *,
         max_cost: Optional[float] = None,
         timeout_sec: int = 120,
+        wait: bool = True,
         wait_for_phones: bool = False,
         phone_timeout_sec: int = 360,
     ) -> Any:
         """Execute a paid tool call (blocking). Handles the full x402 flow.
 
+        Set ``wait=False`` to return as soon as the job is queued — you get
+        ``{"request_id": ..., "status": ...}`` and can resolve it later with
+        :meth:`wait_for_result`.
+
         Set ``wait_for_phones=True`` to keep polling AFTER status=completed
         until Apollo's async phone-reveal webhook delivers phone numbers
         (or until ``phone_timeout_sec`` expires, default 6 min — Apollo says
@@ -270,11 +446,50 @@ class OneShotClient:
                 payload,
                 max_cost=max_cost,
                 timeout_sec=timeout_sec,
+                wait=wait,
                 wait_for_phones=wait_for_phones,
                 phone_timeout_sec=phone_timeout_sec,
             )
         )
 
+    def wait_for_result(
+        self,
+        request_id: str,
+        *,
+        timeout_sec: int = 120,
+        wait_for_phones: bool = False,
+        phone_timeout_sec: int = 360,
+    ) -> Any:
+        """Wait for a previously dispatched job (e.g. from ``wait=False``) and return its result."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.await_result(
+                request_id,
+                timeout_sec=timeout_sec,
+                wait_for_phones=wait_for_phones,
+                phone_timeout_sec=phone_timeout_sec,
+            )
+        )
+
+    async def await_result(
+        self,
+        request_id: str,
+        *,
+        timeout_sec: int = 120,
+        wait_for_phones: bool = False,
+        phone_timeout_sec: int = 360,
+    ) -> Any:
+        """Async form of :meth:`wait_for_result`: poll ``GET /v1/requests/{id}`` until terminal."""
+        if not request_id:
+            raise ValidationError("request_id is required", "request_id")
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            return await self._poll_job(
+                client,
+                request_id,
+                timeout_sec,
+                wait_for_phones=wait_for_phones,
+                phone_timeout_sec=phone_timeout_sec,
+            )
+
     async def acall_tool(
         self,
         endpoint: str,
@@ -282,11 +497,15 @@ class OneShotClient:
         *,
         max_cost: Optional[float] = None,
         timeout_sec: int = 120,
+        wait: bool = True,
         wait_for_phones: bool = False,
         phone_timeout_sec: int = 360,
     ) -> Any:
-        """Execute a paid tool call (async). Handles the full x402 flow."""
-        # Validate memo
+        """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.
+        """
         memo = payload.get("memo")
         if memo is not None:
             if not isinstance(memo, str) or not memo.strip():
@@ -297,7 +516,6 @@ class OneShotClient:
         elif "/inbox" not in endpoint and "/notifications" not in endpoint and "/balance" not in endpoint:
             self._log("No memo provided — consider adding a reason for audit trail")
 
-        # Validate decisionContext
         dc = payload.get("decisionContext") or payload.get("decision_context")
         if dc is not None:
             # Normalize to camelCase key for API
@@ -312,10 +530,20 @@ class OneShotClient:
 
         url = f"{self.base_url}{endpoint}"
 
+        # One-time push of the budget config before the first paid call, so
+        # the server-side gate knows about it on this very request.
+        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)
 
+            # The spend-budget gate rejects at quote time (403) so nothing is
+            # signed; surface it as the typed error.
+            budget_rejection = _parse_budget_rejection(resp)
+            if budget_rejection is not None:
+                raise budget_rejection
+
             # Handle validation / content-blocked / emergency-number errors
             if resp.status_code == 400:
                 data = resp.json()
@@ -343,6 +571,8 @@ class OneShotClient:
                     "pending",
                     "processing",
                 ):
+                    if not wait:
+                        return {"request_id": result["request_id"], "status": result["status"]}
                     return await self._poll_job(
                         client,
                         result["request_id"],
@@ -364,7 +594,6 @@ class OneShotClient:
             context = quote_data.get("context", {})
             quote_id = context.get("quote_id")
 
-            # Check max_cost
             total = context.get("total") or context.get("pricing", {}).get("total")
             if max_cost is not None and total is not None:
                 if float(total) > max_cost:
@@ -376,6 +605,7 @@ class OneShotClient:
 
             # Step 3 — Sign x402 payment (zero-cost auth if credits cover full cost)
             charge = _resolve_charge_amount(accepted, payment_request)
+            self._assert_within_budget(charge)
             amount = float(charge)
             if amount == 0:
                 self._log("Credits cover full cost — sending zero-cost authorization")
@@ -424,6 +654,9 @@ class OneShotClient:
                 rejection = _parse_payment_rejection(resp2)
                 if rejection is not None:
                     raise rejection
+                budget_rejection = _parse_budget_rejection(resp2)
+                if budget_rejection is not None:
+                    raise budget_rejection
                 raise ToolError(
                     "Tool request failed after payment",
                     resp2.status_code,
@@ -438,6 +671,8 @@ class OneShotClient:
                 "processing",
             ):
                 self._log(f"Job queued: {result['request_id']}")
+                if not wait:
+                    return {"request_id": result["request_id"], "status": result["status"]}
                 return await self._poll_job(
                     client,
                     result["request_id"],
@@ -524,6 +759,29 @@ class OneShotClient:
                 return {"success": True}
             return resp.json()
 
+    def call_free_put(
+        self,
+        endpoint: str,
+        payload: Optional[dict[str, Any]] = None,
+    ) -> Any:
+        """PUT to a signed mutation endpoint (blocking)."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.acall_free_put(endpoint, payload)
+        )
+
+    async def acall_free_put(
+        self,
+        endpoint: str,
+        payload: Optional[dict[str, Any]] = None,
+    ) -> Any:
+        """PUT to a signed mutation endpoint (async). Sends a write-scoped proof."""
+        url = f"{self.base_url}{endpoint}"
+        async with httpx.AsyncClient(timeout=httpx.Timeout(30.0)) as client:
+            resp = await client.put(url, headers=self._write_headers(), json=payload or {})
+            if not resp.is_success:
+                raise ToolError(f"PUT {endpoint} failed", resp.status_code, resp.text)
+            return resp.json()
+
     def call_free_delete(
         self,
         endpoint: str,
@@ -877,16 +1135,25 @@ class OneShotClient:
         reply within a thread — ``to``/``subject`` are then derived from the
         inbound message unless given.
 
-        The first send from any ``from_mailbox`` on an owned domain — including
-        the default ``agent@`` — provisions a mailbox per address and adds a
-        one-time ``mailbox_provisioning_fee`` to the quote; it's free only once
-        that address is already provisioned (``active``).
-
-        ``mailbox_mode`` ('relay' | 'mailbox', default 'relay') selects how a
-        domain sends: 'relay' is header-only send (no per-address mailbox, no
-        mailbox fee); 'mailbox' provisions a real dedicated mailbox per address
-        (better deliverability + per-address warmup). Only applies when a domain
-        is first set up — use it on a new ``from_domain``.
+        On a domain whose ``mailbox_mode`` is ``'mailbox'``, the first send from
+        any address — including the default ``agent@`` — provisions a mailbox
+        for it and adds a one-time ``mailbox_provisioning_fee`` to the quote;
+        it's free once that address is ``active``. Domains in ``'relay'`` mode
+        never charge it. ``list_domains()`` reports the mode per domain.
+
+        ``mailbox_mode`` ('relay' | 'mailbox') selects how a domain sends:
+        'relay' is header-only send (no per-address mailbox, no mailbox fee);
+        'mailbox' provisions a real dedicated mailbox per address (better
+        deliverability + per-address warmup). It is honored **only while a domain
+        is unprovisioned** — use it on a new ``from_domain``.
+
+        So omitting it is not a way to avoid the fee: an already-provisioned
+        domain always uses the mode it was created with, and ``from_mailbox`` has
+        no bearing on it. (A domain you own that is still unprovisioned does
+        honor it — asking for 'mailbox' there opts it in.) Check
+        ``list_domains()`` for which of your domains report
+        ``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",
@@ -1218,6 +1485,7 @@ class OneShotClient:
     ) -> Any:
         start = time.monotonic()
         retries = 0
+        polls = 0
 
         while (time.monotonic() - start) < timeout_sec:
             try:
@@ -1262,7 +1530,12 @@ class OneShotClient:
                     )
 
                 retries = 0
-                await asyncio.sleep(_POLL_INTERVAL)
+                interval = _POLL_BACKOFF[min(polls, len(_POLL_BACKOFF) - 1)]
+                polls += 1
+                remaining = timeout_sec - (time.monotonic() - start)
+                if remaining <= 0:
+                    break
+                await asyncio.sleep(min(interval, remaining))
 
             except (OneShotError, JobError):
                 raise
@@ -1270,7 +1543,10 @@ class OneShotClient:
                 retries += 1
                 if retries > _MAX_POLL_RETRIES:
                     raise
-                await asyncio.sleep(_POLL_INTERVAL * (2 ** (retries - 1)))
+                remaining = timeout_sec - (time.monotonic() - start)
+                if remaining <= 0:
+                    break
+                await asyncio.sleep(min(_POLL_RETRY_BASE * (2 ** (retries - 1)), remaining))
 
         elapsed_ms = int((time.monotonic() - start) * 1000)
         raise JobTimeoutError(request_id, elapsed_ms)

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

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

oneshot_python-0.20.2/tests/test_budgets.py

@@ -0,0 +1,184 @@
+"""Tests for the spend-budget surface of OneShotClient.
+
+Mirrors tests/unit/sdk-budget-config.test.ts on the TS side: config is synced
+once via a write-scoped PUT, a 403 budget_exceeded maps to BudgetExceededError,
+the per-transaction cap fails fast locally, and get_budgets returns `data`.
+The server-side arithmetic is covered by tests/unit/spend-budget-guard.test.ts.
+"""
+
+from __future__ import annotations
+
+import json
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from oneshot import BudgetExceededError, BudgetSyncError, ToolError, ValidationError
+from oneshot.client import OneShotClient, _parse_budget_rejection
+
+TEST_PRIVATE_KEY = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"
+
+
+class _Resp:
+    def __init__(self, status_code: int, body=None, text: str = ""):
+        self.status_code = status_code
+        self._body = body
+        self.text = text or (json.dumps(body) if body is not None else "")
+        self.is_success = 200 <= status_code < 300
+
+    def json(self):
+        if self._body is None:
+            raise ValueError("no json")
+        return self._body
+
+
+BUDGET_403 = {
+    "error": "budget_exceeded",
+    "message": "over",
+    "budget": {"reason": "daily", "cap": "50.000000", "spent": "49.700000", "charge": "0.500000", "resets_at": "2026-08-23T00:00:00.000Z"},
+}
+
+
+# ── config normalisation ────────────────────────────────────────────────
+
+def test_accepts_snake_and_camel_keys():
+    c = OneShotClient(TEST_PRIVATE_KEY, budgets={"daily": 50, "perTransaction": 5, "alertAt": 0.5})
+    assert c._budgets == {"daily": 50.0, "per_transaction": 5.0, "alert_at": 0.5}
+
+
+def test_no_budget_means_no_sync():
+    c = OneShotClient(TEST_PRIVATE_KEY)
+    assert c._budgets is None and c._alert_email is None
+
+
+# ── 403 mapping ─────────────────────────────────────────────────────────
+
+def test_parse_budget_rejection_maps_fields():
+    err = _parse_budget_rejection(_Resp(403, BUDGET_403))
+    assert isinstance(err, BudgetExceededError)
+    assert err.reason == "daily"
+    assert err.cap == 50.0 and err.spent == 49.7 and err.charge == 0.5
+    assert err.resets_at == "2026-08-23T00:00:00.000Z"
+
+
+def test_parse_budget_rejection_ignores_other_403s():
+    # An auth 403 must not be reported as a budget problem.
+    assert _parse_budget_rejection(_Resp(403, {"error": "forbidden"})) is None
+    assert _parse_budget_rejection(_Resp(403, None, text="nope")) is None
+    assert _parse_budget_rejection(_Resp(402, BUDGET_403)) is None
+
+
+# ── sync ────────────────────────────────────────────────────────────────
+
+def _client_with_put(status: int = 200, exc: Exception | None = None):
+    c = OneShotClient(TEST_PRIVATE_KEY, budgets={"daily": 50, "per_transaction": 5}, alert_email="a@b.co")
+    put = AsyncMock(side_effect=exc) if exc else AsyncMock(return_value=_Resp(status, {"success": True}))
+    return c, put
+
+
+def _patched_httpx(put_mock):
+    client = MagicMock()
+    client.put = put_mock
+    cm = MagicMock()
+    cm.__aenter__ = AsyncMock(return_value=client)
+    cm.__aexit__ = AsyncMock(return_value=False)
+    return patch("oneshot.client.httpx.AsyncClient", return_value=cm)
+
+
+@pytest.mark.asyncio
+async def test_sync_sends_one_write_scoped_put_with_snake_case_body():
+    c, put = _client_with_put()
+    with _patched_httpx(put):
+        await c.aensure_budgets_synced()
+        await c.aensure_budgets_synced()  # second call is a no-op
+    assert put.await_count == 1
+    kwargs = put.await_args.kwargs
+    assert kwargs["json"] == {"daily": 50.0, "per_transaction": 5.0, "alert_email": "a@b.co"}
+    assert put.await_args.args[0].endswith("/v1/agents/me/budgets")
+    # write-scoped proof, not the read one
+    proof = json.loads(__import__("base64").b64decode(kwargs["headers"]["x-agent-proof"]))
+    assert proof["scope"] == "write"
+
+
+@pytest.mark.asyncio
+async def test_sync_fails_closed_on_5xx_network_and_4xx_and_retries_next_call():
+    # Proceeding without the configured guardrail would be the exact failure
+    # the budget exists to prevent — every failure refuses the paid call and
+    # leaves the client unsynced so the next call retries.
+    for status, exc in ((503, None), (429, None), (400, None), (None, ConnectionError("boom"))):
+        c, put = _client_with_put(status=status or 200, exc=exc)
+        with _patched_httpx(put):
+            with pytest.raises(BudgetSyncError) as excinfo:
+                await c.aensure_budgets_synced()
+        assert c._budget_synced is False
+        assert excinfo.value.status == status
+
+    # ...and a later success clears the condition.
+    c, put = _client_with_put(status=200)
+    with _patched_httpx(put):
+        await c.aensure_budgets_synced()
+    assert c._budget_synced is True
+
+
+@pytest.mark.asyncio
+async def test_paid_call_is_refused_when_sync_fails():
+    c, put = _client_with_put(status=503)
+    with _patched_httpx(put):
+        with pytest.raises(BudgetSyncError):
+            await c.acall_tool("/v1/tools/research", {"topic": "x"})
+    # the PUT was attempted, no tool POST followed
+    assert put.await_count == 1
+
+
+# ── config validation ───────────────────────────────────────────────────
+
+@pytest.mark.parametrize(
+    "budgets, field",
+    [
+        ({"daily": -1}, "budgets.daily"),
+        ({"daily": 0}, "budgets.daily"),
+        ({"per_transaction": float("inf")}, "budgets.per_transaction"),
+        ({"alert_at": 2}, "budgets.alert_at"),
+        ({"pauseAt": 0}, "budgets.pause_at"),
+        ({"daily": "5oops"}, "budgets.daily"),
+        ({"daily": True}, "budgets.daily"),          # float(True) == 1.0
+        ({"daliy": 50}, "budgets.daliy"),            # typo'd key must not mean "no cap"
+        ({"daily": 50, "per_tx": 5}, "budgets.per_tx"),
+    ],
+)
+def test_invalid_budget_config_is_rejected_at_construction(budgets, field):
+    with pytest.raises(ValidationError) as excinfo:
+        OneShotClient(TEST_PRIVATE_KEY, budgets=budgets)
+    assert excinfo.value.field == field
+
+
+# ── local per-transaction pre-flight ────────────────────────────────────
+
+def test_per_transaction_preflight_raises_before_signing():
+    c = OneShotClient(TEST_PRIVATE_KEY, budgets={"per_transaction": 1})
+    with pytest.raises(BudgetExceededError) as excinfo:
+        c._assert_within_budget("1.500000")
+    assert excinfo.value.reason == "per_transaction"
+    assert excinfo.value.cap == 1.0
+    c._assert_within_budget("1.000000")  # exactly at the cap is allowed
+    OneShotClient(TEST_PRIVATE_KEY)._assert_within_budget("999")  # no cap → no-op
+
+
+# ── get_budgets ─────────────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_get_budgets_unwraps_data():
+    c = OneShotClient(TEST_PRIVATE_KEY)
+    c.acall_free_get = AsyncMock(return_value={"success": True, "data": {"daily_usdc": 50, "spent_today_usdc": "1.0"}})  # type: ignore[method-assign]
+    out = await c.aget_budgets()
+    assert out == {"daily_usdc": 50, "spent_today_usdc": "1.0"}
+    c.acall_free_get.assert_awaited_once_with("/v1/agents/me/budgets")
+
+
+@pytest.mark.asyncio
+async def test_put_helper_raises_tool_error_on_failure():
+    c = OneShotClient(TEST_PRIVATE_KEY)
+    put = AsyncMock(return_value=_Resp(401, {"error": "proof_required"}))
+    with _patched_httpx(put):
+        with pytest.raises(ToolError):
+            await c.acall_free_put("/v1/agents/me/budgets", {"daily": 1})

oneshot_python-0.20.2/tests/test_poll_backoff.py

@@ -0,0 +1,107 @@
+"""Tests for the job poll cadence in OneShotClient._poll_job.
+
+The client polls GET /v1/requests/{id} immediately, then backs off
+0.3s → 0.6s → 1.0s → 2.0s (and stays at 2.0s). Most jobs finish within a few
+seconds, so the first checks are fast; the previous flat 2s interval added up
+to 2s of dead time to every call. Transient errors keep their own 2s-based
+retry backoff, and no sleep may overshoot the caller's deadline.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from oneshot import client as client_module
+from oneshot._errors import JobTimeoutError
+from oneshot.client import OneShotClient
+
+TEST_PRIVATE_KEY = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"
+REQ = "req_backoff_1"
+
+
+def _resp(payload: dict) -> MagicMock:
+    resp = MagicMock()
+    resp.is_success = True
+    resp.status_code = 200
+    resp.json.return_value = payload
+    return resp
+
+
+def _processing() -> MagicMock:
+    return _resp({"status": "processing", "request_id": REQ})
+
+
+def _completed(result: dict | None = None) -> MagicMock:
+    return _resp({"status": "completed", "request_id": REQ, "result": result or {"ok": True}})
+
+
+@pytest.fixture
+def fake_time(monkeypatch):
+    """Virtual clock: asyncio.sleep records the delay and advances time.monotonic."""
+    clock = {"t": 0.0}
+    sleeps: list[float] = []
+    real_sleep = asyncio.sleep
+
+    async def fake_sleep(delay: float) -> None:
+        sleeps.append(round(delay, 6))
+        clock["t"] += delay
+        await real_sleep(0)
+
+    monkeypatch.setattr(client_module.asyncio, "sleep", fake_sleep)
+    monkeypatch.setattr(client_module.time, "monotonic", lambda: clock["t"])
+    return sleeps
+
+
+async def _run_poll(http_responses, timeout_sec: int = 120):
+    client = OneShotClient(TEST_PRIVATE_KEY)
+    http = MagicMock()
+    http.get = AsyncMock(side_effect=http_responses)
+    return await client._poll_job(http, REQ, timeout_sec), http
+
+
+@pytest.mark.asyncio
+class TestPollBackoff:
+    async def test_first_poll_is_immediate_and_backoff_ramps(self, fake_time):
+        result, http = await _run_poll([_processing()] * 4 + [_completed({"answer": 42})])
+
+        assert result == {"answer": 42, "request_id": REQ}
+        assert fake_time == [0.3, 0.6, 1.0, 2.0]
+        assert http.get.await_count == 5
+
+    async def test_backoff_caps_at_two_seconds(self, fake_time):
+        await _run_poll([_processing()] * 6 + [_completed()])
+
+        assert fake_time == [0.3, 0.6, 1.0, 2.0, 2.0, 2.0]
+
+    async def test_completed_on_first_poll_never_sleeps(self, fake_time):
+        result, http = await _run_poll([_completed()])
+
+        assert result["request_id"] == REQ
+        assert fake_time == []
+        assert http.get.await_count == 1
+
+    async def test_transient_error_uses_retry_backoff(self, fake_time):
+        result, http = await _run_poll([RuntimeError("connection reset"), _completed()])
+
+        assert result["request_id"] == REQ
+        assert fake_time == [2.0]
+        assert http.get.await_count == 2
+
+    async def test_sleep_never_overshoots_deadline(self, fake_time):
+        with pytest.raises(JobTimeoutError):
+            await _run_poll([_processing()] * 50, timeout_sec=1)
+
+        # 0.3 + 0.6 = 0.9 elapsed; the next interval (1.0) is clamped to the
+        # remaining 0.1 so the wait ends at the deadline, not 0.9s past it.
+        assert fake_time == [0.3, 0.6, 0.1]
+
+    async def test_retry_sleep_never_overshoots_deadline(self, fake_time):
+        with pytest.raises(JobTimeoutError):
+            await _run_poll([_processing(), RuntimeError("reset")] + [_processing()] * 50, timeout_sec=1)
+
+        # 0.3 elapsed after the first poll; the 2.0s retry backoff is clamped
+        # to the remaining 0.7 so the timeout fires on time, not ~1.3s late.
+        assert fake_time == [0.3, 0.7]

{oneshot_python-0.19.0 → oneshot_python-0.20.2}/tests/test_request_id.py

@@ -187,16 +187,13 @@ class TestMemoValidation:
     def test_valid_memo_passes_through(self):
         client = make_client()
         payload = {"query": "test", "memo": "valid reason"}
-        # Run validation by calling acall_tool internals
-        # We test by inspecting payload mutation before the HTTP call
-        # Simulating the validation block directly
+        # Simulating acall_tool's validation block directly
         memo = payload.get("memo")
         assert memo == "valid reason"
 
     def test_empty_memo_is_dropped(self):
         client = make_client()
         payload = {"query": "test", "memo": ""}
-        # Simulate validation
         memo = payload.get("memo")
         if memo is not None and (not isinstance(memo, str) or not memo.strip()):
             payload.pop("memo", None)

oneshot_python-0.20.2/tests/test_wait_false.py

@@ -0,0 +1,88 @@
+"""Tests for ``wait=False`` and ``wait_for_result`` / ``await_result``.
+
+Parity with the TS SDK: a paid call can return as soon as the job is queued,
+and the ``request_id`` can be resolved later against ``GET /v1/requests/{id}``.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from oneshot._errors import ValidationError
+from oneshot.client import OneShotClient
+
+TEST_PRIVATE_KEY = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"
+REQ = "req_wait_1"
+
+
+def _resp(status_code: int, payload: dict) -> MagicMock:
+    resp = MagicMock()
+    resp.status_code = status_code
+    resp.is_success = 200 <= status_code < 300
+    resp.json.return_value = payload
+    resp.text = ""
+    resp.raise_for_status = MagicMock()
+    return resp
+
+
+@pytest.mark.asyncio
+class TestWaitFalse:
+    async def test_free_route_queued_job_returns_immediately(self):
+        client = OneShotClient(TEST_PRIVATE_KEY)
+        client._budget_synced = True
+        http = MagicMock()
+        http.post = AsyncMock(return_value=_resp(202, {"request_id": REQ, "status": "processing"}))
+        http.__aenter__ = AsyncMock(return_value=http)
+        http.__aexit__ = AsyncMock(return_value=False)
+        with patch("oneshot.client.httpx.AsyncClient", return_value=http), \
+             patch.object(client, "_poll_job", new=AsyncMock()) as poll:
+            out = await client.acall_tool("/v1/tools/web-read", {"url": "https://example.com"}, wait=False)
+
+        assert out == {"request_id": REQ, "status": "processing"}
+        poll.assert_not_awaited()
+
+    async def test_default_still_waits(self):
+        client = OneShotClient(TEST_PRIVATE_KEY)
+        client._budget_synced = True
+        http = MagicMock()
+        http.post = AsyncMock(return_value=_resp(202, {"request_id": REQ, "status": "processing"}))
+        http.__aenter__ = AsyncMock(return_value=http)
+        http.__aexit__ = AsyncMock(return_value=False)
+        with patch("oneshot.client.httpx.AsyncClient", return_value=http), \
+             patch.object(client, "_poll_job", new=AsyncMock(return_value={"ok": True})) as poll:
+            out = await client.acall_tool("/v1/tools/web-read", {"url": "https://example.com"})
+
+        assert out == {"ok": True}
+        poll.assert_awaited_once()
+
+    async def test_await_result_polls_the_request(self):
+        client = OneShotClient(TEST_PRIVATE_KEY)
+        http = MagicMock()
+        http.get = AsyncMock(side_effect=[
+            _resp(200, {"status": "processing", "request_id": REQ}),
+            _resp(200, {"status": "completed", "request_id": REQ, "result": {"answer": 42}}),
+        ])
+        http.__aenter__ = AsyncMock(return_value=http)
+        http.__aexit__ = AsyncMock(return_value=False)
+        with patch("oneshot.client.httpx.AsyncClient", return_value=http), \
+             patch("oneshot.client.asyncio.sleep", new=AsyncMock()):
+            out = await client.await_result(REQ, timeout_sec=30)
+
+        assert out == {"answer": 42, "request_id": REQ}
+        assert http.get.await_count == 2
+        assert http.get.await_args_list[0].args[0].endswith(f"/v1/requests/{REQ}")
+
+    async def test_await_result_requires_request_id(self):
+        client = OneShotClient(TEST_PRIVATE_KEY)
+        with pytest.raises(ValidationError):
+            await client.await_result("")
+
+
+class TestSyncWrapper:
+    def test_wait_for_result_delegates(self):
+        client = OneShotClient(TEST_PRIVATE_KEY)
+        with patch.object(client, "await_result", new=AsyncMock(return_value={"done": True})) as inner:
+            assert client.wait_for_result(REQ, timeout_sec=5) == {"done": True}
+        inner.assert_awaited_once_with(REQ, timeout_sec=5, wait_for_phones=False, phone_timeout_sec=360)