agentlock-sdk 0.2.0__tar.gz

agentlock_sdk-0.2.0/.gitignore

@@ -0,0 +1,65 @@
+node_modules
+.next
+dist
+.env
+.env.local
+.env.*.local
+.turbo
+.cache
+.pnpm-store
+*.tsbuildinfo
+*.log
+.DS_Store
+.expo
+android
+ios
+
+# Sensitive credential files — never commit
+credentials.json
+/credentials/
+*.jks
+*.keystore
+*.pem
+*.p8
+*.p12
+*.pfx
+TESTDATEN.txt
+
+# Claude Code local settings (may contain command history with secrets)
+.claude/
+
+# Playwright MCP screenshots (may contain sensitive UI state)
+.playwright-mcp/
+
+# Playwright test run artifacts
+test-results/
+playwright-report/
+
+# Test scripts with hardcoded keys — never commit
+test-flow.mjs
+test-gateway.mjs
+packages/shared/test-gateway.mjs
+packages/shared/test-*.mjs
+packages/shared/sign-*.mjs
+packages/shared/e2e-ssh-test.mjs
+scripts/e2e-ssh-test.mjs
+
+# Throwaway working dir for E2E scratch files (signed requests, ed25519 keys)
+tmp/
+/tmp/
+
+# superpowers brainstorm artifacts (server PIDs, HTML prototypes)
+.superpowers/
+
+# Python bytecode cache
+__pycache__/
+*.pyc
+
+# Name-clash backup files (Windows duplicate-save format)
+*# Name clash *#*
+
+# Stray root-level test screenshots and placeholder configs
+/test-*.png
+/app.json
+graphify-out/
+.graphify_*

agentlock_sdk-0.2.0/PKG-INFO

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

@@ -0,0 +1,83 @@
+# 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/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentlock-sdk"
+version = "0.2.0"
+description = "AgentLock Python SDK for AI agent integration"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+dependencies = [
+  "httpx>=0.27.0",
+]
+
+[project.optional-dependencies]
+nacl = ["pynacl>=1.5.0"]
+cryptography = ["cryptography>=43.0.0"]
+all = ["pynacl>=1.5.0", "cryptography>=43.0.0"]
+dev = ["pytest>=8.0.0", "pytest-asyncio>=0.24.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentlock"]

agentlock_sdk-0.2.0/src/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_sdk-0.2.0/src/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_sdk-0.2.0/src/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_sdk-0.2.0/src/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_sdk-0.2.0/src/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")