daimon-sdk 0.1.0__tar.gz

daimon_sdk-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install package and test dependencies
+        run: python -m pip install --upgrade pip && python -m pip install -e ".[dev]" build
+
+      - name: Run unit tests
+        run: python -m pytest tests/test_unit.py -q
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

daimon_sdk-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.pytest_cache/
+.venv/
+dist/
+build/
+*.egg-info/
+__pycache__/
+.pytest-*

daimon_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: daimon-sdk
+Version: 0.1.0
+Summary: Typed async Python SDK for daimon MCP services.
+Author: processd contributors
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: fastmcp<4,>=3.1.1
+Requires-Dist: httpx<1,>=0.28
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio<1,>=0.24; extra == 'dev'
+Requires-Dist: pytest<9,>=8.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# daimon-sdk
+
+Typed async Python SDK for `processd-mcp`.
+
+`daimon-sdk` wraps the raw MCP tool surface exposed by `processd-mcp` and presents it as grouped Python APIs such as `client.files.read()` and `client.exec.start_session()`. The SDK keeps `processd-standalone` as the contract source of truth and focuses on:
+
+- connection and token wiring
+- typed request/response handling
+- structured tool error mapping
+- interactive session helpers
+- compatibility tests against a real `processd-mcp` binary
+
+## Install
+
+```bash
+pip install daimon-sdk
+```
+
+For local development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```python
+import asyncio
+
+from daimon_sdk import DaimonClient
+
+
+async def main() -> None:
+    async with DaimonClient("http://127.0.0.1:8080/mcp") as client:
+        runtime = await client.runtime.get_context()
+        print(runtime.base_workdir)
+
+        result = await client.files.glob("**/*.rs", path=runtime.base_workdir)
+        print(result.filenames[:5])
+
+        bash = await client.exec.bash("printf 'hello from processd\\n'")
+        print(bash.stdout)
+
+
+asyncio.run(main())
+```
+
+## Raw MCP vs SDK
+
+Raw MCP:
+
+```python
+payload = await mcp_client.call_tool("Read", {"file_path": "/tmp/demo.txt"})
+```
+
+SDK:
+
+```python
+read = await client.files.read("/tmp/demo.txt")
+print(read.file.content)
+```
+
+## API Overview
+
+- `DaimonClient(base_url, access_token=None, timeout_s=30.0)`
+- `await client.connect()` / `await client.close()`
+- `async with DaimonClient(...) as client`
+- `client.runtime.get_context()`
+- `client.files.read() / write() / edit() / glob() / grep()`
+- `client.exec.bash() / start_session()`
+- `SessionHandle.write() / poll() / wait_for_exit() / close()`
+- `client.web.fetch()`
+- `client.raw.call_tool()`
+
+## Local Testing
+
+The SDK compatibility tests expect a sibling checkout of `processd-standalone`:
+
+```text
+e2b-project/
+  processd-standalone/
+  processd-sdk/
+```
+
+Run tests with an environment that already has the dev dependencies installed:
+
+```bash
+PYTHONPATH=src python -m pytest -q
+```
+
+The E2E suite builds and launches `../processd-standalone/target/debug/processd-mcp`.
+
+## Release
+
+Releases are published from GitHub Actions when a tag matching `v*` is pushed.
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The tag version must match `pyproject.toml`'s project version.

daimon_sdk-0.1.0/README.md

@@ -0,0 +1,102 @@
+# daimon-sdk
+
+Typed async Python SDK for `processd-mcp`.
+
+`daimon-sdk` wraps the raw MCP tool surface exposed by `processd-mcp` and presents it as grouped Python APIs such as `client.files.read()` and `client.exec.start_session()`. The SDK keeps `processd-standalone` as the contract source of truth and focuses on:
+
+- connection and token wiring
+- typed request/response handling
+- structured tool error mapping
+- interactive session helpers
+- compatibility tests against a real `processd-mcp` binary
+
+## Install
+
+```bash
+pip install daimon-sdk
+```
+
+For local development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```python
+import asyncio
+
+from daimon_sdk import DaimonClient
+
+
+async def main() -> None:
+    async with DaimonClient("http://127.0.0.1:8080/mcp") as client:
+        runtime = await client.runtime.get_context()
+        print(runtime.base_workdir)
+
+        result = await client.files.glob("**/*.rs", path=runtime.base_workdir)
+        print(result.filenames[:5])
+
+        bash = await client.exec.bash("printf 'hello from processd\\n'")
+        print(bash.stdout)
+
+
+asyncio.run(main())
+```
+
+## Raw MCP vs SDK
+
+Raw MCP:
+
+```python
+payload = await mcp_client.call_tool("Read", {"file_path": "/tmp/demo.txt"})
+```
+
+SDK:
+
+```python
+read = await client.files.read("/tmp/demo.txt")
+print(read.file.content)
+```
+
+## API Overview
+
+- `DaimonClient(base_url, access_token=None, timeout_s=30.0)`
+- `await client.connect()` / `await client.close()`
+- `async with DaimonClient(...) as client`
+- `client.runtime.get_context()`
+- `client.files.read() / write() / edit() / glob() / grep()`
+- `client.exec.bash() / start_session()`
+- `SessionHandle.write() / poll() / wait_for_exit() / close()`
+- `client.web.fetch()`
+- `client.raw.call_tool()`
+
+## Local Testing
+
+The SDK compatibility tests expect a sibling checkout of `processd-standalone`:
+
+```text
+e2b-project/
+  processd-standalone/
+  processd-sdk/
+```
+
+Run tests with an environment that already has the dev dependencies installed:
+
+```bash
+PYTHONPATH=src python -m pytest -q
+```
+
+The E2E suite builds and launches `../processd-standalone/target/debug/processd-mcp`.
+
+## Release
+
+Releases are published from GitHub Actions when a tag matching `v*` is pushed.
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The tag version must match `pyproject.toml`'s project version.

