bma-executor-sdk 1.5.2__tar.gz → 1.6.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 (40) hide show
  1. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/PKG-INFO +1 -1
  2. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/pyproject.toml +1 -1
  3. bma_executor_sdk-1.6.0/src/bma_executor_sdk/_input_skills.py +54 -0
  4. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/src/bma_executor_sdk/agent.py +12 -0
  5. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/src/bma_executor_sdk/generated.py +21 -1
  6. bma_executor_sdk-1.6.0/tests/test_agent_input_skills.py +89 -0
  7. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/.gitignore +0 -0
  8. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/README.md +0 -0
  9. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/examples/agent_minimal.py +0 -0
  10. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/examples/executor_minimal.py +0 -0
  11. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/examples/harness_loopback.py +0 -0
  12. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/examples/session_context.py +0 -0
  13. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/src/bma_executor_sdk/__init__.py +0 -0
  14. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/src/bma_executor_sdk/_methods.py +0 -0
  15. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/src/bma_executor_sdk/_npipe.py +0 -0
  16. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/src/bma_executor_sdk/_rpc.py +0 -0
  17. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/src/bma_executor_sdk/client.py +0 -0
  18. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/src/bma_executor_sdk/harness.py +0 -0
  19. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/src/bma_executor_sdk/methods.py +0 -0
  20. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/src/bma_executor_sdk/py.typed +0 -0
  21. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/src/bma_executor_sdk/session_context.py +0 -0
  22. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/src/bma_executor_sdk/tools.py +0 -0
  23. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/src/bma_executor_sdk/transport.py +0 -0
  24. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/tests/executor_helpers.py +0 -0
  25. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/tests/test_base_url.py +0 -0
  26. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/tests/test_close_codes.py +0 -0
  27. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/tests/test_example_session_context.py +0 -0
  28. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/tests/test_executor_conformance.py +0 -0
  29. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/tests/test_executor_contract.py +0 -0
  30. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/tests/test_executor_interop.py +0 -0
  31. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/tests/test_executor_runtime.py +0 -0
  32. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/tests/test_executor_token_refresh.py +0 -0
  33. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/tests/test_npipe.py +0 -0
  34. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/tests/test_reconnect.py +0 -0
  35. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/tests/test_registration_refused.py +0 -0
  36. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/tests/test_review.py +0 -0
  37. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/tests/test_rpc_unretrieved_future.py +0 -0
  38. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/tests/test_session_context.py +0 -0
  39. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/tests/test_typed_tools.py +0 -0
  40. {bma_executor_sdk-1.5.2 → bma_executor_sdk-1.6.0}/tests/typecheck/typed_tools.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: bma-executor-sdk
3
- Version: 1.5.2
3
+ Version: 1.6.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
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "bma-executor-sdk"
3
- version = "1.5.2"
3
+ version = "1.6.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"
@@ -0,0 +1,54 @@
1
+ """Shape gate. An opted-in handler must verify and install the exact bytes."""
2
+ import re
3
+ from ._rpc import RPCError
4
+ from .generated import JsonRpcErrorCode
5
+
6
+
7
+ def validate_input_skill_request(config: object) -> bool:
8
+ def invalid() -> RPCError:
9
+ return RPCError(JsonRpcErrorCode.InvalidParams, "invalid input_skills")
10
+ if config is None:
11
+ return False
12
+ if not isinstance(config, dict):
13
+ raise invalid()
14
+ if "input_skill_receipt" in config:
15
+ raise RPCError(JsonRpcErrorCode.InvalidParams, "input_skill_receipt is effective-only")
16
+ if "input_skills" not in config:
17
+ return False
18
+ documents = config["input_skills"]
19
+ if not isinstance(documents, list) or not 1 <= len(documents) <= 10:
20
+ raise invalid()
21
+ seen = set()
22
+ total = 0
23
+ keys = {"skill_id", "revision_id", "name", "body", "body_sha256"}
24
+ for doc in documents:
25
+ if not isinstance(doc, dict) or set(doc) != keys or any(not isinstance(v, str) for v in doc.values()):
26
+ raise invalid()
27
+ try:
28
+ size = len(doc["body"].encode("utf-8"))
29
+ name_size = len(doc["name"].encode("utf-8"))
30
+ except UnicodeError as error:
31
+ raise invalid() from error
32
+ total += size
33
+ if (not re.fullmatch(r"skl_[a-zA-Z0-9_-]{1,124}", doc["skill_id"])
34
+ or not re.fullmatch(r"skr_[a-zA-Z0-9_-]{1,124}", doc["revision_id"])
35
+ or not re.fullmatch(r"[0-9a-f]{64}", doc["body_sha256"])
36
+ or not doc["name"].strip() or name_size > 255
37
+ or not doc["body"].strip() or size > 65536 or total > 262144
38
+ or doc["skill_id"] in seen):
39
+ raise invalid()
40
+ seen.add(doc["skill_id"])
41
+ return True
42
+
43
+
44
+ def validate_input_skill_receipt(params: dict, result: dict) -> None:
45
+ selected = (params.get("config") or {}).get("input_skills", [])
46
+ receipt = (result.get("effective") or {}).get("input_skill_receipt")
47
+ if not selected and receipt is None:
48
+ return
49
+ if (not isinstance(receipt, dict) or receipt.get("input_id") != params.get("input_id")
50
+ or not isinstance(receipt.get("skills"), list) or len(receipt["skills"]) != len(selected) or not selected):
51
+ raise RPCError(JsonRpcErrorCode.InvalidParams, "input skill receipt does not match the opening input")
52
+ for expected, actual in zip(selected, receipt["skills"]):
53
+ if not isinstance(actual, dict) or any(actual.get(key) != expected[key] for key in ("skill_id", "revision_id", "body_sha256")):
54
+ raise RPCError(JsonRpcErrorCode.InvalidParams, "input skill receipt does not match the opening input")
@@ -12,6 +12,8 @@ Harness side (Go: agent_harness.go): ``Harness(agent=platform)`` with an
12
12
 
