personalclaw-client 0.1.0__tar.gz

personalclaw_client-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: personalclaw-client
+Version: 0.1.0
+Summary: PersonalClaw Client — async Python client for the PersonalClaw Gateway
+Author: PersonalClaw contributors
+License: MIT
+Project-URL: Homepage, https://personalclaw.dev
+Project-URL: Documentation, https://github.com/PersonalClaw/PersonalClaw/tree/main/docs
+Project-URL: Source, https://github.com/PersonalClaw/PersonalClaw
+Project-URL: Issues, https://github.com/PersonalClaw/PersonalClaw/issues
+Keywords: personalclaw,client,ai,agent,gateway
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp>=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: hypothesis>=6.0; extra == "dev"
+Requires-Dist: aiohttp; extra == "dev"
+
+# personalclaw-client
+
+An async Python client for the [PersonalClaw](https://personalclaw.dev) Gateway.
+
+`personalclaw-client` is the small, dependency-light library that apps and
+external tools use to talk to a running PersonalClaw gateway — send messages,
+read status, resolve an app's data directory — without vendoring the core
+package. It is versioned and published independently of the core gateway so a
+tool can pin a stable client contract.
+
+## Install
+
+```sh
+pip install personalclaw-client
+# or
+uv pip install personalclaw-client
+```
+
+## Usage
+
+```python
+from personalclaw_client import PersonalClawClient
+
+async with PersonalClawClient(app_name="my-app") as pc:
+    ok = await pc.ping()
+    status = await pc.get_status()
+    await pc.send_message("session-1", "hello")
+```
+
+## Errors
+
+Client calls raise `PersonalClawError` (with a machine-readable `ErrorCode`) on
+gateway/transport failures — catch it to distinguish "gateway unreachable" from
+"bad request".
+
+## Links
+
+- Homepage: https://personalclaw.dev
+- Source & issues: https://github.com/PersonalClaw/PersonalClaw
+- License: MIT

personalclaw_client-0.1.0/README.md

@@ -0,0 +1,40 @@
+# personalclaw-client
+
+An async Python client for the [PersonalClaw](https://personalclaw.dev) Gateway.
+
+`personalclaw-client` is the small, dependency-light library that apps and
+external tools use to talk to a running PersonalClaw gateway — send messages,
+read status, resolve an app's data directory — without vendoring the core
+package. It is versioned and published independently of the core gateway so a
+tool can pin a stable client contract.
+
+## Install
+
+```sh
+pip install personalclaw-client
+# or
+uv pip install personalclaw-client
+```
+
+## Usage
+
+```python
+from personalclaw_client import PersonalClawClient
+
+async with PersonalClawClient(app_name="my-app") as pc:
+    ok = await pc.ping()
+    status = await pc.get_status()
+    await pc.send_message("session-1", "hello")
+```
+
+## Errors
+
+Client calls raise `PersonalClawError` (with a machine-readable `ErrorCode`) on
+gateway/transport failures — catch it to distinguish "gateway unreachable" from
+"bad request".
+
+## Links
+
+- Homepage: https://personalclaw.dev
+- Source & issues: https://github.com/PersonalClaw/PersonalClaw
+- License: MIT

personalclaw_client-0.1.0/personalclaw_client/__init__.py

@@ -0,0 +1,15 @@
+"""personalclaw-client — async Python client for the PersonalClaw Gateway.
+
+Usage::
+
+    from personalclaw_client import PersonalClawClient
+
+    async with PersonalClawClient(app_name="my-app") as mc:
+        ok = await mc.ping()
+        status = await mc.get_status()
+        await mc.send_message("session-1", "hello")
+"""
+from personalclaw_client.client import PersonalClawClient
+from personalclaw_client.errors import PersonalClawError, ErrorCode
+
+__all__ = ["PersonalClawClient", "PersonalClawError", "ErrorCode"]

personalclaw_client-0.1.0/personalclaw_client/client.py

@@ -0,0 +1,483 @@
+"""PersonalClawClient — async Python client for the PersonalClaw Gateway.
+
+Standalone package (no dependency on backend main package).
+Uses aiohttp for HTTP communication.
+
+Mirrors the TypeScript @personalclaw/client API surface.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import math
+import os
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Awaitable
+
+import aiohttp
+
+from personalclaw_client.errors import PersonalClawError, ErrorCode, http_error
+
+logger = logging.getLogger(__name__)
+
+# Single source of truth for this client's default port. Mirrors the gateway's
+# config.loader._DEFAULT_PORT (this package ships standalone and can't import it).
+_DEFAULT_PORT = 10000
+_DEFAULT_BASE_URL = f"http://localhost:{_DEFAULT_PORT}"
+_DEFAULT_TIMEOUT = 30
+_DEFAULT_MAX_RETRIES = 3
+_DEFAULT_RETRY_BASE_DELAY = 1.0  # seconds
+_MAX_BACKOFF = 30.0
+_DEFAULT_MESSAGE_LIMIT = 40_000
+_CONTEXT_BUFFER_LIMIT = 50
+
+_LOOPBACK_HOSTS = frozenset({"localhost", "127.0.0.1", "::1", "[::1]"})
+
+
+def _is_loopback(url: str) -> bool:
+    try:
+        from urllib.parse import urlparse
+        return urlparse(url).hostname in _LOOPBACK_HOSTS
+    except Exception:
+        return False
+
+
+def _compute_backoff(attempt: int, base_delay: float) -> float:
+    return min(base_delay * (2 ** attempt), _MAX_BACKOFF)
+
+
+def _read_app_secret(app_name: str) -> str:
+    """Read the per-app secret from disk. Returns empty string if unavailable."""
+    home = os.environ.get("PERSONALCLAW_HOME", str(Path.home() / ".personalclaw"))
+    secret_path = Path(home) / "apps" / app_name / ".app_secret"
+    try:
+        return secret_path.read_text(encoding="utf-8").strip()
+    except (OSError, FileNotFoundError):
+        return ""
+
+
+async def _exchange_app_token(base_url: str, app_name: str, secret: str) -> str:
+    """Exchange an app secret for an app-scoped token via the Gateway."""
+    async with aiohttp.ClientSession() as session:
+        async with session.post(
+            f"{base_url}/api/apps/{app_name}/token",
+            headers={"X-App-Secret": secret, "Content-Type": "application/json"},
+        ) as resp:
+            if not resp.ok:
+                raise PersonalClawError(
+                    ErrorCode.AUTH_EXPIRED,
+                    f"App token exchange failed: HTTP {resp.status}",
+                    status=resp.status,
+                )
+            data = await resp.json()
+            return str(data.get("token", ""))
+
+
+@dataclass
+class ContextEntry:
+    content: str
+    source: str | None = None
+    ephemeral: bool = True
+    max_age: float | None = None  # seconds
+    injected_at: float = field(default_factory=time.time)
+
+
+class PersonalClawClient:
+    """Async HTTP client for the PersonalClaw Gateway.
+
+    Usage::
+
+        async with PersonalClawClient(app_name="my-app") as mc:
+            ok = await mc.ping()
+            slots = await mc.list_sessions()
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str = "",
+        token: str = "",
+        app_name: str = "",
+        timeout: int = _DEFAULT_TIMEOUT,
+        max_retries: int = _DEFAULT_MAX_RETRIES,
+        retry_base_delay: float = _DEFAULT_RETRY_BASE_DELAY,
+        message_length_limit: int = _DEFAULT_MESSAGE_LIMIT,
+        on_auth_expired: Callable[[], Awaitable[str]] | None = None,
+    ):
+        port = os.environ.get("PERSONALCLAW_PORT", str(_DEFAULT_PORT))
+        self.base_url = (base_url or f"http://localhost:{port}").rstrip("/")
+        self.token = token
+        self.app_name = app_name
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.retry_base_delay = retry_base_delay
+        self.message_length_limit = message_length_limit
+        self._session: aiohttp.ClientSession | None = None
+        self._pending_buffer: list[ContextEntry] = []
+        self._default_session: str | None = None
+
+        # Auto-token: if app_name is set and no explicit auth, read secret
+        self._app_secret = ""
+        has_explicit_auth = bool(token or on_auth_expired)
+        if app_name and not has_explicit_auth:
+            self._app_secret = _read_app_secret(app_name)
+
+        if self._app_secret and not on_auth_expired:
+            self._on_auth_expired = self._auto_refresh_token
+        else:
+            self._on_auth_expired = on_auth_expired
+
+    async def _auto_refresh_token(self) -> str:
+        """Exchange the on-disk app secret for a fresh token."""
+        return await _exchange_app_token(self.base_url, self.app_name, self._app_secret)
+
+    async def authenticate(self) -> bool:
+        """Bootstrap app auth by exchanging the on-disk secret for a token.
+
+        Call once after construction if no explicit token was provided.
+        No-op if the client already has a token or no app secret is available.
+        """
+        if self.token or not self._app_secret or not self.app_name:
+            return True
+        try:
+            self.token = await _exchange_app_token(
+                self.base_url, self.app_name, self._app_secret
+            )
+            return True
+        except Exception:
+            return False
+
+    async def __aenter__(self) -> PersonalClawClient:
+        self._session = aiohttp.ClientSession(
+            timeout=aiohttp.ClientTimeout(total=self.timeout),
+        )
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        if self._session:
+            await self._session.close()
+            self._session = None
+
+    def _ensure_session(self) -> aiohttp.ClientSession:
+        if not self._session:
+            self._session = aiohttp.ClientSession(
+                timeout=aiohttp.ClientTimeout(total=self.timeout),
+            )
+        return self._session
+
+    def _auth_headers(self) -> dict[str, str]:
+        headers: dict[str, str] = {"Content-Type": "application/json"}
+        if self.token:
+            headers["Cookie"] = f"pc_token={self.token}"
+        return headers
+
+    def _check_auth(self) -> None:
+        if not self.token and not _is_loopback(self.base_url):
+            raise PersonalClawError(
+                ErrorCode.AUTH_REQUIRED,
+                "Auth token required for remote Gateway connections",
+            )
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        body: Any = None,
+    ) -> Any:
+        """Core request with retry logic."""
+        self._check_auth()
+        session = self._ensure_session()
+        url = f"{self.base_url}{path}"
+        last_error: PersonalClawError | None = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                kwargs: dict[str, Any] = {"headers": self._auth_headers()}
+                if body is not None:
+                    kwargs["json"] = body
+
+                async with session.request(method, url, **kwargs) as resp:
+                    # Auth expired — try refresh once
+                    if resp.status in (401, 403) and self._on_auth_expired and attempt == 0:
+                        try:
+                            self.token = await self._on_auth_expired()
+                            continue
+                        except Exception:
+                            pass
+
+                    if resp.ok:
+                        ct = resp.headers.get("content-type", "")
+                        if "application/json" in ct:
+                            return await resp.json()
+                        return {}
+
+                    # Non-retryable 4xx (except 429)
+                    if 400 <= resp.status < 500 and resp.status != 429:
+                        text = await resp.text()
+                        raise http_error(resp.status, text or None)
+
+                    # Retryable
+                    text = await resp.text()
+                    last_error = http_error(resp.status, text or None)
+
+                    if attempt < self.max_retries:
+                        if resp.status == 429:
+                            retry_after = resp.headers.get("Retry-After")
+                            try:
+                                delay = float(retry_after) if retry_after else _compute_backoff(attempt, self.retry_base_delay)
+                            except (ValueError, TypeError):
+                                delay = _compute_backoff(attempt, self.retry_base_delay)
+                        else:
+                            delay = _compute_backoff(attempt, self.retry_base_delay)
+                        await asyncio.sleep(delay)
+
+            except PersonalClawError as e:
+                # Non-retryable errors (4xx except 429) were raised directly
+                # above — re-raise them immediately. Retryable errors (5xx,
+                # 429) are stored in last_error and fall through to the
+                # backoff sleep, so they never reach this branch.
+                raise
+            except Exception as exc:
+                last_error = PersonalClawError(
+                    ErrorCode.NETWORK_ERROR,
+                    str(exc),
+                )
+                if attempt < self.max_retries:
+                    await asyncio.sleep(_compute_backoff(attempt, self.retry_base_delay))
+
+        raise last_error or PersonalClawError(ErrorCode.NETWORK_ERROR, "Request failed")
+
+    async def _get(self, path: str) -> Any:
+        return await self._request("GET", path)
+
+    async def _post(self, path: str, body: Any = None) -> Any:
+        return await self._request("POST", path, body)
+
+    async def _put(self, path: str, body: Any = None) -> Any:
+        return await self._request("PUT", path, body)
+
+    async def _delete(self, path: str) -> Any:
+        return await self._request("DELETE", path)
+
+    # ── Connection ──
+
+    async def ping(self) -> bool:
+        try:
+            await self._get("/api/status")
+            return True
+        except Exception:
+            return False
+
+    async def get_status(self) -> dict[str, Any]:
+        return await self._get("/api/status")
+
+    async def get_system_info(self) -> dict[str, Any]:
+        return await self._get("/api/system")
+
+    # ── Sessions ──
+
+    async def create_session(self, name: str, agent: str = "") -> dict[str, Any]:
+        body: dict[str, str] = {"name": name}
+        if agent:
+            body["agent"] = agent
+        return await self._post("/api/chat/sessions", body)
+
+    async def list_sessions(self) -> list[dict[str, Any]]:
+        result = await self._get("/api/chat/sessions")
+        return result if isinstance(result, list) else []
+
+    async def delete_session(self, session_id: str) -> None:
+        await self._delete(f"/api/chat/sessions/{session_id}")
+
+    async def send_message(self, session_id: str, message: str) -> None:
+        if len(message) > self.message_length_limit:
+            raise PersonalClawError(
+                ErrorCode.VALIDATION_ERROR,
+                f"Message length {len(message)} exceeds limit {self.message_length_limit}",
+            )
+        if self._default_session and session_id == self._default_session and self._pending_buffer:
+            await self.flush_pending_context(session_id)
+        await self._post("/api/chat", {"message": message, "session": session_id})
+
+    # ── Subagents ──
+
+    async def spawn(self, task: str, agent: str = "") -> str:
+        body: dict[str, str] = {"task": task}
+        if agent:
+            body["agent"] = agent
+        result = await self._post("/api/spawn", body)
+        return str(result.get("id", ""))
+
+    async def spawn_many(self, tasks: list[str], agents: list[str] | None = None) -> list[str]:
+        
+        coros = [
+            self.spawn(task, agents[i] if agents and i < len(agents) else "")
+            for i, task in enumerate(tasks)
+        ]
+        return list(await asyncio.gather(*coros))
+
+    async def list_subagents(self) -> list[dict[str, Any]]:
+        result = await self._get("/api/spawn")
+        return result if isinstance(result, list) else []
+
+    async def get_subagent_status(self, agent_id: str) -> dict[str, Any]:
+        return await self._get(f"/api/spawn/{agent_id}")
+
+    # ── Cron ──
+
+    async def add_cron(self, name: str, **options: Any) -> dict[str, Any]:
+        return await self._post("/api/crons", {"name": name, **options})
+
+    async def list_crons(self) -> list[dict[str, Any]]:
+        result = await self._get("/api/crons")
+        return result if isinstance(result, list) else []
+
+    async def update_cron(self, job_id: str, **options: Any) -> dict[str, Any]:
+        return await self._put(f"/api/crons/{job_id}", options)
+
+    async def remove_cron(self, job_id: str) -> None:
+        await self._delete(f"/api/crons/{job_id}")
+
+    async def pause_cron(self, job_id: str) -> None:
+        await self._post(f"/api/crons/{job_id}/enable", {"enabled": False})
+
+    async def resume_cron(self, job_id: str) -> None:
+        await self._post(f"/api/crons/{job_id}/enable", {"enabled": True})
+
+    # ── Lessons ──
+
+    async def add_lesson(self, rule: str, category: str, scope: str = "") -> None:
+        await self._post("/api/lessons", {"rule": rule, "category": category, "scope": scope})
+
+    async def list_lessons(self) -> list[dict[str, Any]]:
+        result = await self._get("/api/lessons")
+        return result if isinstance(result, list) else []
+
+    async def remove_lesson(self, query: str) -> None:
+        await self._delete_with_body("/api/lessons", {"rule": query})
+
+    async def _delete_with_body(self, path: str, body: Any) -> Any:
+        return await self._request("DELETE", path, body)
+
+    # ── Messages ──
+
+    async def send_notification(self, text: str, **options: Any) -> None:
+        if len(text) > self.message_length_limit:
+            raise PersonalClawError(
+                ErrorCode.VALIDATION_ERROR,
+                f"Message length {len(text)} exceeds limit {self.message_length_limit}",
+            )
+        await self._post("/api/send-message", {"text": text, **options})
+
+    # ── MCP Servers ──
+
+    async def list_mcp_servers(self) -> list[dict[str, Any]]:
+        result = await self._get("/api/mcp/servers")
+        return result if isinstance(result, list) else []
+
+    async def register_mcp_server(
+        self, name: str, command: str, args: list[str] | None = None, env: dict[str, str] | None = None,
+    ) -> None:
+        if not name or not command:
+            raise PersonalClawError(ErrorCode.VALIDATION_ERROR, "MCP server requires name and command")
+        body: dict[str, Any] = {"command": command}
+        if args:
+            body["args"] = args
+        if env:
+            body["env"] = env
+        await self._put(f"/api/mcp/servers/{name}", body)
+
+    async def remove_mcp_server(self, name: str) -> None:
+        await self._delete(f"/api/mcp/servers/{name}")
+
+    # ── Agent Runtime ──
+
+    async def dispatch_agent(self, agent: str, prompt: str) -> dict[str, Any]:
+        return await self._post("/api/chat", {"message": prompt, "agent": agent, "app": self.app_name})
+
+    async def dispatch_agent_async(self, agent: str, prompt: str) -> str:
+        result = await self._post("/api/spawn", {"task": prompt, "agent": agent})
+        return str(result.get("id", ""))
+
+    async def get_task_result(self, task_id: str) -> dict[str, Any]:
+        return await self._get(f"/api/spawn/{task_id}")
+
+    # ── App Storage ──
+
+    def get_app_data_dir(self) -> Path:
+        home = os.environ.get("PERSONALCLAW_HOME", str(Path.home() / ".personalclaw"))
+        return Path(home) / "apps" / (self.app_name or "unknown") / "data"
+
+    async def get_app_config(self) -> dict[str, Any]:
+        return await self._get(f"/api/apps/{self.app_name}/config")
+
+    async def set_app_config(self, config: dict[str, Any]) -> None:
+        await self._put(f"/api/apps/{self.app_name}/config", config)
+
+    # ── Memory ──
+
+    async def memory_search(self, query: str, top_k: int = 8) -> list[dict[str, Any]]:
+        from urllib.parse import quote
+        result = await self._get(f"/api/memory/episodic/search?q={quote(query)}&top_k={top_k}")
+        return result if isinstance(result, list) else []
+
+    # ── Context Injection ──
+
+    async def inject_context(
+        self,
+        session_id: str | None,
+        content: str,
+        *,
+        source: str | None = None,
+        ephemeral: bool = True,
+        max_age: float | None = None,
+    ) -> None:
+        entry = ContextEntry(
+            content=content, source=source, ephemeral=ephemeral,
+            max_age=max_age, injected_at=time.time(),
+        )
+        if session_id is None:
+            self._pending_buffer.append(entry)
+            if len(self._pending_buffer) > _CONTEXT_BUFFER_LIMIT:
+                self._pending_buffer.pop(0)
+            return
+
+        await self._post(f"/api/chat/sessions/{session_id}/context", {
+            "content": content, "source": source,
+            "ephemeral": ephemeral, "maxAge": max_age,
+        })
+
+    async def flush_pending_context(self, session_id: str) -> None:
+        now = time.time()
+        to_flush = [
+            e for e in self._pending_buffer
+            if e.max_age is None or e.injected_at + e.max_age >= now
+        ]
+        self._pending_buffer.clear()
+        failed: list[Any] = []
+        last_exc: Exception | None = None
+        for entry in to_flush:
+            try:
+                await self._post(f"/api/chat/sessions/{session_id}/context", {
+                    "content": entry.content, "source": entry.source,
+                    "ephemeral": entry.ephemeral, "maxAge": entry.max_age,
+                })
+            except Exception as exc:
+                last_exc = exc
+                failed.append(entry)
+        self._pending_buffer.extend(failed)
+        if last_exc:
+            raise last_exc
+
+    def set_default_session(self, session_id: str) -> None:
+        self._default_session = session_id
+
+    @property
+    def pending_context_count(self) -> int:
+        return len(self._pending_buffer)

