holon-sh 0.0.1.dev19__tar.gz → 0.0.1.dev21__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 (27) hide show
  1. {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev21}/PKG-INFO +1 -1
  2. {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev21}/holon/ext/events/_client.py +9 -4
  3. {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev21}/holon/ext/files/__init__.py +2 -1
  4. {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev21}/holon/ext/files/_server.py +46 -25
  5. {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev21}/pyproject.toml +1 -1
  6. {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev21}/tests/test_events.py +6 -0
  7. {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev21}/tests/test_files.py +44 -11
  8. {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev21}/.gitignore +0 -0
  9. {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev21}/LICENSE +0 -0
  10. {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev21}/README.md +0 -0
  11. {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev21}/holon/client.py +0 -0
  12. {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev21}/holon/context.py +0 -0
  13. {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev21}/holon/ext/__init__.py +0 -0
  14. {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev21}/holon/ext/events/__init__.py +0 -0
  15. {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev21}/holon/ext/events/_server.py +0 -0
  16. {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev21}/holon/ext/events/_wire.py +0 -0
  17. {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev21}/holon/ext/files/_client.py +0 -0
  18. {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev21}/holon/ext/files/_wire.py +0 -0
  19. {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev21}/holon/py.typed +0 -0
  20. {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev21}/holon/serve.py +0 -0
  21. {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev21}/scripts/verify_distribution.py +0 -0
  22. {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev21}/tests/fixtures/caller/holon/apps/__init__.py +0 -0
  23. {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev21}/tests/test_context.py +0 -0
  24. {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev21}/tests/test_elicit.py +0 -0
  25. {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev21}/tests/test_package.py +0 -0
  26. {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev21}/tests/test_runtime.py +0 -0
  27. {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev21}/tests/test_serve.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: holon-sh
3
- Version: 0.0.1.dev19
3
+ Version: 0.0.1.dev21
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
@@ -141,7 +141,8 @@ class AppEvents:
141
141
  arguments: The subscription's arguments.
142
142
  cursor: Where to resume from. Defaults to now.
143
143
  max_age: Seconds; older events are not replayed.
144
- delivery: ``"push"`` or ``"poll"``. Defaults to push when offered.
144
+ delivery: ``"push"`` or ``"poll"``, which the app refuses when it does not offer it.
145
+ Defaults to push when offered.
145
146
  on_gap: Called when events were skipped.
146
147
 
147
148
  Returns:
@@ -279,10 +280,14 @@ class Subscription(Generic[D]):
279
280
  self._send.close()
280
281
 
281
282
  async def _follow(self, client: Client) -> None:
282
- listed = [each for each in await _list(client) if each["name"] == self._name]
283
- # An unlisted type is left for the app to refuse.
284
- offered = listed[0].get("delivery", []) if listed else ["poll"]
285
283
  wanted: list[Delivery] = [self.delivery] if self.delivery else ["push", "poll"]
284
+ # A named mode, like an unlisted type, is left for the app to refuse.
285
+ offered: list[str] = list(wanted)
286
+ if not self.delivery:
287
+ listed = [
288
+ each for each in await _list(client) if each["name"] == self._name
289
+ ]
290
+ offered = listed[0].get("delivery", []) if listed else ["poll"]
286
291
  modes = [mode for mode in wanted if mode in offered]
287
292
  if not modes:
