happy-engineering-sdk 0.1.0__py3-none-any.whl

happy_engineering_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: happy-engineering-sdk
+Version: 0.1.0
+Summary: Python SDK for controlling Happy agent sessions
+Project-URL: Homepage, https://happy.engineering
+Author-email: Scott Fraser <scott@jascro.com>
+License: MIT
+Keywords: agents,ai,engineering,happy,llm,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=43.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pynacl>=1.5
+Requires-Dist: python-socketio[asyncio]>=5.11
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# happy-engineering-sdk
+
+[![PyPI version](https://img.shields.io/pypi/v/happy-engineering-sdk)](https://pypi.org/project/happy-engineering-sdk/)
+[![Python versions](https://img.shields.io/pypi/pyversions/happy-engineering-sdk)](https://pypi.org/project/happy-engineering-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Python SDK for controlling Happy agent sessions.
+
+## Installation
+
+```bash
+pip install happy-engineering-sdk
+```
+
+## Credentials
+
+The SDK authenticates using a key file and a server URL.
+
+**Key file** — download `agent.key` from the Happy dashboard and place it at:
+
+```
+~/.happy/agent.key
+```
+
+**Server URL** — set the `HAPPY_SERVER_URL` environment variable to your Happy
+server's base URL:
+
+```bash
+export HAPPY_SERVER_URL=https://api.happy.engineering
+```
+
+## Quick start
+
+The simplest usage is `run_task()` — it spawns a session, sends a prompt, waits
+for the agent to finish, and stops the session, all in one call:
+
+```python
+import asyncio
+from happy_sdk import HappyClient
+
+async def main():
+    client = HappyClient()
+    session_id = await client.run_task(
+        machine_id="my-machine",
+        directory="/home/user/project",
+        prompt="Summarise this week's PRs",
+    )
+    print(f"Task complete — session {session_id}")
+
+asyncio.run(main())
+```
+
+## Manual lifecycle
+
+For finer control, manage the session lifecycle directly:
+
+```python
+import asyncio
+from happy_sdk import HappyClient
+
+async def main():
+    client = HappyClient()
+
+    session_id = await client.spawn_session(
+        machine_id="my-machine",
+        directory="/home/user/project",
+    )
+    await client.send_message(session_id, "Hello")
+    await client.wait_for_turn_completion(session_id)
+    await client.stop_session(session_id)
+
+asyncio.run(main())
+```
+
+## API reference
+
+All methods are `async` and must be called from an async context.
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `run_task` | `(machine_id, directory, prompt, agent="claude", timeout_seconds=600)` | Spawn a session, send a prompt, wait for turn completion, and stop — returns the session ID |
+| `spawn_session` | `(machine_id, directory, agent="claude", create_dir=False)` | Create a new agent session on the given machine in the given directory — returns the session ID |
+| `send_message` | `(session_id, text, permission_mode="yolo")` | Send a message to an active session |
+| `wait_for_turn_completion` | `(session_id, timeout_seconds=300)` | Block until the agent finishes its current turn |
+| `stop_session` | `(session_id)` | Stop a running session |
+
+## License
+
+MIT — see [LICENSE](LICENSE).

happy_engineering_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+happy_sdk/__init__.py,sha256=Ars9ST8tjeOutue0kwbzEQggjGUe73Xaa_zS0O4vLhA,540
+happy_sdk/api.py,sha256=e1xOXUnQYgtmMrMB9fitoojv9pXwtI0yLBajHxZljE8,2093
+happy_sdk/client.py,sha256=DbOGfjJZaZcBjZ3YcJKRRDsldiHeueA28DxrumQgcn0,9938
+happy_sdk/credentials.py,sha256=wxSt_dE2fFGvE71gLzPlvzuTa67K6p2xNW7nShe_0OM,1268
+happy_sdk/encryption.py,sha256=Av4-vPRz_esQq62EbiTxGUVpoTbYzL2cHS9vx6xeCqk,4399
+happy_sdk/exceptions.py,sha256=DQWop_jXsYaOtfjf_sflI2qTccd878uTDNt_oXUF9VU,600
+happy_sdk/session_connection.py,sha256=RdkKEx99eAUl8YzaV1beDkYLAbgQXoVQx7gju_Xartg,4722
+happy_sdk/socket_manager.py,sha256=4pHO3aQmo_LnUt1A9py5IKvTJ1KBQSNKXItEm-FDMnA,3428
+happy_sdk/types.py,sha256=IBkx0LyB7ME0LtF5l2klzWXZcsRuC9HG5kiX_kpdEaU,574
+happy_engineering_sdk-0.1.0.dist-info/METADATA,sha256=J85S3iqOcS8B5f8jJYB-0GyTY4NLhsiy5YywbFyP7DQ,3621
+happy_engineering_sdk-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+happy_engineering_sdk-0.1.0.dist-info/RECORD,,

happy_engineering_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

happy_sdk/__init__.py

@@ -0,0 +1,27 @@
+from .client import HappyClient
+from .types import Agent, Machine, Message, PermissionMode, Session
+from .exceptions import (
+    AuthenticationError,
+    ConnectionError,
+    EncryptionError,
+    HappyError,
+    MachineOfflineError,
+    SpawnError,
+    TimeoutError,
+)
+
+__all__ = [
+    "HappyClient",
+    "Machine",
+    "Session",
+    "Message",
+    "Agent",
+    "PermissionMode",
+    "HappyError",
+    "AuthenticationError",
+    "ConnectionError",
+    "EncryptionError",
+    "MachineOfflineError",
+    "SpawnError",
+    "TimeoutError",
+]

happy_sdk/api.py

@@ -0,0 +1,56 @@
+from typing import Any
+
+import httpx
+
+from .exceptions import AuthenticationError, HappyError
+
+
+class HappyAPI:
+    def __init__(self, server_url: str, token: str) -> None:
+        self._base_url = server_url.rstrip("/")
+        self._token = token
+
+    def _headers(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self._token}"}
+
+    async def list_machines(self) -> list[dict[str, Any]]:
+        async with httpx.AsyncClient() as client:
+            r = await client.get(f"{self._base_url}/v1/machines", headers=self._headers())
+            r.raise_for_status()
+            return r.json()
+
+    async def list_sessions(self) -> list[dict[str, Any]]:
+        async with httpx.AsyncClient() as client:
+            r = await client.get(f"{self._base_url}/v1/sessions", headers=self._headers())
+            r.raise_for_status()
+            return r.json()
+
+    async def list_active_sessions(self) -> list[dict[str, Any]]:
+        async with httpx.AsyncClient() as client:
+            r = await client.get(f"{self._base_url}/v2/sessions/active", headers=self._headers())
+            r.raise_for_status()
+            return r.json()
+
+    async def get_session(self, session_id: str) -> dict[str, Any]:
+        async with httpx.AsyncClient() as client:
+            r = await client.get(
+                f"{self._base_url}/v1/sessions/{session_id}", headers=self._headers()
+            )
+            r.raise_for_status()
+            return r.json()
+
+    async def get_messages(self, session_id: str) -> list[dict[str, Any]]:
+        async with httpx.AsyncClient() as client:
+            r = await client.get(
+                f"{self._base_url}/v1/sessions/{session_id}/messages",
+                headers=self._headers(),
+            )
+            r.raise_for_status()
+            return r.json()
+
+    async def delete_session(self, session_id: str) -> None:
+        async with httpx.AsyncClient() as client:
+            r = await client.delete(
+                f"{self._base_url}/v1/sessions/{session_id}", headers=self._headers()
+            )
+            r.raise_for_status()

happy_sdk/client.py

@@ -0,0 +1,255 @@
+import os
+from typing import Any
+
+from .api import HappyAPI
+from .credentials import Credentials, load_credentials
+from .encryption import (
+    decode_base64,
+    decrypt,
+    decrypt_box_bundle,
+    derive_content_key_pair,
+    encode_base64,
+    encrypt,
+)
+from .exceptions import HappyError, MachineOfflineError, SpawnError
+from .session_connection import SessionConnection
+from .socket_manager import SocketManager
+from .types import Agent, Machine, Message, PermissionMode, Session
+
+
+class HappyClient:
+    def __init__(
+        self,
+        server_url: str | None = None,
+        credentials_path: str | None = None,
+    ) -> None:
+        if server_url is None:
+            server_url = os.environ.get("HAPPY_SERVER_URL")
+        if not server_url:
+            raise ValueError("server_url is required (or set HAPPY_SERVER_URL)")
+
+        self._server_url = server_url.rstrip("/")
+        self._creds: Credentials = load_credentials(credentials_path)
+        self._api = HappyAPI(self._server_url, self._creds.token)
+        self._sockets = SocketManager(self._server_url, self._creds.token)
+        # Derive the NaCl content keypair once for decrypting dataEncryptionKey bundles
+        _pub, self._content_secret = derive_content_key_pair(self._creds.secret)
+
+    # -----------------------------------------------------------------------
+    # Key resolution
+    # -----------------------------------------------------------------------
+
+    async def _resolve_session_key(self, session_id: str) -> tuple[bytes, str]:
+        """Return (key_bytes, variant) for a session."""
+        raw = await self._api.get_session(session_id)
+        return self._extract_key(raw)
+
+    async def _resolve_machine_key(self, machine_id: str) -> tuple[bytes, str]:
+        """Return (key_bytes, variant) for a machine."""
+        machines = await self._api.list_machines()
+        for m in machines:
+            if m.get("id") == machine_id:
+                return self._extract_key(m)
+        raise MachineOfflineError(f"Machine {machine_id} not found")
+
+    def _extract_key(self, record: dict[str, Any]) -> tuple[bytes, str]:
+        dek = record.get("dataEncryptionKey")
+        if dek:
+            bundle = decode_base64(dek)
+            # Strip 1-byte version prefix if present
+            if len(bundle) > 56:
+                bundle = bundle[1:]
+            key = decrypt_box_bundle(bundle, self._content_secret)
+            if key is None:
+                from .exceptions import EncryptionError
+                raise EncryptionError("Failed to decrypt dataEncryptionKey")
+            return key, "dataKey"
+        return self._creds.secret, "legacy"
+
+    # -----------------------------------------------------------------------
+    # Machine operations
+    # -----------------------------------------------------------------------
+
+    async def list_machines(self, active_only: bool = False) -> list[Machine]:
+        raw = await self._api.list_machines()
+        machines = [
+            Machine(id=m["id"], active=m.get("active", False), metadata=m.get("metadata", {}))
+            for m in raw
+        ]
+        if active_only:
+            machines = [m for m in machines if m.active]
+        return machines
+
+    async def get_machine(self, machine_id: str) -> Machine:
+        machines = await self._api.list_machines()
+        for m in machines:
+            if m["id"] == machine_id:
+                return Machine(
+                    id=m["id"], active=m.get("active", False), metadata=m.get("metadata", {})
+                )
+        raise HappyError(f"Machine {machine_id} not found")
+
+    # -----------------------------------------------------------------------
+    # Session lifecycle
+    # -----------------------------------------------------------------------
+
+    async def spawn_session(
+        self,
+        machine_id: str,
+        directory: str,
+        agent: Agent = "claude",
+        create_dir: bool = False,
+    ) -> str:
+        machine_key, machine_variant = await self._resolve_machine_key(machine_id)
+        payload = {
+            "type": "spawn-in-directory",
+            "directory": directory,
+            "approvedNewDirectoryCreation": create_dir,
+            "agent": agent,
+        }
+        encrypted = encrypt(machine_key, machine_variant, payload)
+        ack = await self._sockets.rpc_call(
+            f"{machine_id}:spawn-happy-session",
+            encode_base64(encrypted),
+        )
+        result_b64 = ack.get("result", "")
+        result = decrypt(machine_key, machine_variant, decode_base64(result_b64))
+        if not result or result.get("type") != "success":
+            msg = result.get("errorMessage", "unknown") if result else "decrypt failed"
+            raise SpawnError(f"Spawn failed: {msg}")
+        session_id = result.get("sessionId")
+        if not session_id:
+            raise SpawnError("Spawn succeeded but returned no sessionId")
+        return session_id
+
+    async def stop_session(self, session_id: str) -> None:
+        key, variant = await self._resolve_session_key(session_id)
+        sock = await self._sockets.open_session_socket(session_id)
+        conn = SessionConnection(sock, session_id, key, variant)
+        try:
+            await conn.send_stop()
+        finally:
+            await sock.disconnect()
+
+    async def delete_session(self, session_id: str) -> None:
+        await self._api.delete_session(session_id)
+
+    # -----------------------------------------------------------------------
+    # Messaging
+    # -----------------------------------------------------------------------
+
+    async def send_message(
+        self,
+        session_id: str,
+        text: str,
+        permission_mode: PermissionMode = "yolo",
+    ) -> None:
+        key, variant = await self._resolve_session_key(session_id)
+        sock = await self._sockets.open_session_socket(session_id)
+        conn = SessionConnection(sock, session_id, key, variant)
+        try:
+            await conn.send_message(text, permission_mode)
+        finally:
+            await sock.disconnect()
+
+    # -----------------------------------------------------------------------
+    # Waiting
+    # -----------------------------------------------------------------------
+
+    async def wait_for_turn_completion(
+        self, session_id: str, timeout_seconds: float = 300
+    ) -> None:
+        key, variant = await self._resolve_session_key(session_id)
+        sock = await self._sockets.open_session_socket(session_id)
+        conn = SessionConnection(sock, session_id, key, variant)
+        try:
+            await conn.wait_for_turn_completion(timeout_seconds)
+        finally:
+            await sock.disconnect()
+
+    async def wait_for_idle(
+        self, session_id: str, timeout_seconds: float = 300
+    ) -> None:
+        key, variant = await self._resolve_session_key(session_id)
+        sock = await self._sockets.open_session_socket(session_id)
+        conn = SessionConnection(sock, session_id, key, variant)
+        try:
+            await conn.wait_for_idle(timeout_seconds)
+        finally:
+            await sock.disconnect()
+
+    # -----------------------------------------------------------------------
+    # Query
+    # -----------------------------------------------------------------------
+
+    async def list_sessions(self, active_only: bool = False) -> list[Session]:
+        if active_only:
+            raw = await self._api.list_active_sessions()
+        else:
+            raw = await self._api.list_sessions()
+        return [
+            Session(
+                id=s["id"],
+                active=s.get("active", False),
+                created_at=s.get("createdAt", 0),
+                metadata=s.get("metadata", {}),
+                agent_state=s.get("agentState"),
+            )
+            for s in raw
+        ]
+
+    async def get_session(self, session_id: str) -> Session:
+        s = await self._api.get_session(session_id)
+        return Session(
+            id=s["id"],
+            active=s.get("active", False),
+            created_at=s.get("createdAt", 0),
+            metadata=s.get("metadata", {}),
+            agent_state=s.get("agentState"),
+        )
+
+    async def get_messages(self, session_id: str) -> list[Message]:
+        key, variant = await self._resolve_session_key(session_id)
+        raw = await self._api.get_messages(session_id)
+        messages = []
+        for m in raw:
+            content = m.get("content", {})
+            # Decrypt if still encrypted on the wire
+            if isinstance(content, dict) and content.get("t") == "encrypted":
+                c = content.get("c", "")
+                decrypted = decrypt(key, variant, decode_base64(c))
+                content = decrypted if decrypted is not None else content
+            messages.append(
+                Message(
+                    id=m["id"],
+                    seq=m.get("seq", 0),
+                    content=content,
+                    created_at=m.get("createdAt", 0),
+                )
+            )
+        return messages
+
+    # -----------------------------------------------------------------------
+    # Convenience
+    # -----------------------------------------------------------------------
+
+    async def run_task(
+        self,
+        machine_id: str,
+        directory: str,
+        prompt: str,
+        agent: Agent = "claude",
+        timeout_seconds: float = 600,
+    ) -> str:
+        session_id = await self.spawn_session(machine_id, directory, agent)
+        await self.send_message(session_id, prompt)
+        await self.wait_for_turn_completion(session_id, timeout_seconds)
+        await self.stop_session(session_id)
+        return session_id
+
+    # -----------------------------------------------------------------------
+    # Cleanup
+    # -----------------------------------------------------------------------
+
+    async def close(self) -> None:
+        pass  # Connections are per-call; nothing persistent to close in v1

happy_sdk/credentials.py

@@ -0,0 +1,44 @@
+import base64
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from .exceptions import AuthenticationError
+
+
+@dataclass
+class Credentials:
+    token: str
+    secret: bytes
+
+
+def load_credentials(path: str | None = None) -> Credentials:
+    if path is None:
+        home_dir = os.environ.get("HAPPY_HOME_DIR", str(Path.home() / ".happy"))
+        path = os.path.join(home_dir, "agent.key")
+
+    path = os.path.expanduser(path)
+    try:
+        with open(path) as f:
+            data = json.load(f)
+    except FileNotFoundError:
+        raise AuthenticationError(
+            f"Credentials file not found: {path}. Run 'happy-agent auth login' first."
+        )
+    except (json.JSONDecodeError, IOError) as e:
+        raise AuthenticationError(f"Failed to read credentials from {path}: {e}")
+
+    token = data.get("token")
+    secret_b64 = data.get("secret")
+    if not token or not secret_b64:
+        raise AuthenticationError(
+            f"Credentials file {path} is missing 'token' or 'secret' fields."
+        )
+
+    try:
+        secret = base64.b64decode(secret_b64)
+    except Exception as e:
+        raise AuthenticationError(f"Failed to decode secret from credentials: {e}")
+
+    return Credentials(token=token, secret=secret)

happy_sdk/encryption.py

@@ -0,0 +1,135 @@
+import base64
+import hashlib
+import hmac
+import json
+import os
+from typing import Any
+
+import nacl.public
+import nacl.secret
+import nacl.utils
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+from .exceptions import EncryptionError
+
+
+# ---------------------------------------------------------------------------
+# Base64 helpers
+# ---------------------------------------------------------------------------
+
+def encode_base64(data: bytes) -> str:
+    return base64.b64encode(data).decode()
+
+
+def decode_base64(b64: str) -> bytes:
+    return base64.b64decode(b64)
+
+
+# ---------------------------------------------------------------------------
+# Key derivation
+# ---------------------------------------------------------------------------
+
+def hmac_sha512(key: bytes, data: bytes) -> bytes:
+    return hmac.new(key, data, hashlib.sha512).digest()
+
+
+def derive_key(master: bytes, usage: str, path: list[str]) -> bytes:
+    seed_key = f"{usage} Master Seed".encode()
+    root = hmac_sha512(seed_key, master)
+    key, chain = root[:32], root[32:]
+    for segment in path:
+        child = hmac_sha512(chain, b"\x00" + segment.encode())
+        key, chain = child[:32], child[32:]
+    return key
+
+
+def derive_content_key_pair(secret: bytes) -> tuple[bytes, bytes]:
+    """Return (public_key_bytes, private_key_bytes) for NaCl box operations."""
+    raw = derive_key(secret, "Happy EnCoder", ["content"])
+    seed = hashlib.sha512(raw).digest()[:32]
+    private_key = nacl.public.PrivateKey(seed)
+    return bytes(private_key.public_key), bytes(private_key)
+
+
+# ---------------------------------------------------------------------------
+# AES-256-GCM  (wire: 0x00 + nonce[12] + ct+tag)
+# ---------------------------------------------------------------------------
+
+def encrypt_aes_gcm(data: Any, key: bytes) -> bytes:
+    plaintext = json.dumps(data).encode()
+    nonce = os.urandom(12)
+    ct = AESGCM(key).encrypt(nonce, plaintext, None)
+    return b"\x00" + nonce + ct
+
+
+def decrypt_aes_gcm(bundle: bytes, key: bytes) -> Any | None:
+    try:
+        if bundle[0] != 0x00:
+            return None
+        nonce = bundle[1:13]
+        ct = bundle[13:]
+        plaintext = AESGCM(key).decrypt(nonce, ct, None)
+        return json.loads(plaintext)
+    except Exception:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# NaCl secretbox  (legacy variant — wire: nonce[24] + ct)
+# ---------------------------------------------------------------------------
+
+def encrypt_secretbox(data: Any, key: bytes) -> bytes:
+    plaintext = json.dumps(data).encode()
+    box = nacl.secret.SecretBox(key)
+    return bytes(box.encrypt(plaintext))
+
+
+def decrypt_secretbox(bundle: bytes, key: bytes) -> Any | None:
+    try:
+        box = nacl.secret.SecretBox(key)
+        plaintext = box.decrypt(bundle)
+        return json.loads(plaintext)
+    except Exception:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# NaCl box bundle  (wire: ephemeral_pub[32] + nonce[24] + ct)
+# ---------------------------------------------------------------------------
+
+def decrypt_box_bundle(bundle: bytes, secret_key: bytes) -> bytes | None:
+    try:
+        ephemeral_pub = bundle[:32]
+        nonce = bundle[32:56]
+        ct = bundle[56:]
+        box = nacl.public.Box(
+            nacl.public.PrivateKey(secret_key),
+            nacl.public.PublicKey(ephemeral_pub),
+        )
+        return bytes(box.decrypt(ct, nonce))
+    except Exception:
+        return None
+
+
+def encrypt_for_public_key(data: bytes, public_key: bytes) -> bytes:
+    ephemeral = nacl.public.PrivateKey.generate()
+    box = nacl.public.Box(ephemeral, nacl.public.PublicKey(public_key))
+    nonce = nacl.utils.random(24)
+    ct = box.encrypt(data, nonce).ciphertext
+    return bytes(ephemeral.public_key) + nonce + ct
+
+
+# ---------------------------------------------------------------------------
+# Dispatcher
+# ---------------------------------------------------------------------------
+
+def encrypt(key: bytes, variant: str, data: Any) -> bytes:
+    if variant == "dataKey":
+        return encrypt_aes_gcm(data, key)
+    return encrypt_secretbox(data, key)
+
+
+def decrypt(key: bytes, variant: str, bundle: bytes) -> Any | None:
+    if variant == "dataKey":
+        return decrypt_aes_gcm(bundle, key)
+    return decrypt_secretbox(bundle, key)

happy_sdk/exceptions.py

@@ -0,0 +1,26 @@
+class HappyError(Exception):
+    """Base class for all happy-sdk errors."""
+
+
+class AuthenticationError(HappyError):
+    """Credentials missing, expired, or malformed."""
+
+
+class MachineOfflineError(HappyError):
+    """Target machine is not connected to the server."""
+
+
+class SpawnError(HappyError):
+    """Session spawn failed."""
+
+
+class TimeoutError(HappyError):
+    """Wait exceeded the specified timeout."""
+
+
+class EncryptionError(HappyError):
+    """Encrypt or decrypt operation failed."""
+
+
+class ConnectionError(HappyError):
+    """Socket connection failed or disconnected unexpectedly."""

happy_sdk/session_connection.py

@@ -0,0 +1,121 @@
+import asyncio
+import time
+from typing import Any
+
+from .encryption import decode_base64, decrypt, encode_base64, encrypt
+from .exceptions import TimeoutError
+from .socket_manager import SessionSocket
+
+
+class SessionConnection:
+    def __init__(
+        self,
+        socket: SessionSocket,
+        session_id: str,
+        session_key: bytes,
+        variant: str,
+    ) -> None:
+        self._socket = socket
+        self._session_id = session_id
+        self._session_key = session_key
+        self._variant = variant
+
+    async def send_message(self, text: str, permission_mode: str = "yolo") -> None:
+        content = {
+            "role": "user",
+            "content": {"type": "text", "text": text},
+            "meta": {"sentFrom": "happy-sdk-python", "permissionMode": permission_mode},
+        }
+        encrypted = encrypt(self._session_key, self._variant, content)
+        await self._socket.emit(
+            "message",
+            {"sid": self._session_id, "message": encode_base64(encrypted)},
+        )
+
+    async def send_stop(self) -> None:
+        await self._socket.emit(
+            "session-end",
+            {"sid": self._session_id, "time": int(time.time() * 1000)},
+        )
+
+    async def wait_for_turn_completion(self, timeout: float = 300) -> None:
+        deadline = time.monotonic() + timeout
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise TimeoutError(f"wait_for_turn_completion timed out after {timeout}s")
+            update = await self._socket.wait_for_update(remaining)
+            if update is None:
+                raise TimeoutError(f"wait_for_turn_completion timed out after {timeout}s")
+            if self._is_turn_complete(update):
+                return
+
+    async def wait_for_idle(self, timeout: float = 300) -> None:
+        deadline = time.monotonic() + timeout
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise TimeoutError(f"wait_for_idle timed out after {timeout}s")
+            update = await self._socket.wait_for_update(remaining)
+            if update is None:
+                raise TimeoutError(f"wait_for_idle timed out after {timeout}s")
+            if self._is_turn_complete(update):
+                return
+            if self._is_idle(update):
+                return
+
+    def _decrypt_update(self, update: dict[str, Any]) -> Any | None:
+        """Decrypt content from an update body dict."""
+        body = update.get("body", update)
+        t = body.get("t")
+
+        if t == "new-message":
+            msg = body.get("message", {})
+            content = msg.get("content", {})
+            # May be {"t": "encrypted", "c": "<base64>"} or already decrypted
+            if isinstance(content, dict) and content.get("t") == "encrypted":
+                raw = decode_base64(content["c"])
+                return decrypt(self._session_key, self._variant, raw)
+            return content
+
+        if t == "update-session":
+            agent_state = body.get("agentState", {})
+            value = agent_state.get("value")
+            if value:
+                raw = decode_base64(value)
+                return decrypt(self._session_key, self._variant, raw)
+            return agent_state
+
+        return None
+
+    def _is_turn_complete(self, update: dict[str, Any]) -> bool:
+        body = update.get("body", update)
+        if body.get("t") != "new-message":
+            return False
+        decrypted = self._decrypt_update(update)
+        if not isinstance(decrypted, dict):
+            return False
+        # session turn-end: {"role": "session", "content": {"turn": "...", "ev": {"t": "turn-end"}}}
+        content = decrypted.get("content", {})
+        if isinstance(content, dict):
+            ev = content.get("ev", {})
+            if isinstance(ev, dict) and ev.get("t") == "turn-end":
+                return True
+        # agent ready: {"role": "agent", "content": {"type": "event", "data": {"type": "ready"}}}
+        if isinstance(content, dict) and content.get("type") == "event":
+            data = content.get("data", {})
+            if isinstance(data, dict) and data.get("type") == "ready":
+                return True
+        return False
+
+    def _is_idle(self, update: dict[str, Any]) -> bool:
+        body = update.get("body", update)
+        if body.get("t") != "update-session":
+            return False
+        decrypted = self._decrypt_update(update)
+        if not isinstance(decrypted, dict):
+            return False
+        if decrypted.get("controlledByUser") is not False:
+            return False
+        requests = decrypted.get("requests", {})
+        return len(requests) == 0

happy_sdk/socket_manager.py

@@ -0,0 +1,100 @@
+import asyncio
+from typing import Any
+
+import socketio
+
+from .exceptions import ConnectionError, SpawnError
+
+
+_SIO_PATH = "/v1/updates"
+_SIO_TRANSPORT = ["websocket"]
+
+
+class SessionSocket:
+    """Thin wrapper around a connected session-scoped socketio.AsyncClient."""
+
+    def __init__(self, sio: socketio.AsyncClient, session_id: str) -> None:
+        self._sio = sio
+        self._session_id = session_id
+        self._update_event: asyncio.Event = asyncio.Event()
+        self._last_update: dict[str, Any] | None = None
+
+        @sio.on("update")
+        def _on_update(data: dict[str, Any]) -> None:
+            self._last_update = data
+            self._update_event.set()
+
+    async def emit(self, event: str, data: dict[str, Any]) -> None:
+        await self._sio.emit(event, data)
+
+    async def wait_for_update(self, timeout: float) -> dict[str, Any] | None:
+        """Block until an 'update' event arrives or timeout. Returns the body or None."""
+        self._update_event.clear()
+        try:
+            await asyncio.wait_for(self._update_event.wait(), timeout=timeout)
+        except asyncio.TimeoutError:
+            return None
+        data = self._last_update
+        self._last_update = None
+        return data
+
+    async def disconnect(self) -> None:
+        await self._sio.disconnect()
+
+
+class SocketManager:
+    """Creates and manages Socket.IO connections to the Happy server."""
+
+    def __init__(self, server_url: str, token: str) -> None:
+        self._server_url = server_url
+        self._token = token
+
+    async def rpc_call(self, method: str, params: str) -> dict[str, Any]:
+        """
+        One-shot user-scoped connection. Emits rpc-call, waits for ack, disconnects.
+        Returns the ack result dict or raises SpawnError.
+        """
+        sio = socketio.AsyncClient(logger=False, engineio_logger=False)
+        try:
+            await sio.connect(
+                self._server_url,
+                auth={"token": self._token},
+                socketio_path=_SIO_PATH,
+                transports=_SIO_TRANSPORT,
+            )
+            result = await sio.call("rpc-call", {"method": method, "params": params})
+        except Exception as e:
+            raise SpawnError(f"RPC call failed: {e}") from e
+        finally:
+            try:
+                await sio.disconnect()
+            except Exception:
+                pass
+
+        if not isinstance(result, dict):
+            raise SpawnError(f"Unexpected RPC ack type: {type(result)}")
+        if not result.get("ok"):
+            raise SpawnError(f"RPC error: {result.get('error', 'unknown')}")
+        return result
+
+    async def open_session_socket(self, session_id: str) -> SessionSocket:
+        """Return a connected session-scoped socket wrapper."""
+        sio = socketio.AsyncClient(
+            logger=False,
+            engineio_logger=False,
+            reconnection=True,
+        )
+        try:
+            await sio.connect(
+                self._server_url,
+                auth={
+                    "token": self._token,
+                    "clientType": "session-scoped",
+                    "sessionId": session_id,
+                },
+                socketio_path=_SIO_PATH,
+                transports=_SIO_TRANSPORT,
+            )
+        except Exception as e:
+            raise ConnectionError(f"Failed to open session socket for {session_id}: {e}") from e
+        return SessionSocket(sio, session_id)

happy_sdk/types.py

@@ -0,0 +1,29 @@
+from typing import Any, Literal
+from dataclasses import dataclass, field
+
+Agent = Literal["claude", "codex", "gemini", "openclaw"]
+PermissionMode = Literal["yolo", "default"]
+
+
+@dataclass
+class Machine:
+    id: str
+    active: bool
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Session:
+    id: str
+    active: bool
+    created_at: int
+    metadata: dict[str, Any] = field(default_factory=dict)
+    agent_state: dict[str, Any] | None = None
+
+
+@dataclass
+class Message:
+    id: str
+    seq: int
+    content: dict[str, Any]
+    created_at: int