agentlock-sdk 0.2.0__py3-none-any.whl

agentlock/__init__.py

@@ -0,0 +1,36 @@
+"""AgentLock Python SDK"""
+
+from .client import (
+    AgentLockClient,
+    create_client,
+    GatewayResult,
+    ExecutionResult,
+    BrowserActionResult,
+    McpToolInfo,
+    McpListToolsResult,
+    McpContentItem,
+    McpCallToolResult,
+    AgentMessage,
+    NewThreadResult,
+)
+from .errors import (
+    AgentLockError,
+    ApprovalDeniedError,
+    ApprovalTimeoutError,
+    SshSessionExpiredError,
+    SshSessionClosedError,
+)
+from .signing import generate_keypair, KeyPair
+from .ssh import SshSession, SshRunResult
+
+__all__ = [
+    "AgentLockClient", "create_client",
+    "AgentMessage", "BrowserActionResult", "ExecutionResult", "GatewayResult",
+    "McpCallToolResult", "McpContentItem", "McpListToolsResult", "McpToolInfo",
+    "NewThreadResult",
+    "SshSession", "SshRunResult",
+    "AgentLockError", "ApprovalDeniedError", "ApprovalTimeoutError",
+    "SshSessionExpiredError", "SshSessionClosedError",
+    "generate_keypair", "KeyPair",
+]
+__version__ = "0.2.0"

agentlock/_base.py