288
293
  raise NoCompatibleDeliveryMode(
@@ -1,7 +1,8 @@
1
1
  """Files in MCP tool calls.
2
2
 
3
3
  Clients pass a :class:`File` and read returned files with :func:`downloads`. Servers accept files with
4
- :class:`FileServer` and a :class:`Storage` such as :class:`LocalStorage`.
4
+ :class:`FileServer` and a :class:`Storage` such as :class:`LocalStorage`; a tool declares each file argument a
5
+ :class:`ReceivedFile`.
5
6
 
6
7
  https://github.com/modelcontextprotocol/experimental-ext-file-uploads/blob/main/specification/draft/file-uploads.md
7
8
  """
@@ -13,9 +13,9 @@ import shutil
13
13
  import tempfile
14
14
  import time
15
15
  from collections.abc import Callable, Mapping
16
- from dataclasses import dataclass, replace
16
+ from dataclasses import replace
17
17
  from pathlib import Path
18
- from typing import Annotated, Any, Literal, Protocol
18
+ from typing import Annotated, Any, Literal, Protocol, final
19
19
  from urllib.parse import quote
20
20
 
21
21
  import anyio
@@ -38,6 +38,7 @@ from mcp.types import (
38
38
  TextContent,
39
39
  )
40
40
  from pydantic import BaseModel, ConfigDict, Field, ValidationError
41
+ from pydantic_core import CoreSchema, core_schema
41
42
  from starlette import status
42
43
  from starlette.requests import ClientDisconnect, Request
43
44
  from starlette.responses import FileResponse, Response
@@ -50,6 +51,7 @@ from holon.ext.files._wire import (
50
51
  b64url,
51
52
  declared,
52
53
  digest_required,
54
+ file_input_schema,
53
55
  media_type,
54
56
  sha256,
55
57
  walk_files,
@@ -61,23 +63,50 @@ _STATE = "files."
61
63
  _TTL = 900.0
62
64
 
63
65
 
64
- @dataclass(frozen=True)
66
+ @final
65
67
  class ReceivedFile:
66
- """A file argument, its bytes checked against its size and any digest.
68
+ """A file argument of the current call, its bytes checked against its size and any digest.
69
+
70
+ A tool takes one by declaring an argument ``ReceivedFile``. ``ReceivedFile(value)`` decodes
71
+ an argument's value where Pydantic does not, such as in a msgspec ``dec_hook``.
67
72
 
68
73
  Attributes:
69
74
  name: Client-given name. Untrusted.
70
75
  mime_type: Client-claimed media type. Untrusted.
71
76
  size: Size in bytes.
72
77
  digest: Base64url SHA-256, when verified.
78
+
79
+ Raises:
80
+ ValueError: ``value`` is not a file argument of the current call.
73
81
  """
74
82
 
83
+ __slots__ = ("_source", "digest", "mime_type", "name", "size")
75
84
  name: str | None
76
85
  mime_type: str
77
86
  size: int
78
87
  digest: str | None
79
88
  _source: Path | bytes
80
89
 
90
+ def __new__(cls, value: object) -> ReceivedFile:
91
+ file_id = value.get("id") if isinstance(value, dict) else None
92
+ found = (
93
+ (_received.get() or {}).get(file_id) if isinstance(file_id, str) else None
94
+ )
95
+ if found is None:
96
+ raise ValueError("not a file argument of this call")
97
+ return found
98
+
99
+ def __setattr__(self, name: str, value: object) -> None:
100
+ raise AttributeError(f"ReceivedFile.{name} is read-only")
101
+
102
+ @classmethod
103
+ def __get_pydantic_core_schema__(cls, *_: object) -> CoreSchema:
104
+ return core_schema.no_info_plain_validator_function(cls)
105
+
106
+ @classmethod
107
+ def __get_pydantic_json_schema__(cls, *_: object) -> dict[str, Any]:
108
+ return file_input_schema()
109
+
81
110
  async def read(self) -> bytes:
82
111
  if isinstance(self._source, bytes):
83
112
  return self._source
@@ -153,6 +182,16 @@ class _FileInput(BaseModel):
153
182
  class _Refused(Exception): ...
154
183
 
155
184
 
185
+ def _verified(
186
+ file: _FileInput, digest: str | None, source: Path | bytes
187
+ ) -> ReceivedFile:
188
+ made = object.__new__(ReceivedFile)
189
+ values = (source, digest, file.mimeType, file.name, file.size)
190
+ for slot, value in zip(ReceivedFile.__slots__, values, strict=True):
191
+ object.__setattr__(made, slot, value)
192
+ return made
193
+
194
+
156
195
  _received: contextvars.ContextVar[dict[str, ReceivedFile] | None] = (
157
196
  contextvars.ContextVar("holon_files_received", default=None)
158
197
  )
@@ -161,7 +200,7 @@ _received: contextvars.ContextVar[dict[str, ReceivedFile] | None] = (
161
200
  class FileServer:
162
201
  """Low-level server middleware that accepts file arguments in ``tools/call``.
163
202
 
164
- Insert it first::
203
+ Tools declare each file argument as a ``ReceivedFile``. Insert it first::
165
204
 
166
205
  server.extensions[EXTENSION] = files.settings()
167
206
  server.middleware.insert(0, files)
@@ -192,20 +231,6 @@ class FileServer:
192
231
  return {"upload": {}, "maxInlineBytes": self._max_inline_bytes}
193
232
  return {"upload": {}}
194
233
 
195
- def received(self, file_input: Mapping[str, Any]) -> ReceivedFile:
196
- """The checked bytes of a file argument of the current call.
197
-
198
- Raises:
199
- LookupError: The argument is not a file of this call.
200
- """
201
- file_id = file_input.get("id")
202
- found = (
203
- (_received.get() or {}).get(file_id) if isinstance(file_id, str) else None
204
- )
205
- if found is None:
206
- raise LookupError("not a file argument of this call")
207
- return found
208
-
209
234
  async def reply(
210
235
  self,
211
236
  ctx: ServerRequestContext[Any, Any],
@@ -331,9 +356,7 @@ class FileServer:
331
356
  return _error(
332
357
  f"The bytes of file {file.name or file.id!r} did not arrive intact."
333
358
  )
334
- received[file.id] = ReceivedFile(
335
- file.name, file.mimeType, file.size, digest, path
336
- )
359
+ received[file.id] = _verified(file, digest, path)
337
360
  annotations = definition.get("annotations") or {}
338
361
  if annotations.get("idempotentHint") is not True and not (
339
362
  await self._storage.consume(record["n"], record["e"])
@@ -441,9 +464,7 @@ def _inspect(
441
464
  if digest is not None and sha256(raw) != digest:
442
465
  raise _Refused(f"File {label} does not match its digest.")
443
466
  inline += file.size
444
- received[file.id] = ReceivedFile(
445
- file.name, file.mimeType, file.size, digest, raw
446
- )
467
+ received[file.id] = _verified(file, digest, raw)
447
468
  if inline > max_inline_bytes:
448
469
  raise _Refused("The inline file data is larger than this server accepts.")
449
470
  return received, owed
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "holon-sh"
7
- version = "0.0.1.dev19"
7
+ version = "0.0.1.dev21"
8
8
  description = "Typed MCP clients and the caller of an MCP request"
9
9
  readme = "README.md"
10
10
  license = "Apache-2.0"
@@ -382,6 +382,12 @@ async def test_the_messages_on_the_wire_are_the_sketchs():
382
382
  ),
383
383
  ]:
384
384
  assert (await call(http, port, method, params))["error"]["code"] == code
385
+ with pytest.raises(MCPError) as refused:
386
+ async with client(port).subscribe(
387
+ "board.locked", {"board": "b1"}, delivery="push"
388
+ ):
389
+ pass
390
+ assert refused.value.error.code == -32026
385
391
 
386
392
  url, opened = f"http://127.0.0.1:{port}/mcp", changed.cursor()
387
393
  async with http.stream(
@@ -13,7 +13,9 @@ from pathlib import Path
13
13
  import httpx2
14
14
  import pytest
15
15
  import uvicorn
16
+ from mcp.server import MCPServer
16
17
  from mcp.server.lowlevel import Server
18
+ from mcp.server.mcpserver import Context
17
19
  from mcp.server.streamable_http import CONTENT_TYPE_JSON, CONTENT_TYPE_SSE
18
20
  from mcp.shared.inbound import (
19
21
  MCP_METHOD_HEADER,
@@ -48,6 +50,7 @@ from holon.ext.files import (
48
50
  FileTransferError,
49
51
  LocalStorage,
50
52
  OutcomeUnknownError,
53
+ ReceivedFile,
51
54
  downloads,
52
55
  file_input_schema,
53
56
  )
@@ -84,6 +87,16 @@ TOOLS = [
84
87
  ]
85
88
 
86
89
 
90
+ def asking():
91
+ question = ElicitRequestFormParams(
92
+ message="Why?", requested_schema={"type": "object", "properties": {}}
93
+ )
94
+ return InputRequiredResult(
95
+ input_requests={"why": ElicitRequest(params=question)},
96
+ request_state="asked",
97
+ )
98
+
99
+
87
100
  def serve(tmp_path):
88
101
  """A server whose tools save, check and export files; returns (app, ran)."""
89
102
  storage = LocalStorage(tmp_path / "storage")
@@ -102,15 +115,9 @@ def serve(tmp_path):
102
115
  if params.name == "export":
103
116
  return await files.reply(ctx, CSV, name="report.csv", text="Exported.")
104
117
  if arguments.get("note") == "ask" and not params.input_responses:
105
- question = ElicitRequestFormParams(
106
- message="Why?", requested_schema={"type": "object", "properties": {}}
107
- )
108
- return InputRequiredResult(
109
- input_requests={"why": ElicitRequest(params=question)},
110
- request_state="asked",
111
- )
118
+ return asking()
112
119
  for value in arguments.get("files") or [arguments["file"]]:
113
- received = files.received(value)
120
+ received = ReceivedFile(value)
114
121
  if params.name == "save":
115
122
  await received.save(tmp_path / "saved" / Path(received.name).name)
116
123
  return CallToolResult(content=[TextContent(type="text", text="ok")])
@@ -176,15 +183,16 @@ def run(app, body):
176
183
  asyncio.run(asyncio.wait_for(main(), timeout=20))
177
184
 
178
185
 
186
+ async def answer(params):
187
+ return ElicitResult(action="accept", content={})
188
+
189
+
179
190
  def test_files_reach_the_tool_inline_and_out_of_band(tmp_path):
180
191
  (tmp_path / "notes.txt").write_bytes(b"x" * 100)
181
192
  app, ran = serve(tmp_path)
182
193
  seen = []
183
194
  files = client(app, seen)
184
195
 
185
- async def answer(params):
186
- return ElicitResult(action="accept", content={})
187
-
188
196
  async def body():
189
197
  await files.tools.save(file=File(b"tiny", name="a.txt"), cover=None)
190
198
  [inline] = tool_calls(seen)
@@ -220,6 +228,31 @@ def test_files_reach_the_tool_inline_and_out_of_band(tmp_path):
220
228
  assert ran == ["save"] * 3
221
229
 
222
230
 
231
+ def test_a_declared_file_reaches_its_tool_across_an_input_request(tmp_path):
232
+ storage, server, read = LocalStorage(tmp_path), MCPServer("files"), []
233
+
234
+ async def save(file: ReceivedFile, ctx: Context) -> str:
235
+ if not ctx.input_responses:
236
+ return asking()
237
+ read.append(await file.read())
238
+ return "ok"
239
+
240
+ server.add_tool(save)
241
+ [tool] = asyncio.run(server.list_tools())
242
+ declared = tool.model_dump(by_alias=True, exclude_none=True)
243
+ files = FileServer(storage, tools=lambda name: declared, max_inline_bytes=16)
244
+ server._lowlevel_server.extensions[EXTENSION] = files.settings()
245
+ server.middleware.insert(0, files)
246
+ app = server.streamable_http_app(stateless_http=True, json_response=True)
247
+ app.mount("/mcp/files", storage.app)
248
+
249
+ async def body():
250
+ await client(app, []).tools.save({"elicit": answer}, file=File(b"x" * 100))
251
+
252
+ run(app, body)
253
+ assert read == [b"x" * 100]
254
+
255
+
223
256
  def sink(attempts, served=None):
224
257
  """Where transfers land: records each (method, authorization), serves
225
258
  ``served`` by name, and answers 503 for ``busy``."""
File without changes
File without changes