bma-executor-sdk 1.6.0__tar.gz → 1.6.2__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 (41) hide show
  1. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/PKG-INFO +1 -1
  2. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/pyproject.toml +1 -1
  3. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/src/bma_executor_sdk/__init__.py +2 -1
  4. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/src/bma_executor_sdk/agent.py +82 -4
  5. bma_executor_sdk-1.6.2/tests/test_agent_event_resync.py +169 -0
  6. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/.gitignore +0 -0
  7. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/README.md +0 -0
  8. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/examples/agent_minimal.py +0 -0
  9. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/examples/executor_minimal.py +0 -0
  10. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/examples/harness_loopback.py +0 -0
  11. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/examples/session_context.py +0 -0
  12. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/src/bma_executor_sdk/_input_skills.py +0 -0
  13. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/src/bma_executor_sdk/_methods.py +0 -0
  14. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/src/bma_executor_sdk/_npipe.py +0 -0
  15. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/src/bma_executor_sdk/_rpc.py +0 -0
  16. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/src/bma_executor_sdk/client.py +0 -0
  17. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/src/bma_executor_sdk/generated.py +0 -0
  18. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/src/bma_executor_sdk/harness.py +0 -0
  19. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/src/bma_executor_sdk/methods.py +0 -0
  20. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/src/bma_executor_sdk/py.typed +0 -0
  21. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/src/bma_executor_sdk/session_context.py +0 -0
  22. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/src/bma_executor_sdk/tools.py +0 -0
  23. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/src/bma_executor_sdk/transport.py +0 -0
  24. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/tests/executor_helpers.py +0 -0
  25. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/tests/test_agent_input_skills.py +0 -0
  26. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/tests/test_base_url.py +0 -0
  27. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/tests/test_close_codes.py +0 -0
  28. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/tests/test_example_session_context.py +0 -0
  29. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/tests/test_executor_conformance.py +0 -0
  30. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/tests/test_executor_contract.py +0 -0
  31. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/tests/test_executor_interop.py +0 -0
  32. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/tests/test_executor_runtime.py +0 -0
  33. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/tests/test_executor_token_refresh.py +0 -0
  34. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/tests/test_npipe.py +0 -0
  35. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/tests/test_reconnect.py +0 -0
  36. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/tests/test_registration_refused.py +0 -0
  37. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/tests/test_review.py +0 -0
  38. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/tests/test_rpc_unretrieved_future.py +0 -0
  39. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/tests/test_session_context.py +0 -0
  40. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/tests/test_typed_tools.py +0 -0
  41. {bma_executor_sdk-1.6.0 → bma_executor_sdk-1.6.2}/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.6.0
3
+ Version: 1.6.2
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.6.0"
3
+ version = "1.6.2"
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"
@@ -18,7 +18,7 @@ from ._rpc import (
18
18
  SessionContextNotFoundError,
19
19
  )
20
20
  from .session_context import SessionContext
