roder-sdk 0.1.0__tar.gz

roder_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: roder-sdk
+Version: 0.1.0
+Summary: Python SDK for the Roder app-server JSON-RPC API
+Author: Pandelis Zembashis
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: anyio>=4.0
+Requires-Dist: websockets>=14.0
+
+# roder-sdk
+
+Python SDK for the Roder app-server JSON-RPC API.
+
+```py
+from roder_sdk import RoderAgent
+```
+
+Normal tests use in-memory fake transports. Live local and remote smoke checks are opt-in with `RODER_SDK_LIVE=1`.
+
+For process-based automation, spawn `roder exec --json` and consume one JSON
+event per stdout line:
+
+```sh
+printf 'Reply with exactly: ok\n' | roder exec --json --profile eval --mode bypass -
+```
+
+See `docs/roder-exec.md` for the JSONL event contract.
+
+Before building:
+
+```sh
+uv run pytest tests
+uv run pyright src
+```

roder_sdk-0.1.0/README.md

@@ -0,0 +1,25 @@
+# roder-sdk
+
+Python SDK for the Roder app-server JSON-RPC API.
+
+```py
+from roder_sdk import RoderAgent
+```
+
+Normal tests use in-memory fake transports. Live local and remote smoke checks are opt-in with `RODER_SDK_LIVE=1`.
+
+For process-based automation, spawn `roder exec --json` and consume one JSON
+event per stdout line:
+
+```sh
+printf 'Reply with exactly: ok\n' | roder exec --json --profile eval --mode bypass -
+```
+
+See `docs/roder-exec.md` for the JSONL event contract.
+
+Before building:
+
+```sh
+uv run pytest tests
+uv run pyright src
+```

roder_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "roder-sdk"
+version = "0.1.0"
+description = "Python SDK for the Roder app-server JSON-RPC API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  { name = "Pandelis Zembashis" },
+]
+dependencies = [
+  "anyio>=4.0",
+  "websockets>=14.0",
+]
+
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[dependency-groups]
+dev = [
+  "pytest>=8.0",
+  "pyright>=1.1.390",
+]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]
+
+[tool.pyright]
+pythonVersion = "3.10"
+include = ["src"]
+typeCheckingMode = "basic"

roder_sdk-0.1.0/setup.cfg

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

roder_sdk-0.1.0/src/roder_sdk/__init__.py

@@ -0,0 +1,24 @@
+from .agent import RoderAgent
+from .client import RoderRpcClient
+from .events import normalize_notification
+from .hosted import HostedClient
+from .errors import RoderRpcError, RoderTransportError
+from .run import RoderRun
+from .transports import InMemoryTransport, LocalProcessTransport, WebSocketTransport
+from .types_generated import APP_SERVER_MANIFEST, APP_SERVER_METHODS, AppServerMethod
+
+__all__ = [
+    "APP_SERVER_MANIFEST",
+    "APP_SERVER_METHODS",
+    "AppServerMethod",
+    "HostedClient",
+    "InMemoryTransport",
+    "LocalProcessTransport",
+    "RoderAgent",
+    "RoderRpcClient",
+    "RoderRpcError",
+    "RoderRun",
+    "RoderTransportError",
+    "WebSocketTransport",
+    "normalize_notification",
+]

roder_sdk-0.1.0/src/roder_sdk/agent.py

