oneshot-python 0.11.0__tar.gz → 0.12.0__tar.gz

{oneshot_python-0.11.0 → oneshot_python-0.12.0}/PKG-INFO

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

{oneshot_python-0.11.0 → oneshot_python-0.12.0}/README.md

@@ -87,6 +87,37 @@ The SDK operates on **Base Mainnet** with real USDC. Fund your wallet before mak
 - `call_free_post(endpoint, payload=None)` / `acall_free_post(...)` — POST
 - `call_free_patch(endpoint, payload=None)` / `acall_free_patch(...)` — PATCH
 
+### Compute — autonomous goal orchestration
+
+Launch a compute goal and let the orchestrator plan, execute, and iterate. Paid via x402 (same flow as other tools).
+
+```python
+goal = client.compute(
+    objective="Research the top 10 AI startups and build a comparison website",
+    budget_usdc=5.00,
+    max_cost=10.00,
+)
+print(goal["goal_id"])
+
+# Observe
+status = client.get_compute_goal(goal["goal_id"])
+tasks = client.get_compute_tasks(goal["goal_id"])
+budget = client.get_compute_budget(goal["goal_id"])
+
+# Top up a recurring goal (paid)
+client.fund_compute_goal(goal["goal_id"], 10.00)
+
+# Lifecycle
+client.pause_compute_goal(goal["goal_id"])
+client.resume_compute_goal(goal["goal_id"])
+client.cancel_compute_goal(goal["goal_id"], reason="done")
+
+# HITL — respond to an approval task
+client.respond_to_compute_task(goal["goal_id"], "task_01H…", approved=True)
+```
+
+Every method has an `a*` async mirror (`acompute`, `aget_compute_goal`, …).
+
 ## Requirements
 
 - Python 3.10+

{oneshot_python-0.11.0 → oneshot_python-0.12.0}/oneshot/__init__.py

@@ -9,6 +9,18 @@ from oneshot._errors import (
     ToolError,
     ValidationError,
 )
+from oneshot._types import (
+    ComputeBudgetStatus,
+    ComputeCancelResult,
+    ComputeFundResult,
+    ComputeGoalResult,
+    ComputeGoalStatus,
+    ComputePauseResult,
+    ComputeResumeResult,
+    ComputeSchedule,
+    ComputeTask,
+    ComputeTaskResponseResult,
+)
 from oneshot.client import OneShotClient
 from oneshot.x402 import sign_payment_authorization
 
@@ -22,4 +34,14 @@ __all__ = [
     "ContentBlockedError",
     "EmergencyNumberError",
     "sign_payment_authorization",
+    "ComputeSchedule",
+    "ComputeGoalResult",
+    "ComputeGoalStatus",
+    "ComputeTask",
+    "ComputeBudgetStatus",
+    "ComputeCancelResult",
+    "ComputeTaskResponseResult",
+    "ComputePauseResult",
+    "ComputeResumeResult",
+    "ComputeFundResult",
 ]

oneshot_python-0.12.0/oneshot/_types.py

