bma-executor-sdk 0.4.8__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.
- {bma_executor_sdk-0.4.8 → bma_executor_sdk-1.0.0}/PKG-INFO +27 -18
- {bma_executor_sdk-0.4.8 → bma_executor_sdk-1.0.0}/README.md +25 -16
- bma_executor_sdk-1.0.0/examples/executor_minimal.py +57 -0
- {bma_executor_sdk-0.4.8 → bma_executor_sdk-1.0.0}/examples/harness_loopback.py +3 -3
- {bma_executor_sdk-0.4.8 → bma_executor_sdk-1.0.0}/pyproject.toml +9 -3
- {bma_executor_sdk-0.4.8 → bma_executor_sdk-1.0.0}/src/bma_executor_sdk/__init__.py +40 -0
- bma_executor_sdk-1.0.0/src/bma_executor_sdk/_methods.py +36 -0
- {bma_executor_sdk-0.4.8 → bma_executor_sdk-1.0.0}/src/bma_executor_sdk/agent.py +5 -5
- {bma_executor_sdk-0.4.8 → bma_executor_sdk-1.0.0}/src/bma_executor_sdk/client.py +99 -37
- {bma_executor_sdk-0.4.8 → bma_executor_sdk-1.0.0}/src/bma_executor_sdk/generated.py +66 -1
- {bma_executor_sdk-0.4.8 → bma_executor_sdk-1.0.0}/src/bma_executor_sdk/harness.py +79 -17
- bma_executor_sdk-1.0.0/src/bma_executor_sdk/methods.py +95 -0
- bma_executor_sdk-1.0.0/src/bma_executor_sdk/py.typed +0 -0
- bma_executor_sdk-1.0.0/src/bma_executor_sdk/tools.py +191 -0
- bma_executor_sdk-1.0.0/tests/test_base_url.py +17 -0
- {bma_executor_sdk-0.4.8 → bma_executor_sdk-1.0.0}/tests/test_executor_conformance.py +1 -1
- {bma_executor_sdk-0.4.8 → bma_executor_sdk-1.0.0}/tests/test_executor_contract.py +1 -1
- {bma_executor_sdk-0.4.8 → bma_executor_sdk-1.0.0}/tests/test_executor_interop.py +6 -6
- {bma_executor_sdk-0.4.8 → bma_executor_sdk-1.0.0}/tests/test_executor_runtime.py +16 -18
- {bma_executor_sdk-0.4.8 → bma_executor_sdk-1.0.0}/tests/test_npipe.py +4 -4
- bma_executor_sdk-1.0.0/tests/test_review.py +95 -0
- bma_executor_sdk-1.0.0/tests/test_typed_tools.py +144 -0
- bma_executor_sdk-1.0.0/tests/typecheck/typed_tools.py +60 -0
- bma_executor_sdk-0.4.8/examples/executor_minimal.py +0 -64
- {bma_executor_sdk-0.4.8 → bma_executor_sdk-1.0.0}/.gitignore +0 -0
- {bma_executor_sdk-0.4.8 → bma_executor_sdk-1.0.0}/examples/agent_minimal.py +0 -0
- {bma_executor_sdk-0.4.8 → bma_executor_sdk-1.0.0}/src/bma_executor_sdk/_npipe.py +0 -0
- {bma_executor_sdk-0.4.8 → bma_executor_sdk-1.0.0}/src/bma_executor_sdk/_rpc.py +0 -0
- {bma_executor_sdk-0.4.8 → bma_executor_sdk-1.0.0}/src/bma_executor_sdk/transport.py +0 -0
- {bma_executor_sdk-0.4.8 → bma_executor_sdk-1.0.0}/tests/executor_helpers.py +0 -0
- {bma_executor_sdk-0.4.8 → bma_executor_sdk-1.0.0}/tests/test_close_codes.py +0 -0
- {bma_executor_sdk-0.4.8 → 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.
|
|
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-
|
|
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
|
[](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`](
|
|
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.
|
|
21
|
-
| Protocol | `bma.executor.v1.1` (contract 1.1.0, [`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](
|
|
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.
|
|
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`](
|
|
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
|
-
|
|
45
|
-
|
|
46
|
-
|
|
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(
|
|
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
|
|
|
@@ -90,11 +97,11 @@ Chosen by the channel URL of the token source:
|
|
|
90
97
|
| Windows named pipe (`npipe:////./pipe/<name>`, Windows ProactorEventLoop) | `token_source=static_token("npipe:////./pipe/<name>", token)` | `await harness.serve_npipe(name)` |
|
|
91
98
|
| In process | `dialer=harness.inprocess_dialer()` | — |
|
|
92
99
|
|
|
93
|
-
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](
|
|
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).
|
|
94
101
|
|
|
95
102
|
## Agent executors
|
|
96
103
|
|
|
97
|
-
`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](
|
|
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).
|
|
98
105
|
|
|
99
106
|
## Go ↔ Python
|
|
100
107
|
|
|
@@ -103,8 +110,10 @@ The executor-listens local socket is not implemented in Python (use the Go or Ty
|
|
|
103
110
|
| `NewClient(Options{...})` | `ExecutorClient(environment_id=..., executor=..., ...)` |
|
|
104
111
|
| `Options.TokenSource`, `StaticToken(url, token)` | `token_source=`, `static_token(url, token)` |
|
|
105
112
|
| `Client.Start` / `Stop` / `State` / `ExecutorID` / `ConnectionID` / `ActiveSessions` | `start()` / `stop(reason)` / `state` / `executor_id` / `connection_id` / `active_sessions` |
|
|
106
|
-
| `
|
|
107
|
-
| `
|
|
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` |
|
|
108
117
|
| `ServeAgent(handler, AgentCapability)` | `serve_agent(handler, capability)` |
|
|
109
118
|
| `AgentHandler.OpenTurn` / `RunTurn` / `CloseSession` | `open_turn` / `run_turn` / `close_session` |
|
|
110
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
|
[](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`](
|
|
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.
|
|
10
|
-
| Protocol | `bma.executor.v1.1` (contract 1.1.0, [`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](
|
|
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.
|
|
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`](
|
|
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
|
-
|
|
34
|
-
|
|
35
|
-
|
|
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(
|
|
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
|
|
|
@@ -79,11 +86,11 @@ Chosen by the channel URL of the token source:
|
|
|
79
86
|
| Windows named pipe (`npipe:////./pipe/<name>`, Windows ProactorEventLoop) | `token_source=static_token("npipe:////./pipe/<name>", token)` | `await harness.serve_npipe(name)` |
|
|
80
87
|
| In process | `dialer=harness.inprocess_dialer()` | — |
|
|
81
88
|
|
|
82
|
-
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](
|
|
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).
|
|
83
90
|
|
|
84
91
|
## Agent executors
|
|
85
92
|
|
|
86
|
-
`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](
|
|
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).
|
|
87
94
|
|
|
88
95
|
## Go ↔ Python
|
|
89
96
|
|
|
@@ -92,8 +99,10 @@ The executor-listens local socket is not implemented in Python (use the Go or Ty
|
|
|
92
99
|
| `NewClient(Options{...})` | `ExecutorClient(environment_id=..., executor=..., ...)` |
|
|
93
100
|
| `Options.TokenSource`, `StaticToken(url, token)` | `token_source=`, `static_token(url, token)` |
|
|
94
101
|
| `Client.Start` / `Stop` / `State` / `ExecutorID` / `ConnectionID` / `ActiveSessions` | `start()` / `stop(reason)` / `state` / `executor_id` / `connection_id` / `active_sessions` |
|
|
95
|
-
| `
|
|
96
|
-
| `
|
|
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` |
|
|
97
106
|
| `ServeAgent(handler, AgentCapability)` | `serve_agent(handler, capability)` |
|
|
98
107
|
| `AgentHandler.OpenTurn` / `RunTurn` / `CloseSession` | `open_turn` / `run_turn` / `close_session` |
|
|
99
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.
|
|
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.
|
|
38
|
-
print(result["outcome"],
|
|
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.
|
|
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-
|
|
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
|
|
@@ -133,7 +133,7 @@ class AgentTurn:
|
|
|
133
133
|
"event_type": event_type, "index": index, "text": text,
|
|
134
134
|
}
|
|
135
135
|
try:
|
|
136
|
-
await client.
|
|
136
|
+
await client._notify(METHOD_SESSION_EVENT_DELTA, params)
|
|
137
137
|
except (NotConnectedError, ClientStoppedError) as error:
|
|
138
138
|
client._log("debug", "session.event_delta dropped", error) # noqa: SLF001
|
|
139
139
|
|
|
@@ -155,7 +155,7 @@ class AgentTurn:
|
|
|
155
155
|
s.pending[interaction_id] = answer
|
|
156
156
|
try:
|
|
157
157
|
await self.flush()
|
|
158
|
-
await s.call_until_connected(lambda: s.runtime.client.
|
|
158
|
+
await s.call_until_connected(lambda: s.runtime.client._call(METHOD_INTERACTION_REQUEST, params))
|
|
159
159
|
timeout = None
|
|
160
160
|
if params.get("expires_at"):
|
|
161
161
|
expires = datetime.fromisoformat(params["expires_at"].replace("Z", "+00:00"))
|
|
@@ -304,7 +304,7 @@ class _AgentRuntime:
|
|
|
304
304
|
async def ended() -> None:
|
|
305
305
|
try:
|
|
306
306
|
await asyncio.wait_for(
|
|
307
|
-
s.call_until_connected(lambda: self.client.
|
|
307
|
+
s.call_until_connected(lambda: self.client._call(METHOD_SESSION_ENDED, {"session_id": s.id, "reason": params.get("reason", "")})),
|
|
308
308
|
_AGENT_CLOSE_FLUSH_WAIT,
|
|
309
309
|
)
|
|
310
310
|
except Exception as error:
|
|
@@ -373,7 +373,7 @@ class _AgentSession:
|
|
|
373
373
|
client = self.runtime.client
|
|
374
374
|
params: InteractionCancelParams = {"session_id": self.id, "interaction_id": interaction_id, "reason": reason} # type: ignore[typeddict-item]
|
|
375
375
|
try:
|
|
376
|
-
await asyncio.wait_for(self.call_until_connected(lambda: client.
|
|
376
|
+
await asyncio.wait_for(self.call_until_connected(lambda: client._call(METHOD_INTERACTION_CANCEL, params)), _AGENT_CLOSE_FLUSH_WAIT)
|
|
377
377
|
except Exception as error:
|
|
378
378
|
client._log("warn", f"interaction.cancel for {interaction_id} failed", error) # noqa: SLF001
|
|
379
379
|
|
|
@@ -391,7 +391,7 @@ class _AgentSession:
|
|
|
391
391
|
continue
|
|
392
392
|
head = self.outbox[0]
|
|
393
393
|
try:
|
|
394
|
-
await self.call_until_connected(lambda: client.
|
|
394
|
+
await self.call_until_connected(lambda: client._call(METHOD_SESSION_EVENT, head))
|
|
395
395
|
except ClientStoppedError:
|
|
396
396
|
return
|
|
397
397
|
except RPCError as error:
|