bma-executor-sdk 0.4.4__tar.gz → 0.4.5__tar.gz

{bma_executor_sdk-0.4.4 → bma_executor_sdk-0.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bma-executor-sdk
-Version: 0.4.4
+Version: 0.4.5
 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
@@ -17,13 +17,13 @@ asyncio executor (`ExecutorClient`), harness (`Harness`) and agent ends of the B
 
 | | |
 | --- | --- |
-| Version | 0.4.4 (tag `executor-python/v0.4.4`), see [CHANGELOG](../../CHANGELOG.md) |
+| Version | 0.4.5 (tag `executor-python/v0.4.5`), see [CHANGELOG](../../CHANGELOG.md) |
 | Protocol | `bma.executor.v1.1` (contract 1.1.0, [`lock.json`](../../contracts/bma/executor/lock.json)) |
 | Python | 3.10 or newer; depends on `httpx` and `websockets` |
 | Integration guide | [docs/executor](../../docs/executor/README.md) ([中文](../../docs/executor/README.zh-CN.md)) |
 
 ```sh
-pip install bma-executor-sdk==0.4.4
+pip install bma-executor-sdk==0.4.5
 ```
 
 The REST / façade client is the separate package [`bma-sdk`](../../python).

{bma_executor_sdk-0.4.4 → bma_executor_sdk-0.4.5}/README.md

@@ -6,13 +6,13 @@ asyncio executor (`ExecutorClient`), harness (`Harness`) and agent ends of the B
 
 | | |
 | --- | --- |
-| Version | 0.4.4 (tag `executor-python/v0.4.4`), see [CHANGELOG](../../CHANGELOG.md) |
+| Version | 0.4.5 (tag `executor-python/v0.4.5`), see [CHANGELOG](../../CHANGELOG.md) |
 | Protocol | `bma.executor.v1.1` (contract 1.1.0, [`lock.json`](../../contracts/bma/executor/lock.json)) |
 | Python | 3.10 or newer; depends on `httpx` and `websockets` |
 | Integration guide | [docs/executor](../../docs/executor/README.md) ([中文](../../docs/executor/README.zh-CN.md)) |
 
 ```sh
-pip install bma-executor-sdk==0.4.4
+pip install bma-executor-sdk==0.4.5
 ```
 
 The REST / façade client is the separate package [`bma-sdk`](../../python).

{bma_executor_sdk-0.4.4 → bma_executor_sdk-0.4.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "bma-executor-sdk"
-version = "0.4.4"
+version = "0.4.5"
 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"

{bma_executor_sdk-0.4.4 → bma_executor_sdk-0.4.5}/src/bma_executor_sdk/client.py

@@ -21,6 +21,7 @@ from .generated import (
     METHOD_EXECUTOR_DRAIN,
     METHOD_EXECUTOR_HEARTBEAT,
     METHOD_EXECUTOR_REGISTER,
+    METHOD_EXECUTOR_TOKEN_REFRESH,
     METHOD_SESSION_ASSIGN,
     METHOD_SESSION_ENDED,
     METHOD_SESSION_READY,
@@ -69,6 +70,8 @@ PROTOCOL_V11 = ProtocolVersion.BmaExecutorV11.value
 _MAX_TRACKED_TOOL_RESULTS = 8192
 _MAX_TOOL_RESULT_RETRY_DELAY = 10.0
 _MAX_RECONNECT_DELAY = 30.0
+# Fraction of a token's lifetime after which executor.token.refresh is sent.
+_TOKEN_REFRESH_AT = 0.7
 
 TokenSource = Callable[[], Awaitable[ExecutorTokenResponse]]
 ToolCallHandler = Callable[[ToolCallParams], Awaitable[ToolResultParams]]
@@ -127,6 +130,7 @@ class ExecutorClient:
         heartbeat_load: Callable[[], ExecutorLoad | None] | None = None,
         max_reconnect_attempts: int = DEFAULT_MAX_RECONNECT_ATTEMPTS,
         reconnect_base_delay: float = DEFAULT_RECONNECT_BASE_DELAY,
+        reconnect_max_delay: float = _MAX_RECONNECT_DELAY,
         random: Callable[[], float] = _random.random,
         tool_result_retry_attempts: int = DEFAULT_TOOL_RESULT_RETRY_ATTEMPTS,
         tool_result_retry_base_delay: float = DEFAULT_TOOL_RESULT_RETRY_BASE_DELAY,
@@ -153,6 +157,7 @@ class ExecutorClient:
         self._heartbeat_load = heartbeat_load
         self._max_reconnect_attempts = max_reconnect_attempts
         self._reconnect_base_delay = reconnect_base_delay
+        self._reconnect_max_delay = reconnect_max_delay
         self._random = random
         self._tool_result_retry_attempts = max(1, tool_result_retry_attempts)
         self._tool_result_retry_base_delay = tool_result_retry_base_delay
@@ -411,6 +416,45 @@ class ExecutorClient:
         registered, self._registered = self._registered, asyncio.Event()
         registered.set()
         self._log("info", f"executor registered as {result['executor_id']}")
+        if token.get("expires_in"):
+            self._spawn(self._refresh_token_loop(peer, float(token["expires_in"])))
+
+    async def _refresh_token_loop(self, peer: Peer, lifetime: float) -> None:
+        """Keep peer open across token lifetimes: at 70% of the token's
+        lifetime fetch a new token and send executor.token.refresh. A harness
+        without the method (-32601) closes with 4001 at expiry and the client
+        reconnects as before."""
+        loop = asyncio.get_running_loop()
+        expires_at = loop.time() + lifetime
+        wait = lifetime * _TOKEN_REFRESH_AT
+        while True:
+            await asyncio.sleep(wait)
+            if self._stopped or self._peer is not peer:
+                return
+            try:
+                fresh = await self._fetch_token()
+                await self.call(METHOD_EXECUTOR_TOKEN_REFRESH, {"token": fresh["token"]})
+            except RPCError as error:
+                if error.code in (-32601, -32012):
+                    self._log("info", "harness does not refresh executor tokens; reconnecting at expiry")
+                    return
+                failure: BaseException = error
+            except asyncio.CancelledError:
+                raise
+            except Exception as error:
+                failure = error
+            else:
+                lifetime = float(fresh.get("expires_in") or 0)
+                if lifetime <= 0:
+                    return
+                expires_at = loop.time() + lifetime
+                wait = lifetime * _TOKEN_REFRESH_AT
+                continue
+            self._log("warn", "executor token refresh failed", failure)
+            remaining = expires_at - loop.time()
+            if remaining < 2:
+                return
+            wait = remaining / 2
 
     def _resume_state(self) -> dict[str, Any] | None:
         if not self._executor_id and not self._connection_id and not self._sessions:
@@ -448,7 +492,7 @@ class ExecutorClient:
                 return
             attempt = self._reconnect_attempts
             self._reconnect_attempts += 1
-            delay = min(self._reconnect_base_delay * (1 << attempt), _MAX_RECONNECT_DELAY)
+            delay = min(self._reconnect_base_delay * (1 << attempt), self._reconnect_max_delay)
             delay *= 0.5 + self._random() * 0.5
             self._log("info", f"reconnecting executor channel in {delay:.3f}s")
             await asyncio.sleep(delay)

{bma_executor_sdk-0.4.4 → bma_executor_sdk-0.4.5}/src/bma_executor_sdk/generated.py

@@ -184,6 +184,7 @@ class Cursors(TypedDict):
 class DisplayCapability(TypedDict):
     """v1.1 display object. v1 sent a boolean; the server accepts both."""
     rfb: NotRequired[bool]
+    desktop: NotRequired[bool]
 
 class EvaluatedPermission(TypedDict):
     """Permission decision the executor applied to a tool use. ask means the executor opened an interaction.request for it."""
@@ -236,6 +237,10 @@ class ExecutorResume(TypedDict):
     last_connection_id: NotRequired[str]
     active_sessions: NotRequired[list[str]]
 
+class ExecutorTokenRefreshResult(TypedDict):
+    """executor.token.refresh result: the connection now closes with 4001 at expires_at."""
+    expires_at: str
+
 class ExecutorTokenRequest(TypedDict):
     """POST /v1/executors/token body. The bearer is an environment key, or a machine daemon token. An empty environment_id with a machine token requests a machine-scoped executor: its executor_id is exec_<machine_id>, stable across refreshes, and the JWT carries machine_id and daemon_token_id."""
     environment_id: str
@@ -816,6 +821,10 @@ class ExecutorHeartbeatParams(TypedDict):
     active_sessions: list[str]
     load: NotRequired[ExecutorLoad]
 
+class ExecutorTokenRefreshParams(TypedDict):
+    "Params object of executor.token.refresh."
+    token: str
+
 class ExecutorCapabilitiesUpdateParams(TypedDict):
     "Params object of executor.capabilities.update."
     capabilities: Capabilities
@@ -1082,6 +1091,7 @@ class MethodSpec:
 
 METHOD_EXECUTOR_REGISTER = "executor.register"
 METHOD_EXECUTOR_HEARTBEAT = "executor.heartbeat"
+METHOD_EXECUTOR_TOKEN_REFRESH = "executor.token.refresh"
 METHOD_EXECUTOR_CAPABILITIES_UPDATE = "executor.capabilities.update"
 METHOD_EXECUTOR_DRAIN = "executor.drain"
 METHOD_EXECUTOR_CLOSE = "executor.close"
@@ -1119,6 +1129,7 @@ METHOD_INTERACTION_CANCEL = "interaction.cancel"
 METHODS: dict[str, MethodSpec] = {
     "executor.register": MethodSpec(name="executor.register", direction="executor-to-harness", kind="request", since="bma.executor.v1", params_type="ExecutorRegisterParams", result_type="ExecutorRegisterResult", capability=None, idempotent_by=None),
     "executor.heartbeat": MethodSpec(name="executor.heartbeat", direction="executor-to-harness", kind="request", since="bma.executor.v1", params_type="ExecutorHeartbeatParams", result_type="ExecutorHeartbeatResult", capability=None, idempotent_by=None),
+    "executor.token.refresh": MethodSpec(name="executor.token.refresh", direction="executor-to-harness", kind="request", since="bma.executor.v1.1", params_type="ExecutorTokenRefreshParams", result_type="ExecutorTokenRefreshResult", capability=None, idempotent_by=None),
     "executor.capabilities.update": MethodSpec(name="executor.capabilities.update", direction="executor-to-harness", kind="notification", since="bma.executor.v1", params_type="ExecutorCapabilitiesUpdateParams", result_type=None, capability=None, idempotent_by=None),
     "executor.drain": MethodSpec(name="executor.drain", direction="harness-to-executor", kind="request", since="bma.executor.v1", params_type="ExecutorDrainParams", result_type="ExecutorDrainResult", capability=None, idempotent_by=None),
     "executor.close": MethodSpec(name="executor.close", direction="bidirectional", kind="notification", since="bma.executor.v1", params_type="ExecutorCloseParams", result_type=None, capability=None, idempotent_by=None),

bma_executor_sdk-0.4.5/tests/test_executor_token_refresh.py

@@ -0,0 +1,88 @@
+"""executor.token.refresh: one control connection across token lifetimes,
+and the 4001 reconnect on a harness without the method."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import Callable
+from typing import Any
+
+from websockets.asyncio.server import ServerConnection, serve
+
+import bma_executor_sdk as bx
+
+EXECUTOR = {"name": "py-test", "os": "linux", "arch": "arm64", "version": "0.1.0"}
+
+
+async def fake_harness(answer_refresh: Callable[[dict[str, Any]], dict[str, Any]]):
+    refreshes: list[str] = []
+    dials: list[int] = []
+
+    async def handler(ws: ServerConnection) -> None:
+        dials.append(1)
+        async for raw in ws:
+            frame = json.loads(raw)
+            if "id" not in frame or "method" not in frame:
+                continue
+            if frame["method"] == "executor.register":
+                reply: dict[str, Any] = {
+                    "result": {
+                        "protocol": "bma.executor.v1.1", "executor_id": "exec_test", "connection_id": "conn_test",
+                        "server_time": "2026-11-01T00:00:00Z", "heartbeat_interval_ms": 60000, "lease_ttl_ms": 60000,
+                        "max_control_frame_bytes": 65536, "max_mcp_frame_bytes": 1 << 20,
+                    }
+                }
+            elif frame["method"] == "executor.token.refresh":
+                refreshes.append(frame["params"]["token"])
+                reply = answer_refresh(frame)
+            else:
+                reply = {"result": {"accepted": True}}
+            await ws.send(json.dumps({"jsonrpc": "2.0", "id": frame["id"], **reply}))
+
+    server = await serve(handler, "127.0.0.1", 0, subprotocols=["bma.executor.v1.1"])
+    port = server.sockets[0].getsockname()[1]
+    return server, f"ws://127.0.0.1:{port}", refreshes, dials
+
+
+def client(url: str) -> bx.ExecutorClient:
+    minted = 0
+
+    async def source() -> Any:
+        nonlocal minted
+        minted += 1
+        return {"executor_id": "exec_test", "token": f"tok-{minted}", "expires_in": 1, "ws_url": url, "channel_scope": []}
+
+    return bx.ExecutorClient(environment_id="", executor=EXECUTOR, token_source=source)  # type: ignore[arg-type]
+
+
+async def test_refreshes_inside_the_connection() -> None:
+    server, url, refreshes, dials = await fake_harness(lambda _: {"result": {"expires_at": "2026-11-01T00:00:01Z"}})
+    executor = client(url)
+    try:
+        await executor.start()
+        for _ in range(400):
+            if len(refreshes) >= 3:
+                break
+            await asyncio.sleep(0.01)
+        assert refreshes[:3] == ["tok-2", "tok-3", "tok-4"]
+        assert len(dials) == 1
+    finally:
+        await executor.stop()
+        server.close()
+        await server.wait_closed()
+
+
+async def test_stops_refreshing_on_method_not_found() -> None:
+    server, url, refreshes, _ = await fake_harness(
+        lambda _: {"error": {"code": -32601, "message": "unknown method executor.token.refresh"}}
+    )
+    executor = client(url)
+    try:
+        await executor.start()
+        await asyncio.sleep(2.5)
+        assert refreshes == ["tok-2"]
+    finally:
+        await executor.stop()
+        server.close()
+        await server.wait_closed()