happy-engineering-sdk 0.1.0__tar.gz

happy_engineering_sdk-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.env
+*.egg
+.pytest_cache/

happy_engineering_sdk-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,89 @@
+# 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/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_engineering_sdk-0.1.0/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_engineering_sdk-0.1.0/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_engineering_sdk-0.1.0/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)