13
13
  from __future__ import annotations
14
14
 
15
+ from ._input_skills import validate_input_skill_request, validate_input_skill_receipt
16
+
15
17
  import asyncio
16
18
  from collections import deque
17
19
  from collections.abc import Awaitable, Callable
@@ -228,11 +230,15 @@ class _AgentRuntime:
228
230
  return session
229
231
 
230
232
  async def turn_start(self, params: TurnStartParams) -> TurnStartResult:
233
+ selected = validate_input_skill_request(params.get("config"))
234
+ if selected and self.capability.get("input_skills") is not True:
235
+ raise RPCError(JsonRpcErrorCode.CapabilityUnavailable, "input_skills is not supported")
231
236
  if not params.get("session_id") or not params.get("turn_id") or not params.get("input"):
232
237
  raise RPCError(JsonRpcErrorCode.InvalidParams, "session_id, turn_id and input are required")
233
238
  s = self.session(params["session_id"], True)
234
239
  assert s is not None
235
240
  if params["turn_id"] in s.results:
241
+ validate_input_skill_receipt(params,s.results[params["turn_id"]])
236
242
  return s.results[params["turn_id"]]
237
243
  if s.turn is not None:
238
244
  raise RPCError(JsonRpcErrorCode.Conflict, "a turn is already running; use turn.input")
@@ -242,8 +248,12 @@ class _AgentRuntime:
242
248
  result = dict(await self.handler.open_turn(params))
243
249
  if not result.get("accepted"):
244
250
  raise RPCError(JsonRpcErrorCode.ExecutorBusy, "turn not accepted")
251
+ validate_input_skill_receipt(params,result)
245
252
  except BaseException:
253
+ _cancel_turn(turn)
254
+ turn.ended = True
246
255
  s.turn = None
256
+ turn._done.set() # noqa: SLF001
247
257
  raise
248
258
  result["turn_id"] = params["turn_id"]
249
259
  s.results[params["turn_id"]] = result # type: ignore[assignment]
@@ -288,6 +298,8 @@ class _AgentRuntime:
288
298
  raise RPCError(JsonRpcErrorCode.Conflict, "turn is not running; start a new turn")
289
299
  if params.get("input_id") in turn._seen: # noqa: SLF001
290
300
  return {"accepted": True}
301
+ if (turn.params.get("config") or {}).get("input_skills"):
302
+ raise RPCError(JsonRpcErrorCode.Conflict, "selected-skill input requires its own turn")
291
303
  turn._seen.add(params.get("input_id", "")) # noqa: SLF001
292
304
  put = asyncio.ensure_future(turn.inputs.put(params))
293
305
  ended = asyncio.ensure_future(turn._done.wait()) # noqa: SLF001