personalclaw_client-0.1.0/personalclaw_client/errors.py

@@ -0,0 +1,64 @@
+"""Structured error types for personalclaw-client."""
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+
+class ErrorCode(str, Enum):
+    AUTH_REQUIRED = "AUTH_REQUIRED"
+    AUTH_EXPIRED = "AUTH_EXPIRED"
+    VALIDATION_ERROR = "VALIDATION_ERROR"
+    NOT_FOUND = "NOT_FOUND"
+    RATE_LIMITED = "RATE_LIMITED"
+    SERVER_ERROR = "SERVER_ERROR"
+    NETWORK_ERROR = "NETWORK_ERROR"
+
+
+class PersonalClawError(Exception):
+    """Structured error with code, message, status, and optional body."""
+
+    def __init__(
+        self,
+        code: ErrorCode | str,
+        message: str,
+        status: int | None = None,
+        body: Any = None,
+    ):
+        super().__init__(message)
+        self.code = ErrorCode(code) if isinstance(code, str) else code
+        self.status = status
+        self.body = body
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {"code": self.code.value, "message": str(self)}
+        if self.status is not None:
+            d["status"] = self.status
+        if self.body is not None:
+            d["body"] = self.body
+        return d
+
+
+def http_status_to_code(status: int) -> ErrorCode:
+    if status == 401:
+        return ErrorCode.AUTH_EXPIRED
+    if status == 403:
+        return ErrorCode.AUTH_EXPIRED
+    if status == 404:
+        return ErrorCode.NOT_FOUND
+    if status == 429:
+        return ErrorCode.RATE_LIMITED
+    if status >= 500:
+        return ErrorCode.SERVER_ERROR
+    return ErrorCode.VALIDATION_ERROR
+
+
+def http_error(status: int, body: Any = None) -> PersonalClawError:
+    code = http_status_to_code(status)
+    if isinstance(body, str):
+        message = body
+    elif isinstance(body, dict) and "error" in body:
+        message = str(body["error"])
+    else:
+        message = f"HTTP {status}"
+    return PersonalClawError(code, message, status=status, body=body)

