bma-executor-sdk 0.4.7__tar.gz → 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. {bma_executor_sdk-0.4.7 → bma_executor_sdk-1.0.0}/PKG-INFO +28 -18
  2. {bma_executor_sdk-0.4.7 → bma_executor_sdk-1.0.0}/README.md +26 -16
  3. bma_executor_sdk-1.0.0/examples/executor_minimal.py +57 -0
  4. {bma_executor_sdk-0.4.7 → bma_executor_sdk-1.0.0}/examples/harness_loopback.py +3 -3
  5. {bma_executor_sdk-0.4.7 → bma_executor_sdk-1.0.0}/pyproject.toml +9 -3
  6. {bma_executor_sdk-0.4.7 → bma_executor_sdk-1.0.0}/src/bma_executor_sdk/__init__.py +40 -0
  7. bma_executor_sdk-1.0.0/src/bma_executor_sdk/_methods.py +36 -0
  8. bma_executor_sdk-1.0.0/src/bma_executor_sdk/_npipe.py +281 -0
  9. {bma_executor_sdk-0.4.7 → bma_executor_sdk-1.0.0}/src/bma_executor_sdk/agent.py +5 -5
  10. {bma_executor_sdk-0.4.7 → bma_executor_sdk-1.0.0}/src/bma_executor_sdk/client.py +100 -38
  11. {bma_executor_sdk-0.4.7 → bma_executor_sdk-1.0.0}/src/bma_executor_sdk/generated.py +82 -2
  12. {bma_executor_sdk-0.4.7 → bma_executor_sdk-1.0.0}/src/bma_executor_sdk/harness.py +110 -23
  13. bma_executor_sdk-1.0.0/src/bma_executor_sdk/methods.py +95 -0
  14. bma_executor_sdk-1.0.0/src/bma_executor_sdk/py.typed +0 -0
  15. bma_executor_sdk-1.0.0/src/bma_executor_sdk/tools.py +191 -0
  16. {bma_executor_sdk-0.4.7 → bma_executor_sdk-1.0.0}/src/bma_executor_sdk/transport.py +13 -5
  17. {bma_executor_sdk-0.4.7 → bma_executor_sdk-1.0.0}/tests/executor_helpers.py +28 -0
  18. bma_executor_sdk-1.0.0/tests/test_base_url.py +17 -0
  19. {bma_executor_sdk-0.4.7 → bma_executor_sdk-1.0.0}/tests/test_executor_conformance.py +1 -1
  20. {bma_executor_sdk-0.4.7 → bma_executor_sdk-1.0.0}/tests/test_executor_contract.py +1 -1
  21. {bma_executor_sdk-0.4.7 → bma_executor_sdk-1.0.0}/tests/test_executor_interop.py +28 -12
  22. {bma_executor_sdk-0.4.7 → bma_executor_sdk-1.0.0}/tests/test_executor_runtime.py +39 -24
  23. bma_executor_sdk-1.0.0/tests/test_npipe.py +53 -0
  24. bma_executor_sdk-1.0.0/tests/test_review.py +95 -0
  25. bma_executor_sdk-1.0.0/tests/test_typed_tools.py +144 -0
  26. bma_executor_sdk-1.0.0/tests/typecheck/typed_tools.py +60 -0
  27. bma_executor_sdk-0.4.7/examples/executor_minimal.py +0 -64
  28. {bma_executor_sdk-0.4.7 → bma_executor_sdk-1.0.0}/.gitignore +0 -0
  29. {bma_executor_sdk-0.4.7 → bma_executor_sdk-1.0.0}/examples/agent_minimal.py +0 -0
  30. {bma_executor_sdk-0.4.7 → bma_executor_sdk-1.0.0}/src/bma_executor_sdk/_rpc.py +0 -0
  31. {bma_executor_sdk-0.4.7 → bma_executor_sdk-1.0.0}/tests/test_close_codes.py +0 -0
  32. {bma_executor_sdk-0.4.7 → bma_executor_sdk-1.0.0}/tests/test_executor_token_refresh.py +0 -0
@@ -1,8 +1,8 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: bma-executor-sdk
3
- Version: 0.4.7
3
+ Version: 1.0.0
4
4
  Summary: BMA executor protocol (bma.executor.v1.1): executor, harness and agent ends on asyncio with WebSocket, Unix socket and in-process transports.
5
- Project-URL: Repository, https://github.com/beeos-ai/bma-sdks
5
+ Project-URL: Repository, https://github.com/beeos-ai/bma-executor-sdk
6
6
  License-Expression: Apache-2.0
7
7
  Requires-Python: >=3.10
8
8
  Requires-Dist: httpx<1,>=0.27