@@ -0,0 +1,255 @@
+from __future__ import annotations
+
+import asyncio
+import inspect
+from collections.abc import Awaitable, Callable
+from typing import Any, cast
+
+from .client import RoderRpcClient
+from .events import EventMode
+from .run import RoderRun
+from .transports import InMemoryTransport, LocalProcessTransport, RoderTransport, WebSocketTransport
+
+ApprovalCallback = Callable[[Any], dict[str, Any] | Awaitable[dict[str, Any]]]
+
+
+class RoderAgent:
+    def __init__(
+        self,
+        transport: RoderTransport,
+        *,
+        cwd: str | None = None,
+        model: dict[str, str] | None = None,
+        thread_id: str | None = None,
+        workspace_id: str | None = None,
+        tool_allowlist: list[str] | None = None,
+        instructions: str | None = None,
+        runner: dict[str, Any] | None = None,
+        approvals: dict[str, ApprovalCallback] | None = None,
+        event_mode: EventMode = "permissive",
+    ) -> None:
+        self.transport = transport
+        self.client = RoderRpcClient(transport)
+        self.cwd = cwd
+        self.model = model or {}
+        self.thread_id = thread_id
+        self.workspace_id = workspace_id
+        self.tool_allowlist = tool_allowlist
+        self.instructions = instructions
+        self.runner = runner
+        self.approvals = approvals or {}
+        self.event_mode: EventMode = event_mode
+        self._callback_task: asyncio.Task[None] | None = None
+
+    @classmethod
+    async def create(
+        cls,
+        *,
+        local: dict[str, Any] | None = None,
+        remote: dict[str, Any] | None = None,
+        transport: RoderTransport | None = None,
+        cwd: str | None = None,
+        model: dict[str, str] | None = None,
+        thread_id: str | None = None,
+        workspace_id: str | None = None,
+        tool_allowlist: list[str] | None = None,
+        instructions: str | None = None,
+        runner: dict[str, Any] | None = None,
+        approvals: dict[str, ApprovalCallback] | None = None,
+        event_mode: EventMode = "permissive",
+    ) -> "RoderAgent":
+        resolved = await _resolve_transport(local=local, remote=remote, transport=transport, cwd=cwd)
+        agent = cls(
+            resolved,
+            cwd=cwd,
+            model=model,
+            thread_id=thread_id,
+            workspace_id=workspace_id,
+            tool_allowlist=tool_allowlist,
+            instructions=instructions,
+            runner=runner,
+            approvals=approvals,
+            event_mode=event_mode,
+        )
+        agent._start_callback_loop()
+        return agent
+
+    async def __aenter__(self) -> "RoderAgent":
+        return self
+
+    async def __aexit__(self, exc_type: object, exc: object, tb: object) -> None:
+        await self.close()
+
+    async def send(
+        self,
+        input: str | list[dict[str, Any]],
+        *,
+        developer_context: str | None = None,
+    ) -> RoderRun:
+        """
+        developer_context is per-turn developer-authority context layered after
+        the thread's developerInstructions for this turn only. Never persisted
+        with the thread; resend it on each turn that needs it.
+        """
+        thread_id = self.thread_id or await self._start_thread()
+        self.thread_id = thread_id
+        params: dict[str, Any] = {"threadId": thread_id, "input": _normalize_input(input)}
+        if developer_context is not None:
+            params["developerContext"] = developer_context
+        result = await self.client.call("turn/start", params)
+        turn_id = _extract_id(result, "turn") or _extract_string(result, "turnId") or _extract_string(result, "id")
+        if not turn_id:
+            raise RuntimeError("turn/start response did not include a turn id")
+        return RoderRun(self.client, thread_id, turn_id, event_mode=self.event_mode)
+
+    async def list_models(self) -> Any:
+        return await self.client.call("model/list")
+
+    async def list_providers(self) -> Any:
+        return await self.client.call("providers/list")
+
+    async def read_thread(self, thread_id: str | None = None) -> Any:
+        selected = thread_id or self.thread_id
+        if not selected:
+            raise RuntimeError("read_thread requires a thread id")
+        return await self.client.call("thread/read", {"threadId": selected})
+
+    async def list_threads(self) -> Any:
+        return await self.client.call("thread/list")
+
+    async def list_tools(self) -> Any:
+        return await self.client.call("tools/list")
+
+    async def list_commands(self) -> Any:
+        return await self.client.call("commands/list")
+
+    async def close(self) -> None:
+        if self._callback_task:
+            self._callback_task.cancel()
+        await self.client.close()
+
+    async def _start_thread(self) -> str:
+        workspace_id = self.workspace_id or await self._resolve_workspace_id(self.cwd)
+        params: dict[str, Any] = {
+            "cwd": self.cwd,
+            "model": self.model.get("id"),
+            "modelProvider": self.model.get("provider"),
+        }
+        if self.tool_allowlist is not None:
+            params["toolAllowlist"] = self.tool_allowlist
+        if self.instructions is not None:
+            params["developerInstructions"] = self.instructions
+        if self.runner is not None:
+            params["runner"] = self.runner
+        params["workspaceId"] = workspace_id
+        result = await self.client.call("thread/start", params)
+        thread_id = _extract_id(result, "thread") or _extract_string(result, "threadId") or _extract_string(result, "id")
+        if not thread_id:
+            raise RuntimeError("thread/start response did not include a thread id")
+        return thread_id
+
+    async def _resolve_workspace_id(self, cwd: str | None) -> str:
+        if not cwd:
+            raise RuntimeError("starting a thread requires a workspace_id or a cwd to resolve one from")
+        listed = await self.client.call("workspace/list", {})
+        workspaces = listed.get("workspaces") if isinstance(listed, dict) else None
+        for workspace in workspaces if isinstance(workspaces, list) else []:
+            if not isinstance(workspace, dict):
+                continue
+            roots = workspace.get("roots")
+            workspace_id = _extract_string(workspace, "id")
+            if (
+                workspace_id
+                and isinstance(roots, list)
+                and any(_extract_string(root, "path") == cwd for root in roots)
+            ):
+                return workspace_id
+        created = await self.client.call("workspace/create", {"roots": [{"path": cwd}]})
+        workspace_id = _extract_id(created, "workspace")
+        if not workspace_id:
+            raise RuntimeError("workspace/create response did not include a workspace id")
+        return workspace_id
+
+    def _start_callback_loop(self) -> None:
+        if not self.approvals:
+            return
+        self._callback_task = asyncio.create_task(self._callback_loop())
+
+    async def _callback_loop(self) -> None:
+        async for notification in self.client.notifications():
+            await self._handle_callback_notification(str(notification.get("method")), notification.get("params"))
+
+    async def _handle_callback_notification(self, method: str, params: Any) -> None:
+        if method == "thread/approvalRequested" and "on_tool_approval" in self.approvals:
+            decision = await _maybe_await(self.approvals["on_tool_approval"](params))
+            await self.client.call(
+                "thread/resolve_approval",
+                {
+                    "approvalId": _extract_string(params, "approvalId"),
+                    "approved": bool(decision.get("approved")),
+                },
+            )
+        elif method == "thread/userInputRequested" and "on_user_input" in self.approvals:
+            decision = await _maybe_await(self.approvals["on_user_input"](params))
+            await self.client.call(
+                "thread/resolve_user_input",
+                {"requestId": _extract_string(params, "requestId"), "answers": decision.get("answers")},
+            )
+        elif method == "thread/planExitRequested" and "on_plan_exit" in self.approvals:
+            decision = await _maybe_await(self.approvals["on_plan_exit"](params))
+            await self.client.call(
+                "thread/exit_plan",
+                {
+                    "requestId": _extract_string(params, "requestId"),
+                    "approved": bool(decision.get("approved")),
+                },
+            )
+
+
+async def _resolve_transport(
+    *,
+    local: dict[str, Any] | None,
+    remote: dict[str, Any] | None,
+    transport: RoderTransport | None,
+    cwd: str | None,
+) -> RoderTransport:
+    if transport:
+        return transport
+    if remote:
+        return await WebSocketTransport.connect(**remote)
+    if local:
+        return await LocalProcessTransport.create(
+            command=local.get("command", "roder"),
+            args=local.get("args"),
+            cwd=local.get("cwd", cwd),
+            env=local.get("env"),
+        )
+    return InMemoryTransport(
+        lambda request: {
+            "jsonrpc": "2.0",
+            "id": request.get("id"),
+            "error": {"code": -32000, "message": "no transport configured"},
+        }
+    )
+
+
+def _normalize_input(input: str | list[dict[str, Any]]) -> list[dict[str, Any]]:
+    return [{"type": "text", "text": input}] if isinstance(input, str) else input
+
+
+def _extract_id(value: Any, key: str) -> str | None:
+    if isinstance(value, dict) and isinstance(value.get(key), dict):
+        return _extract_string(value[key], "id")
+    return None
+
+
+def _extract_string(value: Any, key: str) -> str | None:
+    if isinstance(value, dict) and isinstance(value.get(key), str):
+        return str(value[key])
+    return None
+
+
+async def _maybe_await(value: dict[str, Any] | Awaitable[dict[str, Any]]) -> dict[str, Any]:
+    if inspect.isawaitable(value):
+        return await cast(Awaitable[dict[str, Any]], value)
+    return cast(dict[str, Any], value)