personalclaw_client-0.1.0/personalclaw_client.egg-info/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: personalclaw-client
+Version: 0.1.0
+Summary: PersonalClaw Client — async Python client for the PersonalClaw Gateway
+Author: PersonalClaw contributors
+License: MIT
+Project-URL: Homepage, https://personalclaw.dev
+Project-URL: Documentation, https://github.com/PersonalClaw/PersonalClaw/tree/main/docs
+Project-URL: Source, https://github.com/PersonalClaw/PersonalClaw
+Project-URL: Issues, https://github.com/PersonalClaw/PersonalClaw/issues
+Keywords: personalclaw,client,ai,agent,gateway
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp>=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: hypothesis>=6.0; extra == "dev"
+Requires-Dist: aiohttp; extra == "dev"
+
+# personalclaw-client
+
+An async Python client for the [PersonalClaw](https://personalclaw.dev) Gateway.
+
+`personalclaw-client` is the small, dependency-light library that apps and
+external tools use to talk to a running PersonalClaw gateway — send messages,
+read status, resolve an app's data directory — without vendoring the core
+package. It is versioned and published independently of the core gateway so a
+tool can pin a stable client contract.
+
+## Install
+
+```sh
+pip install personalclaw-client
+# or
+uv pip install personalclaw-client
+```
+
+## Usage
+
+```python
+from personalclaw_client import PersonalClawClient
+
+async with PersonalClawClient(app_name="my-app") as pc:
+    ok = await pc.ping()
+    status = await pc.get_status()
+    await pc.send_message("session-1", "hello")
+```
+
+## Errors
+
+Client calls raise `PersonalClawError` (with a machine-readable `ErrorCode`) on
+gateway/transport failures — catch it to distinguish "gateway unreachable" from
+"bad request".
+
+## Links
+
+- Homepage: https://personalclaw.dev
+- Source & issues: https://github.com/PersonalClaw/PersonalClaw
+- License: MIT

personalclaw_client-0.1.0/personalclaw_client.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+personalclaw_client/__init__.py
+personalclaw_client/client.py
+personalclaw_client/errors.py
+personalclaw_client.egg-info/PKG-INFO
+personalclaw_client.egg-info/SOURCES.txt
+personalclaw_client.egg-info/dependency_links.txt
+personalclaw_client.egg-info/requires.txt
+personalclaw_client.egg-info/top_level.txt
+tests/test_client.py

personalclaw_client-0.1.0/personalclaw_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

personalclaw_client-0.1.0/personalclaw_client.egg-info/requires.txt

@@ -0,0 +1,7 @@
+aiohttp>=3.9
+
+[dev]
+pytest>=8.0
+pytest-asyncio>=0.23
+hypothesis>=6.0
+aiohttp

personalclaw_client-0.1.0/personalclaw_client.egg-info/top_level.txt

@@ -0,0 +1 @@
+personalclaw_client

personalclaw_client-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "personalclaw-client"
+version = "0.1.0"
+description = "PersonalClaw Client — async Python client for the PersonalClaw Gateway"
+readme = "README.md"
+license = { text = "MIT" }
+# Deliberately broader than core (>=3.12): the client is a thin, dependency-light
+# library meant to be embeddable in tools on older interpreters.
+requires-python = ">=3.9"
+
+authors = [
+    { name = "PersonalClaw contributors" },
+]
+
+keywords = ["personalclaw", "client", "ai", "agent", "gateway"]
+
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries",
+    "Framework :: AsyncIO",
+]
+
+dependencies = ["aiohttp>=3.9"]
+
+# NOTE: [project.urls] MUST come after the bare `dependencies` key — a table
+# header placed earlier would absorb `dependencies` into the urls table (a TOML
+# table runs until the next header), zeroing the runtime deps. (Same footgun
+# fixed in the core pyproject, plan 34 T1.1.)
+[project.urls]
+Homepage      = "https://personalclaw.dev"
+Documentation = "https://github.com/PersonalClaw/PersonalClaw/tree/main/docs"
+Source        = "https://github.com/PersonalClaw/PersonalClaw"
+Issues        = "https://github.com/PersonalClaw/PersonalClaw/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "hypothesis>=6.0", "aiohttp"]
+
+[tool.setuptools.packages.find]
+include = ["personalclaw_client*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

personalclaw_client-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

personalclaw_client-0.1.0/tests/test_client.py

@@ -0,0 +1,124 @@
+"""Tests for personalclaw_client — mirrors TS @personalclaw/client test coverage."""
+from __future__ import annotations
+
+import pytest
+
+from personalclaw_client import PersonalClawClient, PersonalClawError
+from personalclaw_client.errors import ErrorCode, http_status_to_code, http_error
+
+
+class TestErrors:
+    def test_5xx_maps_to_server_error(self):
+        for status in (500, 502, 503):
+            assert http_status_to_code(status) == ErrorCode.SERVER_ERROR
+
+    def test_429_maps_to_rate_limited(self):
+        assert http_status_to_code(429) == ErrorCode.RATE_LIMITED
+
+    def test_404_maps_to_not_found(self):
+        assert http_status_to_code(404) == ErrorCode.NOT_FOUND
+
+    def test_401_maps_to_auth_expired(self):
+        assert http_status_to_code(401) == ErrorCode.AUTH_EXPIRED
+
+    def test_4xx_non_retryable(self):
+        for status in (400, 403, 404, 405, 422):
+            code = http_status_to_code(status)
+            assert code not in (ErrorCode.SERVER_ERROR, ErrorCode.RATE_LIMITED)
+
+    def test_http_error_has_code_and_message(self):
+        err = http_error(500, "internal error")
+        assert err.code == ErrorCode.SERVER_ERROR
+        assert "internal error" in str(err)
+        assert err.status == 500
+
+    def test_to_dict(self):
+        err = PersonalClawError(ErrorCode.NOT_FOUND, "not found", status=404)
+        d = err.to_dict()
+        assert d["code"] == "NOT_FOUND"
+        assert d["message"] == "not found"
+        assert d["status"] == 404
+
+
+class TestAuthCheck:
+    def test_localhost_no_token_ok(self):
+        pc = PersonalClawClient(base_url="http://localhost:7777")
+        # Should not raise on construction
+        assert pc.base_url == "http://localhost:7777"
+
+    def test_remote_no_token_raises(self):
+        pc = PersonalClawClient(base_url="http://example.com:7777")
+        with pytest.raises(PersonalClawError) as exc_info:
+            pc._check_auth()
+        assert exc_info.value.code == ErrorCode.AUTH_REQUIRED
+
+    def test_remote_with_token_ok(self):
+        pc = PersonalClawClient(base_url="http://example.com:7777", token="test")
+        pc._check_auth()  # should not raise
+
+
+class TestMessageValidation:
+    @pytest.mark.asyncio
+    async def test_rejects_long_message(self):
+        pc = PersonalClawClient(message_length_limit=100)
+        with pytest.raises(PersonalClawError) as exc_info:
+            await pc.send_message("session-1", "x" * 101)
+        assert exc_info.value.code == ErrorCode.VALIDATION_ERROR
+
+    @pytest.mark.asyncio
+    async def test_rejects_long_notification(self):
+        pc = PersonalClawClient(message_length_limit=100)
+        with pytest.raises(PersonalClawError) as exc_info:
+            await pc.send_notification("x" * 101)
+        assert exc_info.value.code == ErrorCode.VALIDATION_ERROR
+
+
+class TestMcpValidation:
+    @pytest.mark.asyncio
+    async def test_rejects_empty_name(self):
+        pc = PersonalClawClient()
+        with pytest.raises(PersonalClawError) as exc_info:
+            await pc.register_mcp_server("", "node server.js")
+        assert exc_info.value.code == ErrorCode.VALIDATION_ERROR
+
+    @pytest.mark.asyncio
+    async def test_rejects_empty_command(self):
+        pc = PersonalClawClient()
+        with pytest.raises(PersonalClawError) as exc_info:
+            await pc.register_mcp_server("my-server", "")
+        assert exc_info.value.code == ErrorCode.VALIDATION_ERROR
+
+
+class TestContextBuffer:
+    @pytest.mark.asyncio
+    async def test_null_session_buffers_locally(self):
+        pc = PersonalClawClient()
+        await pc.inject_context(None, "test content")
+        assert pc.pending_context_count == 1
+
+    @pytest.mark.asyncio
+    async def test_buffer_limit_fifo(self):
+        pc = PersonalClawClient()
+        for i in range(60):
+            await pc.inject_context(None, f"entry-{i}")
+        assert pc.pending_context_count == 50
+
+    @pytest.mark.asyncio
+    async def test_flush_preserves_failed_entries(self):
+        pc = PersonalClawClient(max_retries=0)
+        await pc.inject_context(None, "a")
+        await pc.inject_context(None, "b")
+        assert pc.pending_context_count == 2
+        with pytest.raises(Exception):
+            await pc.flush_pending_context("session-1")
+        # Failed entries preserved for retry
+        assert pc.pending_context_count == 2
+
+
+class TestAppDataDir:
+    def test_contains_app_name(self):
+        pc = PersonalClawClient(app_name="my-tool")
+        d = pc.get_app_data_dir()
+        assert "my-tool" in str(d)
+        assert ".personalclaw" in str(d)
+        assert "apps" in str(d)