21
- from .agent import AgentEventRecord, AgentHandler, AgentPlatform, AgentSessionClosedError, AgentTurn
21
+ from .agent import AgentEventRecord, AgentHandler, AgentPlatform, AgentSessionClosedError, AgentTurn, EventRejectedError
22
22
  from .client import (
23
23
  DEFAULT_BASE_URL,
24
24
  MACHINE_ID_ENV,
@@ -75,6 +75,7 @@ __all__ = [
75
75
  "METADATA_AGENT_SESSION_ID",
76
76
  "DaemonHTTPError",
77
77
  "ErrorReason",
78
+ "EventRejectedError",
78
79
  "MachineTokenRequiredError",
79
80
  "SessionContext",
80
81
  "SessionContextNotFoundError",
@@ -68,6 +68,21 @@ class AgentSessionClosedError(ExecutorError):
68
68
  super().__init__("agent session closed")
69
69
 
70
70
 
71
+ class EventRejectedError(ExecutorError):
72
+ """Why the SDK ended a turn: the platform rejected one of its events for
73
+ good, and the turn cannot go on without it. The turn ends with
74
+ session.error (agent_error, "event_rejected: ...") and session.status_idle
75
+ (retries_exhausted, failed) at the rejected sequence, its task is canceled
76
+ (AgentTurn.event_rejected is set first) and its later events are not sent."""
77
+
78
+ def __init__(self, event_id: str, cause: RPCError) -> None:
79
+ super().__init__(
80
+ f"event_rejected: the platform rejected event {event_id} of this turn ({cause.code}: {cause.message}); the turn cannot go on without it"
81
+ )
82
+ self.event_id = event_id
83
+ self.cause = cause
84
+
85
+
71
86
  # --- executor side ---
72
87
 
73
88
 
@@ -102,6 +117,8 @@ class AgentTurn:
102
117
  self._canceled = False
103
118
  self._done = asyncio.Event()
104
119
  self.ended = False
120
+ self.event_rejected: EventRejectedError | None = None
121
+ """Set when the SDK ended the turn because the platform rejected one of its events for good."""
105
122
 
106
123
  @property
107
124
  def session_id(self) -> str:
@@ -404,6 +421,8 @@ class _AgentSession:
404
421
  self.custom_done: set[str] = set()
405
422
  self.answered: set[str] = set()
406
423
  self.sender: asyncio.Task[Any] | None = None
424
+ self.failed_turns: set[str] = set()
425
+ """Turns ended after a permanent rejection: their later events are not sent."""
407
426
 
408
427
  def new_event_id(self) -> str:
409
428
  self.next_id += 1
@@ -412,6 +431,8 @@ class _AgentSession:
412
431
  def enqueue(self, turn_id: str, event_id: str, event: Any) -> None:
413
432
  if self.closed:
414
433
  raise AgentSessionClosedError()
434
+ if turn_id in self.failed_turns:
435
+ return # the turn already ended on the channel
415
436
  self.outbox.append({"session_id": self.id, "turn_id": turn_id, "event_id": event_id, "sequence": self.next_seq, "event": event})
416
437
  self.next_seq += 1
417
438
  self.drained.clear()
@@ -429,7 +450,11 @@ class _AgentSession:
429
450
  async def send_loop(self) -> None:
430
451
  """Deliver the outbox head first, one event at a time, so the platform
431
452
  sees every session in sequence order. A transport failure keeps the
432
- event and waits for the next registration: the resend after reconnect."""
453
+ event and waits for the next registration: the resend after reconnect.
454
+ No failure leaves a hole in the sequence: the platform's own failure
455
+ (-32603) is resent, a gap answer (-32013 with expected_sequence)
456
+ renumbers the unacknowledged events from it, and any other rejection
457
+ ends the event's turn at that sequence (_end_turn)."""
433
458
  client = self.runtime.client
434
459
  while True:
435
460
  if not self.outbox:
@@ -440,17 +465,70 @@ class _AgentSession:
440
465
  continue
441
466
  head = self.outbox[0]
442
467
  try:
443
- await self.call_until_connected(lambda: client._call(METHOD_SESSION_EVENT, head))
468
+ await self.call_until_connected(lambda: client._call(METHOD_SESSION_EVENT, {k: v for k, v in head.items() if k != "terminal"}))
444
469
  except ClientStoppedError:
445
470
  return
446
471
  except RPCError as error:
447
- # A permanent rejection cannot be fixed by resending; surface it
448
- # instead of blocking the session.
472
+ if error.code == JsonRpcErrorCode.InternalError:
473
+ # The platform's own failure (a storage conflict or outage):
474
+ # the event is idempotent, send it again.
475
+ client._log("warn", f"session.event {head['event_id']} failed on the platform; resending", error) # noqa: SLF001
476
+ await asyncio.sleep(_AGENT_RESEND_DELAY)
477
+ continue
478
+ expected = (error.data or {}).get("expected_sequence") if error.code == JsonRpcErrorCode.Conflict else None
479
+ if isinstance(expected, int) and expected > 0:
480
+ self._resync(expected)
481
+ continue
449
482
  client._log("error", f"session.event {head['event_id']} rejected", error) # noqa: SLF001
483
+ if not head.get("terminal"):
484
+ # Going on past a rejected event would leave a hole in the
485
+ # session: end its turn at this sequence.
486
+ self._end_turn(head, error)
487
+ continue
450
488
  self.outbox.popleft()
451
489
  if not self.outbox:
452
490
  self.drained.set()
453
491
 
492
+ def _resync(self, expected: int) -> None:
493
+ """Follow the platform's expected_sequence: events below it are
494
+ persisted, the rest are numbered from it."""
495
+ if expected > self.outbox[0]["sequence"]:
496
+ while self.outbox and self.outbox[0]["sequence"] < expected:
497
+ self.outbox.popleft()
498
+ if not self.outbox:
499
+ self.drained.set()
500
+ return
501
+ self._renumber(expected)
502
+
503
+ def _renumber(self, first: int) -> None:
504
+ for index, item in enumerate(self.outbox):
505
+ item["sequence"] = first + index
506
+ self.next_seq = first + len(self.outbox)
507
+
508
+ def _end_turn(self, rejected: dict[str, Any], cause: RPCError) -> None:
509
+ """Replace the rejected event and every later event of its turn by
510
+ session.error + session.status_idle (retries_exhausted, failed) at the
511
+ rejected sequence, and cancel the turn's task."""
512
+ turn_id = rejected["turn_id"]
513
+ reason = EventRejectedError(rejected["event_id"], cause)
514
+ self.failed_turns.add(turn_id)
515
+ rest = [item for item in self.outbox if item["turn_id"] != turn_id]
516
+
517
+ def end(event: dict[str, Any]) -> dict[str, Any]:
518
+ return {"session_id": self.id, "turn_id": turn_id, "event_id": self.new_event_id(), "sequence": 0, "event": event, "terminal": True}
519
+
520
+ self.outbox.clear()
521
+ self.outbox.extend([
522
+ end(_session_error("agent_error", str(reason))),
523
+ end({"type": AgentEventType.SessionStatusIdle.value, "stop_reason": {"type": "retries_exhausted"}, "turn_outcome": TurnOutcome.Failed.value}),
524
+ *rest,
525
+ ])
526
+ self._renumber(rejected["sequence"])
527
+ turn = self.turn
528
+ if turn is not None and turn.turn_id == turn_id:
529
+ turn.event_rejected = reason
530
+ _cancel_turn(turn)
531
+
454
532
  async def call_until_connected(self, call: Callable[[], Awaitable[Any]]) -> Any:
455
533
  """Retry call across disconnects. Only transport failures,
456
534
  executor_busy and retryable JSON-RPC errors are retried."""
@@ -0,0 +1,169 @@
1
+ """session.event failures must never leave a hole in a session's sequence: a
2
+ platform failure is resent, a gap answer renumbers from expected_sequence, and a
3
+ permanent rejection ends the turn visibly at the rejected sequence (11-12: one
4
+ rejected event left a session stuck on "sequence gap" for good). Same
5
+ scenarios as the Go agent_event_resync_test.go and the TypeScript
6
+ agent-event-resync.test.ts."""
7
+
8
+ from __future__ import annotations
9
+
10
+ import asyncio
11
+ from typing import Any
12
+
13
+ import bma_executor_sdk as bx
14
+ from bma_executor_sdk.agent import _AgentRuntime
15
+ from bma_executor_sdk.generated import ConnectionState, JsonRpcErrorCode
16
+
17
+
18
+ class FakeClient:
19
+ """The platform side of session.event, scripted per call."""
20
+
21
+ def __init__(self) -> None:
22
+ self.stored: list[dict[str, Any]] = []
23
+ self.sent: list[int] = []
24
+ self.acked = 0
25
+ self.failures: dict[int, bx.RPCError] = {}
26
+ """Answers the n-th call (0-based) with an error instead of storing it."""
27
+ self.refuse: set[str] = set()
28
+ """Event types refused for good, every time."""
29
+ self.calls = 0
30
+ self._registered = asyncio.Event()
31
+ self._registered.set()
32
+ self._stopped = False
33
+ self._sessions: set[str] = set()
34
+ self.state = ConnectionState.Ready
35
+ self.tasks: set[asyncio.Task[Any]] = set()
36
+
37
+ async def _call(self, method: str, params: dict[str, Any]) -> dict[str, Any]:
38
+ if method != "session.event":
39
+ return {"accepted": True}
40
+ self.sent.append(params["sequence"])
41
+ call, self.calls = self.calls, self.calls + 1
42
+ if call in self.failures:
43
+ raise self.failures[call]
44
+ if params["event"]["type"] in self.refuse:
45
+ raise bx.RPCError(JsonRpcErrorCode.InvalidParams, "bad event")
46
+ if params["sequence"] <= self.acked:
47
+ return {"accepted": True, "acked_sequence": self.acked}
48
+ if params["sequence"] != self.acked + 1:
49
+ raise bx.RPCError(JsonRpcErrorCode.Conflict, "conflict", {"retryable": False, "expected_sequence": self.acked + 1})
50
+ self.acked = params["sequence"]
51
+ self.stored.append({"sequence": params["sequence"], "type": params["event"]["type"], "event": params["event"]})
52
+ return {"accepted": True, "acked_sequence": self.acked}
53
+
54
+ def _spawn(self, coro: Any) -> asyncio.Task[Any]:
55
+ task = asyncio.ensure_future(coro)
56
+ self.tasks.add(task)
57
+ return task
58
+
59
+ def _log(self, *_: Any) -> None:
60
+ pass
61
+
62
+ def types(self) -> list[str]:
63
+ return [s["type"] for s in self.stored]
64
+
65
+ def sequences(self) -> list[int]:
66
+ return [s["sequence"] for s in self.stored]
67
+
68
+ async def close(self) -> None:
69
+ self._stopped = True
70
+ for task in self.tasks:
71
+ task.cancel()
72
+ await asyncio.gather(*self.tasks, return_exceptions=True)
73
+
74
+
75
+ class Agent:
76
+ """Emits three events; then waits for release or cancellation and records
77
+ the turn's event_rejected."""
78
+
79
+ def __init__(self, release: asyncio.Event) -> None:
80
+ self.release = release
81
+ self.rejected: list[Any] = []
82
+
83
+ async def open_turn(self, params: Any) -> Any:
84
+ return {"accepted": True, "turn_id": params["turn_id"], "executor_session_ref": "ref", "resumed": False, "effective": {}}
85
+
86
+ async def run_turn(self, turn: bx.AgentTurn) -> None:
87
+ turn.emit({"type": "agent.message", "content": [{"type": "text", "text": "one"}]})
88
+ turn.emit({"type": "agent.tool_use", "name": "bash", "input": {}})
89
+ turn.emit({"type": "agent.message", "content": [{"type": "text", "text": "two"}]})
90
+ try:
91
+ await self.release.wait()
92
+ finally:
93
+ self.rejected.append(turn.event_rejected)
94
+
95
+ async def close_session(self, session_id: str, reason: str) -> None:
96
+ pass
97
+
98
+
99
+ async def run(client: FakeClient, release: asyncio.Event) -> Agent:
100
+ agent = Agent(release)
101
+ runtime = _AgentRuntime(client, agent, {"enabled": True}) # type: ignore[arg-type,typeddict-item]
102
+ await runtime.turn_start({"session_id": "ses_1", "turn_id": "t_1", "input_id": "in_1", "input": [{"type": "text", "text": "go"}]}) # type: ignore[typeddict-item]
103
+ return agent
104
+
105
+
106
+ async def wait_for(predicate: Any, timeout: float = 5.0) -> None:
107
+ async def loop() -> None:
108
+ while not predicate():
109
+ await asyncio.sleep(0.01)
110
+
111
+ await asyncio.wait_for(loop(), timeout)
112
+
113
+
114
+ def has_idle(client: FakeClient) -> bool:
115
+ return "session.status_idle" in client.types()
116
+
117
+
118
+ async def test_platform_failure_is_resent_in_place() -> None:
119
+ client = FakeClient()
120
+ # -32603 not marked retryable: the platform's own failure, the event is idempotent.
121
+ client.failures[2] = bx.RPCError(JsonRpcErrorCode.InternalError, "internal error")
122
+ release = asyncio.Event()
123
+ release.set()
124
+ try:
125
+ await run(client, release)
126
+ await wait_for(lambda: has_idle(client))
127
+ assert client.types() == ["session.status_running", "agent.message", "agent.tool_use", "agent.message", "session.status_idle"]
128
+ assert client.sequences() == [1, 2, 3, 4, 5]
129
+ finally:
130
+ await client.close()
131
+
132
+
133
+ async def test_gap_answer_renumbers_from_expected_sequence() -> None:
134
+ client = FakeClient()
135
+ release = asyncio.Event()
136
+ try:
137
+ await run(client, release)
138
+ await wait_for(lambda: len(client.stored) == 4)
139
+ # The platform starts a new epoch for the session: it expects 1 again.
140
+ client.acked = 0
141
+ client.stored.clear()
142
+ release.set()
143
+ await wait_for(lambda: has_idle(client))
144
+ assert client.sequences() == [1], "the next event is renumbered to the expected sequence"
145
+ assert client.sent[-2] == 5, "it was first sent as 5 and refused as a gap"
146
+ finally:
147
+ await client.close()
148
+
149
+
150
+ async def test_permanent_rejection_ends_the_turn_at_that_sequence() -> None:
151
+ client = FakeClient()
152
+ client.refuse.add("agent.tool_use")
153
+ release = asyncio.Event()
154
+ try:
155
+ agent = await run(client, release)
156
+ await wait_for(lambda: has_idle(client))
157
+ assert client.types() == ["session.status_running", "agent.message", "session.error", "session.status_idle"]
158
+ assert client.sequences() == [1, 2, 3, 4], "the terminal events take the rejected sequence on"
159
+ error = client.stored[2]["event"]["error"]
160
+ assert error["type"] == "agent_error" and error["message"].startswith("event_rejected: ")
161
+ assert client.stored[3]["event"]["stop_reason"] == {"type": "retries_exhausted"}
162
+ assert client.stored[3]["event"]["turn_outcome"] == "failed"
163
+ await wait_for(lambda: agent.rejected)
164
+ assert isinstance(agent.rejected[0], bx.EventRejectedError), "the turn is stopped"
165
+ release.set()
166
+ await asyncio.sleep(0.05)
167
+ assert len(client.stored) == 4, "nothing of the ended turn follows"
168
+ finally:
169
+ await client.close()