@@ -0,0 +1,178 @@
+"""Type hints for the compute orchestration API.
+
+These TypedDicts mirror libs/agent-sdk/src/types.ts field-for-field. They are
+optional at runtime — `OneShotClient` continues to return raw dicts — but
+expose the shape to IDEs and `mypy` so callers get auto-complete + type
+checking when they want it.
+
+Keep the field set IN SYNC with the TS interfaces. If you add a field here,
+add it there (and vice versa).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional, TypedDict
+
+
+class ComputeSchedule(TypedDict, total=False):
+    """Recurring-goal schedule. Mirrors `ComputeSchedule` in TS."""
+
+    cron: str
+    budget_per_run: float
+    max_runs: int
+
+
+class ComputeGoalInner(TypedDict, total=False):
+    objective: str
+    budget_usdc: str
+    deadline: str
+    schedule_cron: str
+    budget_per_run: float
+    max_runs: int
+    next_run_at: str
+
+
+class ComputeGoalResult(TypedDict, total=False):
+    """Returned by `compute()` / `acompute()` after the goal is created."""
+
+    goal_id: str
+    request_id: str
+    receipt_id: str
+    status: str
+    message: str
+    memo: str
+    cost: float
+    goal: ComputeGoalInner
+
+
+class ComputeBudgetInner(TypedDict, total=False):
+    total: str
+    spent: str
+    reserved: str
+    remaining: str
+
+
+class ComputeGoalScheduleInner(TypedDict, total=False):
+    cron: str
+    budget_per_run: str
+    max_runs: Optional[int]
+    run_count: int
+    last_run_at: Optional[str]
+    next_run_at: Optional[str]
+
+
+class ComputeGoalStatus(TypedDict, total=False):
+    """Returned by `get_compute_goal()` / `aget_compute_goal()`."""
+
+    id: str
+    status: str
+    name: str
+    objective: str
+    current_phase: Optional[int]
+    plan: Any
+    budget: Optional[ComputeBudgetInner]
+    soul_agent_id: Optional[str]
+    deadline: Optional[str]
+    started_at: Optional[str]
+    completed_at: Optional[str]
+    last_wake_at: Optional[str]
+    next_wake_at: Optional[str]
+    created_at: str
+    schedule: ComputeGoalScheduleInner
+
+
+class ComputeTask(TypedDict, total=False):
+    """Single item from `get_compute_tasks()` / `aget_compute_tasks()`."""
+
+    id: str
+    task_type: str
+    tool: Optional[str]
+    description: str
+    status: str
+    phase: Optional[int]
+    sequence: Optional[int]
+    progress_pct: Optional[float]
+    progress_message: Optional[str]
+    result: Any
+    quoted_usdc: Optional[str]
+    actual_usdc: Optional[str]
+    run_number: Optional[int]
+    started_at: Optional[str]
+    completed_at: Optional[str]
+    created_at: str
+
+
+class ComputeBudgetSpendEntry(TypedDict, total=False):
+    category: str
+    amount_usdc: str
+    description: str
+    created_at: str
+
+
+class ComputeBudgetStatus(TypedDict, total=False):
+    """Returned by `get_compute_budget()` / `aget_compute_budget()`."""
+
+    budgetId: str
+    goalId: str
+    totalBudgetUsdc: str
+    spentUsdc: str
+    reservedUsdc: str
+    remainingUsdc: str
+    spend_entries: list[ComputeBudgetSpendEntry]
+
+
+class ComputeCancelResult(TypedDict, total=False):
+    """Returned by `cancel_compute_goal()`."""
+
+    goal_id: str
+    status: str
+    remaining_budget: str
+
+
+class ComputeTaskResponseResult(TypedDict, total=False):
+    """Returned by `respond_to_compute_task()`."""
+
+    task_id: str
+    goal_id: str
+    task_status: str
+    orchestrator_action: str
+
+
+class ComputePauseResult(TypedDict, total=False):
+    """Returned by `pause_compute_goal()`."""
+
+    goal_id: str
+    status: str
+    run_count: int
+
+
+class ComputeResumeResult(TypedDict, total=False):
+    """Returned by `resume_compute_goal()`."""
+
+    goal_id: str
+    status: str
+    next_run_at: str
+    run_count: int
+
+
+class ComputeFundResult(TypedDict, total=False):
+    """Returned by `fund_compute_goal()`."""
+
+    goal_id: str
+    topped_up: float
+    total_budget: str
+    remaining: str
+
+
+__all__ = [
+    "ComputeSchedule",
+    "ComputeGoalResult",
+    "ComputeGoalStatus",
+    "ComputeTask",
+    "ComputeBudgetStatus",
+    "ComputeCancelResult",
+    "ComputeTaskResponseResult",
+    "ComputePauseResult",
+    "ComputeResumeResult",
+    "ComputeFundResult",
+]

{oneshot_python-0.11.0 → oneshot_python-0.12.0}/oneshot/client.py

@@ -46,29 +46,44 @@ _MAX_POLL_RETRIES = 3
 
 
 def _build_email_payload(
-    to: str,
-    subject: str,
+    to: Optional[str],
+    subject: Optional[str],
     body: str,
     from_domain: Optional[str],
     from_mailbox: Optional[str],
     from_name: Optional[str],
     extra: dict[str, Any],
+    *,
+    reply_to_email_id: Optional[str] = None,
 ) -> dict[str, Any]:
     """Build the /v1/tools/email/send body in the API's field convention.
 
     The API expects ``from_address`` + ``to_address`` (see
     EmailSendRequestSchema). Construct from_address from the mailbox/domain
     and forward the optional display name.