roder_sdk-0.1.0/src/roder_sdk/client.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from .errors import RoderRpcError
+from .transports import JsonRpcNotification, RoderTransport
+from .types_generated import APP_SERVER_METHODS, AppServerMethod, JsonRpcRequest, JsonRpcResponse
+
+
+class RoderRpcClient:
+    def __init__(self, transport: RoderTransport) -> None:
+        self._transport = transport
+        self._next_id = 1
+        self.methods: dict[str, Callable[[Any | None], Any]] = {
+            method: self._method_helper(method) for method in APP_SERVER_METHODS
+        }
+
+    async def call(self, method: AppServerMethod, params: Any = None) -> Any:
+        request: JsonRpcRequest = {
+            "jsonrpc": "2.0",
+            "id": self._allocate_id(),
+            "method": method,
+        }
+        if params is not None:
+            request["params"] = params
+        response = await self.raw_request(request)
+        error = response.get("error")
+        if error:
+            raise RoderRpcError(
+                code=int(error.get("code", -32000)),
+                message=str(error.get("message", "JSON-RPC error")),
+                data=error.get("data"),
+                method=method,
+                request_id=response.get("id"),
+            )
+        return response.get("result")
+
+    async def raw_request(self, request: JsonRpcRequest) -> JsonRpcResponse:
+        return await self._transport.request(request)
+
+    def notifications(self):
+        return self._transport.notifications()
+
+    async def close(self) -> None:
+        await self._transport.close()
+
+    def _allocate_id(self) -> int:
+        request_id = self._next_id
+        self._next_id += 1
+        return request_id
+
+    def _method_helper(self, method: str) -> Callable[[Any | None], Any]:
+        async def helper(params: Any = None) -> Any:
+            return await self.call(method, params)  # type: ignore[arg-type]
+
+        return helper
+
+
+__all__ = ["JsonRpcNotification", "RoderRpcClient"]