@@ -1,4 +1,4 @@
1
- # Code generated by tools/contract/gen-python.mjs from contracts/bma (executor protocol 1.4.0). DO NOT EDIT.
1
+ # Code generated by tools/contract/gen-python.mjs from contracts/bma (executor protocol 1.5.0). DO NOT EDIT.
2
2
 
3
3
  from __future__ import annotations
4
4
 
@@ -28,6 +28,7 @@ class AgentCapability(TypedDict):
28
28
  custom_tools: NotRequired[bool]
29
29
  harness: NotRequired[AgentHarnessCapability]
30
30
  harnesses: NotRequired[list[AgentHarnessCapability]]
31
+ input_skills: NotRequired[bool]
31
32
 
32
33
  class AgentCustomToolUseEvent(TypedDict):
33
34
  """A custom tool the local agent is calling: a tool the user's application runs and answers (capability agent.custom_tools). Its event_id is the tool_use_id. The platform shows the session as waiting (session.status_idle with stop_reason requires_action naming the event) and delivers the user's result with agent.custom_tool_result. The turn stays open while the executor waits: the executor does not send session.status_idle for it. If its own timeout passes first, the executor ends the call with a failed agent.tool_result naming this event."""
@@ -147,6 +148,8 @@ class AgentTurnConfig(TypedDict):
147
148
  environment_info: NotRequired[EnvironmentInfo]
148
149
  system: NotRequired[str]
149
150
  harness: NotRequired[str]
151
+ input_skills: NotRequired[list[InputSkillDocument]]
152
+ input_skill_receipt: NotRequired[InputSkillReceipt]
150
153
 
151
154
  class ArtifactCapability(TypedDict):
152
155
  """v1.1 artifact upload (POST /v1/environments/{environment_id}/artifacts; legacy alias POST /v1/executors/artifacts). Environment-scoped executors only."""
@@ -396,6 +399,23 @@ class IOMode(str, Enum):
396
399
  """process.start io_mode. "pty" runs the command on a 24x80 pseudo-terminal: stdout is the PTY output, stdin writes go to the PTY and close_stdin is rejected. Requires process.pty."""
397
400
  Pty = "pty"
398
401
 
402
+ class InputSkillDocument(TypedDict):
403
+ """Exact SKILL.md bytes for one authorized frozen revision. Hash covers UTF-8 body bytes, independently verified by the executor. At most 256 KiB across the selected documents."""
404
+ skill_id: str
405
+ revision_id: str
406
+ name: str
407
+ body: str
408
+ body_sha256: str
409
+
410
+ class InputSkillReceipt(TypedDict):
411
+ input_id: str
412
+ skills: list[InputSkillVersionReceipt]
413
+
414
+ class InputSkillVersionReceipt(TypedDict):
415
+ skill_id: str
416
+ revision_id: str
417
+ body_sha256: str
418
+
399
419
  class InteractionCancelReason(str, Enum):
400
420
  """Why the executor withdrew an open interaction."""
401
421
  ResolvedLocally = "resolved_locally"