+
+    When ``reply_to_email_id`` is set (threaded reply to an inbound email),
+    ``to``/``subject`` may be omitted — the server derives them from the
+    inbound message; otherwise they are required.
     """
+    if not reply_to_email_id:
+        if not to:
+            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"
     payload: dict[str, Any] = {
         "from_address": f"{mailbox}@{domain}",
-        "to_address": to,
-        "subject": subject,
         "body": body,
         **extra,
     }
+    if to is not None:
+        payload["to_address"] = to
+    if subject is not None:
+        payload["subject"] = subject
+    if reply_to_email_id:
+        payload["reply_to_email_id"] = reply_to_email_id
     if from_name:
         payload["from_name"] = from_name
     return payload
@@ -417,6 +432,207 @@ class OneShotClient:
                 return {"success": True}
             return resp.json()
 
+    # ------------------------------------------------------------------
+    # Compute — autonomous goal orchestration (mirrors TS SDK)
+    # ------------------------------------------------------------------
+    # Two paid endpoints (compute + fund) reuse `acall_tool` for the full
+    # x402 quote+pay flow. The seven free endpoints are one-line wrappers
+    # around `acall_free_get / post` + the `_unwrap_data` envelope strip.
+    # Method names mirror the TS camelCase under Python snake_case
+    # (`getComputeGoal` -> `get_compute_goal`).
+
+    @staticmethod
+    def _unwrap_data(envelope: Any) -> Any:
+        """Strip the `{"success": true, "data": …}` envelope the compute
+        endpoints return — matches the TS SDK convention so callers see the
+        inner shape directly. `acall_tool` already unwraps for paid endpoints;
+        `acall_free_get / post` do not, so this helper handles them here."""
+        if isinstance(envelope, dict) and "data" in envelope:
+            return envelope["data"]
+        return envelope
+
+    def compute(
+        self,
+        objective: str,
+        *,
+        params: Optional[dict[str, Any]] = None,
+        budget_usdc: Optional[float] = None,
+        deadline: Optional[str] = None,
+        soul_slug: Optional[str] = None,
+        soul_service_slug: Optional[str] = None,
+        schedule: Optional[dict[str, Any]] = None,
+        max_cost: Optional[float] = None,
+        memo: Optional[str] = None,
+    ) -> Any:
+        """Create a compute goal. Blocking."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.acompute(
+                objective,
+                params=params,
+                budget_usdc=budget_usdc,
+                deadline=deadline,
+                soul_slug=soul_slug,
+                soul_service_slug=soul_service_slug,
+                schedule=schedule,
+                max_cost=max_cost,
+                memo=memo,
+            )
+        )
+
+    async def acompute(
+        self,
+        objective: str,
+        *,
+        params: Optional[dict[str, Any]] = None,
+        budget_usdc: Optional[float] = None,
+        deadline: Optional[str] = None,
+        soul_slug: Optional[str] = None,
+        soul_service_slug: Optional[str] = None,
+        schedule: Optional[dict[str, Any]] = None,
+        max_cost: Optional[float] = None,
+        memo: Optional[str] = None,
+    ) -> Any:
+        """Create a compute goal — the orchestrator plans + executes autonomously.
+
+        Quote+pay (x402) flow handled by `acall_tool`. Returns the
+        ``data`` block of the 202 response (`goal_id`, `status`, …).
+        """
+        payload: dict[str, Any] = {"objective": objective}
+        if params is not None:
+            payload["params"] = params
+        if budget_usdc is not None:
+            payload["budget_usdc"] = budget_usdc
+        if deadline is not None:
+            payload["deadline"] = deadline
+        if soul_slug is not None:
+            payload["soul_slug"] = soul_slug
+        if soul_service_slug is not None:
+            payload["soul_service_slug"] = soul_service_slug
+        if schedule is not None:
+            payload["schedule"] = schedule
+        if memo is not None:
+            payload["memo"] = memo
+        return await self.acall_tool("/v1/compute", payload, max_cost=max_cost)
+
+    def get_compute_goal(self, goal_id: str) -> Any:
+        """Get goal status. Blocking."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.aget_compute_goal(goal_id)
+        )
+
+    async def aget_compute_goal(self, goal_id: str) -> Any:
+        """Get goal status. Async."""
+        return self._unwrap_data(await self.acall_free_get(f"/v1/compute/{goal_id}"))
+
+    def get_compute_tasks(self, goal_id: str) -> Any:
+        """List tasks under a goal. Blocking."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.aget_compute_tasks(goal_id)
+        )
+
+    async def aget_compute_tasks(self, goal_id: str) -> Any:
+        """List tasks under a goal. Async."""
+        return self._unwrap_data(await self.acall_free_get(f"/v1/compute/{goal_id}/tasks"))
+
+    def get_compute_budget(self, goal_id: str) -> Any:
+        """Get budget breakdown. Blocking."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.aget_compute_budget(goal_id)
+        )
+
+    async def aget_compute_budget(self, goal_id: str) -> Any:
+        """Get budget breakdown. Async."""
+        return self._unwrap_data(await self.acall_free_get(f"/v1/compute/{goal_id}/budget"))
+
+    def cancel_compute_goal(self, goal_id: str, reason: Optional[str] = None) -> Any:
+        """Cancel a goal; remaining budget is credited. Blocking."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.acancel_compute_goal(goal_id, reason)
+        )
+
+    async def acancel_compute_goal(
+        self, goal_id: str, reason: Optional[str] = None
+    ) -> Any:
+        """Cancel a goal; remaining budget is credited. Async."""
+        payload: dict[str, Any] = {"reason": reason} if reason is not None else {}
+        return self._unwrap_data(
+            await self.acall_free_post(f"/v1/compute/{goal_id}/cancel", payload)
+        )
+
+    def respond_to_compute_task(
+        self,
+        goal_id: str,
+        task_id: str,
+        *,
+        response: Optional[str] = None,
+        approved: Optional[bool] = None,
+    ) -> Any:
+        """Respond to a human-in-the-loop approval task. Blocking."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.arespond_to_compute_task(
+                goal_id, task_id, response=response, approved=approved
+            )
+        )
+
+    async def arespond_to_compute_task(
+        self,
+        goal_id: str,
+        task_id: str,
+        *,
+        response: Optional[str] = None,
+        approved: Optional[bool] = None,
+    ) -> Any:
+        """Respond to a human-in-the-loop approval task. Async."""
+        payload: dict[str, Any] = {"task_id": task_id}
+        if response is not None:
+            payload["response"] = response
+        if approved is not None:
+            payload["approved"] = approved
+        return self._unwrap_data(
+            await self.acall_free_post(f"/v1/compute/{goal_id}/respond", payload)
+        )
+
+    def pause_compute_goal(self, goal_id: str, reason: Optional[str] = None) -> Any:
+        """Pause a recurring goal. Blocking."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.apause_compute_goal(goal_id, reason)
+        )
+
+    async def apause_compute_goal(
+        self, goal_id: str, reason: Optional[str] = None
+    ) -> Any:
+        """Pause a recurring goal. Async."""
+        payload: dict[str, Any] = {"reason": reason} if reason is not None else {}
+        return self._unwrap_data(
+            await self.acall_free_post(f"/v1/compute/{goal_id}/pause", payload)
+        )
+
+    def resume_compute_goal(self, goal_id: str) -> Any:
+        """Resume a paused recurring goal. Blocking."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.aresume_compute_goal(goal_id)
+        )
+
+    async def aresume_compute_goal(self, goal_id: str) -> Any:
+        """Resume a paused recurring goal. Async."""
+        return self._unwrap_data(
+            await self.acall_free_post(f"/v1/compute/{goal_id}/resume", {})
+        )
+
+    def fund_compute_goal(self, goal_id: str, amount: float) -> Any:
+        """Top up budget on a recurring goal. Blocking."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.afund_compute_goal(goal_id, amount)
+        )
+
+    async def afund_compute_goal(self, goal_id: str, amount: float) -> Any:
+        """Top up budget on a recurring goal. Quote+pay (x402) via `acall_tool`."""
+        if not amount or amount <= 0:
+            raise ValidationError("amount must be a positive number", "amount")
+        return await self.acall_tool(
+            f"/v1/compute/{goal_id}/fund", {"amount": amount}
+        )
+
     # ------------------------------------------------------------------
     # Browser
     # ------------------------------------------------------------------
