singularity-grid 0.9.0__tar.gz → 0.9.2__tar.gz

{singularity_grid-0.9.0 → singularity_grid-0.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: singularity-grid
-Version: 0.9.0
+Version: 0.9.2
 Summary: Python SDK for the SGL Network confidential compute grid (end-to-end encrypted + streaming)
 Project-URL: Homepage, https://singularitylayer.xyz
 Project-URL: Repository, https://github.com/Singularity-Layer/sgl-network-sdk
@@ -119,6 +119,39 @@ attestation = grid.get_attestation(job.job_id)
 print(f"TEE verified: {attestation.verified}")
 ```
 
+### 4. System One / Laya
+
+Laya is served as a typed-decision model, not as chat completions.
+
+```python
+from singularity_grid import GridClient
+
+grid = GridClient(api_key="x402c_your_api_key")
+
+systemone_models = grid.systemone_models()
+print([model["id"] for model in systemone_models])
+
+decision = grid.system_one(
+    model="convaiinnovations/laya",
+    state={"ticket": "Enterprise customer cannot access billing exports"},
+    questions={
+        "route": {
+            "type": "choice",
+            "instructions": "Choose the best team.",
+            "criteria": {
+                "billing": "Billing, invoice, refund, or account credit issue.",
+                "support": "Product defect or technical troubleshooting.",
+            },
+        },
+        "urgency": {
+            "type": "score",
+            "instructions": "Score urgency from 0 to 1.",
+        },
+    },
+)
+print(decision["answers"])
+```
+
 ## API reference
 
 ### GridClient
@@ -127,7 +160,10 @@ print(f"TEE verified: {attestation.verified}")
 |---|---|---|
 | `capacity()` | No | Grid-wide capacity summary |
 | `models()` | No | Available models with pricing and TEE info |
+| `v1_models(type=None)` | No | OpenAI-compatible model list; pass `type="systemone"` for Laya |
+| `systemone_models()` | No | List Laya/System One typed-decision models |
 | `pricing()` | No | Pricing table for all models |
+| `system_one(state, questions, ...)` | Yes | Call `/v1/systemone` for typed decisions |
 | `submit_job(model, input_payload, ...)` | Yes | Submit a compute job |
 | `get_job(job_id)` | Yes | Get job status and result |
 | `get_attestation(job_id)` | Yes | Get TEE attestation proof |

{singularity_grid-0.9.0 → singularity_grid-0.9.2}/README.md

@@ -88,6 +88,39 @@ attestation = grid.get_attestation(job.job_id)
 print(f"TEE verified: {attestation.verified}")
 ```
 
+### 4. System One / Laya
+
+Laya is served as a typed-decision model, not as chat completions.
+
+```python
+from singularity_grid import GridClient
+
+grid = GridClient(api_key="x402c_your_api_key")
+
+systemone_models = grid.systemone_models()
+print([model["id"] for model in systemone_models])
+
+decision = grid.system_one(
+    model="convaiinnovations/laya",
+    state={"ticket": "Enterprise customer cannot access billing exports"},
+    questions={
+        "route": {
+            "type": "choice",
+            "instructions": "Choose the best team.",
+            "criteria": {
+                "billing": "Billing, invoice, refund, or account credit issue.",
+                "support": "Product defect or technical troubleshooting.",
+            },
+        },
+        "urgency": {
+            "type": "score",
+            "instructions": "Score urgency from 0 to 1.",
+        },
+    },
+)
+print(decision["answers"])
+```
+
 ## API reference
 
 ### GridClient
@@ -96,7 +129,10 @@ print(f"TEE verified: {attestation.verified}")
 |---|---|---|
 | `capacity()` | No | Grid-wide capacity summary |
 | `models()` | No | Available models with pricing and TEE info |
+| `v1_models(type=None)` | No | OpenAI-compatible model list; pass `type="systemone"` for Laya |
+| `systemone_models()` | No | List Laya/System One typed-decision models |
 | `pricing()` | No | Pricing table for all models |
+| `system_one(state, questions, ...)` | Yes | Call `/v1/systemone` for typed decisions |
 | `submit_job(model, input_payload, ...)` | Yes | Submit a compute job |
 | `get_job(job_id)` | Yes | Get job status and result |
 | `get_attestation(job_id)` | Yes | Get TEE attestation proof |

{singularity_grid-0.9.0 → singularity_grid-0.9.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "singularity-grid"
-version = "0.9.0"
+version = "0.9.2"
 description = "Python SDK for the SGL Network confidential compute grid (end-to-end encrypted + streaming)"
 readme = "README.md"
 license = "MIT"

{singularity_grid-0.9.0 → singularity_grid-0.9.2}/singularity_grid/__init__.py

@@ -10,6 +10,11 @@ from .client import (
     SGLError,
     SGLNotFoundError,
 )
+from .pods import (
+    DEFAULT_PODS_BASE_URL,
+    PodsClient,
+    verify_pod_webhook,
+)
 from .models import (
     AttestationProof,
     CapacityResponse,
@@ -24,13 +29,17 @@ from .models import (
 )
 from .openai_compat import create_openai_client
 
-__version__ = "0.2.0"
+__version__ = "0.9.2"
 
 __all__ = [
     # Processors — a SEPARATE client on processors.x402compute.cc. Until 0.9.0 these methods
     # lived on GridClient and pointed at /grid/processors, which has never existed.
     "ProcessorsClient",
     "PROCESSORS_BASE_URL",
+    # Agent Pods — hosted agents, on compute.x402layer.cc.
+    "PodsClient",
+    "DEFAULT_PODS_BASE_URL",
+    "verify_pod_webhook",
     # Client
     "GridClient",
     "create_openai_client",

{singularity_grid-0.9.0 → singularity_grid-0.9.2}/singularity_grid/client.py

@@ -170,6 +170,22 @@ class GridClient:
         wrapped = PricingResponse.model_validate(data)
         return wrapped.pricing
 
+    def v1_models(self, type: Optional[str] = None) -> List[Dict[str, Any]]:
+        """Return OpenAI-compatible ``/v1/models`` descriptors.
+
+        Pass ``type="systemone"`` to discover Laya/Jev-style typed-decision
+        models.
+        """
+        params: Dict[str, Any] = {}
+        if type is not None:
+            params["type"] = type
+        data = self._request("GET", "/v1/models", params=params or None)
+        return list(data.get("data", []))
+
+    def systemone_models(self) -> List[Dict[str, Any]]:
+        """List Laya/Jev-style System One typed-decision models."""
+        return self.v1_models(type="systemone")
+
     # -- authenticated endpoints --------------------------------------------
 
     def submit_job(
@@ -310,6 +326,9 @@ class GridClient:
         sealed = data.get("sealed_result")
         if not sealed:
             raise SGLAPIError(500, "No sealed result returned")
+        # Prove WHO produced this before opening it. AEAD only proves someone
+        # sealed it to our key, and the orchestrator knows that key.
+        e2e.require_verified_reply(reservation, data)
         plain = e2e.open_output(resp_sk, resp_pub, sealed["ephemeral_public_key"], sealed["ciphertext"])
         parsed = _json.loads(plain)
         return {
@@ -357,6 +376,44 @@ class GridClient:
                 raise SGLAPIError(402, "Payment required — pass api_key (credits); the Python GridClient does not sign x402 payments.") from err
             raise
 
+    def system_one(
+        self,
+        state: Dict[str, Any],
+        questions: Dict[str, Dict[str, Any]],
+        *,
+        model: str = "convaiinnovations/laya",
+        node: Optional[str] = None,
+        cluster: Optional[str] = None,
+        max_price: Optional[float] = None,
+    ) -> Dict[str, Any]:
+        """Call Laya/System One typed decisions via ``POST /v1/systemone``.
+
+        This is not a chat-completions model. Use it for compact typed outputs
+        such as choices, scores, and no-output-language summaries. Requires
+        ``api_key`` (credits); x402 pay-per-call is not signed by this client.
+        """
+        body: Dict[str, Any] = {
+            "model": model,
+            "state": state,
+            "questions": questions,
+        }
+        if node is not None:
+            body["node"] = node
+        if cluster is not None:
+            body["cluster"] = cluster
+        if max_price is not None:
+            body["max_price"] = max_price
+        try:
+            return self._request("POST", "/v1/systemone", json=body)
+        except SGLAPIError as err:
+            if err.status_code == 402:
+                raise SGLAPIError(402, "Payment required — pass api_key (credits); the Python GridClient does not sign x402 payments.") from err
+            raise
+
+    def systemone(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
+        """Alias for :meth:`system_one` matching the HTTP endpoint spelling."""
+        return self.system_one(*args, **kwargs)
+
     def embed(self, model: str, input: Any, **kwargs: Any) -> List[List[float]]:
         """Convenience wrapper around :meth:`embeddings` that returns just the list of
         vectors, ordered to match ``input``."""
@@ -417,6 +474,9 @@ class GridClient:
                 sealed = data.get("sealed_result")
                 if not sealed:
                     raise SGLAPIError(500, "No sealed result returned")
+                # Same check on the non-streaming fallback: an orchestrator that
+                # can force this path must not get an unverified reply through it.
+                e2e.require_verified_reply(reservation, data)
                 plain = e2e.open_output(resp_sk, resp_pub, sealed["ephemeral_public_key"], sealed["ciphertext"])
                 content = _json.loads(plain).get("content", "")
                 if content:
@@ -453,6 +513,24 @@ class GridClient:
                         raise SGLAPIError(502, "stream chunk 0 missing ephemeral key")
                     out_key = e2e.stream_out_key(resp_sk, stream_eph)
                 is_final = chunk.get("final") is True
+                # Verify EVERY chunk before opening it. The node signs each with
+                # kind "stream:{seq}:{final}" over the chunk ciphertext, and the
+                # orchestrator relays that signature rather than consuming it.
+                # Without this a compromised relay could splice or invent chunks,
+                # i.e. edit the answer as it arrives.
+                if chunk.get("sigv") and chunk["sigv"] != "v1":
+                    raise e2e.UnverifiedReply(f"unknown chunk envelope version {chunk['sigv']!r}")
+                kind = f"stream:{seq}:{1 if is_final else 0}"
+                if not e2e.verify_result_envelope(
+                    reservation.get("node_ed25519_pubkey"),
+                    chunk.get("job"),
+                    kind,
+                    chunk["ct"],
+                    chunk.get("sig"),
+                ):
+                    raise e2e.UnverifiedReply(
+                        f"stream chunk {seq} is not signed by the reserved node — refusing it."
+                    )
                 text = e2e.open_stream_chunk(out_key, resp_pub, stream_eph, nonce, seq, is_final, chunk["ct"]).decode()
                 if text:
                     yield text

{singularity_grid-0.9.0 → singularity_grid-0.9.2}/singularity_grid/e2e.py

@@ -80,6 +80,83 @@ def seal_input(node_pub_b58: str, resp_pub_b58: str, plaintext: bytes) -> tuple[
     return _b58e(nonce + ct), eph_b58
 
 
+class UnverifiedReply(Exception):
+    """A sealed reply could not be proven to come from the reserved node."""
+
+
+def verify_result_envelope(
+    node_ed25519_b58: str | None,
+    job_id: str | None,
+    kind: str,
+    ciphertext: str,
+    signature_b58: str | None,
+) -> bool:
+    """Verify the node's v1 envelope signature over a sealed reply.
+
+    The signature covers the PUBLIC ciphertext, not the plaintext, so it can be
+    checked exactly -- no re-serialising, no key-ordering problem. Message:
+    ``sgl-result-v1\\n{job_id}\\n{kind}\\n{sha256_hex(ciphertext)}``, and the
+    ciphertext is hashed as the literal UTF-8 string, not as decoded bytes.
+    """
+    if not node_ed25519_b58 or not signature_b58 or not job_id:
+        return False
+    try:
+        from hashlib import sha256
+
+        from nacl.signing import VerifyKey
+
+        digest = sha256(ciphertext.encode()).hexdigest()
+        msg = f"sgl-result-v1\n{job_id}\n{kind}\n{digest}".encode()
+        VerifyKey(_b58d(node_ed25519_b58)).verify(msg, _b58d(signature_b58))
+        return True
+    except Exception:
+        return False
+
+
+def require_verified_reply(
+    reservation: dict,
+    data: dict,
+    kind: str = "sealed",
+) -> None:
+    """Refuse a sealed reply we cannot attribute to the reserved node.
+
+    Why this is mandatory rather than best-effort: ``client_response_pubkey``
+    reaches the orchestrator in cleartext, so a compromised orchestrator cannot
+    READ a prompt but CAN fabricate a reply, seal it to that key, and have it
+    decrypt cleanly. AEAD proves only that someone sealed it to us; this proves
+    WHO. Without it the grid could put words in the model's mouth -- and for an
+    agentic caller, tool calls in its hands.
+
+    A MISSING signature fails exactly like an invalid one. Every sealed reply
+    carries one, so absence means something is wrong, and "warn and continue" is
+    what let this gap survive unnoticed in the first place.
+    """
+    sealed = data.get("sealed_result") or {}
+    version = data.get("result_envelope_version")
+    if version is not None and version != "v1":
+        raise UnverifiedReply(f"unknown result envelope version {version!r}")
+    # `job_id` is explicit on current grids; older ones only embed it in `id`.
+    job_id = data.get("job_id")
+    if not job_id:
+        raw_id = data.get("id") or ""
+        job_id = raw_id[len("chatcmpl-") :] if raw_id.startswith("chatcmpl-") else None
+    ok = verify_result_envelope(
+        reservation.get("node_ed25519_pubkey"),
+        job_id,
+        kind,
+        sealed.get("ciphertext", ""),
+        data.get("result_envelope_signature"),
+    )
+    if not ok:
+        # NEVER fall back to `result_signature`: that legacy field signs the
+        # PLAINTEXT and is always absent for sealed replies, so reaching for it
+        # would make this check silently meaningless.
+        raise UnverifiedReply(
+            "sealed reply is not signed by the reserved node — refusing it. "
+            "Update the grid if this persists."
+        )
+
+
 def open_output(resp_sk: bytes, resp_pub_b58: str, node_eph_b58: str, ct_b58: str) -> bytes:
     """Open the node's (non-stream) reply sealed to our response key."""
     shared = bindings.crypto_scalarmult(resp_sk, _b58d(node_eph_b58))

singularity_grid-0.9.2/singularity_grid/pods.py

@@ -0,0 +1,492 @@
+"""Agent Pods — hosted agents you can create, drive and destroy over an API key.
+
+A pod is a running agent on its own machine: it holds a conversation, keeps a workspace, can
+be given scheduled tasks and connectors, and exposes an OpenAI-compatible endpoint so anything
+that already speaks to OpenAI can speak to it instead.
+
+Two things are worth knowing before you use this.
+
+**Create is idempotent, and the key is not decoration.** Creating a pod provisions a machine
+and charges for it, so a retry after a timeout must not do it twice. ``create_pod`` generates
+an idempotency key when you do not pass one, and replaying the same key returns the original
+response byte for byte rather than making a second pod. Pass your own key when your caller has
+a natural id for the attempt (an order number, a job id) — that is what makes a retry after a
+crash safe rather than merely likely to be safe.
+
+**Delete is not instant.** Providers refuse to delete a machine that is still installing, so a
+destroy can come back as ``destroying`` rather than ``destroyed``. ``delete_pod`` reports
+which, and ``wait_for_destroyed`` holds until the machine is genuinely gone. Treating the first
+as the second is how you keep paying for something you thought you deleted.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import re
+import time
+import uuid
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from .client import SGLAPIError, SGLAuthError, SGLConnectionError, SGLNotFoundError
+
+DEFAULT_PODS_BASE_URL = "https://compute.x402layer.cc"
+DEFAULT_TIMEOUT = 120.0
+
+
+class PodsClient:
+    """Client for the Agent Pods API.
+
+    Args:
+        api_key: mint one in the dashboard under Settings -> API Keys.
+        base_url: override for testing against a local worker.
+        timeout: seconds. Creating a pod is the slow call; it provisions a machine.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_PODS_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        if not api_key:
+            raise SGLAuthError(401, "An api_key is required. Mint one under Settings -> API Keys.")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._client = httpx.Client(timeout=timeout)
+
+    def __enter__(self) -> "PodsClient":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._client.close()
+
+    # ── transport ──────────────────────────────────────────────────────────────────────
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        json: Optional[Dict[str, Any]] = None,
+        extra_headers: Optional[Dict[str, str]] = None,
+    ) -> Any:
+        headers = {"X-API-Key": self.api_key, "Accept": "application/json"}
+        if extra_headers:
+            headers.update(extra_headers)
+        try:
+            resp = self._client.request(
+                method, f"{self.base_url}/pods/v1{path}", json=json, headers=headers
+            )
+        except httpx.RequestError as exc:
+            raise SGLConnectionError(f"Could not reach the pods API: {exc}") from exc
+
+        try:
+            parsed = resp.json() if resp.content else None
+        except ValueError:
+            parsed = None
+
+        if resp.status_code >= 400:
+            err = (parsed or {}).get("error", {}) if isinstance(parsed, dict) else {}
+            message = err.get("message") or f"HTTP {resp.status_code}"
+            # Echoed on every response, and the fastest way for us to find your request in our
+            # logs — so it travels with the error rather than being dropped.
+            request_id = resp.headers.get("x-request-id")
+            if request_id:
+                message = f"{message} (request id {request_id})"
+            body = {"code": err.get("code"), "details": err.get("details"), "request_id": request_id}
+            if resp.status_code in (401, 403):
+                raise SGLAuthError(resp.status_code, message, body)
+            if resp.status_code == 404:
+                raise SGLNotFoundError(resp.status_code, message, body)
+            raise SGLAPIError(resp.status_code, message, body)
+        return parsed
+
+    # ── pods ───────────────────────────────────────────────────────────────────────────
+
+    def create_pod(
+        self,
+        tier: str = "starter",
+        name: Optional[str] = None,
+        external_ref: Optional[str] = None,
+        model: Optional[str] = None,
+        system_prompt: Optional[str] = None,
+        region: Optional[str] = None,
+        term_hours: Optional[int] = None,
+        capabilities: Optional[Dict[str, bool]] = None,
+        ai: Optional[Dict[str, str]] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Create a pod. Provisions a machine and charges for it.
+
+        Returns as soon as the order exists, with ``status == "provisioning"``; the machine
+        takes a few minutes to boot. Use :meth:`wait_for_online` if you need to wait.
+
+        ``external_ref`` is YOUR id for this pod. It comes back on reads and filters
+        :meth:`list_pods`, so you can find a pod again from your own database without storing
+        ours.
+        """
+        body: Dict[str, Any] = {"tier": tier}
+        for key, value in (
+            ("name", name), ("external_ref", external_ref), ("model", model),
+            ("system_prompt", system_prompt), ("region", region),
+            ("term_hours", term_hours), ("capabilities", capabilities), ("ai", ai),
+        ):
+            if value is not None:
+                body[key] = value
+        return self._request(
+            "POST", "/pods", body,
+            {"Idempotency-Key": idempotency_key or f"sdk-{uuid.uuid4()}"},
+        )["pod"]
+
+    def get_pod(self, pod_id: str) -> Dict[str, Any]:
+        return self._request("GET", f"/pods/{pod_id}")["pod"]
+
+    def list_pods(
+        self,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+        external_ref: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """List pods, newest first. ``external_ref`` filters by your own id."""
+        parts = []
+        if limit:
+            parts.append(f"limit={limit}")
+        if cursor:
+            parts.append(f"cursor={cursor}")
+        if external_ref:
+            parts.append(f"external_ref={external_ref}")
+        query = f"?{'&'.join(parts)}" if parts else ""
+        return self._request("GET", f"/pods{query}")
+
+    def update_pod(self, pod_id: str, **patch: Any) -> Dict[str, Any]:
+        """Change ``name``, ``model``, ``slug`` or ``auto_renew``."""
+        return self._request("PATCH", f"/pods/{pod_id}", patch)["pod"]
+
+    def delete_pod(self, pod_id: str) -> Dict[str, Any]:
+        """Destroy a pod.
+
+        ``destroyed`` means the machine is confirmed gone. ``destroying`` means the provider
+        would not delete it yet — usually because it is still installing — and a sweep will
+        retry; it may bill for a few more minutes. Do not treat the second as the first.
+        """
+        res = self._request("DELETE", f"/pods/{pod_id}")
+        return {"status": res["pod"]["status"], "message": res.get("message", "")}
+
+    def wait_for_online(
+        self, pod_id: str, timeout: float = 900.0, interval: float = 10.0
+    ) -> Dict[str, Any]:
+        """Poll until the pod is online, or raise when it lands somewhere it cannot leave."""
+        return self._wait(pod_id, {"online"}, {"destroyed", "destroying"}, timeout, interval)
+
+    def wait_for_destroyed(
+        self, pod_id: str, timeout: float = 900.0, interval: float = 10.0
+    ) -> Dict[str, Any]:
+        """Poll until the machine is genuinely gone, not merely accepted for teardown."""
+        return self._wait(pod_id, {"destroyed"}, set(), timeout, interval)
+
+    def _wait(
+        self,
+        pod_id: str,
+        done: set,
+        fatal: set,
+        timeout: float,
+        interval: float,
+    ) -> Dict[str, Any]:
+        deadline = time.monotonic() + timeout
+        while True:
+            pod = self.get_pod(pod_id)
+            status = pod.get("status")
+            if status in done:
+                return pod
+            if status in fatal:
+                raise SGLAPIError(409, f"Pod {pod_id} is {status}; it will not come online.")
+            if time.monotonic() >= deadline:
+                raise SGLAPIError(504, f"Timed out waiting for pod {pod_id}; it is {status}.")
+            time.sleep(interval)
+
+    # ── talking to a pod ───────────────────────────────────────────────────────────────
+
+    def endpoint_url(self, pod: Any) -> str:
+        """The pod's OpenAI-compatible base URL.
+
+        Point an OpenAI client at this with a key from :meth:`mint_pod_key` and use the model
+        id ``agent-pod``. Anything that already speaks OpenAI works unchanged::
+
+            from openai import OpenAI
+            key = pods.mint_pod_key(pod["id"])["secret"]
+            oa = OpenAI(base_url=pods.endpoint_url(pod), api_key=key)
+            oa.chat.completions.create(model="agent-pod", messages=[...])
+        """
+        if isinstance(pod, str):
+            return f"{self.base_url}/pods/{pod}/v1"
+        endpoint = pod.get("endpoint") or {}
+        return endpoint.get("base_url") or f"{self.base_url}/pods/{pod['id']}/v1"
+
+    def mint_pod_key(
+        self, pod_id: str, label: Optional[str] = None, daily_cap_usd: Optional[float] = None
+    ) -> Dict[str, Any]:
+        """Mint a key for the pod's own endpoint. The secret is returned ONCE."""
+        body: Dict[str, Any] = {}
+        if label is not None:
+            body["label"] = label
+        if daily_cap_usd is not None:
+            body["daily_cap_usd"] = daily_cap_usd
+        return self._request("POST", f"/pods/{pod_id}/keys", body)["key"]
+
+    def list_pod_keys(self, pod_id: str) -> List[Dict[str, Any]]:
+        return self._request("GET", f"/pods/{pod_id}/keys")["keys"]
+
+    def revoke_pod_key(self, pod_id: str, key_id: str) -> None:
+        self._request("DELETE", f"/pods/{pod_id}/keys/{key_id}")
+
+    # ── operating a pod ────────────────────────────────────────────────────────────────
+
+    def usage(self, pod_id: str) -> Dict[str, Any]:
+        return self._request("GET", f"/pods/{pod_id}/usage")["usage"]
+
+    def queue_action(self, pod_id: str, action: str) -> Dict[str, Any]:
+        """Queue ``restart``, ``stop``, ``redeploy``, ``update``, ``diagnose`` or ``logs``.
+
+        Applied on the pod's next check-in, usually within a minute, which is why this returns
+        202 rather than pretending it already happened. ``diagnose`` and ``logs`` write their
+        output back; read it from :meth:`get_actions`.
+        """
+        return self._request("POST", f"/pods/{pod_id}/actions", {"action": action})["action"]
+
+    def get_actions(self, pod_id: str) -> Dict[str, Any]:
+        return self._request("GET", f"/pods/{pod_id}/actions")["actions"]
+
+    def list_tasks(self, pod_id: str) -> Dict[str, Any]:
+        return self._request("GET", f"/pods/{pod_id}/tasks")
+
+    def add_task(
+        self,
+        pod_id: str,
+        name: str,
+        kind: str,
+        schedule: str,
+        message: Optional[str] = None,
+        session: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"name": name, "kind": kind, "schedule": schedule}
+        if message is not None:
+            body["message"] = message
+        if session is not None:
+            body["session"] = session
+        return self._request("POST", f"/pods/{pod_id}/tasks", body)
+
+    def remove_task(self, pod_id: str, job_id: str) -> Dict[str, Any]:
+        return self._request("DELETE", f"/pods/{pod_id}/tasks/{job_id}")
+
+    def get_wallet(self, pod_id: str) -> Dict[str, Any]:
+        return self._request("GET", f"/pods/{pod_id}/wallet")["wallet"]
+
+    def update_wallet(self, pod_id: str, **patch: Any) -> Dict[str, Any]:
+        """Change a pod wallet's spend controls.
+
+        Needs ``pods:wallet:write`` — a general key that manages pods must not be able to
+        raise the cap on the money it can spend. The field is ``per_tx_cap_usd``, not
+        ``spend_cap_usd``; the API lists the editable names if you get it wrong.
+        """
+        return self._request("PATCH", f"/pods/{pod_id}/wallet", patch)
+
+    def add_connector(
+        self,
+        pod_id: str,
+        name: str,
+        url: str,
+        transport: Optional[str] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> List[Dict[str, Any]]:
+        """Attach an MCP connector, giving the agent a new tool.
+
+        Needs ``pods:control:write`` for the same reason: handing an agent new tools is not
+        something a general-purpose key should do.
+        """
+        body: Dict[str, Any] = {"name": name, "url": url}
+        if transport is not None:
+            body["transport"] = transport
+        if headers is not None:
+            body["headers"] = headers
+        return self._request("POST", f"/pods/{pod_id}/connectors", body)["connectors"]
+
+    def remove_connector(self, pod_id: str, connector_id: str) -> List[Dict[str, Any]]:
+        return self._request("DELETE", f"/pods/{pod_id}/connectors/{connector_id}")["connectors"]
+
+    def update_backups(
+        self, pod_id: str, enabled: bool, passphrase: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Turn automatic backups on or off. Setting a passphrase needs ``pods:wallet:write``."""
+        body: Dict[str, Any] = {"enabled": enabled}
+        if passphrase is not None:
+            body["passphrase"] = passphrase
+        return self._request("PATCH", f"/pods/{pod_id}/backups", body)["backups"]
+
+    def telegram_join_code(self, pod_id: str) -> Dict[str, Any]:
+        """Mint a Telegram join code for a group."""
+        return self._request("POST", f"/pods/{pod_id}/channels/telegram/join-code")["join"]
+
+    def telegram_join_status(self, pod_id: str) -> Dict[str, Any]:
+        """Poll whether a group has claimed the code. Never echoes the code back."""
+        return self._request("GET", f"/pods/{pod_id}/channels/telegram/join-code")["join"]
+
+    def get_update_policy(self, pod_id: str) -> Dict[str, Any]:
+        """Who decides WHEN this pod takes our updates.
+
+        By default we do: the pod polls every six hours and applies whatever we answer,
+        restarting its gateway for about forty seconds. Fine for a pod you run for yourself,
+        wrong for pods you run for customers who did not choose that moment.
+        """
+        return self._request("GET", f"/pods/{pod_id}/updates")["updates"]
+
+    def set_update_policy(self, pod_id: str, mode: str) -> Dict[str, Any]:
+        """``auto`` or ``manual``.
+
+        ``manual`` makes us keep answering with the version the pod already has, so it never
+        updates itself; you apply it with ``queue_action(pod_id, "update")`` when it suits
+        you. The hold expires after 30 days, because security fixes ride these bundles, and
+        the response always names the date so it is never a surprise.
+        """
+        return self._request("PATCH", f"/pods/{pod_id}/updates", {"mode": mode})["updates"]
+
+    def chat_ticket(self, pod_id: str) -> Dict[str, Any]:
+        """A short-lived ticket for the pod's streaming chat socket.
+
+        ``scope`` says what the socket will accept. Without ``pods:control:write`` it is
+        ``chat``, conversation only. Most integrations want the OpenAI endpoint instead.
+        """
+        return self._request("POST", f"/pods/{pod_id}/chat-ticket")["chat"]
+
+    def connect_telegram_group(
+        self, pod_id: str, require_mention: Optional[bool] = None, prompt: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Attach the Telegram group that claimed the join code.
+
+        Takes no chat id: it attaches only the group that claimed the code, because a claim
+        proves somebody typed it inside that room. Existing groups are preserved.
+        """
+        body: Dict[str, Any] = {}
+        if require_mention is not None:
+            body["require_mention"] = require_mention
+        if prompt is not None:
+            body["prompt"] = prompt
+        return self._request("POST", f"/pods/{pod_id}/channels/telegram/connect", body)["channel"]
+
+    def approve_pairing(self, pod_id: str, code: str, channel: str = "telegram") -> Dict[str, Any]:
+        """Approve someone to DM the agent.
+
+        A stranger who finds the bot can DM it, and unlike a group nobody else sees that
+        conversation, so the agent refuses unknown people and shows them a code. The code must
+        come from the agent, so this approves a request somebody already made.
+        """
+        return self._request("POST", f"/pods/{pod_id}/channels/{channel}/pair", {"code": code})["pairing"]
+
+    def wallet_send(self, pod_id: str, **body: Any) -> Dict[str, Any]:
+        """Move funds out of the pod's wallet. Needs ``pods:wallet:write``.
+
+        The spend cap is enforced server-side before the transfer and the pod holds no keys,
+        so this cannot exceed the policy set by :meth:`update_wallet`.
+        """
+        return self._request("POST", f"/pods/{pod_id}/wallet/send", body)
+
+    def wallet_pay_x402(self, pod_id: str, **body: Any) -> Dict[str, Any]:
+        """Pay an x402 endpoint from the pod's wallet. Needs ``pods:wallet:write``."""
+        return self._request("POST", f"/pods/{pod_id}/wallet/x402/pay", body)
+
+    def list_connectors(self, pod_id: str) -> List[Dict[str, Any]]:
+        return self._request("GET", f"/pods/{pod_id}/connectors")["connectors"]
+
+    def get_backups(self, pod_id: str) -> Dict[str, Any]:
+        return self._request("GET", f"/pods/{pod_id}/backups")["backups"]
+
+    # ── events and webhooks ────────────────────────────────────────────────────────────
+
+    def list_events(
+        self,
+        after: Optional[int] = None,
+        limit: Optional[int] = None,
+        type: Optional[str] = None,
+        pod_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Page the event log.
+
+        Paged by ``seq``, an integer that only goes up, NOT by timestamp — two events can
+        share a millisecond, and a timestamp cursor would either skip one or repeat it
+        forever. Store the ``next_after`` you get back and pass it as ``after`` next time.
+
+        This is also the answer to a missed webhook: delivery is a cursor over these same
+        rows, so anything a broken endpoint dropped is still here.
+        """
+        parts = []
+        if after is not None:
+            parts.append(f"after={after}")
+        if limit:
+            parts.append(f"limit={limit}")
+        if type:
+            parts.append(f"type={type}")
+        if pod_id:
+            parts.append(f"pod_id={pod_id}")
+        query = f"?{'&'.join(parts)}" if parts else ""
+        return self._request("GET", f"/events{query}")
+
+    def create_webhook(
+        self, url: str, event_types: Optional[List[str]] = None
+    ) -> Dict[str, Any]:
+        """Register a webhook. HTTPS only.
+
+        The signing ``secret`` comes back ONCE. Store it — it is how you verify a delivery
+        really came from us. Omit ``event_types`` to receive everything; an empty list is
+        refused, because a subscription to nothing is a webhook that silently never fires.
+        """
+        body: Dict[str, Any] = {"url": url}
+        if event_types is not None:
+            body["event_types"] = event_types
+        return self._request("POST", "/webhooks", body)["webhook"]
+
+    def list_webhooks(self) -> List[Dict[str, Any]]:
+        return self._request("GET", "/webhooks")["webhooks"]
+
+    def update_webhook(self, webhook_id: str, **patch: Any) -> Dict[str, Any]:
+        return self._request("PATCH", f"/webhooks/{webhook_id}", patch)["webhook"]
+
+    def delete_webhook(self, webhook_id: str) -> None:
+        self._request("DELETE", f"/webhooks/{webhook_id}")
+
+
+_SIG_RE = re.compile(r"^t=(\d+),v1=([0-9a-f]{64})$")
+
+
+def verify_pod_webhook(
+    raw_body: str,
+    signature_header: str,
+    secret: str,
+    tolerance_sec: int = 300,
+    now: Optional[float] = None,
+) -> bool:
+    """Verify a webhook delivery came from us and is recent.
+
+    Pass the RAW request body, not a re-serialised object: re-encoding JSON changes bytes
+    (key order, spacing) and the signature is over the bytes we sent.
+
+    The timestamp is inside the signed string, so a captured delivery cannot be replayed later
+    under a fresh one. ``tolerance_sec`` is what stops an old capture being accepted at all.
+    """
+    match = _SIG_RE.match((signature_header or "").strip())
+    if not match:
+        return False
+    timestamp = int(match.group(1))
+    current = int(now if now is not None else time.time())
+    if abs(current - timestamp) > tolerance_sec:
+        return False
+    expected = hmac.new(
+        secret.encode(), f"{timestamp}.{raw_body}".encode(), hashlib.sha256
+    ).hexdigest()
+    # compare_digest, not ==: a short-circuiting compare leaks how much of a forged signature
+    # was right, which is enough to reconstruct one byte at a time.
+    return hmac.compare_digest(match.group(2), expected)

singularity_grid-0.9.2/tests/test_pod_webhook.py

@@ -0,0 +1,50 @@
+"""The wire format for webhook signatures, pinned against a vector the SERVER produced.
+
+The signature is generated by the worker and verified here. Writing both halves from the same
+understanding is how two sides agree with each other and disagree with reality, so the vector
+below was emitted by the real `signWebhook` in the backend rather than recomputed here.
+"""
+
+import time
+
+from singularity_grid import verify_pod_webhook
+
+# Emitted by SGLCompute_Backend `signWebhook` (src/lib/pod-events.ts).
+SECRET = "whsec_" + "a" * 48
+BODY = '{"event":{"id":"e1","seq":7,"type":"pod.destroyed"}}'
+TS = 1788000000
+SIG = "t=1788000000,v1=367d429c4547093ae53a97b3bf5d8b62670e39676709fda0fb3748279dc71531"
+
+# Evaluated as if it were moments after signing, so the age check is not what is under test.
+NOW = TS + 5
+
+
+def test_accepts_a_signature_the_server_actually_produced():
+    assert verify_pod_webhook(BODY, SIG, SECRET, now=NOW) is True
+
+
+def test_rejects_a_re_encoded_body():
+    # Re-serialising JSON changes key order and spacing. A partner who parses then re-encodes
+    # would fail to verify a genuine delivery and conclude our signatures are broken, so this
+    # documents that the RAW bytes are what must be passed.
+    import json
+
+    reencoded = json.dumps(json.loads(BODY), indent=2)
+    assert verify_pod_webhook(reencoded, SIG, SECRET, now=NOW) is False
+
+
+def test_rejects_wrong_secret_and_tampered_body():
+    assert verify_pod_webhook(BODY, SIG, "whsec_" + "b" * 48, now=NOW) is False
+    assert verify_pod_webhook(BODY + " ", SIG, SECRET, now=NOW) is False
+
+
+def test_rejects_a_genuine_signature_that_is_too_old():
+    # The timestamp is inside the signed string, so an old capture cannot be replayed under a
+    # fresh one — but only if the receiver enforces the window.
+    assert verify_pod_webhook(BODY, SIG, SECRET, now=TS + 4000) is False
+    assert verify_pod_webhook(BODY, SIG, SECRET, now=TS + 10) is True
+
+
+def test_rejects_a_malformed_header_instead_of_raising():
+    for bad in ["", "nonsense", "t=abc,v1=def", "t=1,v1=short", "v1=" + "a" * 64, None]:
+        assert verify_pod_webhook(BODY, bad, SECRET, now=NOW) is False