holon-sh 0.0.1.dev9__tar.gz → 0.0.1.dev10__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 (26) hide show
  1. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev10}/PKG-INFO +2 -2
  2. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev10}/README.md +1 -1
  3. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev10}/holon/ext/events.py +66 -24
  4. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev10}/pyproject.toml +1 -1
  5. holon_sh-0.0.1.dev10/tests/test_events.py +537 -0
  6. holon_sh-0.0.1.dev9/tests/test_events.py +0 -581
  7. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev10}/.gitignore +0 -0
  8. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev10}/LICENSE +0 -0
  9. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev10}/holon/binding.py +0 -0
  10. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev10}/holon/client.py +0 -0
  11. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev10}/holon/context.py +0 -0
  12. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev10}/holon/ext/__init__.py +0 -0
  13. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev10}/holon/ext/files/__init__.py +0 -0
  14. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev10}/holon/ext/files/_client.py +0 -0
  15. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev10}/holon/ext/files/_server.py +0 -0
  16. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev10}/holon/ext/files/_wire.py +0 -0
  17. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev10}/holon/py.typed +0 -0
  18. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev10}/scripts/verify_distribution.py +0 -0
  19. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev10}/tests/fixtures/caller/holon/apps/__init__.py +0 -0
  20. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev10}/tests/fixtures/caller/requirements.txt +0 -0
  21. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev10}/tests/fixtures/caller/server.json +0 -0
  22. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev10}/tests/test_context.py +0 -0
  23. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev10}/tests/test_elicit.py +0 -0
  24. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev10}/tests/test_files.py +0 -0
  25. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev10}/tests/test_package.py +0 -0
  26. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev10}/tests/test_runtime.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: holon-sh
3
- Version: 0.0.1.dev9
3
+ Version: 0.0.1.dev10
4
4
  Summary: Typed MCP clients and the caller of an MCP request
5
5
  Project-URL: Repository, https://github.com/holon-sh/sdk-py
6
6
  License-Expression: Apache-2.0
@@ -14,7 +14,7 @@ Description-Content-Type: text/markdown
14
14
  # Holon Python SDK
15
15
 