@@ -0,0 +1,102 @@
+"""Base mixin: HTTP transport, signing, request/await primitives, shared dataclasses."""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+import httpx
+
+from .signing import sign_request
+
+
+@dataclass
+class GatewayResult:
+    request_id: str
+    decision: str
+    status: str
+    message: Optional[str] = None
+    expires_at: Optional[str] = None
+
+
+@dataclass
+class ExecutionResult:
+    status: str
+    result: Optional[Dict[str, Any]] = None
+    error: Optional[str] = None
+
+
+class _BaseClient:
+    """HTTP plumbing shared by all per-connector mixins.
+
+    Subclasses MUST set: ``base_url``, ``agent_id``, ``private_key``, ``timeout``,
+    ``_client`` (an ``httpx.Client``).
+    """
+
+    base_url: str
+    agent_id: str
+    private_key: str
+    timeout: float
+    _client: httpx.Client
+
+    def _request_with_retry(self, method: str, url: str, **kwargs) -> httpx.Response:
+        max_retries = 3
+        for attempt in range(max_retries + 1):
+            response = self._client.request(method, url, **kwargs)
+            if response.status_code not in (429, 502, 503, 504) or attempt == max_retries:
+                response.raise_for_status()
+                return response
+            retry_after = response.headers.get('retry-after')
+            delay = int(retry_after) if retry_after else min(2 ** attempt, 10)
+            time.sleep(delay)
+        raise RuntimeError('Unreachable')
+
+    def request_action(
+        self,
+        action_type: str,
+        tool: str,
+        payload: Dict[str, Any],
+        cost_estimate: Optional[float] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> GatewayResult:
+        body: Dict[str, Any] = {"action_type": action_type, "tool": tool, "payload": payload}
+        if cost_estimate is not None:
+            body["cost_estimate"] = cost_estimate
+        if idempotency_key:
+            body["idempotency_key"] = idempotency_key
+
+        headers = sign_request(body, self.agent_id, self.private_key)
+        headers["Content-Type"] = "application/json"
+
+        response = self._request_with_retry(
+            "POST", f"{self.base_url}/api/gateway/request", json=body, headers=headers,
+        )
+        data = response.json()
+        return GatewayResult(
+            request_id=data["request_id"],
+            decision=data["decision"],
+            status=data["status"],
+            message=data.get("message"),
+            expires_at=data.get("expires_at"),
+        )
+
+    def await_result(
+        self,
+        request_id: str,
+        poll_interval: float = 2.0,
+        timeout: float = 300.0,
+    ) -> ExecutionResult:
+        deadline = time.time() + timeout
+        while time.time() < deadline:
+            poll_body = {"requestId": request_id}
+            headers = sign_request(poll_body, self.agent_id, self.private_key)
+            response = self._request_with_retry(
+                "GET", f"{self.base_url}/api/gateway/result/{request_id}", headers=headers,
+            )
+            data = response.json()
+            if data["status"] in {"SUCCEEDED", "FAILED", "DENIED", "EXPIRED", "BLOCKED"}:
+                return ExecutionResult(
+                    status=data["status"], result=data.get("result"), error=data.get("error"),
+                )
+            time.sleep(poll_interval)
+        raise TimeoutError(f"Timeout waiting for result of request {request_id}")

agentlock/browser.py

@@ -0,0 +1,122 @@
+"""Browser session mixin."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+from .signing import sign_request
+from ._base import _BaseClient
+
+
+@dataclass
+class BrowserActionResult:
+    session_id: str
+    snapshot: str
+    page_url: str
+    page_title: str
+    action_performed: str = ""
+    screenshot: Optional[str] = None
+
+
+class _BrowserMixin(_BaseClient):
+    def browser_open(
+        self,
+        url: str,
+        *,
+        allowed_domains: Optional[List[str]] = None,
+    ) -> BrowserActionResult:
+        payload: Dict[str, Any] = {"url": url}
+        if allowed_domains is not None:
+            payload["allowed_domains"] = allowed_domains
+
+        gateway_result = self.request_action(
+            action_type="write", tool="browser.open", payload=payload,
+        )
+        if gateway_result.status == "BLOCKED":
+            raise RuntimeError(f"Browser open blocked: {gateway_result.message}")
+
+        final_result = self.await_result(gateway_result.request_id)
+        if final_result.status == "DENIED":
+            raise RuntimeError("Browser session was denied")
+        if final_result.status == "EXPIRED":
+            raise RuntimeError("Browser session approval expired")
+        if final_result.status == "FAILED":
+            raise RuntimeError(f"Browser open failed: {final_result.error}")
+
+        result = final_result.result or {}
+        if not result.get("session_id"):
+            raise RuntimeError("No session_id in browser.open result")
+
+        return BrowserActionResult(
+            session_id=result["session_id"],
+            snapshot=result.get("snapshot", ""),
+            page_url=result.get("page_url", ""),
+            page_title=result.get("page_title", ""),
+            action_performed=result.get("action_performed", ""),
+            screenshot=result.get("screenshot"),
+        )
+
+    def browser_action(
+        self,
+        session_id: str,
+        tool: str,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> BrowserActionResult:
+        if not tool.startswith("browser."):
+            tool = f"browser.{tool}"
+        payload: Dict[str, Any] = {"session_id": session_id}
+        if params:
+            payload.update(params)
+
+        body: Dict[str, Any] = {"action_type": "write", "tool": tool, "payload": payload}
+        headers = sign_request(body, self.agent_id, self.private_key)
+        headers["Content-Type"] = "application/json"
+
+        response = self._client.post(
+            f"{self.base_url}/api/gateway/request", json=body, headers=headers,
+        )
+        if not response.is_success:
+            err = response.json() if response.headers.get("content-type", "").startswith("application/json") else {}
+            raise RuntimeError(f"Browser action failed: {err.get('error', response.text)}")
+
+        data = response.json()
+        result = data.get("result")
+        if not result:
+            raise RuntimeError(data.get("error", "No result from browser action"))
+
+        return BrowserActionResult(
+            session_id=result.get("session_id", session_id),
+            snapshot=result.get("snapshot", ""),
+            page_url=result.get("page_url", ""),
+            page_title=result.get("page_title", ""),
+            action_performed=result.get("action_performed", ""),
+            screenshot=result.get("screenshot"),
+        )
+
+    def browser_fill_credentials(
+        self, session_id: str, credential_name: str, field_mapping: Dict[str, str],
+    ) -> BrowserActionResult:
+        return self.browser_action(
+            session_id, "browser.fill_credentials",
+            params={"credential_name": credential_name, "field_mapping": field_mapping},
+        )
+
+    def browser_close(self, session_id: str) -> BrowserActionResult:
+        return self.browser_action(session_id, "browser.close")
+
+    def browser_snapshot(self, session_id: str) -> Dict[str, Any]:
+        """Take an accessibility-tree snapshot of the current page.
+
+        Convenience wrapper over ``browser_action(session_id, 'snapshot')``.
+        Returns a dict with ``html``, ``url``, ``title``, and optionally
+        ``screenshot`` (base64) when the runner returns one.
+        """
+        r = self.browser_action(session_id, "browser.snapshot")
+        out: Dict[str, Any] = {
+            "html": r.snapshot,
+            "url": r.page_url,
+            "title": r.page_title,
+        }
+        if r.screenshot:
+            out["screenshot"] = r.screenshot
+        return out

agentlock/client.py

@@ -0,0 +1,74 @@
+"""AgentLock Python SDK Client (composition root).
+
+The actual connector logic lives in per-mixin modules: _base, browser,
+mcp, messaging. This file wires them together so the public
+``AgentLockClient`` keeps its flat, instance-method-per-tool API.
+"""
+from __future__ import annotations
+
+import httpx
+
+from ._base import _BaseClient, GatewayResult, ExecutionResult
+from .browser import _BrowserMixin, BrowserActionResult
+from .http import _HttpMixin
+from .mcp import _McpMixin, McpToolInfo, McpListToolsResult, McpContentItem, McpCallToolResult
+from .messaging import _MessagingMixin, AgentMessage, NewThreadResult
+from .ssh import _SshMixin, SshSession, SshRunResult
+
+
+class AgentLockClient(
+    _SshMixin,
+    _BrowserMixin,
+    _McpMixin,
+    _MessagingMixin,
+    _HttpMixin,
+    _BaseClient,
+):
+    def __init__(
+        self,
+        base_url: str,
+        agent_id: str,
+        private_key: str,
+        timeout: float = 30.0,
+    ):
+        if not base_url.startswith("https://") and not base_url.startswith("http://localhost"):
+            raise ValueError(
+                "AgentLockClient: base_url must use HTTPS (or http://localhost for development)"
+            )
+        self.base_url = base_url.rstrip("/")
+        self.agent_id = agent_id
+        self.private_key = private_key
+        self.timeout = timeout
+        self._client = httpx.Client(timeout=self.timeout)
+
+    def close(self):
+        self._client.close()
+        self.private_key = None  # type: ignore[assignment]
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"AgentLockClient(agent_id={self.agent_id!r})"
+
+
+def create_client(
+    base_url: str, agent_id: str, private_key: str, timeout: float = 30.0,
+) -> AgentLockClient:
+    return AgentLockClient(
+        base_url=base_url, agent_id=agent_id, private_key=private_key, timeout=timeout,
+    )
+
+
+# Re-export public dataclasses so existing `from agentlock.client import X` works.
+__all__ = [
+    "AgentLockClient", "create_client",
+    "GatewayResult", "ExecutionResult",
+    "BrowserActionResult",
+    "McpToolInfo", "McpListToolsResult", "McpContentItem", "McpCallToolResult",
+    "AgentMessage", "NewThreadResult",
+    "SshSession", "SshRunResult",
+]

agentlock/errors.py

@@ -0,0 +1,38 @@
+"""Typed error classes for the AgentLock SDK."""
+from __future__ import annotations
+from datetime import datetime
+from typing import Optional
+
+
+class AgentLockError(Exception):
+    """Base class for all AgentLock SDK errors."""
+
+
+class ApprovalDeniedError(AgentLockError):
+    def __init__(self, request_id: str, denial_reason: Optional[str] = None):
+        self.request_id = request_id
+        self.denial_reason = denial_reason
+        msg = f"Approval denied for request {request_id}"
+        if denial_reason:
+            msg += f": {denial_reason}"
+        super().__init__(msg)
+
+
+class ApprovalTimeoutError(AgentLockError):
+    def __init__(self, request_id: str, waited_ms: int):
+        self.request_id = request_id
+        self.waited_ms = waited_ms
+        super().__init__(f"Approval timed out for request {request_id} after {waited_ms}ms")
+
+
+class SshSessionExpiredError(AgentLockError):
+    def __init__(self, session_id: str, expires_at: datetime):
+        self.session_id = session_id
+        self.expires_at = expires_at
+        super().__init__(f"SSH session {session_id} expired at {expires_at.isoformat()}")
+
+
+class SshSessionClosedError(AgentLockError):
+    def __init__(self, session_id: str):
+        self.session_id = session_id
+        super().__init__(f"SSH session {session_id} has been closed")

agentlock/http.py

@@ -0,0 +1,56 @@
+"""HTTP convenience wrapper."""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from ._base import _BaseClient
+from .errors import ApprovalDeniedError, ApprovalTimeoutError
+
+
+READ_ONLY_METHODS = {"GET", "HEAD", "OPTIONS"}
+
+
+class _HttpMixin(_BaseClient):
+    def http_request(
+        self,
+        *,
+        method: str,
+        url: str,
+        headers: Optional[Dict[str, str]] = None,
+        body: Any = None,
+        credential_id: Optional[str] = None,
+        approval_timeout: float = 300.0,
+    ) -> Dict[str, Any]:
+        """Make an HTTP request through the AgentLock proxy.
+
+        Returns a dict with ``status``, ``headers``, ``body``, ``duration_ms``.
+        Raises ``ApprovalDeniedError`` / ``ApprovalTimeoutError`` if approval
+        is required and not granted.
+        """
+        payload: Dict[str, Any] = {"method": method, "url": url}
+        if headers is not None: payload["headers"] = headers
+        if body is not None: payload["body"] = body
+        if credential_id is not None: payload["credential_id"] = credential_id
+
+        action_type = "read" if method.upper() in READ_ONLY_METHODS else "write"
+        gateway_result = self.request_action(
+            action_type=action_type, tool="http", payload=payload,
+        )
+        if gateway_result.status == "BLOCKED":
+            raise RuntimeError(f"http blocked: {gateway_result.message}")
+
+        final = self.await_result(gateway_result.request_id, timeout=approval_timeout)
+        if final.status == "DENIED":
+            raise ApprovalDeniedError(gateway_result.request_id, final.error)
+        if final.status == "EXPIRED":
+            raise ApprovalTimeoutError(gateway_result.request_id, int(approval_timeout * 1000))
+        if final.status == "FAILED":
+            raise RuntimeError(f"http failed: {final.error}")
+
+        r = final.result or {}
+        return {
+            "status": int(r.get("status", 0)),
+            "headers": r.get("headers", {}),
+            "body": r.get("body"),
+            "duration_ms": int(r.get("duration_ms", 0)),
+        }

agentlock/mcp.py

@@ -0,0 +1,94 @@
+"""MCP (Model Context Protocol) mixin."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from ._base import _BaseClient
+
+
+@dataclass
+class McpToolInfo:
+    name: str
+    description: str
+    input_schema: Optional[Any] = None
+
+
+@dataclass
+class McpListToolsResult:
+    server: str
+    tools: List[McpToolInfo] = field(default_factory=list)
+
+
+@dataclass
+class McpContentItem:
+    type: str
+    text: Optional[str] = None
+    data: Optional[str] = None
+    mime_type: Optional[str] = None
+
+
+@dataclass
+class McpCallToolResult:
+    server: str
+    method: str
+    content: List[McpContentItem] = field(default_factory=list)
+    text: Optional[str] = None
+    is_error: bool = False
+
+
+class _McpMixin(_BaseClient):
+    def mcp_list_tools(self, server: str) -> McpListToolsResult:
+        gateway_result = self.request_action(
+            action_type="read", tool="mcp.list_tools", payload={"server": server},
+        )
+        if gateway_result.status == "BLOCKED":
+            raise RuntimeError(f"MCP list_tools blocked: {gateway_result.message}")
+        final_result = self.await_result(gateway_result.request_id)
+        if final_result.status == "FAILED":
+            raise RuntimeError(f"MCP list_tools failed: {final_result.error}")
+
+        result = final_result.result or {}
+        tools = [
+            McpToolInfo(
+                name=t.get("name", ""),
+                description=t.get("description", ""),
+                input_schema=t.get("input_schema"),
+            )
+            for t in result.get("tools", [])
+        ]
+        return McpListToolsResult(server=result.get("server", server), tools=tools)
+
+    def mcp_call_tool(
+        self, server: str, method: str,
+        args: Optional[Dict[str, Any]] = None,
+        action_type: str = "write",
+    ) -> McpCallToolResult:
+        gateway_result = self.request_action(
+            action_type=action_type, tool="mcp.call_tool",
+            payload={"server": server, "method": method, "arguments": args or {}},
+        )
+        if gateway_result.status == "BLOCKED":
+            raise RuntimeError(f"MCP call_tool blocked: {gateway_result.message}")
+        final_result = self.await_result(gateway_result.request_id)
+        if final_result.status == "DENIED":
+            raise RuntimeError("MCP call_tool was denied")
+        if final_result.status == "EXPIRED":
+            raise RuntimeError("MCP call_tool approval expired")
+        if final_result.status == "FAILED":
+            raise RuntimeError(f"MCP call_tool failed: {final_result.error}")
+
+        result = final_result.result or {}
+        content = [
+            McpContentItem(
+                type=c.get("type", ""), text=c.get("text"),
+                data=c.get("data"), mime_type=c.get("mimeType"),
+            )
+            for c in result.get("content", [])
+        ]
+        return McpCallToolResult(
+            server=result.get("server", server),
+            method=result.get("method", method),
+            content=content, text=result.get("text"),
+            is_error=result.get("is_error", False),
+        )

agentlock/messaging.py

@@ -0,0 +1,264 @@
+"""User<->agent messaging mixin."""
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional
+from urllib.parse import urlencode
+
+from .signing import sign_request
+from ._base import _BaseClient
+
+
+@dataclass
+class AgentMessage:
+    """A message from the user→agent channel."""
+    id: str
+    thread_id: str
+    sender_type: str  # "user" | "agent"
+    sender_id: str
+    content: str
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    read_at: Optional[str] = None
+    created_at: str = ""
+
+
+@dataclass
+class NewThreadResult:
+    """Result from creating a new thread."""
+    thread_id: str
+    subject: Optional[str]
+    message: AgentMessage
+
+
+class _MessagingMixin(_BaseClient):
+    def get_messages(
+        self,
+        *,
+        since: Optional[str] = None,
+        limit: int = 20,
+        include_read: bool = False,
+        thread_id: Optional[str] = None,
+    ) -> List[AgentMessage]:
+        """Fetch messages addressed to this agent.
+
+        By default returns only unread ``user`` messages and marks them as
+        read server-side. Pass ``include_read=True`` to fetch the full
+        conversation history (both user and agent messages, read or unread).
+
+        Args:
+            since: ISO-8601 timestamp; only return messages created after this.
+            limit: Max messages to fetch (default 20, clamped server-side to 50).
+            include_read: If True, include already-read messages and agent replies.
+            thread_id: Filter to a specific thread.
+
+        Returns:
+            A list of ``AgentMessage`` objects, oldest first.
+        """
+        params: Dict[str, str] = {}
+        if since is not None:
+            params["since"] = since
+        if limit:
+            params["limit"] = str(limit)
+        if include_read:
+            params["include_read"] = "true"
+        if thread_id:
+            params["thread_id"] = thread_id
+
+        # Sign the poll request — the gateway requires either a Bearer token
+        # or a valid Ed25519 signature. For GET the SDK signs a fixed body.
+        headers = sign_request({"_poll": "messages"}, self.agent_id, self.private_key)
+
+        query = f"?{urlencode(params)}" if params else ""
+        response = self._request_with_retry(
+            "GET",
+            f"{self.base_url}/api/gateway/messages{query}",
+            headers=headers,
+        )
+        data = response.json()
+        messages = data.get("messages", []) if isinstance(data, dict) else []
+
+        return [
+            AgentMessage(
+                id=m.get("id", ""),
+                thread_id=m.get("thread_id", ""),
+                sender_type=m.get("sender_type", ""),
+                sender_id=m.get("sender_id", ""),
+                content=m.get("content", ""),
+                metadata=m.get("metadata") or {},
+                read_at=m.get("read_at"),
+                created_at=m.get("created_at", ""),
+            )
+            for m in messages
+        ]
+
+    def send_message(
+        self,
+        thread_id: str,
+        content: str,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> AgentMessage:
+        """Send a reply in an existing thread.
+
+        Use the ``thread_id`` from a received message to reply in context.
+        The message body is encrypted at rest by the gateway.
+
+        Args:
+            thread_id: The thread to reply in.
+            content: The reply text (1–4096 chars).
+            metadata: Optional JSON metadata (≤8KB serialized).
+
+        Returns:
+            The inserted ``AgentMessage``.
+        """
+        body: Dict[str, Any] = {"thread_id": thread_id, "content": content}
+        if metadata is not None:
+            body["metadata"] = metadata
+
+        headers = sign_request(body, self.agent_id, self.private_key)
+        headers["Content-Type"] = "application/json"
+
+        response = self._request_with_retry(
+            "POST",
+            f"{self.base_url}/api/gateway/messages",
+            json=body,
+            headers=headers,
+        )
+        data = response.json()
+        msg = data.get("message", {}) if isinstance(data, dict) else {}
+
+        return AgentMessage(
+            id=msg.get("id", ""),
+            thread_id=msg.get("thread_id", thread_id),
+            sender_type=msg.get("sender_type", "agent"),
+            sender_id=msg.get("sender_id", self.agent_id),
+            content=msg.get("content", content),
+            metadata=msg.get("metadata") or {},
+            read_at=msg.get("read_at"),
+            created_at=msg.get("created_at", ""),
+        )
+
+    def create_thread(
+        self,
+        content: str,
+        *,
+        subject: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> NewThreadResult:
+        """Start a new thread with the user (agent-initiated).
+
+        Args:
+            content: The first message body (1–4096 chars).
+            subject: Optional thread title (≤200 chars).
+            metadata: Optional JSON metadata (≤8KB serialized).
+
+        Returns:
+            ``NewThreadResult`` with ``thread_id`` and the inserted message.
+        """
+        body: Dict[str, Any] = {"create_thread": True, "content": content}
+        if subject is not None:
+            body["subject"] = subject
+        if metadata is not None:
+            body["metadata"] = metadata
+
+        headers = sign_request(body, self.agent_id, self.private_key)
+        headers["Content-Type"] = "application/json"
+
+        response = self._request_with_retry(
+            "POST",
+            f"{self.base_url}/api/gateway/messages",
+            json=body,
+            headers=headers,
+        )
+        data = response.json()
+        thread = data.get("thread", {}) if isinstance(data, dict) else {}
+        msg = data.get("message", {}) if isinstance(data, dict) else {}
+
+        return NewThreadResult(
+            thread_id=thread.get("id", ""),
+            subject=thread.get("subject"),
+            message=AgentMessage(
+                id=msg.get("id", ""),
+                thread_id=msg.get("thread_id", thread.get("id", "")),
+                sender_type=msg.get("sender_type", "agent"),
+                sender_id=msg.get("sender_id", self.agent_id),
+                content=msg.get("content", content),
+                metadata=msg.get("metadata") or {},
+                read_at=msg.get("read_at"),
+                created_at=msg.get("created_at", ""),
+            ),
+        )
+
+    def on_message(
+        self,
+        callback: Callable[[AgentMessage], None],
+        *,
+        poll_interval: float = 5.0,
+        max_backoff: float = 60.0,
+        on_error: Optional[Callable[[Exception], None]] = None,
+    ) -> Callable[[], None]:
+        """Listen for messages in a background thread.
+
+        Polls ``GET /api/gateway/messages`` every ``poll_interval`` seconds and
+        calls ``callback`` once per new message. This is a polling transport —
+        expect up to one interval of latency between the user sending a message
+        and the agent receiving it. The gateway rate limit is 60 requests/min
+        per agent; do not set ``poll_interval`` below ~1 second.
+
+        Failures do not stop the loop: they are reported via ``on_error`` (if
+        provided) and the poller backs off exponentially up to ``max_backoff``
+        seconds. A successful poll resets the backoff.
+
+        Args:
+            callback: Invoked for each new message.
+            poll_interval: Seconds between polls (default 5.0).
+            max_backoff: Max backoff on consecutive failures (default 60.0).
+            on_error: Optional callable invoked with any polling or callback error.
+
+        Returns:
+            A zero-arg ``stop()`` function — call it to stop the background
+            thread cleanly. The thread is a daemon so it will also die with
+            the interpreter.
+        """
+        stop_event = threading.Event()
+        last_seen: Dict[str, Optional[str]] = {"ts": None}
+
+        def _loop() -> None:
+            consecutive_failures = 0
+            while not stop_event.is_set():
+                try:
+                    messages = self.get_messages(since=last_seen["ts"])
+                    consecutive_failures = 0
+                    for msg in messages:
+                        last_seen["ts"] = msg.created_at
+                        try:
+                            callback(msg)
+                        except Exception as cb_err:  # noqa: BLE001
+                            if on_error is not None:
+                                try:
+                                    on_error(cb_err)
+                                except Exception:  # noqa: BLE001
+                                    pass
+                    # Success path: use the normal poll interval
+                    if stop_event.wait(poll_interval):
+                        return
+                except Exception as err:  # noqa: BLE001
+                    consecutive_failures += 1
+                    if on_error is not None:
+                        try:
+                            on_error(err)
+                        except Exception:  # noqa: BLE001
+                            pass
+                    # Exponential backoff: poll_interval * 2^n, capped at max_backoff
+                    exponent = min(consecutive_failures, 10)
+                    backoff = min(poll_interval * (2 ** exponent), max_backoff)
+                    if stop_event.wait(backoff):
+                        return
+
+        thread = threading.Thread(target=_loop, name="agentlock-onmessage", daemon=True)
+        thread.start()
+
+        def stop() -> None:
+            stop_event.set()
+
+        return stop

agentlock/signing.py

@@ -0,0 +1,121 @@
+"""Ed25519 request signing for AgentLock Python SDK"""
+
+import base64
+import json
+import math
+import os
+import time
+from dataclasses import dataclass
+from typing import Any, Dict
+
+# Signature scheme version. Bumped when the canonical pre-image format changes
+# in a way that breaks backward compatibility. The gateway always accepts v1;
+# when a future v2 is defined, clients bump this constant and send the header.
+SIGNATURE_VERSION_CURRENT = "1"
+
+try:
+    import nacl.signing
+    import nacl.encoding
+    HAS_NACL = True
+except ImportError:
+    HAS_NACL = False
+
+try:
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+        Ed25519PrivateKey,
+        Ed25519PublicKey,
+    )
+    HAS_CRYPTOGRAPHY = True
+except ImportError:
+    HAS_CRYPTOGRAPHY = False
+
+
+@dataclass
+class KeyPair:
+    public_key: str  # base64
+    private_key: str  # base64
+
+
+def generate_keypair() -> KeyPair:
+    """Generate an Ed25519 keypair for agent authentication."""
+    if HAS_NACL:
+        signing_key = nacl.signing.SigningKey.generate()
+        verify_key = signing_key.verify_key
+        private_key_bytes = bytes(signing_key) + bytes(verify_key)  # nacl concatenates
+        return KeyPair(
+            public_key=base64.b64encode(bytes(verify_key)).decode(),
+            private_key=base64.b64encode(private_key_bytes).decode(),
+        )
+    elif HAS_CRYPTOGRAPHY:
+        private_key = Ed25519PrivateKey.generate()
+        public_key = private_key.public_key()
+        private_bytes = private_key.private_bytes_raw()
+        public_bytes = public_key.public_bytes_raw()
+        combined = private_bytes + public_bytes  # match nacl format
+        return KeyPair(
+            public_key=base64.b64encode(public_bytes).decode(),
+            private_key=base64.b64encode(combined).decode(),
+        )
+    else:
+        raise ImportError("Install 'pynacl' or 'cryptography': pip install pynacl")
+
+
+class _CanonicalEncoder(json.JSONEncoder):
+    """JSON encoder that normalizes floats with no fractional part to ints,
+    matching JavaScript's JSON.stringify behaviour (e.g. 1.0 -> 1)."""
+
+    def encode(self, o: Any) -> str:
+        return super().encode(self._normalize(o))
+
+    def _normalize(self, obj: Any) -> Any:
+        if isinstance(obj, float):
+            if math.isfinite(obj) and obj == int(obj):
+                return int(obj)
+            return obj
+        if isinstance(obj, dict):
+            return {k: self._normalize(v) for k, v in sorted(obj.items())}
+        if isinstance(obj, (list, tuple)):
+            return [self._normalize(v) for v in obj]
+        return obj
+
+
+def canonical_stringify(obj: dict) -> str:
+    """Stable JSON serialization (sorted keys, JS-compatible float handling)."""
+    return json.dumps(obj, cls=_CanonicalEncoder, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def sign_request(
+    body: dict,
+    agent_id: str,
+    private_key_b64: str,
+) -> Dict[str, str]:
+    """Sign a request body and return headers."""
+    timestamp = str(int(time.time() * 1000))
+    nonce = base64.b64encode(os.urandom(16)).decode()
+    canonical = canonical_stringify(body)
+    # Bind the signature-scheme version into the signed material so a future
+    # v2 rollout cannot be downgraded to v1 by stripping the header on the
+    # wire. Must mirror packages/shared/src/signing.ts:signRequest exactly.
+    message = f"{canonical}:{timestamp}:{nonce}:{SIGNATURE_VERSION_CURRENT}".encode()
+
+    private_key_bytes = base64.b64decode(private_key_b64)
+
+    if HAS_NACL:
+        # nacl format: 64 bytes (first 32 = private, last 32 = public)
+        signing_key = nacl.signing.SigningKey(private_key_bytes[:32])
+        signed = signing_key.sign(message)
+        signature = base64.b64encode(signed.signature).decode()
+    elif HAS_CRYPTOGRAPHY:
+        private_key = Ed25519PrivateKey.from_private_bytes(private_key_bytes[:32])
+        sig_bytes = private_key.sign(message)
+        signature = base64.b64encode(sig_bytes).decode()
+    else:
+        raise ImportError("Install 'pynacl' or 'cryptography'")
+
+    return {
+        "x-agent-id": agent_id,
+        "x-timestamp": timestamp,
+        "x-signature": signature,
+        "x-nonce": nonce,
+        "x-signature-version": SIGNATURE_VERSION_CURRENT,
+    }

agentlock/ssh.py

@@ -0,0 +1,260 @@
+"""SSH session-handle pattern for the AgentLock SDK."""
+from __future__ import annotations
+
+import datetime as dt
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Protocol
+
+import httpx
+
+from .signing import sign_request
+from ._base import _BaseClient
+from .errors import (
+    AgentLockError,
+    ApprovalDeniedError,
+    ApprovalTimeoutError,
+    SshSessionClosedError,
+    SshSessionExpiredError,
+)
+
+
+@dataclass
+class SshRunResult:
+    stdout: str
+    stderr: str
+    exit_code: Optional[int]
+    signal: Optional[str]
+    truncated: bool
+    duration_ms: int
+
+
+class SshTransport(Protocol):
+    def run_on_session(self, session_id: str, command: str) -> SshRunResult: ...
+    def close_session(self, session_id: str) -> None: ...
+    def forget_session(self, session_id: str) -> None: ...
+
+
+@dataclass
+class SshSession:
+    id: str
+    host: str
+    user: str
+    port: int
+    via_vpn: bool
+    expires_at: dt.datetime
+    transport: SshTransport
+    last_activity_at: Optional[dt.datetime] = None
+    action_count: Optional[int] = None
+    _closed: bool = field(default=False, init=False, repr=False)
+
+    def is_expired(self) -> bool:
+        # Use timezone-aware UTC comparison
+        now = dt.datetime.now(self.expires_at.tzinfo or dt.timezone.utc)
+        return now >= self.expires_at
+
+    def run(self, command: str) -> SshRunResult:
+        if self._closed:
+            raise SshSessionClosedError(self.id)
+        if self.is_expired():
+            raise SshSessionExpiredError(self.id, self.expires_at)
+        return self.transport.run_on_session(self.id, command)
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        try:
+            self.transport.close_session(self.id)
+        finally:
+            self.transport.forget_session(self.id)
+
+    def __enter__(self) -> "SshSession":
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.close()
+
+
+class SshNamespace:
+    """Owns the per-client session cache; implements SshTransport for handles."""
+
+    def __init__(self, client: _BaseClient):
+        self._client = client
+        self._cache: Dict[str, SshSession] = {}
+
+    # ---- Public API -------------------------------------------------------
+
+    def open(
+        self,
+        *,
+        credential_id: Optional[str] = None,
+        host: Optional[str] = None,
+        user: Optional[str] = None,
+        port: Optional[int] = None,
+        ttl_ms: Optional[int] = None,
+        approval_timeout: float = 300.0,
+    ) -> SshSession:
+        payload: Dict[str, Any] = {}
+        if credential_id is not None:
+            payload["credential_id"] = credential_id
+        if host is not None:
+            payload["host"] = host
+        if user is not None:
+            payload["user"] = user
+        if port is not None:
+            payload["port"] = port
+        if ttl_ms is not None:
+            payload["ttl_ms"] = ttl_ms
+
+        gateway_result = self._client.request_action(
+            action_type="admin", tool="ssh.open", payload=payload,
+        )
+        if gateway_result.status == "BLOCKED":
+            raise RuntimeError(f"ssh.open blocked: {gateway_result.message}")
+
+        final = self._client.await_result(gateway_result.request_id, timeout=approval_timeout)
+        if final.status == "DENIED":
+            raise ApprovalDeniedError(gateway_result.request_id, final.error)
+        if final.status == "EXPIRED":
+            raise ApprovalTimeoutError(gateway_result.request_id, int(approval_timeout * 1000))
+        if final.status == "FAILED":
+            raise RuntimeError(f"ssh.open failed: {final.error}")
+
+        r = final.result or {}
+        session = SshSession(
+            id=str(r["session_id"]),
+            host=str(r.get("host", "")),
+            user=str(r.get("user", "")),
+            port=int(r.get("port", 22)),
+            via_vpn=bool(r.get("via_vpn", False)),
+            expires_at=dt.datetime.fromisoformat(str(r["expires_at"]).replace("Z", "+00:00")),
+            transport=self,
+        )
+        self._cache[session.id] = session
+        return session
+
+    def list(self) -> List[SshSession]:
+        headers = sign_request({}, self._client.agent_id, self._client.private_key)
+        try:
+            response = self._client._request_with_retry(
+                "GET", f"{self._client.base_url}/api/gateway/ssh-sessions", headers=headers,
+            )
+        except httpx.HTTPStatusError as e:
+            raise AgentLockError(
+                f"Failed to list SSH sessions (HTTP {e.response.status_code}): {e.response.text}"
+            ) from e
+        data = response.json()
+        out: List[SshSession] = []
+        for s in data.get("sessions", []):
+            sid = s["session_id"]
+            fresh_host = s.get("host", "")
+            fresh_user = s.get("user", "")
+            fresh_port = int(s.get("port", 22))
+            fresh_via_vpn = bool(s.get("via_vpn", False))
+            fresh_expires_at = dt.datetime.fromisoformat(
+                str(s["expires_at"]).replace("Z", "+00:00")
+            )
+            fresh_last_activity = (
+                dt.datetime.fromisoformat(str(s["last_activity_at"]).replace("Z", "+00:00"))
+                if s.get("last_activity_at") else None
+            )
+            fresh_action_count = s.get("action_count")
+
+            existing = self._cache.get(sid)
+            if existing is not None:
+                # Refresh ALL wire-derived fields. Only `id` is the cache key
+                # and never changes. This matters for handles created via
+                # adopt() — they start as stubs with empty host/user and a
+                # placeholder expires_at, and list() is the canonical way to
+                # populate them.
+                existing.host = fresh_host
+                existing.user = fresh_user
+                existing.port = fresh_port
+                existing.via_vpn = fresh_via_vpn
+                existing.expires_at = fresh_expires_at
+                if fresh_last_activity is not None:
+                    existing.last_activity_at = fresh_last_activity
+                if isinstance(fresh_action_count, int):
+                    existing.action_count = fresh_action_count
+                out.append(existing)
+                continue
+
+            session = SshSession(
+                id=sid,
+                host=fresh_host,
+                user=fresh_user,
+                port=fresh_port,
+                via_vpn=fresh_via_vpn,
+                expires_at=fresh_expires_at,
+                last_activity_at=fresh_last_activity,
+                action_count=fresh_action_count,
+                transport=self,
+            )
+            self._cache[sid] = session
+            out.append(session)
+        return out
+
+    def adopt(self, session_id: str) -> SshSession:
+        existing = self._cache.get(session_id)
+        if existing is not None:
+            return existing
+        stub = SshSession(
+            id=session_id, host="", user="", port=22, via_vpn=False,
+            expires_at=dt.datetime.now(dt.timezone.utc) + dt.timedelta(days=365),
+            transport=self,
+        )
+        self._cache[session_id] = stub
+        return stub
+
+    # ---- SshTransport implementation -------------------------------------
+
+    def run_on_session(self, session_id: str, command: str) -> SshRunResult:
+        gateway_result = self._client.request_action(
+            action_type="admin", tool="ssh.run",
+            payload={"session_id": session_id, "command": command},
+        )
+        if gateway_result.status == "BLOCKED":
+            raise RuntimeError(f"ssh.run blocked: {gateway_result.message}")
+        final = self._client.await_result(gateway_result.request_id)
+        if final.status == "DENIED":
+            raise ApprovalDeniedError(gateway_result.request_id, final.error)
+        if final.status == "EXPIRED":
+            raise ApprovalTimeoutError(gateway_result.request_id, 0)
+        if final.status == "FAILED":
+            raise RuntimeError(f"ssh.run failed: {final.error}")
+        r = final.result or {}
+        return SshRunResult(
+            stdout=str(r.get("stdout", "")),
+            stderr=str(r.get("stderr", "")),
+            exit_code=None if r.get("exit_code") is None else int(r["exit_code"]),
+            signal=None if r.get("signal") is None else str(r["signal"]),
+            truncated=bool(r.get("truncated", False)),
+            duration_ms=int(r.get("duration_ms", 0)),
+        )
+
+    def close_session(self, session_id: str) -> None:
+        try:
+            gateway_result = self._client.request_action(
+                action_type="admin", tool="ssh.close",
+                payload={"session_id": session_id},
+            )
+            if gateway_result.status == "BLOCKED":
+                return
+            self._client.await_result(gateway_result.request_id)
+        except Exception:
+            # close() must be idempotent
+            pass
+
+    def forget_session(self, session_id: str) -> None:
+        self._cache.pop(session_id, None)
+
+
+class _SshMixin(_BaseClient):
+    """Adds ``client.ssh`` namespace. Lazily constructed on first access."""
+    _ssh: Optional[SshNamespace] = None
+
+    @property
+    def ssh(self) -> SshNamespace:
+        if self._ssh is None:
+            self._ssh = SshNamespace(self)
+        return self._ssh

agentlock_sdk-0.2.0.dist-info/METADATA

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: agentlock-sdk
+Version: 0.2.0
+Summary: AgentLock Python SDK for AI agent integration
+License: MIT
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: all
+Requires-Dist: cryptography>=43.0.0; extra == 'all'
+Requires-Dist: pynacl>=1.5.0; extra == 'all'
+Provides-Extra: cryptography
+Requires-Dist: cryptography>=43.0.0; extra == 'cryptography'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Provides-Extra: nacl
+Requires-Dist: pynacl>=1.5.0; extra == 'nacl'
+Description-Content-Type: text/markdown
+
+# agentlock-sdk (Python)
+
+Python SDK for integrating AI agents with AgentLock.
+
+## Installation
+
+```bash
+pip install agentlock-sdk
+# or with poetry:
+poetry add agentlock-sdk
+```
+
+## Quick Start
+
+```python
+from agentlock import AgentLockClient, generate_keypair
+
+# Generate once
+keypair = generate_keypair()
+print("Public key (register in dashboard):", keypair.public_key)
+
+# Create client
+client = AgentLockClient(
+    base_url="https://your-agentlock.vercel.app",
+    agent_id="your-agent-id",
+    private_key=keypair.private_key,  # or load from env
+)
+
+# Request an action
+result = client.request_action(
+    action_type="write",
+    tool="demo",
+    payload={"message": "Hello from Python!"},
+)
+
+print(result.decision)  # ALLOW | REQUIRE_APPROVAL | BLOCK
+
+if result.status == "PENDING":
+    final = client.await_result(result.request_id)
+    print(final)
+```
+
+## SDK Implementation
+
+See `src/agentlock/client.py` for the full implementation.
+Uses `pynacl` for Ed25519 signing.
+
+## SSH sessions
+
+```python
+with client.ssh.open(credential_id="cred-1") as session:
+    print(session.run("uname -a").stdout)
+    print(session.run("uptime").stdout)
+# auto-closes
+```
+
+Re-attach to an existing session:
+
+```python
+sessions = client.ssh.list()
+ops = next((s for s in sessions if s.host == "ops-prod-01"), None)
+if ops:
+    print(ops.run("tail -n 50 /var/log/nginx/access.log").stdout)
+```
+
+## Browser snapshot
+
+```python
+snap = client.browser_snapshot(session_id)
+# {"html": ..., "url": ..., "title": ..., "screenshot": ... (optional)}
+```
+
+## HTTP requests
+
+```python
+res = client.http_request(
+    method="POST",
+    url="https://api.example.com/items",
+    body={"name": "x"},
+    credential_id="cred-api",
+)
+# {"status": 201, "headers": {...}, "body": {...}, "duration_ms": 42}
+```

agentlock_sdk-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+agentlock/__init__.py,sha256=eC_Q2BXxx7m6xBPZeMj6ToyDYg-NLtr3QHT92Q1b6xw,1007
+agentlock/_base.py,sha256=oXFrvAU38MIk3evv78q7wOOQ07erdrqiogNw_roEADE,3525
+agentlock/browser.py,sha256=AHP0fqJkJnG8qG-P4QyH9TpAdzNzGWh5XwcyVaCMyUQ,4637
+agentlock/client.py,sha256=lqvC6KWkaCGBCKiTNY8c2TKFCTZpQ8qc6WI7rzNr0Ok,2362
+agentlock/errors.py,sha256=-AhyQwaTjhY2inZ4zu9P940kj-2NBpRTayv2moj5v18,1361
+agentlock/http.py,sha256=kDPZn6zZ6eHHKrK2mRXr6WwBP6_PuDfTnl2EfWRzNek,2143
+agentlock/mcp.py,sha256=8-sgXRP1lV85uxMoONeP_1kPH__5hHs2mattMZHotWY,3235
+agentlock/messaging.py,sha256=WNsdvXCrS7wE-11CTP6vHDTXj0tm9KlkXBmRwOW13n0,9964
+agentlock/signing.py,sha256=Faxum7luIa5D7dPvdgdOjM-cPPELTmWf4DZQWp5u75k,4370
+agentlock/ssh.py,sha256=KQwAGkK6pjugoBIU1T1ILo42PW-5NIKug4uu-OHfq-U,9636
+agentlock_sdk-0.2.0.dist-info/METADATA,sha256=2lFHlQ-YXbT6WvwfnIB4a8xBJkGaAdJasqODVfBispk,2393
+agentlock_sdk-0.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+agentlock_sdk-0.2.0.dist-info/RECORD,,

agentlock_sdk-0.2.0.dist-info/WHEEL

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