bma-executor-sdk 1.1.0__tar.gz → 1.2.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 (39) hide show
  1. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/PKG-INFO +2 -2
  2. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/README.md +1 -1
  3. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/pyproject.toml +2 -2
  4. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/src/bma_executor_sdk/__init__.py +2 -0
  5. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/src/bma_executor_sdk/client.py +26 -5
  6. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/src/bma_executor_sdk/generated.py +48 -5
  7. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/src/bma_executor_sdk/methods.py +8 -0
  8. bma_executor_sdk-1.2.0/tests/test_base_url.py +60 -0
  9. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/tests/typecheck/typed_tools.py +2 -2
  10. bma_executor_sdk-1.1.0/tests/test_base_url.py +0 -36
  11. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/.gitignore +0 -0
  12. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/examples/agent_minimal.py +0 -0
  13. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/examples/executor_minimal.py +0 -0
  14. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/examples/harness_loopback.py +0 -0
  15. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/examples/session_context.py +0 -0
  16. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/src/bma_executor_sdk/_methods.py +0 -0
  17. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/src/bma_executor_sdk/_npipe.py +0 -0
  18. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/src/bma_executor_sdk/_rpc.py +0 -0
  19. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/src/bma_executor_sdk/agent.py +0 -0
  20. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/src/bma_executor_sdk/harness.py +0 -0
  21. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/src/bma_executor_sdk/py.typed +0 -0
  22. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/src/bma_executor_sdk/session_context.py +0 -0
  23. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/src/bma_executor_sdk/tools.py +0 -0
  24. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/src/bma_executor_sdk/transport.py +0 -0
  25. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/tests/executor_helpers.py +0 -0
  26. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/tests/test_close_codes.py +0 -0
  27. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/tests/test_example_session_context.py +0 -0
  28. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/tests/test_executor_conformance.py +0 -0
  29. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/tests/test_executor_contract.py +0 -0
  30. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/tests/test_executor_interop.py +0 -0
  31. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/tests/test_executor_runtime.py +0 -0
  32. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/tests/test_executor_token_refresh.py +0 -0
  33. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/tests/test_npipe.py +0 -0
  34. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/tests/test_reconnect.py +0 -0
  35. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/tests/test_registration_refused.py +0 -0
  36. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/tests/test_review.py +0 -0
  37. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/tests/test_rpc_unretrieved_future.py +0 -0
  38. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/tests/test_session_context.py +0 -0
  39. {bma_executor_sdk-1.1.0 → bma_executor_sdk-1.2.0}/tests/test_typed_tools.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: bma-executor-sdk
3
- Version: 1.1.0
3
+ Version: 1.2.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
5
  Project-URL: Repository, https://github.com/beeos-ai/bma-executor-sdk
6
6
  License-Expression: Apache-2.0
@@ -58,7 +58,7 @@ async def main() -> None:
58
58
  asyncio.run(main())
59
59
  ```
60
60
 
61
- 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.
61
+ 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/environments/{environment_id}/token` (a machine daemon token to `{base_url}/v1/machines/{machine_id}/token`) and drops a trailing `/api/v1`. `machine_id` and `environment_id` are alternatives; an empty `machine_id` reads `BMA_MACHINE_ID` (`MACHINE_ID_ENV`), and without any id the legacy `/api/v1/executors/token` alias is used. The SDK does not read `BMA_BASE_URL` itself. A `token_source` carries its own channel URL.
62
62
 
63
63
  ### A machine-scoped executor must declare `process` or `agent`
64
64
 
@@ -47,7 +47,7 @@ async def main() -> None:
47
47
  asyncio.run(main())
48
48
  ```
49
49
 
50
- 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.
50
+ 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/environments/{environment_id}/token` (a machine daemon token to `{base_url}/v1/machines/{machine_id}/token`) and drops a trailing `/api/v1`. `machine_id` and `environment_id` are alternatives; an empty `machine_id` reads `BMA_MACHINE_ID` (`MACHINE_ID_ENV`), and without any id the legacy `/api/v1/executors/token` alias is used. The SDK does not read `BMA_BASE_URL` itself. A `token_source` carries its own channel URL.
51
51
 