@@ -13,53 +13,60 @@ Description-Content-Type: text/markdown
13
13
 
14
14
  [![PyPI](https://img.shields.io/pypi/v/bma-executor-sdk.svg)](https://pypi.org/project/bma-executor-sdk/)
15
15
 
16
- asyncio executor (`ExecutorClient`), harness (`Harness`) and agent ends of the BMA Executor Protocol `bma.executor.v1.1`, the counterpart of the [Go `executor` module](../README.md). Protocol types are TypedDicts generated into `bma_executor_sdk/generated.py` from the contract in [`contracts/bma/executor`](../../contracts/bma/executor), so messages are plain JSON dicts.
16
+ asyncio executor (`ExecutorClient`), harness (`Harness`) and agent ends of the BMA Executor Protocol `bma.executor.v1.1`, the counterpart of the [Go `executor` module](../README.md). Protocol types are TypedDicts generated into `bma_executor_sdk/generated.py` from the contract in [`contracts/bma/executor`](../contracts/bma/executor), so messages are plain JSON dicts.
17
17
 
18
18
  | | |
19
19
  | --- | --- |
20
- | Version | 0.4.7 (tag `executor-python/v0.4.7`), see [CHANGELOG](../../CHANGELOG.md) |
21
- | Protocol | `bma.executor.v1.1` (contract 1.1.0, [`lock.json`](../../contracts/bma/executor/lock.json)) |
20
+ | Version | 0.4.9 (tag `v0.4.9`), see [CHANGELOG](../CHANGELOG.md) |
21
+ | Protocol | `bma.executor.v1.1` (contract 1.1.0, [`lock.json`](../contracts/bma/executor/lock.json)) |
22
22
  | Python | 3.10 or newer; depends on `httpx` and `websockets` |
23
- | Integration guide | [docs/executor](../../docs/executor/README.md) ([中文](../../docs/executor/README.zh-CN.md)) |
23
+ | Integration guide | [docs/executor](../docs/executor/README.md) ([中文](../docs/executor/README.zh-CN.md)) |
24
24
 
25
25
  ```sh
26
- pip install bma-executor-sdk==0.4.7
26
+ pip install bma-executor-sdk==0.4.9
27
27
  ```
28
28
 
29
- The REST / façade client is the separate package [`bma-sdk`](../../python).
29
+ The REST / façade client is the separate package [`bma-sdk`](https://github.com/beeos-ai/bma-sdk/tree/main/python).
30
30
 
31
31
  ## Executor quick start
32
32
 
33
33
  ```python
34
34
  import asyncio, os
35
- from bma_executor_sdk import ExecutorClient
35
+ from bma_executor_sdk import BashInput, BashResult, ExecutorClient, ToolContext
36
36
 
37
37
  async def main() -> None:
38
38
  client = ExecutorClient(
39
+ base_url=os.environ["BMA_BASE_URL"], # required: see below
39
40
  environment_key=os.environ["BMA_ENVIRONMENT_KEY"],
40
41
  environment_id=os.environ["BMA_ENVIRONMENT_ID"],
41
42
  executor={"name": "my-executor", "os": "linux", "arch": "arm64", "version": "0.1.0"},
42
43
  )
43
44
 
44
- async def on_tool_call(call):
45
- return {"session_id": call["session_id"], "tool_call_id": call["tool_call_id"],
46
- "outcome": "succeeded", "is_error": False, "content": [{"type": "text", "text": "ok"}]}
45
+ @client.tools.bash.handler # one typed slot per built-in tool; only registered tools are advertised
46
+ async def bash(input: BashInput, ctx: ToolContext) -> BashResult:
47
+ proc = await asyncio.create_subprocess_shell(
48
+ input["command"], stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE)
49
+ out, err = await proc.communicate()
50
+ return BashResult(stdout=out.decode(), stderr=err.decode(), exit_code=proc.returncode or 0)
47
51
 
48
- client.on_tool_call(on_tool_call)
49
52
  await client.start()
50
53
  await asyncio.Event().wait()
51
54
 
52
55
  asyncio.run(main())
53
56
  ```
54
57
 
58
+ Set `base_url` to your BMA deployment: the hosted service is in early access and the default `DEFAULT_BASE_URL` (`https://api.bma.beeos.ai`) does not resolve yet. It is the deployment origin, the same value as `BMA_BASE_URL` in bma-sdk (for example `https://api.staging.bma.beeos.ai`); the client posts the environment key to `{base_url}/v1/executors/token` and drops a trailing `/api/v1`. The SDK does not read `BMA_BASE_URL` itself. A `token_source` carries its own channel URL.
59
+
55
60
  A complete version that runs bash and stops the process on cancellation is [`examples/executor_minimal.py`](examples/executor_minimal.py); set `BMA_HARNESS_URL` (`ws://…` or `unix:///path.sock`) to connect it to a local harness instead of BMA.
56
61
 
57
62
  Behavior matches the Go SDK:
58
63
 
64
+ - A handler returns a string, content blocks, `ToolResult(content, is_error, artifacts)` or (bash) `BashResult`, rendered like the Go `Core`; `raise ToolError(text)` reports a tool-level error (`is_error: true`), any other exception is `outcome: "failed"`. The harness calls tools as `await session.tools.bash.call({"command": "ls"})`.
59
65
  - `tool.cancel` cancels the handler's task and reports `outcome: "canceled"`; duplicate `tool.call` ids run once.
60
66
  - `tool.result` retries `-32009` / `-32004` / `retryable` errors and hands a lost result to `on_tool_result_lost`.
61
67
  - Reconnect resumes with `resume.executor_id` / `active_sessions`; close codes 1008, 4002, 4003 and 4004 stop the client (4001 and 4005 reconnect).
62
- - Call `session_ready` after setup and `session_ended` after cleanup. `on_request(method, handler)` serves `process.*`, `terminal.*` or `skill.install` yourself; there is no execution `Core` in Python.
68
+ - Call `session_ready` after setup and `session_ended` after cleanup. `client.on_request(methods.PROCESS_START, handler)` serves `process.*`, `terminal.*`, `skill.install` or `workspace.backup` yourself with the contract's TypedDicts; `await client.call(methods.SESSION_EVENT, params)` / `await client.notify(methods.TOOL_PROGRESS, params)` send typed methods (`bma_executor_sdk.methods`). There is no execution `Core` in Python.
69
+ - Input missing a required member fails the call before the handler runs; a `tool.call` for a tool without a handler is refused with `-32012` before the ack; `shell` / `files` are enabled while a handler of the group is registered unless set `enabled: False`, and a handler registered after `start()` sends `executor.capabilities.update`. `BashResult` beyond `INLINE_RESULT_BYTES` (or `truncated=True`) is cut to Go Core's preview. The `computer_*` tools get slots once the contract defines their input.
63
70
 
64
71
  ## Harness quick start
65
72
 
@@ -87,13 +94,14 @@ Chosen by the channel URL of the token source:
87
94
  | --- | --- | --- |
88
95
  | WebSocket (`ws://`, `wss://`) | default | `await harness.serve(host, port)` |
89
96
  | WebSocket over a Unix domain socket (`unix:///path.sock`) | `token_source=static_token("unix:///path.sock", token)` | `await harness.serve_unix(path)` |
97
+ | Windows named pipe (`npipe:////./pipe/<name>`, Windows ProactorEventLoop) | `token_source=static_token("npipe:////./pipe/<name>", token)` | `await harness.serve_npipe(name)` |
90
98
  | In process | `dialer=harness.inprocess_dialer()` | — |
91
99
 
92
- The executor-listens local socket and Windows named pipes are not implemented in Python (use the Go or TypeScript SDK). See [local connection](../../docs/executor/local-connection.md).
100
+ The executor-listens local socket is not implemented in Python (use the Go or TypeScript SDK); named pipes need the Windows `ProactorEventLoop` (the asyncio default there) and are tested on a Windows runner in CI. See [local connection](../docs/executor/local-connection.md).
93
101
 
94
102
  ## Agent executors
95
103
 
96
- `client.serve_agent(handler, capability)` serves the `agent` capability; `handler` implements `open_turn`, `run_turn` and `close_session` (async; cancellation is task cancellation), and `run_turn` uses `turn.emit`, `await turn.delta(...)`, `turn.inputs` (an `asyncio.Queue`) and `turn.request_interaction`. The harness side is `Harness(agent=platform)` with an `AgentPlatform`. See [agent capability](../../docs/executor/agent-capability.md).
104
+ `client.serve_agent(handler, capability)` serves the `agent` capability; `handler` implements `open_turn`, `run_turn` and `close_session` (async; cancellation is task cancellation), and `run_turn` uses `turn.emit`, `await turn.delta(...)`, `turn.inputs` (an `asyncio.Queue`) and `turn.request_interaction`. The harness side is `Harness(agent=platform)` with an `AgentPlatform`. See [agent capability](../docs/executor/agent-capability.md).
97
105
 
98
106
  ## Go ↔ Python
99
107
 
@@ -102,8 +110,10 @@ The executor-listens local socket and Windows named pipes are not implemented in
102
110
  | `NewClient(Options{...})` | `ExecutorClient(environment_id=..., executor=..., ...)` |
103
111
  | `Options.TokenSource`, `StaticToken(url, token)` | `token_source=`, `static_token(url, token)` |
104
112
  | `Client.Start` / `Stop` / `State` / `ExecutorID` / `ConnectionID` / `ActiveSessions` | `start()` / `stop(reason)` / `state` / `executor_id` / `connection_id` / `active_sessions` |
105
- | `OnToolCall` / `OnSessionAssign` / `OnSessionStop` / `OnDrain` / `OnRequest` / `OnNotification` | `on_tool_call` / `on_session_assign` / `on_session_stop` / `on_drain` / `on_request` / `on_notification` |
106
- | `Call` / `Notify` / `ReportToolResult` / `SessionReady` / `SessionEnded` / `OpenMCPChannel` | `call` / `notify` / `report_tool_result` / `session_ready` / `session_ended` / `open_mcp_channel` |
113
+ | `Tools.Bash.Handle(fn)` | `@client.tools.bash.handler` |
114
+ | `OnSessionAssign` / `OnSessionStop` / `OnDrain` | `on_session_assign` / `on_session_stop` / `on_drain` |
115
+ | `Requests.X.Handle(client, fn)` / `Calls.X.Call(ctx, client, p)` / `Notifications.X.Notify(ctx, client, p)` | `on_request(methods.X, fn)` / `await call(methods.X, p)` / `await notify(methods.X, p)` |
116
+ | `ReportToolResult` / `SessionReady` / `SessionEnded` / `OpenMCPChannel` | `report_tool_result` / `session_ready` / `session_ended` / `open_mcp_channel` |
107
117
  | `ServeAgent(handler, AgentCapability)` | `serve_agent(handler, capability)` |
108
118
  | `AgentHandler.OpenTurn` / `RunTurn` / `CloseSession` | `open_turn` / `run_turn` / `close_session` |
109
119
  | `AgentTurn.Emit` / `EmitWithID` / `NewEventID` / `Delta` / `Flush` / `Inputs()` / `RequestInteraction` / `CancelInteraction` | `emit` / `emit_with_id` / `new_event_id` / `await delta` / `await flush` / `inputs` / `request_interaction` / `cancel_interaction` |
@@ -2,53 +2,60 @@
2
2
 
3
3
  [![PyPI](https://img.shields.io/pypi/v/bma-executor-sdk.svg)](https://pypi.org/project/bma-executor-sdk/)
4
4
 
5
- asyncio executor (`ExecutorClient`), harness (`Harness`) and agent ends of the BMA Executor Protocol `bma.executor.v1.1`, the counterpart of the [Go `executor` module](../README.md). Protocol types are TypedDicts generated into `bma_executor_sdk/generated.py` from the contract in [`contracts/bma/executor`](../../contracts/bma/executor), so messages are plain JSON dicts.
5
+ asyncio executor (`ExecutorClient`), harness (`Harness`) and agent ends of the BMA Executor Protocol `bma.executor.v1.1`, the counterpart of the [Go `executor` module](../README.md). Protocol types are TypedDicts generated into `bma_executor_sdk/generated.py` from the contract in [`contracts/bma/executor`](../contracts/bma/executor), so messages are plain JSON dicts.
6
6
 
7
7
  | | |
8
8
  | --- | --- |
9
- | Version | 0.4.7 (tag `executor-python/v0.4.7`), see [CHANGELOG](../../CHANGELOG.md) |
10
- | Protocol | `bma.executor.v1.1` (contract 1.1.0, [`lock.json`](../../contracts/bma/executor/lock.json)) |
9
+ | Version | 0.4.9 (tag `v0.4.9`), see [CHANGELOG](../CHANGELOG.md) |
10
+ | Protocol | `bma.executor.v1.1` (contract 1.1.0, [`lock.json`](../contracts/bma/executor/lock.json)) |
11
11
  | Python | 3.10 or newer; depends on `httpx` and `websockets` |
12
- | Integration guide | [docs/executor](../../docs/executor/README.md) ([中文](../../docs/executor/README.zh-CN.md)) |
12
+ | Integration guide | [docs/executor](../docs/executor/README.md) ([中文](../docs/executor/README.zh-CN.md)) |
13
13
 
14
14
  ```sh
15
- pip install bma-executor-sdk==0.4.7
15
+ pip install bma-executor-sdk==0.4.9
16
16
  ```
17
17
 
18
- The REST / façade client is the separate package [`bma-sdk`](../../python).
18
+ The REST / façade client is the separate package [`bma-sdk`](https://github.com/beeos-ai/bma-sdk/tree/main/python).
19
19
 
20
20
  ## Executor quick start
21
21
 
22
22
  ```python
23
23
  import asyncio, os
24
- from bma_executor_sdk import ExecutorClient
24
+ from bma_executor_sdk import BashInput, BashResult, ExecutorClient, ToolContext
25
25
 
26
26
  async def main() -> None:
27
27
  client = ExecutorClient(
28
+ base_url=os.environ["BMA_BASE_URL"], # required: see below
28
29
  environment_key=os.environ["BMA_ENVIRONMENT_KEY"],
29
30
  environment_id=os.environ["BMA_ENVIRONMENT_ID"],
30
31
  executor={"name": "my-executor", "os": "linux", "arch": "arm64", "version": "0.1.0"},
31
32
  )
32
33
 
33
- async def on_tool_call(call):
34
- return {"session_id": call["session_id"], "tool_call_id": call["tool_call_id"],
35
- "outcome": "succeeded", "is_error": False, "content": [{"type": "text", "text": "ok"}]}
34
+ @client.tools.bash.handler # one typed slot per built-in tool; only registered tools are advertised
35
+ async def bash(input: BashInput, ctx: ToolContext) -> BashResult:
36
+ proc = await asyncio.create_subprocess_shell(
37
+ input["command"], stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE)
38
+ out, err = await proc.communicate()
39
+ return BashResult(stdout=out.decode(), stderr=err.decode(), exit_code=proc.returncode or 0)
36
40
 
37
- client.on_tool_call(on_tool_call)
38
41
  await client.start()
39
42
  await asyncio.Event().wait()
40
43
 
41
44
  asyncio.run(main())
42
45
  ```
43
46
 
47
+ Set `base_url` to your BMA deployment: the hosted service is in early access and the default `DEFAULT_BASE_URL` (`https://api.bma.beeos.ai`) does not resolve yet. It is the deployment origin, the same value as `BMA_BASE_URL` in bma-sdk (for example `https://api.staging.bma.beeos.ai`); the client posts the environment key to `{base_url}/v1/executors/token` and drops a trailing `/api/v1`. The SDK does not read `BMA_BASE_URL` itself. A `token_source` carries its own channel URL.
48
+
44
49
  A complete version that runs bash and stops the process on cancellation is [`examples/executor_minimal.py`](examples/executor_minimal.py); set `BMA_HARNESS_URL` (`ws://…` or `unix:///path.sock`) to connect it to a local harness instead of BMA.
45
50
 
46
51
  Behavior matches the Go SDK:
47
52
 
53
+ - A handler returns a string, content blocks, `ToolResult(content, is_error, artifacts)` or (bash) `BashResult`, rendered like the Go `Core`; `raise ToolError(text)` reports a tool-level error (`is_error: true`), any other exception is `outcome: "failed"`. The harness calls tools as `await session.tools.bash.call({"command": "ls"})`.
48
54
  - `tool.cancel` cancels the handler's task and reports `outcome: "canceled"`; duplicate `tool.call` ids run once.
49
55
  - `tool.result` retries `-32009` / `-32004` / `retryable` errors and hands a lost result to `on_tool_result_lost`.
50
56
  - Reconnect resumes with `resume.executor_id` / `active_sessions`; close codes 1008, 4002, 4003 and 4004 stop the client (4001 and 4005 reconnect).
51
- - Call `session_ready` after setup and `session_ended` after cleanup. `on_request(method, handler)` serves `process.*`, `terminal.*` or `skill.install` yourself; there is no execution `Core` in Python.
57
+ - Call `session_ready` after setup and `session_ended` after cleanup. `client.on_request(methods.PROCESS_START, handler)` serves `process.*`, `terminal.*`, `skill.install` or `workspace.backup` yourself with the contract's TypedDicts; `await client.call(methods.SESSION_EVENT, params)` / `await client.notify(methods.TOOL_PROGRESS, params)` send typed methods (`bma_executor_sdk.methods`). There is no execution `Core` in Python.
58
+ - Input missing a required member fails the call before the handler runs; a `tool.call` for a tool without a handler is refused with `-32012` before the ack; `shell` / `files` are enabled while a handler of the group is registered unless set `enabled: False`, and a handler registered after `start()` sends `executor.capabilities.update`. `BashResult` beyond `INLINE_RESULT_BYTES` (or `truncated=True`) is cut to Go Core's preview. The `computer_*` tools get slots once the contract defines their input.
52
59
 
53
60
  ## Harness quick start
54
61
 
@@ -76,13 +83,14 @@ Chosen by the channel URL of the token source:
76
83
  | --- | --- | --- |
77
84
  | WebSocket (`ws://`, `wss://`) | default | `await harness.serve(host, port)` |
78
85
  | WebSocket over a Unix domain socket (`unix:///path.sock`) | `token_source=static_token("unix:///path.sock", token)` | `await harness.serve_unix(path)` |
86
+ | Windows named pipe (`npipe:////./pipe/<name>`, Windows ProactorEventLoop) | `token_source=static_token("npipe:////./pipe/<name>", token)` | `await harness.serve_npipe(name)` |
79
87
  | In process | `dialer=harness.inprocess_dialer()` | — |
80
88
 
81
- The executor-listens local socket and Windows named pipes are not implemented in Python (use the Go or TypeScript SDK). See [local connection](../../docs/executor/local-connection.md).
89
+ The executor-listens local socket is not implemented in Python (use the Go or TypeScript SDK); named pipes need the Windows `ProactorEventLoop` (the asyncio default there) and are tested on a Windows runner in CI. See [local connection](../docs/executor/local-connection.md).
82
90
 
83
91
  ## Agent executors
84
92
 
85
- `client.serve_agent(handler, capability)` serves the `agent` capability; `handler` implements `open_turn`, `run_turn` and `close_session` (async; cancellation is task cancellation), and `run_turn` uses `turn.emit`, `await turn.delta(...)`, `turn.inputs` (an `asyncio.Queue`) and `turn.request_interaction`. The harness side is `Harness(agent=platform)` with an `AgentPlatform`. See [agent capability](../../docs/executor/agent-capability.md).
93
+ `client.serve_agent(handler, capability)` serves the `agent` capability; `handler` implements `open_turn`, `run_turn` and `close_session` (async; cancellation is task cancellation), and `run_turn` uses `turn.emit`, `await turn.delta(...)`, `turn.inputs` (an `asyncio.Queue`) and `turn.request_interaction`. The harness side is `Harness(agent=platform)` with an `AgentPlatform`. See [agent capability](../docs/executor/agent-capability.md).
86
94
 
87
95
  ## Go ↔ Python
88
96
 
@@ -91,8 +99,10 @@ The executor-listens local socket and Windows named pipes are not implemented in
91
99
  | `NewClient(Options{...})` | `ExecutorClient(environment_id=..., executor=..., ...)` |
92
100
  | `Options.TokenSource`, `StaticToken(url, token)` | `token_source=`, `static_token(url, token)` |
93
101
  | `Client.Start` / `Stop` / `State` / `ExecutorID` / `ConnectionID` / `ActiveSessions` | `start()` / `stop(reason)` / `state` / `executor_id` / `connection_id` / `active_sessions` |
94
- | `OnToolCall` / `OnSessionAssign` / `OnSessionStop` / `OnDrain` / `OnRequest` / `OnNotification` | `on_tool_call` / `on_session_assign` / `on_session_stop` / `on_drain` / `on_request` / `on_notification` |
95
- | `Call` / `Notify` / `ReportToolResult` / `SessionReady` / `SessionEnded` / `OpenMCPChannel` | `call` / `notify` / `report_tool_result` / `session_ready` / `session_ended` / `open_mcp_channel` |
102
+ | `Tools.Bash.Handle(fn)` | `@client.tools.bash.handler` |
103
+ | `OnSessionAssign` / `OnSessionStop` / `OnDrain` | `on_session_assign` / `on_session_stop` / `on_drain` |
104
+ | `Requests.X.Handle(client, fn)` / `Calls.X.Call(ctx, client, p)` / `Notifications.X.Notify(ctx, client, p)` | `on_request(methods.X, fn)` / `await call(methods.X, p)` / `await notify(methods.X, p)` |
105
+ | `ReportToolResult` / `SessionReady` / `SessionEnded` / `OpenMCPChannel` | `report_tool_result` / `session_ready` / `session_ended` / `open_mcp_channel` |
96
106
  | `ServeAgent(handler, AgentCapability)` | `serve_agent(handler, capability)` |
97
107
  | `AgentHandler.OpenTurn` / `RunTurn` / `CloseSession` | `open_turn` / `run_turn` / `close_session` |
98
108
  | `AgentTurn.Emit` / `EmitWithID` / `NewEventID` / `Delta` / `Flush` / `Inputs()` / `RequestInteraction` / `CancelInteraction` | `emit` / `emit_with_id` / `new_event_id` / `await delta` / `await flush` / `inputs` / `request_interaction` / `cancel_interaction` |
@@ -0,0 +1,57 @@
1
+ """Minimal executor: registers with BMA and answers bash tool calls.
2
+
3
+ BMA_ENVIRONMENT_KEY=... BMA_ENVIRONMENT_ID=... python executor_minimal.py
4
+
5
+ Set BMA_HARNESS_URL (ws://..., unix:///path.sock) to connect to a local
6
+ harness instead of BMA, for example the one harness_loopback.py starts.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import asyncio
12
+ import os
13
+ import platform
14
+
15
+ from bma_executor_sdk import BashInput, BashResult, ExecutorClient, ToolContext, static_token
16
+
17
+
18
+ async def run_bash(input: BashInput, ctx: ToolContext) -> BashResult:
19
+ proc = await asyncio.create_subprocess_shell(
20
+ input["command"], cwd=input.get("cwd"), stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE,
21
+ )
22
+ try:
23
+ stdout, stderr = await proc.communicate()
24
+ except asyncio.CancelledError: # tool.cancel or the deadline: stop the process
25
+ proc.kill()
26
+ raise
27
+ return BashResult(stdout=stdout.decode(errors="replace"), stderr=stderr.decode(errors="replace"), exit_code=proc.returncode or 0)
28
+
29
+
30
+ def make_client() -> ExecutorClient:
31
+ info = {"name": "py-executor", "os": platform.system().lower(), "arch": platform.machine(), "version": "0.1.0"}
32
+ harness_url = os.environ.get("BMA_HARNESS_URL")
33
+ if harness_url:
34
+ client = ExecutorClient(environment_id="env_local", executor=info, token_source=static_token(harness_url)) # type: ignore[arg-type]
35
+ else:
36
+ client = ExecutorClient(
37
+ environment_id=os.environ["BMA_ENVIRONMENT_ID"],
38
+ environment_key=os.environ["BMA_ENVIRONMENT_KEY"],
39
+ base_url=os.environ.get("BMA_BASE_URL", "https://api.bma.beeos.ai"),
40
+ executor=info, # type: ignore[arg-type]
41
+ )
42
+ client.tools.bash.handler(run_bash) # advertises the shell capability
43
+ return client
44
+
45
+
46
+ async def main() -> None:
47
+ client = make_client()
48
+ registered = await client.start()
49
+ print("registered as", registered["executor_id"])
50
+ try:
51
+ await asyncio.Event().wait()
52
+ finally:
53
+ await client.stop("shutdown")
54
+
55
+
56
+ if __name__ == "__main__":
57
+ asyncio.run(main())
@@ -28,14 +28,14 @@ async def main(unix_path: str | None) -> None:
28
28
  return {"accepted": True, "session_id": params["session_id"]}
29
29
 
30
30
  client.on_session_assign(on_assign)
31
- client.on_tool_call(run_bash)
31
+ client.tools.bash.handler(run_bash)
32
32
  await client.start()
33
33
  try:
34
34
  executor = await harness.wait_executor()
35
35
  session = await executor.assign_session({"session_id": "ses_local"}) # type: ignore[typeddict-item]
36
36
  await session.ready()
37
- result = await session.call_tool({"tool": "bash", "input": {"command": "echo hello from the hand"}}) # type: ignore[typeddict-item]
38
- print(result["outcome"], result["content"][0]["text"].strip())
37
+ result = await session.tools.bash.call({"command": "echo hello from the hand"})
38
+ print(result["outcome"], [block.get("text", "").strip() for block in result["content"]])
39
39
  await session.stop("done")
40
40
  finally:
41
41
  await client.stop("done")
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "bma-executor-sdk"
3
- version = "0.4.7"
3
+ version = "1.0.0"
4
4
  description = "BMA executor protocol (bma.executor.v1.1): executor, harness and agent ends on asyncio with WebSocket, Unix socket and in-process transports."
5
5
  readme = "README.md"
6
6
  license = "Apache-2.0"
@@ -8,10 +8,10 @@ requires-python = ">=3.10"
8
8
  dependencies = ["httpx>=0.27,<1", "websockets>=14,<17"]
9
9
 
10
10
  [project.urls]
11
- Repository = "https://github.com/beeos-ai/bma-sdks"
11
+ Repository = "https://github.com/beeos-ai/bma-executor-sdk"
12
12
 
13
13
  [dependency-groups]
14
- dev = ["pytest>=8", "pytest-asyncio>=0.24"]
14
+ dev = ["pytest>=8", "pytest-asyncio>=0.24", "pyright==1.1.407"]
15
15
 
16
16
  [build-system]
17
17
  requires = ["hatchling>=1.26"]
@@ -24,3 +24,9 @@ packages = ["src/bma_executor_sdk"]
24
24
  testpaths = ["tests"]
25
25
  asyncio_mode = "auto"
26
26
  asyncio_default_fixture_loop_scope = "function"
27
+
28
+ [tool.pyright]
29
+ include = ["tests/typecheck", "examples/executor_minimal.py"]
30
+ pythonVersion = "3.10"
31
+ strict = ["tests/typecheck"]
32
+ reportUnnecessaryTypeIgnoreComment = "error"
@@ -19,17 +19,33 @@ from .client import (
19
19
  MCPChannel,
20
20
  static_token,
21
21
  )
22
+ from .generated import (
23
+ BashInput,
24
+ ComputerActionInput,
25
+ ComputerObserveInput,
26
+ EditInput,
27
+ GlobInput,
28
+ GrepInput,
29
+ ListFilesInput,
30
+ ReadInput,
31
+ WriteInput,
32
+ )
22
33
  from .harness import (
23
34
  AssignRejectedError,
24
35
  Executor,
25
36
  Harness,
26
37
  HarnessMCPChannel,
38
+ HarnessTools,
39
+ HarnessToolSlot,
27
40
  Principal,
28
41
  Session,
29
42
  SessionEndedError,
30
43
  ToolOutcomeUnknownError,
31
44
  Unauthorized,
32
45
  )
46
+ from . import methods
47
+ from ._methods import Call, Notification, Request
48
+ from .tools import INLINE_RESULT_BYTES, BashResult, ExecutorTools, ToolContext, ToolError, ToolHandler, ToolOutput, ToolResult, ToolSlot
33
49
  from .transport import (
34
50
  TERMINAL_CLOSE_CODES,
35
51
  ChannelClosed,
@@ -40,6 +56,11 @@ from .transport import (
40
56
  )
41
57
 
42
58
  __all__ = [
59
+ "INLINE_RESULT_BYTES",
60
+ "Call",
61
+ "Notification",
62
+ "Request",
63
+ "methods",
43
64
  "DEFAULT_BASE_URL",
44
65
  "PROTOCOL_V1",
45
66
  "PROTOCOL_V11",
@@ -50,27 +71,46 @@ __all__ = [
50
71
  "AgentSessionClosedError",
51
72
  "AgentTurn",
52
73
  "AssignRejectedError",
74
+ "BashInput",
75
+ "BashResult",
53
76
  "ChannelClosed",
54
77
  "ClientStoppedError",
78
+ "ComputerActionInput",
79
+ "ComputerObserveInput",
55
80
  "ConnectRequest",
56
81
  "Connection",
57
82
  "Dialer",
83
+ "EditInput",
58
84
  "Executor",
59
85
  "ExecutorClient",
60
86
  "ExecutorError",
61
87
  "ExecutorTokenError",
62
88
  "ExecutorTokenScopeError",
89
+ "ExecutorTools",
90
+ "GlobInput",
91
+ "GrepInput",
63
92
  "Harness",
64
93
  "HarnessMCPChannel",
94
+ "HarnessToolSlot",
95
+ "HarnessTools",
96
+ "ListFilesInput",
65
97
  "LogEvent",
66
98
  "MCPChannel",
67
99
  "NotConnectedError",
68
100
  "Principal",
69
101
  "RPCError",
102
+ "ReadInput",
70
103
  "Session",
71
104
  "SessionEndedError",
105
+ "ToolContext",
106
+ "ToolError",
107
+ "ToolHandler",
72
108
  "ToolOutcomeUnknownError",
109
+ "ToolOutput",
110
+ "ToolResult",
111
+ "ToolSlot",
73
112
  "Unauthorized",
113
+ "WriteInput",
74
114
  "dial",
75
115
  "generated",
76
116
  "static_token",
@@ -0,0 +1,36 @@
1
+ """Typed protocol method descriptors (ADR 0012 §4.3); the instances are in
2
+ ``bma_executor_sdk.methods`` (generated by tools/gen_methods.py)."""
3
+
4
+ from __future__ import annotations
5
+
6
+ from dataclasses import dataclass
7
+ from typing import Generic, TypeVar
8
+
9
+ P = TypeVar("P")
10
+ R = TypeVar("R")
11
+
12
+ __all__ = ["Call", "Notification", "Request"]
13
+
14
+
15
+ @dataclass(frozen=True)
16
+ class Request(Generic[P, R]):
17
+ """A harness-to-executor request with params ``P`` and result ``R``,
18
+ served with ``client.on_request``."""
19
+
20
+ method: str
21
+
22
+
23
+ @dataclass(frozen=True)
24
+ class Call(Generic[P, R]):
25
+ """An executor-to-harness request with params ``P`` and result ``R``,
26
+ sent with ``await client.call``."""
27
+
28
+ method: str
29
+
30
+
31
+ @dataclass(frozen=True)
32
+ class Notification(Generic[P]):
33
+ """An executor-to-harness notification with params ``P``, sent with
34
+ ``await client.notify``."""
35
+
36
+ method: str