roder_sdk-0.1.0/src/roder_sdk/errors.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class RoderRpcError(Exception):
+    def __init__(
+        self,
+        *,
+        code: int,
+        message: str,
+        data: Any = None,
+        method: str,
+        request_id: str | int | None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.data = data
+        self.method = method
+        self.request_id = request_id
+
+
+class RoderTransportError(Exception):
+    pass

roder_sdk-0.1.0/src/roder_sdk/events.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from typing import Any, Literal, TypedDict
+
+JsonRpcNotification = dict[str, Any]
+EventMode = Literal["strict", "permissive"]
+
+
+class RoderSdkEvent(TypedDict):
+    type: str
+    raw: JsonRpcNotification
+
+
+EVENT_TYPES: dict[str, str] = {
+    "thread/started": "thread.started",
+    "thread/status/changed": "thread.status.changed",
+    "turn/started": "turn.started",
+    "turn/completed": "turn.completed",
+    "item/started": "item.started",
+    "item/completed": "item.completed",
+    "item/agentMessage/delta": "item.delta",
+    "item/reasoning/textDelta": "item.delta",
+    "item/reasoning/summaryPartAdded": "item.delta",
+    "item/reasoning/summaryTextDelta": "item.delta",
+    "thread/toolExecutionRequested": "tool_execution.requested",
+    "thread/toolExecutionResolved": "tool_execution.resolved",
+    "thread/approvalRequested": "approval.requested",
+    "thread/approvalResolved": "approval.resolved",
+    "thread/userInputRequested": "user_input.requested",
+    "thread/userInputResolved": "user_input.resolved",
+    "thread/planExitRequested": "plan_exit.requested",
+    "thread/planExitResolved": "plan_exit.resolved",
+    "command/exec/outputDelta": "command.output_delta",
+}
+
+
+def normalize_notification(
+    raw: JsonRpcNotification,
+    mode: EventMode = "permissive",
+) -> RoderSdkEvent | None:
+    event_type = EVENT_TYPES.get(str(raw.get("method")))
+    if event_type:
+        return {"type": event_type, "raw": raw}
+    if mode == "permissive":
+        return {"type": "raw.notification", "raw": raw}
+    return None

roder_sdk-0.1.0/src/roder_sdk/hosted.py

@@ -0,0 +1,121 @@
+"""Hosted multi-tenant connection helpers (roadmap phase 72, Task 6).
+
+Hosted Roder authenticates at the WebSocket handshake with a bearer
+credential in the ``Authorization`` header — the gateway always rejects
+query-string credentials. :class:`HostedClient` wraps the standard RPC
+client with typed helpers for ``hosted/*`` methods; raw JSON-RPC access
+stays available via ``client.raw_request`` for forward-compatible hosted
+methods.
+
+Token refresh/reconnect: connections authenticate once at handshake time,
+so refreshing a token means reconnecting. :meth:`HostedClient.reconnect`
+builds a fresh transport using the token provider. Requests in flight when
+a connection drops fail with a transport error and are NEVER replayed
+automatically — callers retry mutating requests themselves because only
+they know whether the operation is idempotent.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from .client import RoderRpcClient
+from .transports import WebSocketTransport
+
+TokenProvider = Callable[[], "str | Awaitable[str]"]
+
+
+class HostedClient:
+    def __init__(self, options: dict[str, Any], client: RoderRpcClient) -> None:
+        self._options = options
+        self.client = client
+
+    @classmethod
+    async def connect(
+        cls,
+        url: str,
+        *,
+        token: str | None = None,
+        token_provider: TokenProvider | None = None,
+        headers: dict[str, str] | None = None,
+        connector: Callable[..., Awaitable[Any]] | None = None,
+    ) -> "HostedClient":
+        """Connects and authenticates against a hosted Roder gateway."""
+        options = {
+            "url": url,
+            "token": token,
+            "token_provider": token_provider,
+            "headers": headers,
+            "connector": connector,
+        }
+        client = await _hosted_rpc_client(options)
+        return cls(options, client)
+
+    async def reconnect(self) -> None:
+        """Re-authenticates with a fresh credential and replaces the
+        connection. In-flight requests on the old connection fail; nothing
+        is replayed."""
+        next_client = await _hosted_rpc_client(self._options)
+        previous = self.client
+        self.client = next_client
+        await previous.close()
+
+    async def whoami(self) -> dict[str, Any]:
+        return await self.client.call("hosted/whoami", {})
+
+    async def create_service_account(self, display_name: str) -> dict[str, Any]:
+        return await self.client.call(
+            "hosted/service_accounts/create", {"displayName": display_name}
+        )
+
+    async def revoke_service_account(self, key_id: str) -> dict[str, Any]:
+        return await self.client.call("hosted/service_accounts/revoke", {"keyId": key_id})
+
+    async def list_hooks(self) -> dict[str, Any]:
+        return await self.client.call("hosted/hooks/list", {})
+
+    async def create_hook(self, hook: dict[str, Any]) -> dict[str, Any]:
+        return await self.client.call("hosted/hooks/create", {"hook": hook})
+
+    async def delete_hook(self, hook_id: str) -> dict[str, Any]:
+        return await self.client.call("hosted/hooks/delete", {"hookId": hook_id})
+
+    async def audit_list(self) -> dict[str, Any]:
+        return await self.client.call("hosted/audit/list", {})
+
+    def notifications(self):
+        return self.client.notifications()
+
+    async def close(self) -> None:
+        await self.client.close()
+
+
+async def _resolve_token(options: dict[str, Any]) -> str | None:
+    provider: TokenProvider | None = options.get("token_provider")
+    if provider is not None:
+        token = provider()
+        if inspect.isawaitable(token):
+            token = await token
+        return str(token)
+    return options.get("token")
+
+
+async def _hosted_rpc_client(options: dict[str, Any]) -> RoderRpcClient:
+    token = await _resolve_token(options)
+    headers: dict[str, str] | None = options.get("headers")
+    has_external_auth = bool(headers) and any(
+        key.lower() == "authorization" for key in headers
+    )
+    if not token and not has_external_auth:
+        raise ValueError(
+            "hosted connections require a token, token_provider, or an Authorization header"
+        )
+    transport = await WebSocketTransport.connect(
+        options["url"],
+        token=token,
+        headers=headers,
+        connector=options.get("connector"),
+    )
+    return RoderRpcClient(transport)