@@ -0,0 +1,89 @@
1
+ """Unsupported input controls fail before any session or handler is touched."""
2
+ import pytest
3
+ from bma_executor_sdk.agent import _AgentRuntime
4
+ from bma_executor_sdk.generated import JsonRpcErrorCode
5
+ from bma_executor_sdk._rpc import RPCError
6
+
7
+ async def test_unsupported_selected_skills_refused_before_handler():
8
+ runtime = _AgentRuntime(None, None, {"enabled": True})
9
+ params = {"session_id":"sesn_test","turn_id":"turn_test","input_id":"in_test","input":[{"type":"text","text":"test"}],"config":{"input_skills":[{"skill_id":"skl_test","revision_id":"skr_v1","name":"Review","body":"skill","body_sha256":"a"*64}]}}
10
+ with pytest.raises(RPCError) as failure:
11
+ await runtime.turn_start(params)
12
+ assert failure.value.code == JsonRpcErrorCode.CapabilityUnavailable
13
+ params["config"] = {"input_skill_receipt":{"input_id":"in_test","skills":[]}}
14
+ with pytest.raises(RPCError) as failure:
15
+ await runtime.turn_start(params)
16
+ assert failure.value.code == JsonRpcErrorCode.InvalidParams
17
+
18
+
19
+ @pytest.mark.parametrize("value", [{}, [], None, False, [None], [{"skill_id":"skl_only"}]])
20
+ async def test_malformed_selected_skills_refused_before_handler(value):
21
+ runtime = _AgentRuntime(None, None, {"enabled": True})
22
+ with pytest.raises(RPCError) as failure:
23
+ await runtime.turn_start({"config":{"input_skills":value}})
24
+ assert failure.value.code == JsonRpcErrorCode.InvalidParams
25
+
26
+ async def test_null_receipt_is_still_effective_only():
27
+ runtime = _AgentRuntime(None, None, {"enabled": True})
28
+ with pytest.raises(RPCError) as failure:
29
+ await runtime.turn_start({"config":{"input_skill_receipt":None}})
30
+ assert failure.value.code == JsonRpcErrorCode.InvalidParams
31
+
32
+ async def test_selected_skill_turn_refuses_another_input():
33
+ from bma_executor_sdk.agent import AgentTurn, _AgentSession
34
+ runtime = _AgentRuntime(None, None, {"enabled": True, "input_skills":True})
35
+ session = _AgentSession(runtime,"s")
36
+ session.turn = AgentTurn(session,{"turn_id":"t","input_id":"opening","config":{"input_skills":[{}]}})
37
+ runtime.sessions["s"] = session
38
+ with pytest.raises(RPCError) as failure:
39
+ await runtime.turn_input({"session_id":"s","turn_id":"t","input_id":"other"})
40
+ assert failure.value.code == JsonRpcErrorCode.Conflict
41
+ assert await runtime.turn_input({"session_id":"s","turn_id":"t","input_id":"opening"}) == {"accepted":True}
42
+
43
+ def test_exact_receipt_bound_to_opening_input_and_revision():
44
+ from bma_executor_sdk._input_skills import validate_input_skill_receipt
45
+ from copy import deepcopy
46
+ doc = {"skill_id":"skl_one","revision_id":"skr_one","body_sha256":"a"*64}
47
+ params = {"input_id":"opening","config":{"input_skills":[doc]}}
48
+ result = {"effective":{"input_skill_receipt":{"input_id":"opening","skills":[doc]}}}
49
+ validate_input_skill_receipt(params,result)
50
+ invalid = [{}, {"effective":{"input_skill_receipt":{"input_id":"other","skills":[doc]}}}, {"effective":{"input_skill_receipt":{"input_id":"opening","skills":[]}}}]
51
+ changed = deepcopy(result);changed["effective"]["input_skill_receipt"]["skills"][0]["revision_id"] = "skr_other";invalid.append(changed)
52
+ for receipt in invalid:
53
+ with pytest.raises(RPCError):
54
+ validate_input_skill_receipt(params,receipt)
55
+
56
+ async def test_receipt_refusal_unblocks_concurrent_close():
57
+ import asyncio
58
+ from types import SimpleNamespace
59
+ started, release = asyncio.Event(), asyncio.Event()
60
+ ran = []
61
+ async def opened(params):
62
+ started.set();await release.wait()
63
+ return {"accepted":True,"turn_id":"t","effective":{}}
64
+ async def run(turn):
65
+ ran.append(True)
66
+ async def close(sid,reason):
67
+ pass
68
+ async def call(*args):
69
+ return {"accepted":True}
70
+ tasks = []
71
+ def spawn(work):
72
+ task=asyncio.create_task(work);tasks.append(task);return task
73
+ client=SimpleNamespace(_sessions=set(),_spawn=spawn,_registered=asyncio.Event(),_call=call,_log=lambda *args:None)
74
+ runtime=_AgentRuntime(client,SimpleNamespace(open_turn=opened,run_turn=run,close_session=close),{"enabled":True,"input_skills":True})
75
+ params={"session_id":"s","turn_id":"t","input_id":"i","input":[{"type":"text","text":"x"}],"config":{"input_skills":[{"skill_id":"skl_one","revision_id":"skr_one","name":"One","body":"skill","body_sha256":"a"*64}]}}
76
+ opening=asyncio.create_task(runtime.turn_start(params))
77
+ await started.wait()
78
+ closing=asyncio.create_task(runtime.session_close({"session_id":"s","reason":"test"}))
79
+ # Wait for session.close's cancellation, proving it captured this turn.
80
+ async def captured():
81
+ while not runtime.sessions["s"].turn._canceled:
82
+ await asyncio.sleep(0)
83
+ await asyncio.wait_for(captured(),1)
84
+ release.set()
85
+ with pytest.raises(RPCError):
86
+ await opening
87
+ assert await asyncio.wait_for(closing,1)=={"closed":True}
88
+ assert not ran
89
+ await asyncio.gather(*tasks)