@@ -529,36 +745,48 @@ class OneShotClient:
 
     def email(
         self,
-        to: str,
-        subject: str,
-        body: str,
+        to: Optional[str] = None,
+        subject: Optional[str] = None,
+        body: str = "",
         *,
         from_domain: Optional[str] = None,
         from_mailbox: Optional[str] = None,
         from_name: Optional[str] = None,
+        reply_to_email_id: Optional[str] = None,
         **kwargs: Any,
     ) -> Any:
-        """Send an email. Blocking."""
+        """Send an email. Blocking.
+
+        Set ``reply_to_email_id`` (an inbound email id from ``inbox()``) to
+        reply within a thread — ``to``/``subject`` are then derived from the
+        inbound message unless given.
+        """
         return self.call_tool(
             "/v1/tools/email/send",
-            _build_email_payload(to, subject, body, from_domain, from_mailbox, from_name, kwargs),
+            _build_email_payload(to, subject, body, from_domain, from_mailbox, from_name, kwargs, reply_to_email_id=reply_to_email_id),
         )
 
     async def aemail(
         self,
-        to: str,
-        subject: str,
-        body: str,
+        to: Optional[str] = None,
+        subject: Optional[str] = None,
+        body: str = "",
         *,
         from_domain: Optional[str] = None,
         from_mailbox: Optional[str] = None,
         from_name: Optional[str] = None,
+        reply_to_email_id: Optional[str] = None,
         **kwargs: Any,
     ) -> Any:
