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

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

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

{oneshot_python-0.36.0 → oneshot_python-0.37.0}/README.md

@@ -194,6 +194,7 @@ print(goal["goal_id"])
 # Observe
 status = client.get_compute_goal(goal["goal_id"])
 tasks = client.get_compute_tasks(goal["goal_id"])
+outputs = client.get_compute_outputs(goal["goal_id"])  # what the tasks produced; read one with get_compute_output(goal_id, key)
 budget = client.get_compute_budget(goal["goal_id"])
 
 # Top up a recurring goal (paid)
@@ -212,7 +213,7 @@ Every method has an `a*` async mirror (`acompute`, `aget_compute_goal`, …).
 
 ### 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 a second charge. Postal delivery does not prove the letter was read; paid receipts and fulfillment events are separate. Lob credentials stay on OneShot's server.
+`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 a second charge. Postal delivery does not prove the letter was read; paid receipts and fulfillment events are separate. Mail provider credentials stay on OneShot's server.
 
 ### Account login and 2FA (0.24.0+)
 

{oneshot_python-0.36.0 → oneshot_python-0.37.0}/oneshot/client.py

@@ -59,11 +59,13 @@ try:
 
     SDK_VERSION = _pkg_version("oneshot-python")
 except Exception:  # pragma: no cover - editable/source runs without dist metadata
-    SDK_VERSION = "0.36.0"
+    SDK_VERSION = "0.37.0"
 
 _BASE_URL = "https://win.oneshotagent.com"
 _HUNT_BASE_URL = "https://api.soulhunt.ai"
 _ACCESS_TOKEN_RE = re.compile(r"^oneshot_[0-9a-f]{64}$")
+# Endpoints whose admission reads a "submit"-scoped agent proof (same list as the TypeScript SDK).
+_DURABLE_ADMISSION_ENDPOINT = re.compile(r"(enrich/(profile|email)|verify/email|physical-mail/send)$")
 _CHAIN_ID = 8453
 _USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
 
@@ -631,6 +633,24 @@ class OneShotClient:
             self._log(f"Failed to sign read proof (continuing without): {e}")
         return headers
 
+    def _prove_wallet(self, headers: dict[str, str], endpoint: str) -> dict[str, str]:
+        """Add a signed agent proof to a paid-call leg that carries no signed
+        payment. The API spends an agent's credits, and shows them on a quote,
+        only for a caller that has proven it holds the wallet: ``X-Agent-ID``
+        alone is a public address. A leg with a real payment signature needs
+        none. The endpoints with durable admission read a ``submit`` proof.
+        An access-token session is already bound to its agent. A signing
+        failure is logged and the leg goes without, so the call is priced as
+        if the agent held no credits."""
+        if self._access_token:
+            return headers
+        scope = "submit" if _DURABLE_ADMISSION_ENDPOINT.search(endpoint) else "write"
+        try:
+            headers["x-agent-proof"] = sign_read_proof(self._private_key, self.address, scope=scope)
+        except Exception as e:  # noqa: BLE001
+            self._log(f"Failed to sign agent proof (continuing without; credits will not be used): {e}")
+        return headers
+
     def _write_headers(self, domain_name: str = "OneShot Agent Auth") -> dict[str, str]:
         """Like ``_read_headers`` but with a ``write``-scoped proof, for the
         signed mutation routes (budgets). The server enforces the proof on
@@ -851,6 +871,7 @@ class OneShotClient:
             # on this very first attempt, so an already-obtained quote_id
             # must be sent from the start, not just on the paid retry.
             initial_headers = self._with_approval(self._headers(max_cost=max_cost, idempotency_key=idempotency_key), approval_id)
+            self._prove_wallet(initial_headers, endpoint)
             if quote_id:
                 initial_headers["x-quote-id"] = quote_id
             resp = await client.post(url, headers=initial_headers, json=payload)
@@ -985,6 +1006,9 @@ class OneShotClient:
                     **self._with_approval(self._headers(max_cost=max_cost, idempotency_key=idempotency_key), approval_id),
                     "payment-signature": encode_payment_header(auth),
                 }
+                # The zero-cost authorization is an unsigned stub, so this leg
+                # still has to prove the wallet for the credits to be spent.
+                self._prove_wallet(headers, endpoint)
                 if quote_id:
                     headers["x-quote-id"] = quote_id
                 resp2 = await client.post(url, headers=headers, json=payload)
@@ -1368,6 +1392,32 @@ class OneShotClient:
         """List tasks under a goal. Async."""
         return self._unwrap_data(await self.acall_free_get(f"/v1/compute/{goal_id}/tasks"))
 
+    def get_compute_outputs(self, goal_id: str) -> Any:
+        """List what a goal produced: the files its sandbox tasks left and the
+        tool results too large for a task row. The goal's short answer is
+        ``result`` on ``get_compute_goal``. Blocking."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.aget_compute_outputs(goal_id)
+        )
+
+    async def aget_compute_outputs(self, goal_id: str) -> Any:
+        """List what a goal produced. Async."""
+        return self._unwrap_data(await self.acall_free_get(f"/v1/compute/{goal_id}/outputs"))
+
+    def get_compute_output(self, goal_id: str, key: str) -> Any:
+        """Read one output of a goal by the ``key`` from ``get_compute_outputs``
+        (or a task's ``outputs``). ``content`` is None when the output was too
+        large to keep (``readable`` False). Blocking."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.aget_compute_output(goal_id, key)
+        )
+
+    async def aget_compute_output(self, goal_id: str, key: str) -> Any:
+        """Read one output of a goal. Async."""
+        # The key is a path: keep its slashes, escape everything else.
+        path = "/".join(quote(part, safe="") for part in key.split("/"))
+        return self._unwrap_data(await self.acall_free_get(f"/v1/compute/{goal_id}/outputs/{path}"))
+
     def get_compute_budget(self, goal_id: str) -> Any:
         """Get budget breakdown. Blocking."""
         return asyncio.get_event_loop().run_until_complete(
@@ -2118,7 +2168,7 @@ class OneShotClient:
 
     async def apause_domain(self, domain: str) -> DomainPoolStatusResult:
         """Take a domain out of rotation without releasing it. Async."""
-        return await self.acall_free_post(self._domain_action_path(domain, "pause"))
+        return await self.acall_free_post(self._domain_action_path(domain, "pause"), scope="write")
 
     def resume_domain(self, domain: str) -> DomainPoolStatusResult:
         """Put a paused domain back into rotation. Blocking."""
@@ -2130,7 +2180,7 @@ class OneShotClient:
         Reputation pauses (`pause_reason='low_reputation'`) auto-recover once the
         domain is warmed again; a manual pause needs this call.
         """
-        return await self.acall_free_post(self._domain_action_path(domain, "resume"))
+        return await self.acall_free_post(self._domain_action_path(domain, "resume"), scope="write")
 
     @staticmethod
     def _domain_action_path(domain: str, action: str) -> str:

{oneshot_python-0.36.0 → oneshot_python-0.37.0}/pyproject.toml

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

oneshot_python-0.37.0/tests/test_compute_outputs.py

@@ -0,0 +1,47 @@
+"""Reading what a compute goal produced. Mirrors tests/unit/sdk-compute-outputs.test.ts."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from oneshot.client import OneShotClient
+
+TEST_PRIVATE_KEY = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"
+GOAL = "b33839af-380f-4880-8355-57629ec68cb3"
+KEY = "artifacts/5b36dba3-7978-4bab-b222-c003455c1bcf/result.txt"
+OUTPUT = {"key": KEY, "task_id": "5b36dba3-7978-4bab-b222-c003455c1bcf", "content_type": "text/plain",
+          "size_bytes": 84, "summary": "Agent output", "readable": True, "updated_at": "2026-10-12T09:54:52.000Z"}
+
+
+@pytest.mark.asyncio
+async def test_lists_outputs():
+    client = OneShotClient(TEST_PRIVATE_KEY)
+    with patch.object(client, "acall_free_get", new=AsyncMock(return_value={"success": True, "data": [OUTPUT]})) as get:
+        assert await client.aget_compute_outputs(GOAL) == [OUTPUT]
+    get.assert_awaited_once_with(f"/v1/compute/{GOAL}/outputs")
+
+
+@pytest.mark.asyncio
+async def test_reads_one_output_keeping_the_slashes_of_its_key():
+    client = OneShotClient(TEST_PRIVATE_KEY)
+    body = {**OUTPUT, "content": "f6a0\n2880067194370816120", "truncated": False}
+    with patch.object(client, "acall_free_get", new=AsyncMock(return_value={"success": True, "data": body})) as get:
+        out = await client.aget_compute_output(GOAL, KEY)
+    assert out["content"] == "f6a0\n2880067194370816120"
+    get.assert_awaited_once_with(f"/v1/compute/{GOAL}/outputs/{KEY}")
+
+
+@pytest.mark.asyncio
+async def test_escapes_each_segment_of_a_key():
+    client = OneShotClient(TEST_PRIVATE_KEY)
+    with patch.object(client, "acall_free_get", new=AsyncMock(return_value={"success": True, "data": {}})) as get:
+        await client.aget_compute_output(GOAL, "artifacts/task/my report #1.txt")
+    get.assert_awaited_once_with(f"/v1/compute/{GOAL}/outputs/artifacts/task/my%20report%20%231.txt")
+
+
+def test_blocking_wrappers_exist():
+    client = OneShotClient(TEST_PRIVATE_KEY)
+    with patch.object(client, "acall_free_get", new=AsyncMock(return_value={"success": True, "data": [OUTPUT]})):
+        assert client.get_compute_outputs(GOAL) == [OUTPUT]

{oneshot_python-0.36.0 → oneshot_python-0.37.0}/tests/test_domains.py

@@ -148,7 +148,7 @@ class TestPauseResumeDomain:
         ) as mock:
             result = await client.apause_domain("warmed-example.com")
 
-        mock.assert_called_once_with("/v1/tools/email/domains/warmed-example.com/pause")
+        mock.assert_called_once_with("/v1/tools/email/domains/warmed-example.com/pause", scope="write")
         assert result == MOCK_STATUS_RESPONSE
 
     @pytest.mark.asyncio
@@ -160,7 +160,7 @@ class TestPauseResumeDomain:
         ) as mock:
             await client.aresume_domain("warmed-example.com")
 
-        mock.assert_called_once_with("/v1/tools/email/domains/warmed-example.com/resume")
+        mock.assert_called_once_with("/v1/tools/email/domains/warmed-example.com/resume", scope="write")
 
     @pytest.mark.asyncio
     async def test_encodes_the_domain_segment(self) -> None:
@@ -173,7 +173,7 @@ class TestPauseResumeDomain:
             await client.apause_domain("evil.com/../../admin")
 
         mock.assert_called_once_with(
-            "/v1/tools/email/domains/evil.com%2F..%2F..%2Fadmin/pause"
+            "/v1/tools/email/domains/evil.com%2F..%2F..%2Fadmin/pause", scope="write"
         )
 
     @pytest.mark.asyncio

oneshot_python-0.37.0/tests/test_domains_signed.py

@@ -0,0 +1,78 @@
+"""The email-domain routes are signed by this SDK (#1399).
+
+The API answers an unsigned caller 401 ``proof_required`` on GET
+/v1/tools/email/domains (read proof) and POST .../pause and .../resume (write
+proof). These tests decode the real ``x-agent-proof`` header the client sends,
+not just that one is present.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from oneshot.client import OneShotClient
+
+TEST_PRIVATE_KEY = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"
+
+
+def _proof(headers: dict[str, str]) -> dict:
+    assert "x-agent-proof" in headers, f"no x-agent-proof in {sorted(headers)}"
+    return json.loads(base64.b64decode(headers["x-agent-proof"]))
+
+
+def _http(method: str) -> MagicMock:
+    resp = MagicMock()
+    resp.is_success = True
+    resp.status_code = 200
+    resp.json.return_value = {"ok": True}
+    http = MagicMock()
+    setattr(http, method, AsyncMock(return_value=resp))
+    http.__aenter__ = AsyncMock(return_value=http)
+    http.__aexit__ = AsyncMock(return_value=None)
+    return http
+
+
+@pytest.mark.asyncio
+async def test_list_domains_sends_a_read_proof() -> None:
+    client = OneShotClient(TEST_PRIVATE_KEY)
+    http = _http("get")
+    with patch("oneshot.client.httpx.AsyncClient", return_value=http):
+        await client.alist_domains()
+
+    call = http.get.call_args
+    assert call.args[0].endswith("/v1/tools/email/domains")
+    proof = _proof(call.kwargs["headers"])
+    assert proof["scope"] == "read"
+    assert proof["agent"] == client.address
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("action", ["pause", "resume"])
+async def test_pause_and_resume_send_a_write_proof(action: str) -> None:
+    client = OneShotClient(TEST_PRIVATE_KEY)
+    http = _http("post")
+    method = client.apause_domain if action == "pause" else client.aresume_domain
+    with patch("oneshot.client.httpx.AsyncClient", return_value=http):
+        await method("warmed-example.com")
+
+    call = http.post.call_args
+    assert call.args[0].endswith(f"/v1/tools/email/domains/warmed-example.com/{action}")
+    proof = _proof(call.kwargs["headers"])
+    assert proof["scope"] == "write"
+    assert proof["agent"] == client.address
+
+
+@pytest.mark.asyncio
+async def test_each_domain_call_signs_a_fresh_nonce() -> None:
+    client = OneShotClient(TEST_PRIVATE_KEY)
+    http = _http("post")
+    with patch("oneshot.client.httpx.AsyncClient", return_value=http):
+        await client.apause_domain("a.com")
+        await client.apause_domain("a.com")
+
+    nonces = [_proof(c.kwargs["headers"])["nonce"] for c in http.post.call_args_list]
+    assert len(set(nonces)) == 2

oneshot_python-0.37.0/tests/test_paid_call_proof.py

@@ -0,0 +1,101 @@
+"""The SDK proves the wallet on the legs of a paid call that carry no signed payment.
+
+The API spends an agent's credits, and shows them on a quote, only for a caller
+that has proven it holds the wallet: ``X-Agent-ID`` alone is a public address.
+Mirrors tests/unit/sdk-paid-call-proof.test.ts on the TypeScript side.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from eth_account import Account
+from eth_account.messages import encode_typed_data
+
+from oneshot.client import OneShotClient
+
+TEST_PRIVATE_KEY = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"
+ACCESS_TOKEN = "oneshot_" + "a" * 64
+WALLET = "0x" + "22" * 20
+
+
+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.headers = {}
+    return resp
+
+
+def _proof(headers: dict) -> dict:
+    """Decode an x-agent-proof header and recover who signed it."""
+    proof = json.loads(base64.b64decode(headers["x-agent-proof"]))
+    signable = encode_typed_data(
+        domain_data={"name": "OneShot Agent Auth", "version": "1"},
+        message_types={"AgentReadAuth": [
+            {"name": "agent", "type": "address"}, {"name": "scope", "type": "string"},
+            {"name": "issuedAt", "type": "uint256"}, {"name": "nonce", "type": "bytes32"},
+        ]},
+        message_data={"agent": proof["agent"], "scope": proof["scope"], "issuedAt": proof["issuedAt"],
+                      "nonce": bytes.fromhex(proof["nonce"][2:])},
+    )
+    proof["signer"] = Account.recover_message(signable, signature=proof["signature"])
+    return proof
+
+
+async def _first_leg_headers(client: OneShotClient, endpoint: str) -> dict:
+    """Run one paid call that the API answers at once, and return the headers of its first request."""
+    client._budget_synced = True
+    http = MagicMock()
+    http.post = AsyncMock(return_value=_resp(200, {"success": True, "data": {"status": "completed"}}))
+    http.__aenter__ = AsyncMock(return_value=http)
+    http.__aexit__ = AsyncMock(return_value=False)
+    with patch("oneshot.client.httpx.AsyncClient", return_value=http):
+        await client.acall_tool(endpoint, {"query": "x", "memo": "test"})
+    return http.post.await_args_list[0].kwargs["headers"]
+
+
+@pytest.mark.asyncio
+async def test_first_leg_carries_a_write_proof_signed_by_the_wallet():
+    client = OneShotClient(TEST_PRIVATE_KEY)
+    headers = await _first_leg_headers(client, "/v1/tools/search")
+    assert "payment-signature" not in headers
+    proof = _proof(headers)
+    assert proof["scope"] == "write"
+    assert proof["agent"] == client.address
+    assert proof["signer"] == client.address
+
+
+@pytest.mark.asyncio
+async def test_each_call_signs_a_fresh_proof():
+    client = OneShotClient(TEST_PRIVATE_KEY)
+    first = _proof(await _first_leg_headers(client, "/v1/tools/search"))
+    second = _proof(await _first_leg_headers(client, "/v1/tools/search"))
+    assert first["nonce"] != second["nonce"]
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("endpoint", ["/v1/tools/enrich/profile", "/v1/tools/enrich/email", "/v1/tools/verify/email"])
+async def test_durable_admission_endpoints_get_the_submit_proof_they_read(endpoint):
+    client = OneShotClient(TEST_PRIVATE_KEY)
+    assert _proof(await _first_leg_headers(client, endpoint))["scope"] == "submit"
+
+
+def test_access_token_session_sends_no_proof():
+    client = OneShotClient(access_token=ACCESS_TOKEN, address=WALLET)
+    headers = client._prove_wallet(client._headers(), "/v1/tools/search")
+    assert headers["Authorization"] == f"Bearer {ACCESS_TOKEN}"
+    assert "x-agent-proof" not in headers
+
+
+def test_a_signing_failure_sends_the_leg_without_a_proof():
+    client = OneShotClient(TEST_PRIVATE_KEY)
+    with patch("oneshot.client.sign_read_proof", side_effect=RuntimeError("no signer")):
+        headers = client._prove_wallet(client._headers(), "/v1/tools/search")
+    assert "x-agent-proof" not in headers
+    assert headers["X-Agent-ID"] == client.address