daimon_sdk-0.1.0/examples/auth.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+import asyncio
+import os
+
+from daimon_sdk import DaimonClient
+
+
+async def main() -> None:
+    token = os.environ["PROCESSD_TOKEN"]
+    async with DaimonClient("http://127.0.0.1:8080/mcp", access_token=token) as client:
+        result = await client.exec.exec_command("echo secure", yield_time_ms=200)
+        print(result.output.strip())
+
+
+asyncio.run(main())

daimon_sdk-0.1.0/examples/exec_session.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+import asyncio
+
+from daimon_sdk import DaimonClient
+
+
+async def main() -> None:
+    async with DaimonClient("http://127.0.0.1:8080/mcp") as client:
+        session = await client.exec.start_session("/bin/cat", tty=True, yield_time_ms=100)
+        echoed = await session.write("hello session\n", yield_time_ms=100)
+        print(echoed.output)
+        exited = await session.close(exit_payload="\u0004", yield_time_ms=500)
+        print(exited.exit_code)
+
+
+asyncio.run(main())

daimon_sdk-0.1.0/examples/files.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+from daimon_sdk import DaimonClient
+
+
+async def main() -> None:
+    target = Path("/tmp/daimon-sdk-demo.txt")
+    async with DaimonClient("http://127.0.0.1:8080/mcp") as client:
+        await client.files.edit(str(target), old_string="", new_string="hello from sdk\n")
+        read = await client.files.read(str(target))
+        print(read.file.content)
+        glob = await client.files.glob("*.txt", path=str(target.parent))
+        print(glob.filenames)
+
+
+asyncio.run(main())

daimon_sdk-0.1.0/examples/runtime_and_web.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+import asyncio
+
+from daimon_sdk import DaimonClient
+
+
+async def main() -> None:
+    async with DaimonClient("http://127.0.0.1:8080/mcp") as client:
+        runtime = await client.runtime.get_context()
+        print(runtime.summary)
+
+        page = await client.web.fetch("https://example.com")
+        print(page.status_code, page.result_type)
+
+
+asyncio.run(main())