52
52
  ### A machine-scoped executor must declare `process` or `agent`
53
53
 
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "bma-executor-sdk"
3
- version = "1.1.0"
3
+ version = "1.2.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"
@@ -11,7 +11,7 @@ dependencies = ["httpx>=0.27,<1", "websockets>=14,<17"]
11
11
  Repository = "https://github.com/beeos-ai/bma-executor-sdk"
12
12
 
13
13
  [dependency-groups]
14
- dev = ["pytest>=8", "pytest-asyncio>=0.24", "pyright==1.1.407"]
14
+ dev = ["pytest>=9", "pytest-asyncio>=1.4", "pyright==1.1.414"]
15
15
 
16
16
  [build-system]
17
17
  requires = ["hatchling>=1.26"]
@@ -21,6 +21,7 @@ from .session_context import SessionContext
21
21
  from .agent import AgentEventRecord, AgentHandler, AgentPlatform, AgentSessionClosedError, AgentTurn
22
22
  from .client import (
23
23
  DEFAULT_BASE_URL,
24
+ MACHINE_ID_ENV,
24
25
  PROTOCOL_V1,
25
26
  PROTOCOL_V11,
26
27
  CredentialRejectedError,
@@ -82,6 +83,7 @@ __all__ = [
82
83
  "Request",
83
84
  "methods",
84
85
  "DEFAULT_BASE_URL",
86
+ "MACHINE_ID_ENV",
85
87
  "PROTOCOL_V1",
86
88
  "PROTOCOL_V11",
87
89
  "TERMINAL_CLOSE_CODES",
@@ -8,10 +8,12 @@ lifecycle, tool cancellation, retried tool results, and the MCP channel.
8
8
  from __future__ import annotations
9
9
 
10
10
  import asyncio
11
+ import os
11
12
  import random as _random
12
13
  from collections.abc import Awaitable, Callable, Sequence
13
14
  from dataclasses import dataclass
14
15
  from typing import TYPE_CHECKING, Any, TypeVar
16
+ from urllib.parse import quote
15
17
 
16
18
  import httpx
17
19
 
@@ -64,6 +66,9 @@ if TYPE_CHECKING:
64
66
  from .generated import AgentCapability
65
67
 
66
68
  DEFAULT_BASE_URL = "https://api.bma.beeos.ai"
69
+ # The environment variable that carries the machine id of a machine-scoped executor
70
+ # (injected by the machine pool template).
71
+ MACHINE_ID_ENV = "BMA_MACHINE_ID"
67
72
  DEFAULT_REQUEST_TIMEOUT = 30.0
68
73
  # 0 reconnects until stop(), as gRPC connection backoff and long-running
69
74
  # agents (GitHub Actions runner, Buildkite agent) do.
@@ -127,6 +132,7 @@ class ExecutorClient:
127
132
  environment_id: str,
128
133
  executor: ExecutorInfo,
129
134
  capabilities: Capabilities | None = None,
135
+ machine_id: str = "",
130
136
  environment_key: str = "",
131
137
  base_url: str = DEFAULT_BASE_URL,
132
138
  ws_url: str = "",
@@ -146,17 +152,25 @@ class ExecutorClient:
146
152
  on_log: Callable[[LogEvent], None] | None = None,
147
153
  ) -> None:
148
154
  # environment_id may be empty: a machine-scoped executor registers
149
- # without one (executor.register in the v1.1 contract).
155
+ # without one (executor.register in the v1.1 contract). environment_id
156
+ # and machine_id are alternatives; machine_id defaults to BMA_MACHINE_ID
157
+ # when environment_id is empty. With neither, the legacy alias
158
+ # POST /api/v1/executors/token serves a machine daemon token.
159
+ if environment_id and machine_id:
160
+ raise ValueError("bma_executor_sdk: environment_id and machine_id are alternatives; set one")
161
+ if not environment_id and not machine_id:
162
+ machine_id = os.environ.get(MACHINE_ID_ENV, "").strip()
150
163
  if token_source is None and not environment_key.strip():
151
164
  raise ValueError("bma_executor_sdk: environment_key is required without token_source")
152
165
  if not executor.get("name"):
153
166
  raise ValueError("bma_executor_sdk: executor['name'] is required")
154
167
  self._environment_id = environment_id
168
+ self._machine_id = machine_id
155
169
  self._executor = executor
156
170
  self._capabilities: Capabilities = capabilities or {}
157
171
  self._environment_key = environment_key
158
172
  # The deployment origin (as BMA_BASE_URL in bma-sdk); a trailing
159
- # /api/v1 is dropped so the /v1/executors paths are not nested.
173
+ # /api/v1 is dropped so the /v1 paths are not nested.
160
174
  self._base_url = base_url.rstrip("/").removesuffix("/api/v1")
161
175
  self._ws_url = ws_url
162
176
  self._token_source = token_source
@@ -471,6 +485,14 @@ class ExecutorClient:
471
485
  if self._on_log is not None:
472
486
  self._on_log(LogEvent(level, message, error))
473
487
 
488
+ def _token_path(self) -> str:
489
+ """The token exchange of the executor's own resource (ADR-0023 1.3)."""
490
+ if self._environment_id:
491
+ return f"/v1/environments/{quote(self._environment_id, safe='')}/token"
492
+ if self._machine_id:
493
+ return f"/v1/machines/{quote(self._machine_id, safe='')}/token"
494
+ return "/api/v1/executors/token"
495
+
474
496
  async def _fetch_token(self) -> ExecutorTokenResponse:
475
497
  if self._token_source is not None:
476
498
  token = await self._token_source()
@@ -480,9 +502,7 @@ class ExecutorClient:
480
502
  client = self._http_client or httpx.AsyncClient()
481
503
  try:
482
504
  response = await client.post(
483
- # A machine daemon token (no environment id) is exchanged by
484
- # bma-api, an environment key by managed-agents.
485
- f"{self._base_url}{'/v1' if self._environment_id else '/api/v1'}/executors/token",
505
+ f"{self._base_url}{self._token_path()}",
486
506
  json={"environment_id": self._environment_id, "executor": self._executor},
487
507
  headers={"Authorization": f"Bearer {self._environment_key}"},
488
508
  timeout=self._request_timeout,
@@ -936,6 +956,7 @@ def _canceled_tool_result(params: ToolCallParams, reason: str) -> ToolResultPara
936
956
 
937
957
  __all__ = [
938
958
  "DEFAULT_BASE_URL",
959
+ "MACHINE_ID_ENV",
939
960
  "PROTOCOL_V1",
940
961
  "PROTOCOL_V11",
941
962
  "ExecutorClient",
@@ -1,4 +1,4 @@
1
- # Code generated by tools/contract/gen-python.mjs from contracts/bma (executor protocol 1.1.0). DO NOT EDIT.
1
+ # Code generated by tools/contract/gen-python.mjs from contracts/bma (executor protocol 1.2.0). DO NOT EDIT.
2
2
 
3
3
  from __future__ import annotations
4
4
 
@@ -24,6 +24,7 @@ class AgentCapability(TypedDict):
24
24
  file_inputs: NotRequired[bool]
25
25
  max_sessions: NotRequired[int]
26
26
  turn_resume: NotRequired[bool]
27
+ platform_credentials: NotRequired[list[Literal["brain_tools", "harness_model"]]]
27
28
  harness: NotRequired[AgentHarnessCapability]
28
29
 
29
30
  class AgentErrorInfo(TypedDict):
@@ -127,12 +128,12 @@ class AgentTurnConfig(TypedDict):
127
128
  system: NotRequired[str]
128
129
 
129
130
  class ArtifactCapability(TypedDict):
130
- """v1.1 artifact upload (POST /v1/executors/artifacts). Environment-scoped executors only."""
131
+ """v1.1 artifact upload (POST /v1/environments/{environment_id}/artifacts; legacy alias POST /v1/executors/artifacts). Environment-scoped executors only."""
131
132
  upload: bool
132
133
  max_bytes: NotRequired[int]
133
134
 
134
135
  class ArtifactRef(TypedDict):
135
- """Artifact reference returned by POST /v1/executors/artifacts and listed in tool.result artifacts (v1.1 §6.5)."""
136
+ """Artifact reference returned by POST /v1/environments/{environment_id}/artifacts (legacy alias POST /v1/executors/artifacts) and listed in tool.result artifacts (v1.1 §6.5)."""
136
137
  artifact_id: str
137
138
  name: NotRequired[str]
138
139
  mime_type: str
@@ -162,6 +163,7 @@ class Capabilities(TypedDict):
162
163
  workspace: NotRequired[WorkspaceCapability]
163
164
  agent: NotRequired[AgentCapability]
164
165
  session_files: NotRequired[SessionFilesCapability]
166
+ fs: NotRequired[FsCapability]
165
167
 
166
168
  class ChannelScope(str, Enum):
167
169
  """Channels a short-lived executor JWT may open."""
@@ -282,12 +284,12 @@ class ExecutorTokenRefreshResult(TypedDict):
282
284
  expires_at: str
283
285
 
284
286
  class ExecutorTokenRequest(TypedDict):
285
- """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."""
287
+ """Token request body for POST /v1/machines/{machine_id}/token (bearer: machine daemon token) and POST /v1/environments/{environment_id}/token (bearer: environment key); the legacy alias POST /v1/executors/token takes either bearer. The id in the path must equal the credential's machine or environment, otherwise 404; on the new paths environment_id may be empty or absent for a machine and, when sent for an environment, must equal the path id. 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."""
286
288
  environment_id: str
287
289
  executor: ExecutorInfo
288
290
 
289
291
  class ExecutorTokenResponse(TypedDict):
290
- """POST /v1/executors/token response."""
292
+ """Token response of POST /v1/machines/{machine_id}/token, POST /v1/environments/{environment_id}/token and the legacy alias POST /v1/executors/token."""
291
293
  executor_id: str
292
294
  token: str
293
295
  expires_in: int
@@ -317,6 +319,32 @@ class FilesCapability(TypedDict):
317
319
  read_roots: NotRequired[list[str]]
318
320
  write_roots: NotRequired[list[str]]
319
321
 
322
+ class FsCapability(TypedDict):
323
+ """Session file views mounted by the executor as FUSE file systems backed by bma-file (docs/adr/0021). Declared only after the executor probed that it can mount. Absent or fuse=false: the session files stay on the copy-and-scan protocol (session_files). views lists the views the executor can mount; the harness only mounts those. Machine-scoped executors only."""
324
+ fuse: bool
325
+ views: NotRequired[list[str]]
326
+
327
+ class FsMount(TypedDict):
328
+ """One view to mount. path is the absolute mount point on the executor host (derived from session_files by the harness). readonly is also fixed inside token; the executor mounts read-only when it is true. token is a capability token for this session and machine: keep it in memory only, never write it to disk, argv, environment or logs."""
329
+ view: str
330
+ path: str
331
+ readonly: bool
332
+ token: str
333
+ options: NotRequired[dict[str, str]]
334
+
335
+ class FsMountResult(TypedDict):
336
+ """fs.mount result. state is "mounted" once every listed view is mounted and serving, or "failed" with error_code and error (nothing stays half-mounted)."""
337
+ state: Literal["mounted", "failed"]
338
+ error_code: NotRequired[str]
339
+ error: NotRequired[str]
340
+
341
+ class FsUnmountResult(TypedDict):
342
+ """fs.unmount result. pending_bytes is data not yet committed to bma-file when flush was requested (always 0 for read-only views)."""
343
+ state: Literal["unmounted", "failed"]
344
+ pending_bytes: int
345
+ error_code: NotRequired[str]
346
+ error: NotRequired[str]
347
+
320
348
  class GlobInput(TypedDict):
321
349
  """glob input: list paths matching pattern."""
322
350
  pattern: str
@@ -1092,6 +1120,17 @@ class WorkspaceBackupParams(TypedDict):
1092
1120
  exclude: NotRequired[list[str]]
1093
1121
  skip_if_fingerprint: NotRequired[str]
1094
1122
 
1123
+ class FsMountParams(TypedDict):
1124
+ "Params object of fs.mount."
1125
+ session_id: str
1126
+ service_url: str
1127
+ mounts: list[FsMount]
1128
+
1129
+ class FsUnmountParams(TypedDict):
1130
+ "Params object of fs.unmount."
1131
+ session_id: str
1132
+ flush: NotRequired[bool]
1133
+
1095
1134
  class TurnStartParams(TypedDict):
1096
1135
  "Params object of turn.start."
1097
1136
  session_id: str
@@ -1202,6 +1241,8 @@ METHOD_TERMINAL_ATTACH = "terminal.attach"
1202
1241
  METHOD_TERMINAL_CLOSE = "terminal.close"
1203
1242
  METHOD_SKILL_INSTALL = "skill.install"
1204
1243
  METHOD_WORKSPACE_BACKUP = "workspace.backup"
1244
+ METHOD_FS_MOUNT = "fs.mount"
1245
+ METHOD_FS_UNMOUNT = "fs.unmount"
1205
1246
  METHOD_TURN_START = "turn.start"
1206
1247
  METHOD_TURN_INPUT = "turn.input"
1207
1248
  METHOD_TURN_CANCEL = "turn.cancel"
@@ -1240,6 +1281,8 @@ METHODS: dict[str, MethodSpec] = {
1240
1281
  "terminal.close": MethodSpec(name="terminal.close", direction="harness-to-executor", kind="request", since="bma.executor.v1.1", params_type="TerminalCloseParams", result_type="TerminalCloseResult", capability="terminal.enabled", idempotent_by="terminal_id"),
1241
1282
  "skill.install": MethodSpec(name="skill.install", direction="harness-to-executor", kind="request", since="bma.executor.v1.1", params_type="SkillInstallParams", result_type="SkillInstallResult", capability="skills.install", idempotent_by="skill_id+revision_id+digest"),
1242
1283
  "workspace.backup": MethodSpec(name="workspace.backup", direction="harness-to-executor", kind="request", since="bma.executor.v1.1", params_type="WorkspaceBackupParams", result_type="WorkspaceBackupResult", capability="workspace.backup", idempotent_by="backup_id"),
1284
+ "fs.mount": MethodSpec(name="fs.mount", direction="harness-to-executor", kind="request", since="bma.executor.v1.1", params_type="FsMountParams", result_type="FsMountResult", capability="fs.fuse", idempotent_by="session_id+view"),
1285
+ "fs.unmount": MethodSpec(name="fs.unmount", direction="harness-to-executor", kind="request", since="bma.executor.v1.1", params_type="FsUnmountParams", result_type="FsUnmountResult", capability="fs.fuse", idempotent_by="session_id"),
1243
1286
  "turn.start": MethodSpec(name="turn.start", direction="harness-to-executor", kind="request", since="bma.executor.v1.1", params_type="TurnStartParams", result_type="TurnStartResult", capability="agent", idempotent_by="turn_id"),
1244
1287
  "turn.input": MethodSpec(name="turn.input", direction="harness-to-executor", kind="request", since="bma.executor.v1.1", params_type="TurnInputParams", result_type="Ack", capability="agent", idempotent_by="input_id"),
1245
1288
  "turn.cancel": MethodSpec(name="turn.cancel", direction="harness-to-executor", kind="request", since="bma.executor.v1.1", params_type="TurnCancelParams", result_type="TurnCancelResult", capability="agent", idempotent_by=None),
@@ -8,6 +8,10 @@ from ._methods import Call, Notification, Request
8
8
  from .generated import (
9
9
  Ack,
10
10
  ExecutorCapabilitiesUpdateParams,
11
+ FsMountParams,
12
+ FsMountResult,
13
+ FsUnmountParams,
14
+ FsUnmountResult,
11
15
  InteractionCancelParams,
12
16
  InteractionRequestParams,
13
17
  InteractionRequestResult,
@@ -53,6 +57,8 @@ __all__ = [
53
57
  "TERMINAL_CLOSE",
54
58
  "SKILL_INSTALL",
55
59
  "WORKSPACE_BACKUP",
60
+ "FS_MOUNT",
61
+ "FS_UNMOUNT",
56
62
  "SESSION_READY",
57
63
  "SESSION_EVENT",
58
64
  "SESSION_ENDED",
@@ -78,6 +84,8 @@ TERMINAL_ATTACH: Request[TerminalAttachParams, TerminalAttachResult] = Request("
78
84
  TERMINAL_CLOSE: Request[TerminalCloseParams, TerminalCloseResult] = Request("terminal.close")
79
85
  SKILL_INSTALL: Request[SkillInstallParams, SkillInstallResult] = Request("skill.install")
80
86
  WORKSPACE_BACKUP: Request[WorkspaceBackupParams, WorkspaceBackupResult] = Request("workspace.backup")
87
+ FS_MOUNT: Request[FsMountParams, FsMountResult] = Request("fs.mount")
88
+ FS_UNMOUNT: Request[FsUnmountParams, FsUnmountResult] = Request("fs.unmount")
81
89
 
82
90
  # Executor-to-harness requests a client sends with call.
83
91
  SESSION_READY: Call[SessionReadyParams, Ack] = Call("session.ready")
@@ -0,0 +1,60 @@
1
+ """base_url is the deployment origin: a trailing /api/v1 is dropped."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import pytest
6
+
7
+ import bma_executor_sdk as bx
8
+
9
+
10
+ @pytest.mark.parametrize("base_url", ["https://bma.test", "https://bma.test/", "https://bma.test/api/v1", "https://bma.test/api/v1/"])
11
+ def test_base_url_is_the_origin(base_url: str) -> None:
12
+ assert bx.DEFAULT_BASE_URL == "https://api.bma.beeos.ai"
13
+ client = bx.ExecutorClient(
14
+ environment_id="env", environment_key="k", base_url=base_url,
15
+ executor={"name": "t", "os": "linux", "arch": "arm64", "version": "0"},
16
+ )
17
+ assert client._base_url == "https://bma.test" # pyright: ignore[reportPrivateUsage]
18
+
19
+
20
+ _EXECUTOR = {"name": "t", "os": "linux", "arch": "arm64", "version": "0"}
21
+
22
+
23
+ async def _token_path(monkeypatch: pytest.MonkeyPatch, *, environment_id: str, machine_id: str = "", env: str = "") -> str:
24
+ import httpx
25
+
26
+ monkeypatch.setenv(bx.MACHINE_ID_ENV, env)
27
+ seen: list[str] = []
28
+
29
+ def handler(request: httpx.Request) -> httpx.Response:
30
+ seen.append(request.url.raw_path.decode().split("?")[0])
31
+ return httpx.Response(200, json={"executor_id": "exec_t", "token": "jwt", "expires_in": 300, "ws_url": "ws://x"})
32
+
33
+ client = bx.ExecutorClient(
34
+ environment_id=environment_id, machine_id=machine_id, environment_key="k", base_url="https://bma.test",
35
+ executor=_EXECUTOR, # type: ignore[arg-type]
36
+ http_client=httpx.AsyncClient(transport=httpx.MockTransport(handler)),
37
+ )
38
+ await client._fetch_token() # pyright: ignore[reportPrivateUsage]
39
+ assert len(seen) == 1
40
+ return seen[0]
41
+
42
+
43
+ async def test_token_exchange_path_follows_the_resource(monkeypatch: pytest.MonkeyPatch) -> None:
44
+ assert await _token_path(monkeypatch, environment_id="env") == "/v1/environments/env/token"
45
+ assert await _token_path(monkeypatch, environment_id="", machine_id="mach_1") == "/v1/machines/mach_1/token"
46
+ assert await _token_path(monkeypatch, environment_id="", machine_id="a/b") == "/v1/machines/a%2Fb/token"
47
+ # No id: the legacy alias keeps serving a machine daemon token.
48
+ assert await _token_path(monkeypatch, environment_id="") == "/api/v1/executors/token"
49
+
50
+
51
+ async def test_machine_id_comes_from_bma_machine_id(monkeypatch: pytest.MonkeyPatch) -> None:
52
+ assert bx.MACHINE_ID_ENV == "BMA_MACHINE_ID"
53
+ assert await _token_path(monkeypatch, environment_id="", env="mach_env") == "/v1/machines/mach_env/token"
54
+ # An explicit environment_id wins over the ambient variable.
55
+ assert await _token_path(monkeypatch, environment_id="env", env="mach_env") == "/v1/environments/env/token"
56
+
57
+
58
+ def test_environment_id_and_machine_id_are_alternatives() -> None:
59
+ with pytest.raises(ValueError, match="environment_id and machine_id"):
60
+ bx.ExecutorClient(environment_id="env", machine_id="mach_1", environment_key="k", executor=_EXECUTOR) # type: ignore[arg-type]
@@ -12,12 +12,12 @@ from bma_executor_sdk.generated import ToolResultParams
12
12
 
13
13
  def register(client: ExecutorClient) -> None:
14
14
  @client.tools.bash.handler
15
- async def bash(input: BashInput, ctx: ToolContext) -> BashResult: # pyright: ignore[reportUnusedFunction]
15
+ async def bash(input: BashInput, ctx: ToolContext) -> BashResult:
16
16
  assert_type(input["command"], str)
17
17
  return BashResult(stdout="", stderr="", exit_code=0)
18
18
 
19
19
  @client.tools.read.handler
20
- async def read(input: ReadInput, ctx: ToolContext) -> str: # pyright: ignore[reportUnusedFunction]
20
+ async def read(input: ReadInput, ctx: ToolContext) -> str:
21
21
  return input["path"]
22
22
 
23
23
  async def wrong(input: BashInput, ctx: ToolContext) -> str:
@@ -1,36 +0,0 @@
1
- """base_url is the deployment origin: a trailing /api/v1 is dropped."""
2
-
3
- from __future__ import annotations
4
-
5
- import pytest
6
-
7
- import bma_executor_sdk as bx
8
-
9
-
10
- @pytest.mark.parametrize("base_url", ["https://bma.test", "https://bma.test/", "https://bma.test/api/v1", "https://bma.test/api/v1/"])
11
- def test_base_url_is_the_origin(base_url: str) -> None:
12
- assert bx.DEFAULT_BASE_URL == "https://api.bma.beeos.ai"
13
- client = bx.ExecutorClient(
14
- environment_id="env", environment_key="k", base_url=base_url,
15
- executor={"name": "t", "os": "linux", "arch": "arm64", "version": "0"},
16
- )
17
- assert client._base_url == "https://bma.test" # pyright: ignore[reportPrivateUsage]
18
-
19
-
20
- @pytest.mark.parametrize(("environment_id", "path"), [("", "/api/v1/executors/token"), ("env", "/v1/executors/token")])
21
- async def test_token_exchange_path_follows_the_credential(environment_id: str, path: str) -> None:
22
- import httpx
23
-
24
- seen: list[str] = []
25
-
26
- def handler(request: httpx.Request) -> httpx.Response:
27
- seen.append(request.url.path)
28
- return httpx.Response(200, json={"executor_id": "exec_t", "token": "jwt", "expires_in": 300, "ws_url": "ws://x"})
29
-
30
- client = bx.ExecutorClient(
31
- environment_id=environment_id, environment_key="k", base_url="https://bma.test",
32
- executor={"name": "t", "os": "linux", "arch": "arm64", "version": "0"},
33
- http_client=httpx.AsyncClient(transport=httpx.MockTransport(handler)),
34
- )
35
- await client._fetch_token() # pyright: ignore[reportPrivateUsage]
36
- assert seen == [path]