bma-executor-sdk 0.4.0__tar.gz

bma_executor_sdk-0.4.0/.gitignore

@@ -0,0 +1,4 @@
+.venv/
+__pycache__/
+dist/
+uv.lock

bma_executor_sdk-0.4.0/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.5
+Name: bma-executor-sdk
+Version: 0.4.0
+Summary: BMA executor protocol (bma.executor.v1.1): executor, harness and agent ends on asyncio with WebSocket, Unix socket and in-process transports.
+Project-URL: Repository, https://github.com/beeos-ai/bma-sdks
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: websockets<17,>=14
+Description-Content-Type: text/markdown
+
+# bma-executor-sdk (Python)
+
+asyncio executor (`ExecutorClient`), harness (`Harness`) and agent ends of the
+BMA executor protocol `bma.executor.v1.1`, with TypedDict protocol types
+generated from the BMA contract (`contracts/bma/executor`). Transports:
+WebSocket, WebSocket over a Unix domain socket (`unix://`), in-process.
+
+```sh
+pip install bma-executor-sdk
+```
+
+```python
+import bma_executor_sdk as bx
+```
+
+See the [repository README](../../README.md#python-executor) and
+[examples](examples). The REST/façade client is the separate `bma-sdk` package.

bma_executor_sdk-0.4.0/README.md

@@ -0,0 +1,17 @@
+# bma-executor-sdk (Python)
+
+asyncio executor (`ExecutorClient`), harness (`Harness`) and agent ends of the
+BMA executor protocol `bma.executor.v1.1`, with TypedDict protocol types
+generated from the BMA contract (`contracts/bma/executor`). Transports:
+WebSocket, WebSocket over a Unix domain socket (`unix://`), in-process.
+
+```sh
+pip install bma-executor-sdk
+```
+
+```python
+import bma_executor_sdk as bx
+```
+
+See the [repository README](../../README.md#python-executor) and
+[examples](examples). The REST/façade client is the separate `bma-sdk` package.

bma_executor_sdk-0.4.0/examples/agent_minimal.py

@@ -0,0 +1,79 @@
+"""Agent executor: a scripted local agent served over the executor protocol,
+driven by an in-process harness with an in-memory platform.
+
+    python agent_minimal.py
+
+Against BMA, keep EchoAgent and serve_agent() and build the client as in
+executor_minimal.py; BMA is then the platform.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from bma_executor_sdk import AgentEventRecord, AgentTurn, ExecutorClient, Harness, static_token
+
+
+class EchoAgent:
+    async def open_turn(self, params: dict[str, Any]) -> dict[str, Any]:
+        return {"accepted": True, "turn_id": params["turn_id"], "executor_session_ref": "echo_" + params["session_id"], "resumed": False, "effective": {"model": "echo"}}
+
+    async def run_turn(self, turn: AgentTurn) -> None:
+        text = turn.params["input"][0]["text"]
+        message_id = turn.new_event_id()
+        await turn.delta(message_id, "agent.message", 0, "Echo: ")  # streaming preview
+        turn.emit_with_id(message_id, {"type": "agent.message", "content": [{"type": "text", "text": "Echo: " + text}]})
+        tool_use_id = turn.emit({"type": "agent.tool_use", "name": "bash", "input": {"command": "date"}, "evaluated_permission": {"type": "ask"}})
+        answer = await turn.request_interaction({"kind": "permission", "tool_use_id": tool_use_id, "tool_name": "bash", "tool_input": {"command": "date"}, "scopes": ["once"]})  # type: ignore[typeddict-item]
+        allowed = answer["outcome"] == "allow"
+        turn.emit({"type": "agent.tool_result", "tool_use_id": tool_use_id, "is_error": not allowed, "content": [{"type": "text", "text": "ran" if allowed else "denied"}]})
+
+    async def close_session(self, session_id: str, reason: str) -> None:
+        print("closed", session_id, reason)
+
+
+class PrintingPlatform:
+    """AgentPlatform that prints events and allows every interaction."""
+
+    def __init__(self) -> None:
+        self.harness: Harness | None = None
+        self.idle = asyncio.Event()
+
+    async def acked_sequence(self, session_id: str) -> int:
+        return 0
+
+    async def agent_event(self, executor: Any, record: AgentEventRecord) -> None:
+        print(f"#{record.sequence} {record.type}")
+        if record.type == "session.status_idle":
+            self.idle.set()
+
+    def agent_delta(self, executor: Any, delta: dict[str, Any]) -> None:
+        print("  delta:", delta["text"])
+
+    async def interaction_requested(self, executor: Any, request: dict[str, Any]) -> str:
+        print("  permission asked for", request["tool_name"])
+        asyncio.ensure_future(executor.respond_interaction({"session_id": request["session_id"], "interaction_id": request["interaction_id"], "outcome": "allow"}))
+        return "pint_" + request["interaction_id"]
+
+    async def interaction_canceled(self, executor: Any, cancel: dict[str, Any]) -> None:
+        return None
+
+
+async def main() -> None:
+    platform = PrintingPlatform()
+    harness = Harness(agent=platform)
+    client = ExecutorClient(environment_id="env_local", executor={"name": "echo-agent", "os": "local", "arch": "local", "version": "0.1.0"}, token_source=static_token("inprocess://"), dialer=harness.inprocess_dialer())  # type: ignore[typeddict-item]
+    client.serve_agent(EchoAgent(), {"models": [{"id": "echo"}], "permission_modes": ["default"], "interaction_kinds": ["permission"]})  # type: ignore[arg-type,typeddict-item]
+    await client.start()
+    try:
+        executor = await harness.wait_executor()
+        await executor.start_turn({"session_id": "ses_demo", "turn_id": "turn_1", "input_id": "in_1", "input": [{"type": "text", "text": "hello"}]})  # type: ignore[typeddict-item]
+        await asyncio.wait_for(platform.idle.wait(), 10)
+        await executor.close_agent_session({"session_id": "ses_demo", "reason": "done"})  # type: ignore[typeddict-item]
+    finally:
+        await client.stop("done")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

bma_executor_sdk-0.4.0/examples/executor_minimal.py

@@ -0,0 +1,64 @@
+"""Minimal executor: registers with BMA and answers bash tool calls.
+
+    BMA_ENVIRONMENT_KEY=... BMA_ENVIRONMENT_ID=... python executor_minimal.py
+
+Set BMA_HARNESS_URL (ws://..., unix:///path.sock) to connect to a local
+harness instead of BMA, for example the one harness_loopback.py starts.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import platform
+
+from bma_executor_sdk import ExecutorClient, static_token
+from bma_executor_sdk.generated import ToolCallParams, ToolResultParams
+
+
+async def run_bash(call: ToolCallParams) -> ToolResultParams:
+    proc = await asyncio.create_subprocess_shell(
+        call["input"].get("command", ""), stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.STDOUT,
+    )
+    try:
+        output, _ = await proc.communicate()
+    except asyncio.CancelledError:  # tool.cancel or the deadline: stop the process
+        proc.kill()
+        raise
+    return {
+        "session_id": call["session_id"],
+        "tool_call_id": call["tool_call_id"],
+        "outcome": "succeeded" if proc.returncode == 0 else "failed",
+        "is_error": proc.returncode != 0,
+        "content": [{"type": "text", "text": output.decode(errors="replace")}],
+    }  # type: ignore[typeddict-item]
+
+
+def make_client() -> ExecutorClient:
+    info = {"name": "py-executor", "os": platform.system().lower(), "arch": platform.machine(), "version": "0.1.0"}
+    capabilities = {"shell": {"enabled": True}}
+    harness_url = os.environ.get("BMA_HARNESS_URL")
+    if harness_url:
+        return ExecutorClient(environment_id="env_local", executor=info, capabilities=capabilities, token_source=static_token(harness_url))  # type: ignore[arg-type]
+    return ExecutorClient(
+        environment_id=os.environ["BMA_ENVIRONMENT_ID"],
+        environment_key=os.environ["BMA_ENVIRONMENT_KEY"],
+        base_url=os.environ.get("BMA_BASE_URL", "https://api.bma.beeos.ai"),
+        executor=info,  # type: ignore[arg-type]
+        capabilities=capabilities,  # type: ignore[arg-type]
+    )
+
+
+async def main() -> None:
+    client = make_client()
+    client.on_tool_call(run_bash)
+    registered = await client.start()
+    print("registered as", registered["executor_id"])
+    try:
+        await asyncio.Event().wait()
+    finally:
+        await client.stop("shutdown")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

bma_executor_sdk-0.4.0/examples/harness_loopback.py

@@ -0,0 +1,50 @@
+"""Local brain and hand in one process: a harness and an executor connected
+in-process (or over a Unix socket with --unix PATH), one bash tool call.
+
+    python harness_loopback.py [--unix /tmp/bma-harness.sock]
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+
+from bma_executor_sdk import ExecutorClient, Harness, static_token
+from executor_minimal import run_bash
+
+
+async def main(unix_path: str | None) -> None:
+    harness = Harness()  # no authenticate hook: in-process or a private socket only
+    server = None
+    if unix_path:
+        server = await harness.serve_unix(unix_path)
+        client = ExecutorClient(environment_id="env_local", executor={"name": "loopback", "os": "local", "arch": "local", "version": "0.1.0"}, token_source=static_token(f"unix://{unix_path}"))  # type: ignore[typeddict-item]
+    else:
+        client = ExecutorClient(environment_id="env_local", executor={"name": "loopback", "os": "local", "arch": "local", "version": "0.1.0"}, token_source=static_token("inprocess://"), dialer=harness.inprocess_dialer())  # type: ignore[typeddict-item]
+
+    async def on_assign(params):  # type: ignore[no-untyped-def]
+        # Report ready once the workspace is prepared (here: nothing to do).
+        asyncio.ensure_future(client.session_ready({"session_id": params["session_id"], "work_id": params["work_id"], "lease_token": params["lease"]["token"]}))
+        return {"accepted": True, "session_id": params["session_id"]}
+
+    client.on_session_assign(on_assign)
+    client.on_tool_call(run_bash)
+    await client.start()
+    try:
+        executor = await harness.wait_executor()
+        session = await executor.assign_session({"session_id": "ses_local"})  # type: ignore[typeddict-item]
+        await session.ready()
+        result = await session.call_tool({"tool": "bash", "input": {"command": "echo hello from the hand"}})  # type: ignore[typeddict-item]
+        print(result["outcome"], result["content"][0]["text"].strip())
+        await session.stop("done")
+    finally:
+        await client.stop("done")
+        if server is not None:
+            server.close()
+            await server.wait_closed()  # also removes the socket file
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--unix")
+    asyncio.run(main(parser.parse_args().unix))

bma_executor_sdk-0.4.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "bma-executor-sdk"
+version = "0.4.0"
+description = "BMA executor protocol (bma.executor.v1.1): executor, harness and agent ends on asyncio with WebSocket, Unix socket and in-process transports."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.27,<1", "websockets>=14,<17"]
+
+[project.urls]
+Repository = "https://github.com/beeos-ai/bma-sdks"
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=0.24"]
+
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bma_executor_sdk"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

bma_executor_sdk-0.4.0/src/bma_executor_sdk/__init__.py

@@ -0,0 +1,77 @@
+"""BMA executor protocol (bma.executor.v1.1): executor, harness and agent ends.
+
+Install with ``pip install bma-executor-sdk``.
+Protocol types are generated from the BMA contract into
+:mod:`bma_executor_sdk.generated` (TypedDicts: plain JSON dicts on the wire).
+"""
+
+from . import generated
+from ._rpc import ClientStoppedError, ExecutorError, NotConnectedError, RPCError
+from .agent import AgentEventRecord, AgentHandler, AgentPlatform, AgentSessionClosedError, AgentTurn
+from .client import (
+    DEFAULT_BASE_URL,
+    PROTOCOL_V1,
+    PROTOCOL_V11,
+    ExecutorClient,
+    ExecutorTokenError,
+    ExecutorTokenScopeError,
+    LogEvent,
+    MCPChannel,
+    static_token,
+)
+from .harness import (
+    AssignRejectedError,
+    Executor,
+    Harness,
+    HarnessMCPChannel,
+    Principal,
+    Session,
+    SessionEndedError,
+    ToolOutcomeUnknownError,
+    Unauthorized,
+)
+from .transport import (
+    TERMINAL_CLOSE_CODES,
+    ChannelClosed,
+    ConnectRequest,
+    Connection,
+    Dialer,
+    dial,
+)
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "PROTOCOL_V1",
+    "PROTOCOL_V11",
+    "TERMINAL_CLOSE_CODES",
+    "AgentEventRecord",
+    "AgentHandler",
+    "AgentPlatform",
+    "AgentSessionClosedError",
+    "AgentTurn",
+    "AssignRejectedError",
+    "ChannelClosed",
+    "ClientStoppedError",
+    "ConnectRequest",
+    "Connection",
+    "Dialer",
+    "Executor",
+    "ExecutorClient",
+    "ExecutorError",
+    "ExecutorTokenError",
+    "ExecutorTokenScopeError",
+    "Harness",
+    "HarnessMCPChannel",
+    "LogEvent",
+    "MCPChannel",
+    "NotConnectedError",
+    "Principal",
+    "RPCError",
+    "Session",
+    "SessionEndedError",
+    "ToolOutcomeUnknownError",
+    "Unauthorized",
+    "dial",
+    "generated",
+    "static_token",
+]

bma_executor_sdk-0.4.0/src/bma_executor_sdk/_rpc.py

@@ -0,0 +1,192 @@
+"""JSON-RPC 2.0 over a Connection, shared by the executor and harness ends."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from .generated import JsonRpcErrorCode
+from .transport import ChannelClosed, Connection
+
+
+class ExecutorError(Exception):
+    """Base class of bma_executor_sdk errors."""
+
+
+class NotConnectedError(ExecutorError):
+    """The channel is not connected (yet, or any more)."""
+
+    def __init__(self, message: str = "executor channel is not connected") -> None:
+        super().__init__(message)
+
+
+class ClientStoppedError(ExecutorError):
+    """The client was stopped, or closed with a terminal close code."""
+
+    def __init__(self, message: str = "client stopped") -> None:
+        super().__init__(message)
+
+
+class RPCError(ExecutorError):
+    """A JSON-RPC error. A handler that raises it keeps its code on the wire."""
+
+    def __init__(self, code: int, message: str, data: dict[str, Any] | None = None) -> None:
+        super().__init__(f"json-rpc error {code}: {message}")
+        self.code = code
+        self.message = message
+        self.data = data
+
+    @property
+    def retryable(self) -> bool | None:
+        return None if self.data is None else self.data.get("retryable")
+
+    def to_wire(self) -> dict[str, Any]:
+        error: dict[str, Any] = {"code": int(self.code), "message": self.message}
+        if self.data is not None:
+            error["data"] = self.data
+        return error
+
+
+def rpc_error(code: JsonRpcErrorCode, message: str, retryable: bool) -> RPCError:
+    return RPCError(code, message, {"retryable": retryable})
+
+
+RequestHandler = Callable[[str, str, Any], Awaitable[Any]]
+NotificationHandler = Callable[[str, Any], None]
+
+
+class Peer:
+    """One JSON-RPC endpoint on a Connection.
+
+    Inbound requests run as tasks (except methods in ``inline``, which are
+    handled in read order); notifications are handled in read order.
+    """
+
+    def __init__(
+        self,
+        conn: Connection,
+        *,
+        id_prefix: str,
+        on_request: RequestHandler,
+        on_notification: NotificationHandler,
+        on_log: Callable[[str, str, BaseException | None], None],
+        inline: frozenset[str] = frozenset(),
+    ) -> None:
+        self.conn = conn
+        self._id_prefix = id_prefix
+        self._on_request = on_request
+        self._on_notification = on_notification
+        self._log = on_log
+        self._inline = inline
+        self._pending: dict[str, asyncio.Future[Any]] = {}
+        self._next_id = 0
+        self._tasks: set[asyncio.Task[Any]] = set()
+        self.closed: ChannelClosed | None = None
+
+    async def call(self, method: str, params: Any, timeout: float) -> Any:
+        if self.closed is not None:
+            raise NotConnectedError()
+        self._next_id += 1
+        request_id = f"{self._id_prefix}_{self._next_id}"
+        future: asyncio.Future[Any] = asyncio.get_running_loop().create_future()
+        self._pending[request_id] = future
+        try:
+            await self._send({"jsonrpc": "2.0", "id": request_id, "method": method, "params": params})
+            return await asyncio.wait_for(future, timeout)
+        except asyncio.TimeoutError as error:
+            raise TimeoutError(f"{method}: no response within {timeout}s") from error
+        finally:
+            self._pending.pop(request_id, None)
+
+    async def notify(self, method: str, params: Any) -> None:
+        if self.closed is not None:
+            raise NotConnectedError()
+        await self._send({"jsonrpc": "2.0", "method": method, "params": params})
+
+    async def _send(self, message: dict[str, Any]) -> None:
+        try:
+            await self.conn.send(json.dumps(message, separators=(",", ":")))
+        except ChannelClosed as error:
+            raise NotConnectedError(f"write {message.get('method', 'response')}: {error}") from error
+
+    async def run(self) -> ChannelClosed:
+        """Read until the channel closes; then fail pending calls."""
+        try:
+            while True:
+                raw = await self.conn.recv()
+                try:
+                    message = json.loads(raw)
+                except ValueError as error:
+                    self._log("warn", "invalid JSON-RPC frame", error)
+                    continue
+                if isinstance(message, dict) and message.get("method") in self._inline and message.get("id") is not None:
+                    await self._handle_request(str(message["id"]), message["method"], message.get("params"))
+                    continue
+                self._dispatch(message)
+        except ChannelClosed as closed:
+            self.closed = closed
+        except asyncio.CancelledError:
+            self.closed = ChannelClosed(1006, "reader canceled")
+            raise
+        finally:
+            if self.closed is None:
+                self.closed = ChannelClosed(1006, "reader failed")
+            self.fail_pending(NotConnectedError())
+        return self.closed
+
+    def fail_pending(self, error: Exception) -> None:
+        pending, self._pending = self._pending, {}
+        for future in pending.values():
+            if not future.done():
+                future.set_exception(error)
+
+    def _dispatch(self, message: Any) -> None:
+        if not isinstance(message, dict):
+            self._log("warn", "JSON-RPC frame is not an object", None)
+            return
+        method, request_id = message.get("method"), message.get("id")
+        if method and request_id is not None:
+            self._spawn(self._handle_request(str(request_id), method, message.get("params")))
+        elif method:
+            try:
+                self._on_notification(method, message.get("params"))
+            except Exception as error:  # a handler bug must not stop the channel
+                self._log("error", f"{method} notification handler failed", error)
+        elif request_id is not None:
+            future = self._pending.pop(str(request_id), None)
+            if future is None or future.done():
+                return
+            error = message.get("error")
+            if error is not None:
+                future.set_exception(RPCError(error.get("code", 0), error.get("message", ""), error.get("data")))
+            else:
+                future.set_result(message.get("result"))
+        else:
+            self._log("warn", "JSON-RPC frame is neither request nor response", None)
+
+    def _spawn(self, coro: Awaitable[None]) -> None:
+        task = asyncio.ensure_future(coro)
+        self._tasks.add(task)
+        task.add_done_callback(self._tasks.discard)
+
+    async def _handle_request(self, request_id: str, method: str, params: Any) -> None:
+        try:
+            result = await self._on_request(request_id, method, params)
+            response: dict[str, Any] = {"jsonrpc": "2.0", "id": request_id, "result": result}
+        except RPCError as error:
+            response = {"jsonrpc": "2.0", "id": request_id, "error": error.to_wire()}
+        except asyncio.CancelledError:
+            raise
+        except Exception as error:
+            self._log("warn", f"{method} handler failed", error)
+            response = {"jsonrpc": "2.0", "id": request_id, "error": {"code": int(JsonRpcErrorCode.InternalError), "message": str(error)}}
+        try:
+            await self._send(response)
+        except NotConnectedError as error:
+            self._log("debug", f"write {method} response", error)
+
+    def cancel_tasks(self) -> None:
+        for task in list(self._tasks):
+            task.cancel()