daimon_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "daimon-sdk"
+version = "0.1.0"
+description = "Typed async Python SDK for daimon MCP services."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [
+  { name = "processd contributors" },
+]
+dependencies = [
+  "fastmcp>=3.1.1,<4",
+  "httpx>=0.28,<1",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.3,<9",
+  "pytest-asyncio>=0.24,<1",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/daimon_sdk"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+python_files = ["test_*.py"]

daimon_sdk-0.1.0/src/daimon_sdk/__init__.py

@@ -0,0 +1,35 @@
+from .client import DaimonClient
+from .exceptions import (
+    DaimonConnectionError,
+    DaimonError,
+    DaimonProtocolError,
+    DaimonToolError,
+)
+from .models import (
+    BashResult,
+    EditResult,
+    ExecResult,
+    GlobResult,
+    GrepResult,
+    RuntimeContextResult,
+    SessionHandle,
+    WebFetchResult,
+    WriteResult,
+)
+
+__all__ = [
+    "BashResult",
+    "EditResult",
+    "ExecResult",
+    "GlobResult",
+    "GrepResult",
+    "DaimonClient",
+    "DaimonConnectionError",
+    "DaimonError",
+    "DaimonProtocolError",
+    "DaimonToolError",
+    "RuntimeContextResult",
+    "SessionHandle",
+    "WebFetchResult",
+    "WriteResult",
+]

daimon_sdk-0.1.0/src/daimon_sdk/_transport.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+from fastmcp import Client
+from fastmcp.client.transports import StreamableHttpTransport
+
+from .exceptions import DaimonConnectionError, DaimonProtocolError, DaimonToolError
+
+
+@dataclass(slots=True)
+class ToolCallEnvelope:
+    tool_name: str
+    payload: dict[str, Any]
+    content_blocks: list[dict[str, Any]]
+    raw_result: Any
+
+
+def _content_block_to_dict(block: Any) -> dict[str, Any]:
+    if isinstance(block, dict):
+        return dict(block)
+    data: dict[str, Any] = {}
+    for key in ("type", "text", "data", "mimeType", "mime_type", "annotations"):
+        value = getattr(block, key, None)
+        if value is not None:
+            data[key] = value
+    if not data and hasattr(block, "model_dump"):
+        dumped = block.model_dump()
+        if isinstance(dumped, dict):
+            data = dumped
+    if not data and hasattr(block, "__dict__"):
+        data = {
+            key: value
+            for key, value in vars(block).items()
+            if not key.startswith("_")
+        }
+    return data
+
+
+def decode_tool_result(result: Any) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+    if isinstance(getattr(result, "structured_content", None), dict):
+        payload = dict(result.structured_content)
+        content = [_content_block_to_dict(block) for block in getattr(result, "content", []) or []]
+        return payload, content
+    if getattr(result, "data", None) is not None:
+        data = result.data
+        if isinstance(data, dict):
+            payload = dict(data)
+        elif isinstance(data, str):
+            try:
+                payload = json.loads(data)
+            except json.JSONDecodeError as exc:
+                raise DaimonProtocolError(f"tool response data was not valid JSON: {data}") from exc
+        else:
+            raise DaimonProtocolError(f"unsupported tool response data type: {type(data)!r}")
+        content = [_content_block_to_dict(block) for block in getattr(result, "content", []) or []]
+        return payload, content
+    content = getattr(result, "content", None) or []
+    if content:
+        text = getattr(content[0], "text", None)
+        if isinstance(text, str):
+            try:
+                payload = json.loads(text)
+            except json.JSONDecodeError as exc:
+                raise DaimonProtocolError(f"tool response text was not valid JSON: {text}") from exc
+            return payload, [_content_block_to_dict(block) for block in content]
+    raise DaimonProtocolError(f"unable to decode tool result: {result!r}")
+
+
+class FastMCPTransportAdapter:
+    def __init__(self, base_url: str, *, access_token: str | None, timeout_s: float) -> None:
+        self.base_url = base_url
+        self.access_token = access_token
+        self.timeout_s = timeout_s
+        self._client: Client | None = None
+
+    @property
+    def client(self) -> Client:
+        if self._client is None:
+            raise DaimonConnectionError("client is not connected")
+        return self._client
+
+    async def connect(self) -> None:
+        if self._client is not None:
+            return
+        headers = {"X-Access-Token": self.access_token} if self.access_token else None
+        transport = StreamableHttpTransport(
+            self.base_url,
+            headers=headers,
+            httpx_client_factory=self._httpx_client_factory,
+        )
+        client = Client(transport, timeout=self.timeout_s)
+        try:
+            await client.__aenter__()
+        except Exception as exc:  # pragma: no cover - fastmcp exception types vary
+            raise DaimonConnectionError(str(exc)) from exc
+        self._client = client
+
+    async def close(self) -> None:
+        if self._client is None:
+            return
+        try:
+            await self._client.__aexit__(None, None, None)
+        finally:
+            self._client = None
+
+    async def call_tool(
+        self,
+        tool_name: str,
+        arguments: dict[str, Any],
+        *,
+        raise_on_error: bool = True,
+    ) -> ToolCallEnvelope:
+        await self.connect()
+        try:
+            result = await self.client.call_tool(tool_name, arguments, raise_on_error=False)
+        except Exception as exc:  # pragma: no cover - transport-side failures vary
+            raise DaimonConnectionError(str(exc)) from exc
+        payload, content_blocks = decode_tool_result(result)
+        if raise_on_error and isinstance(payload.get("error"), str):
+            raise DaimonToolError(payload["error"], tool_name=tool_name, payload=payload)
+        return ToolCallEnvelope(
+            tool_name=tool_name,
+            payload=payload,
+            content_blocks=content_blocks,
+            raw_result=result,
+        )
+
+    def _httpx_client_factory(self, **kwargs: Any) -> httpx.AsyncClient:
+        headers = dict(kwargs.pop("headers", {}) or {})
+        kwargs.setdefault("timeout", self.timeout_s)
+        kwargs.setdefault("follow_redirects", True)
+        return httpx.AsyncClient(headers=headers, **kwargs)