16
16
  [![CI](https://github.com/holon-sh/sdk-py/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/holon-sh/sdk-py/actions/workflows/ci.yml)
17
- [![Docs](https://img.shields.io/badge/docs-holon--labs.dev-blue)](https://holon-labs.dev/docs/)
17
+ [![Docs](https://img.shields.io/badge/docs-holonlabs.ai-blue)](https://holonlabs.ai/docs/)
18
18
  [![PyPI](https://img.shields.io/pypi/v/holon-sh)](https://pypi.org/project/holon-sh/)
19
19
  [![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/downloads/)
20
20
  [![Apache 2.0 License](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE)
@@ -1,7 +1,7 @@
1
1
  # Holon Python SDK
2
2
 
3
3
  [![CI](https://github.com/holon-sh/sdk-py/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/holon-sh/sdk-py/actions/workflows/ci.yml)
4
- [![Docs](https://img.shields.io/badge/docs-holon--labs.dev-blue)](https://holon-labs.dev/docs/)
4
+ [![Docs](https://img.shields.io/badge/docs-holonlabs.ai-blue)](https://holonlabs.ai/docs/)
5
5
  [![PyPI](https://img.shields.io/pypi/v/holon-sh)](https://pypi.org/project/holon-sh/)
6
6
  [![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/downloads/)
7
7
  [![Apache 2.0 License](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE)
@@ -38,7 +38,7 @@ import anyio
38
38
  from mcp import Client
39
39
  from mcp.client import Transport
40
40
  from mcp.client._transport import TransportStreams
41
- from mcp.server.context import HandlerResult, ServerRequestContext
41
+ from mcp.server.context import CallNext, HandlerResult, ServerRequestContext
42
42
  from mcp.server.extension import Extension, MethodBinding
43
43
  from mcp.server.lowlevel.server import Server
44
44
  from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
@@ -281,6 +281,7 @@ class _Hold:
281
281
  wake: Callable[[], None]
282
282
  """Told when there is something new for it, or it was ended."""
283
283
  ended: ErrorData | None = None
284
+ until: int = 0
284
285
  missed: bool = False
285
286
  """An event emitted to it could not be given to it, which its next read reports as a gap."""
286
287
 
@@ -387,8 +388,12 @@ class EventType(Generic[A, D]):
387
388
  def terminate(
388
389
  self, subscription_id: str | None = None, error: ErrorData | None = None
389
390
  ) -> None:
390
- """Terminate one subscription, or all of this type's: a stream is sent ``notifications/events/terminated``
391
- with ``error`` and closed, and the next poll is answered with it. Forbidden unless given."""
391
+ """Terminate one subscription, or all of this type's: a stream is sent what was emitted to it before, then
392
+ ``notifications/events/terminated`` with ``error``, and closed. The next poll is answered with the error.
393
+ Forbidden unless given, which ends delivery at once, since access is lost.
394
+ """
395
+ error = error or _FORBIDDEN
396
+ until = 0 if error.code == _FORBIDDEN.code else self._sequence
392
397
  if subscription_id is None:
393
398
  entries = list(self._subscriptions.values())
394
399
  else:
@@ -397,7 +402,7 @@ class EventType(Generic[A, D]):
397
402
  )
398
403
  for hold in [hold for entry in entries for hold in entry.holds]:
399
404
  if hold.ended is None:
400
- hold.ended = error or _FORBIDDEN
405
+ hold.ended, hold.until = error, until
401
406
  hold.wake()
402
407
 
403
408
  def remove(self) -> None:
@@ -451,18 +456,20 @@ class EventType(Generic[A, D]):
451
456
  )
452
457
  return self._kept[index] if index < len(self._kept) else None
453
458
 
454
- # Where a cursor resumes reading what is kept, and whether events between were let go. A None cursor starts from
455
- # now, and so does one from another process.
456
- def _resume(self, cursor: str | None, max_age_ms: int | None) -> tuple[int, bool]:
459
+ # Where a cursor resumes reading what is kept, and whether events between were let go. A None cursor starts where
460
+ # the subscription was opened, so it has what its on_subscribe emitted, and so does one from another process.
461
+ def _resume(
462
+ self, cursor: str | None, max_age_ms: int | None, opened: int
463
+ ) -> tuple[int, bool]:
457
464
  if cursor is None:
458
- return self._sequence, False
465
+ return opened, False
459
466
  epoch, _, text = cursor.partition(".")
460
467
  if (
461
468
  epoch != self._events._epoch
462
469
  or not text.isdigit()
463
470
  or int(text) > self._sequence
464
471
  ):
465
- return self._sequence, True
472
+ return opened, True
466
473
  sequence, truncated = max(int(text), self._dropped), int(text) < self._dropped
467
474
  if max_age_ms is not None:
468
475
  floor = time.monotonic() - max_age_ms / 1000
@@ -496,9 +503,14 @@ class EventType(Generic[A, D]):
496
503
  # What a poll is owed after a cursor from what is kept. An event that cannot be shaped for this subscription is
497
504
  # skipped for it, and the failure logged.
498
505
  def _since(
499
- self, request: _Request, cursor: str | None, max_age_ms: int | None, limit: int
506
+ self,
507
+ request: _Request,
508
+ cursor: str | None,
509
+ max_age_ms: int | None,
510
+ limit: int,
511
+ opened: int,
500
512
  ) -> _Read:
501
- reached, truncated = self._resume(cursor, max_age_ms)
513
+ reached, truncated = self._resume(cursor, max_age_ms, opened)
502
514
  events: list[tuple[dict[str, Any], str | None]] = []
503
515
  while (kept := self._next(reached)) is not None:
504
516
  if len(events) == limit:
@@ -619,8 +631,9 @@ def _streams(ctx: ServerRequestContext[Any, Any]) -> bool:
619
631
  class Events(Extension):
620
632
  """The event types an app serves as MCP Events, by poll and push.
621
633
 
622
- Pass it to ``MCPServer(extensions=[events])``, or call :meth:`serve` on a low-level ``Server``. Over Streamable
623
- HTTP, push is offered only on an endpoint mounted through :meth:`asgi`; elsewhere clients poll.
634
+ Pass it to ``MCPServer(extensions=[events], middleware=[events])``, or call :meth:`serve` on a low-level
635
+ ``Server``. Over Streamable HTTP, push is offered only on an endpoint mounted through :meth:`asgi`; elsewhere
636
+ clients poll.
624
637
 
625
638
  Each type keeps what it emits, for ten minutes and up to 10,000 events and 4 MiB, for polls and for streams that
626
639
  are behind or reconnect; those cursors last as long as the process, and after a restart a client is told that
@@ -744,8 +757,6 @@ class Events(Extension):
744
757
  self._types[name] = declared
745
758
  return declared
746
759
 
747
- # Declared under capabilities.extensions only. The sketch also declares capabilities.events, but the MCP SDK's
748
- # ServerCapabilities drops top-level keys it does not know, and offers no way to add one.
749
760
  def settings(self) -> dict[str, Any]:
750
761
  # Event types change only in the process, and the SDK has no channel to tell every client of it.
751
762
  return {"listChanged": False}
@@ -764,6 +775,21 @@ class Events(Extension):
764
775
  binding.method, binding.params_type, binding.handler
765
776
  )
766
777
  server.extensions[self.identifier] = self.settings()
778
+ server.middleware.append(self)
779
+
780
+ async def __call__(
781
+ self, ctx: ServerRequestContext[Any, Any], call_next: CallNext
782
+ ) -> HandlerResult:
783
+ """Declare ``capabilities.events`` beside ``capabilities.extensions``, as middleware of the server."""
784
+ result = await call_next(ctx)
785
+ if ctx.method in ("initialize", "server/discover") and isinstance(result, dict):
786
+ capabilities = result.get("capabilities")
787
+ if isinstance(capabilities, dict):
788
+ result = {
789
+ **result,
790
+ "capabilities": {**capabilities, "events": self.settings()},
791
+ }
792
+ return result
767
793
 
768
794
  def asgi(self, manager: StreamableHTTPSessionManager) -> ASGIApp:
769
795
  """The endpoint of ``manager``, on which push is offered.
@@ -820,14 +846,20 @@ class Events(Extension):
820
846
  self, ctx: ServerRequestContext[Any, Any], params: _SubscribeParams
821
847
  ) -> HandlerResult:
822
848
  declared, request = await self._subscription(params, "poll", _streams(ctx))
849
+ opened = declared._sequence
823
850
  hold = await self._lease(declared, request)
824
851
  limit = params.max_events or _PAGE
825
852
  if declared._check is not None:
826
853
  read = await declared._checked(
827
854
  hold, request, params.cursor, params.max_age_ms, limit
828
855
  )
856
+ elif params.cursor is None:
857
+ # The sketch: a poll from null "returns no events and provides a fresh cursor".
858
+ read = _Read([], None, declared._position(opened))
829
859
  else:
830
- read = declared._since(request, params.cursor, params.max_age_ms, limit)
860
+ read = declared._since(
861
+ request, params.cursor, params.max_age_ms, limit, opened
862
+ )
831
863
  # A poll carries its cursor once, for the whole answer.
832
864
  return {
833
865
  "events": [occurrence for occurrence, _ in read.events],
@@ -1125,6 +1157,15 @@ class Events(Extension):
1125
1157
  def position() -> str | None:
1126
1158
  return cursor if checked else declared._position(seen)
1127
1159
 
1160
+ async def send(kept: _Kept) -> None:
1161
+ try:
1162
+ shaped = declared._shape(kept, request)
1163
+ except Exception as error: # noqa: BLE001
1164
+ await say("error", {"error": _described(error)})
1165
+ return
1166
+ if shaped is not None:
1167
+ await deliver(shaped, position(), kept.size)
1168
+
1128
1169
  # Without a first answer there is no stream to tell, and the request fails.
1129
1170
  if checked:
1130
1171
  read = await declared._checked(
@@ -1136,7 +1177,9 @@ class Events(Extension):
1136
1177
  await deliver(occurrence, after)
1137
1178
  due = time.monotonic() + (0 if read.has_more else _INTERVAL)
1138
1179
  else:
1139
- seen, truncated = declared._resume(params.cursor, params.max_age_ms)
1180
+ seen, truncated = declared._resume(
1181
+ params.cursor, params.max_age_ms, seen
1182
+ )
1140
1183
  await say("active", {"cursor": position(), "truncated": truncated})
1141
1184
  due = math.inf
1142
1185
  beat = time.monotonic() + _HEARTBEAT
@@ -1179,16 +1222,15 @@ class Events(Extension):
1179
1222
  await say("active", {"cursor": position(), "truncated": True})
1180
1223
  elif (kept := declared._next(seen)) is not None:
1181
1224
  seen = kept.sequence
1182
- try:
1183
- shaped = declared._shape(kept, request)
1184
- except Exception as error: # noqa: BLE001
1185
- await say("error", {"error": _described(error)})
1186
- continue
1187
- if shaped is not None:
1188
- await deliver(shaped, position(), kept.size)
1225
+ await send(kept)
1189
1226
  else:
1190
1227
  with anyio.move_on_after(min(beat, due) - time.monotonic()):
1191
1228
  await wake.wait()
1229
+ while (
1230
+ kept := declared._next(seen)
1231
+ ) is not None and kept.sequence <= hold.until:
1232
+ seen = kept.sequence
1233
+ await send(kept)
1192
1234
  if hold.ended is not None:
1193
1235
  await say(
1194
1236
  "terminated",
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "holon-sh"
7
- version = "0.0.1.dev9"
7
+ version = "0.0.1.dev10"
8
8
  description = "Typed MCP clients and the caller of an MCP request"
9
9
  readme = "README.md"
10
10
  license = "Apache-2.0"