-        """Send an email. Async."""
+        """Send an email. Async.
+
+        Set ``reply_to_email_id`` (an inbound email id from ``ainbox()``) to
+        reply within a thread — ``to``/``subject`` are then derived from the
+        inbound message unless given.
+        """
         return await self.acall_tool(
             "/v1/tools/email/send",
-            _build_email_payload(to, subject, body, from_domain, from_mailbox, from_name, kwargs),
+            _build_email_payload(to, subject, body, from_domain, from_mailbox, from_name, kwargs, reply_to_email_id=reply_to_email_id),
         )
 
     def voice(self, objective: str, target_number: str, **kwargs: Any) -> Any:

{oneshot_python-0.11.0 → oneshot_python-0.12.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "oneshot-python"
-version = "0.11.0"
+version = "0.12.0"
 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.12.0/tests/test_compute.py

@@ -0,0 +1,291 @@
+"""Tests for OneShotClient.compute() and the eight friends.
+
+Mocks the lower-level `call_tool` / `acall_tool` and `call_free_get/post`
+helpers (matching the test_balance.py pattern). The full x402 quote+pay
+flow is exercised by test_x402.py and the existing acall_tool tests; here
+we lock in the compute-specific contract: correct endpoints, correct
+payload shape, correct passthrough of optional kwargs.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from eth_account import Account
+
+from oneshot._errors import ValidationError
+from oneshot.client import OneShotClient
+
+TEST_PRIVATE_KEY = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"
+TEST_ADDRESS = Account.from_key(TEST_PRIVATE_KEY).address
+
+GOAL_ID = "goal_01HXTEST0000000000000000"
+TASK_ID = "task_01HXTEST0000000000000000"
+
+MOCK_COMPUTE_RESULT = {
+    "goal_id": GOAL_ID,
+    "request_id": "req_01HX",
+    "status": "pending",
+    "message": "Goal created",
+    "goal": {"objective": "research X", "budget_usdc": "5.00"},
+}
+
+MOCK_GOAL_STATUS = {
+    "id": GOAL_ID,
+    "status": "running",
+    "name": "Research X",
+    "objective": "research X",
+    "current_phase": 1,
+    "plan": None,
+    "budget": {"total": "5.00", "spent": "1.20", "reserved": "0.30", "remaining": "3.50"},
+    "soul_agent_id": None,
+    "deadline": None,
+    "started_at": "2026-06-04T00:00:00Z",
+    "completed_at": None,
+    "last_wake_at": None,
+    "next_wake_at": None,
+    "created_at": "2026-06-04T00:00:00Z",
+}
+
+MOCK_TASKS = [
+    {"id": "t1", "task_type": "research", "tool": "research", "description": "…", "status": "completed"},
+    {"id": "t2", "task_type": "build", "tool": "build", "description": "…", "status": "pending"},
+]
+
+MOCK_BUDGET = {
+    "budgetId": "bud_01HX",
+    "goalId": GOAL_ID,
+    "totalBudgetUsdc": "5.00",
+    "spentUsdc": "1.20",
+    "reservedUsdc": "0.30",
+    "remainingUsdc": "3.50",
+    "spend_entries": [],
+}
+
+MOCK_CANCEL = {"goal_id": GOAL_ID, "status": "cancelled", "remaining_budget": "3.50"}
+MOCK_RESPOND = {
+    "task_id": TASK_ID,
+    "goal_id": GOAL_ID,
+    "task_status": "completed",
+    "orchestrator_action": "advance",
+}
+MOCK_PAUSE = {"goal_id": GOAL_ID, "status": "paused", "run_count": 4}
+MOCK_RESUME = {"goal_id": GOAL_ID, "status": "running", "next_run_at": "2026-06-05T00:00:00Z", "run_count": 4}
+MOCK_FUND = {"goal_id": GOAL_ID, "topped_up": 10.0, "total_budget": "15.00", "remaining": "13.50"}
+
+
+def _client() -> OneShotClient:
+    return OneShotClient(TEST_PRIVATE_KEY)
+
+
+# ─── compute() — quote+pay ────────────────────────────────────────────
+
+
+class TestCompute:
+    def test_posts_minimal_payload_to_compute_endpoint(self) -> None:
+        client = _client()
+        with patch.object(client, "acall_tool", new_callable=AsyncMock, return_value=MOCK_COMPUTE_RESULT) as mock:
+            result = client.compute(objective="research X")
+        mock.assert_called_once_with("/v1/compute", {"objective": "research X"}, max_cost=None)
+        assert result == MOCK_COMPUTE_RESULT
+
+    def test_threads_all_optional_kwargs_into_payload(self) -> None:
+        client = _client()
+        with patch.object(client, "acall_tool", new_callable=AsyncMock, return_value=MOCK_COMPUTE_RESULT) as mock:
+            client.compute(
+                objective="research X",
+                params={"depth": "deep"},
+                budget_usdc=5.0,
+                deadline="2026-12-31T23:59:59Z",
+                soul_slug="agent-x",
+                soul_service_slug="svc-x",
+                schedule={"cron": "0 0 * * *", "budget_per_run": 1.0},
+                max_cost=10.0,
+                memo="hello",
+            )
+        call_args = mock.call_args
+        assert call_args.args[0] == "/v1/compute"
+        payload = call_args.args[1]
+        assert payload["objective"] == "research X"
+        assert payload["params"] == {"depth": "deep"}
+        assert payload["budget_usdc"] == 5.0
+        assert payload["deadline"] == "2026-12-31T23:59:59Z"
+        assert payload["soul_slug"] == "agent-x"
+        assert payload["soul_service_slug"] == "svc-x"
+        assert payload["schedule"] == {"cron": "0 0 * * *", "budget_per_run": 1.0}
+        assert payload["memo"] == "hello"
+        assert call_args.kwargs["max_cost"] == 10.0
+
+    def test_omits_none_kwargs_from_payload(self) -> None:
+        client = _client()
+        with patch.object(client, "acall_tool", new_callable=AsyncMock, return_value=MOCK_COMPUTE_RESULT) as mock:
+            client.compute(objective="x", budget_usdc=2.0)
+        payload = mock.call_args.args[1]
+        assert "params" not in payload
+        assert "deadline" not in payload
+        assert "memo" not in payload
+        assert payload["budget_usdc"] == 2.0
+
+    @pytest.mark.asyncio
+    async def test_async_mirror_calls_acall_tool(self) -> None:
+        client = _client()
+        with patch.object(client, "acall_tool", new_callable=AsyncMock, return_value=MOCK_COMPUTE_RESULT) as mock:
+            result = await client.acompute(objective="x", budget_usdc=1.0)
+        mock.assert_awaited_once()
+        assert result == MOCK_COMPUTE_RESULT
+
+
+# ─── free read endpoints ──────────────────────────────────────────────
+
+
+class TestGetComputeGoal:
+    def test_calls_correct_path(self) -> None:
+        client = _client()
+        with patch.object(client, "acall_free_get", new_callable=AsyncMock, return_value=MOCK_GOAL_STATUS) as mock:
+            result = client.get_compute_goal(GOAL_ID)
+        mock.assert_called_once_with(f"/v1/compute/{GOAL_ID}")
+        assert result == MOCK_GOAL_STATUS
+
+    def test_strips_data_envelope(self) -> None:
+        """API returns {success: true, data: {...}}; SDK should unwrap to match TS."""
+        client = _client()
+        envelope = {"success": True, "data": MOCK_GOAL_STATUS}
+        with patch.object(client, "acall_free_get", new_callable=AsyncMock, return_value=envelope):
+            result = client.get_compute_goal(GOAL_ID)
+        assert result == MOCK_GOAL_STATUS
+        assert "data" not in result  # confirmed unwrap, not pass-through
+
+    def test_passes_through_when_already_unwrapped(self) -> None:
+        """Some callers (or future API shape changes) may already return the inner
+        object. Helper should not double-strip a key called `data`."""
+        client = _client()
+        inner = {"id": GOAL_ID, "status": "running"}
+        with patch.object(client, "acall_free_get", new_callable=AsyncMock, return_value=inner):
+            result = client.get_compute_goal(GOAL_ID)
+        assert result == inner
+
+    @pytest.mark.asyncio
+    async def test_async_mirror(self) -> None:
+        client = _client()
+        with patch.object(client, "acall_free_get", new_callable=AsyncMock, return_value=MOCK_GOAL_STATUS):
+            result = await client.aget_compute_goal(GOAL_ID)
+        assert result["id"] == GOAL_ID
+
+
+class TestGetComputeTasks:
+    def test_calls_correct_path(self) -> None:
+        client = _client()
+        with patch.object(client, "acall_free_get", new_callable=AsyncMock, return_value=MOCK_TASKS) as mock:
+            result = client.get_compute_tasks(GOAL_ID)
+        mock.assert_called_once_with(f"/v1/compute/{GOAL_ID}/tasks")
+        assert result == MOCK_TASKS
+
+    @pytest.mark.asyncio
+    async def test_async_mirror(self) -> None:
+        client = _client()
+        with patch.object(client, "acall_free_get", new_callable=AsyncMock, return_value=MOCK_TASKS):
+            result = await client.aget_compute_tasks(GOAL_ID)
+        assert len(result) == 2
+
+
+class TestGetComputeBudget:
+    def test_calls_correct_path(self) -> None:
+        client = _client()
+        with patch.object(client, "acall_free_get", new_callable=AsyncMock, return_value=MOCK_BUDGET) as mock:
+            result = client.get_compute_budget(GOAL_ID)
+        mock.assert_called_once_with(f"/v1/compute/{GOAL_ID}/budget")
+        assert result["remainingUsdc"] == "3.50"
+
+
+# ─── free write endpoints ─────────────────────────────────────────────
+
+
+class TestCancelComputeGoal:
+    def test_omits_reason_when_none(self) -> None:
+        client = _client()
+        with patch.object(client, "acall_free_post", new_callable=AsyncMock, return_value=MOCK_CANCEL) as mock:
+            client.cancel_compute_goal(GOAL_ID)
+        mock.assert_called_once_with(f"/v1/compute/{GOAL_ID}/cancel", {})
+
+    def test_includes_reason_when_provided(self) -> None:
+        client = _client()
+        with patch.object(client, "acall_free_post", new_callable=AsyncMock, return_value=MOCK_CANCEL) as mock:
+            client.cancel_compute_goal(GOAL_ID, reason="user requested")
+        mock.assert_called_once_with(f"/v1/compute/{GOAL_ID}/cancel", {"reason": "user requested"})
+
+    @pytest.mark.asyncio
+    async def test_async_mirror(self) -> None:
+        client = _client()
+        with patch.object(client, "acall_free_post", new_callable=AsyncMock, return_value=MOCK_CANCEL):
+            result = await client.acancel_compute_goal(GOAL_ID, reason="x")
+        assert result["status"] == "cancelled"
+
+
+class TestRespondToComputeTask:
+    def test_threads_task_id_and_optional_fields(self) -> None:
+        client = _client()
+        with patch.object(client, "acall_free_post", new_callable=AsyncMock, return_value=MOCK_RESPOND) as mock:
+            client.respond_to_compute_task(GOAL_ID, TASK_ID, response="ok", approved=True)
+        mock.assert_called_once_with(
+            f"/v1/compute/{GOAL_ID}/respond",
+            {"task_id": TASK_ID, "response": "ok", "approved": True},
+        )
+
+    def test_omits_none_optional_fields(self) -> None:
+        client = _client()
+        with patch.object(client, "acall_free_post", new_callable=AsyncMock, return_value=MOCK_RESPOND) as mock:
+            client.respond_to_compute_task(GOAL_ID, TASK_ID)
+        payload = mock.call_args.args[1]
+        assert payload == {"task_id": TASK_ID}
+
+
+class TestPauseComputeGoal:
+    def test_omits_reason_when_none(self) -> None:
+        client = _client()
+        with patch.object(client, "acall_free_post", new_callable=AsyncMock, return_value=MOCK_PAUSE) as mock:
+            client.pause_compute_goal(GOAL_ID)
+        mock.assert_called_once_with(f"/v1/compute/{GOAL_ID}/pause", {})
+
+    def test_includes_reason_when_provided(self) -> None:
+        client = _client()
+        with patch.object(client, "acall_free_post", new_callable=AsyncMock, return_value=MOCK_PAUSE) as mock:
+            client.pause_compute_goal(GOAL_ID, reason="manual")
+        mock.assert_called_once_with(f"/v1/compute/{GOAL_ID}/pause", {"reason": "manual"})
+
+
+class TestResumeComputeGoal:
+    def test_calls_correct_path_with_empty_payload(self) -> None:
+        client = _client()
+        with patch.object(client, "acall_free_post", new_callable=AsyncMock, return_value=MOCK_RESUME) as mock:
+            client.resume_compute_goal(GOAL_ID)
+        mock.assert_called_once_with(f"/v1/compute/{GOAL_ID}/resume", {})
+
+
+# ─── fund_compute_goal() — quote+pay + validation ─────────────────────
+
+
+class TestFundComputeGoal:
+    def test_rejects_zero_amount(self) -> None:
+        client = _client()
+        with pytest.raises(ValidationError):
+            client.fund_compute_goal(GOAL_ID, 0)
+
+    def test_rejects_negative_amount(self) -> None:
+        client = _client()
+        with pytest.raises(ValidationError):
+            client.fund_compute_goal(GOAL_ID, -1.0)
+
+    def test_posts_to_fund_endpoint_via_acall_tool(self) -> None:
+        client = _client()
+        with patch.object(client, "acall_tool", new_callable=AsyncMock, return_value=MOCK_FUND) as mock:
+            result = client.fund_compute_goal(GOAL_ID, 10.0)
+        mock.assert_called_once_with(f"/v1/compute/{GOAL_ID}/fund", {"amount": 10.0})
+        assert result == MOCK_FUND
+
+    @pytest.mark.asyncio
+    async def test_async_mirror(self) -> None:
+        client = _client()
+        with patch.object(client, "acall_tool", new_callable=AsyncMock, return_value=MOCK_FUND):
+            result = await client.afund_compute_goal(GOAL_ID, 5.0)
+        assert result["total_budget"] == "15.00"

{oneshot_python-0.11.0 → oneshot_python-0.12.0}/tests/test_email_payload.py

@@ -11,9 +11,11 @@ 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) ───────────────────────────────────────────
@@ -44,6 +46,39 @@ def test_payload_passes_extra_kwargs():
     assert p["wait"] is True
 
 
+# ── 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:
@@ -72,3 +107,20 @@ async def test_aemail_sends_correct_contract():
     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")