holon-sh 0.0.1.dev1__tar.gz → 0.0.1.dev2__tar.gz

{holon_sh-0.0.1.dev1 → holon_sh-0.0.1.dev2}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Holon Labs
+Copyright (c) 2026 Holon Systems, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

holon_sh-0.0.1.dev2/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.5
+Name: holon-sh
+Version: 0.0.1.dev2
+Summary: Typed MCP clients, bindings, and app views
+Project-URL: Repository, https://github.com/holon-sh/sdk-py
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: httpx2<3,>=2.10
+Requires-Dist: jsonschema<5,>=4.26
+Requires-Dist: mcp<3,>=2.3
+Description-Content-Type: text/markdown
+
+# holon-sh
+
+The Python runtime for typed MCP clients. The [`holon` CLI](https://github.com/holon-sh/cli) reads the MCP servers your server calls and generates `holon.apps`, a typed client module, into your project. This package is what that module runs on: it connects over Streamable HTTP, validates arguments and results against each tool's JSON Schema, and raises on tool errors.
+
+Start with the [CLI README](https://github.com/holon-sh/cli) for the walkthrough. This page is the Python API.
+
+## Install
+
+```sh
+uv add --prerelease allow holon-sh
+uv add --dev mypy==2.4.0     # holon types check runs mypy from the app's .venv
+```
+
+The distribution is `holon-sh`; the import package is `holon`, a namespace package shared with your generated module. Do not create `holon/__init__.py` in your app, and do not edit `holon/apps/__init__.py`: the CLI rewrites it on every run.
+
+## The generated module
+
+```python
+from holon.apps import Inputs, Outputs, apps, create_apps
+```
+
+| Name | What it is |
+|---|---|
+| `apps` | One client per dependency in `server.json` (`apps.orders`), bound through `<NAME>_MCP_URL`. |
+| `create_apps(bindings)` | Clients bound explicitly, for only the dependencies you pass. |
+| `Inputs.<dep>.<tool>` | The tool's argument type, a `TypedDict`. |
+| `Outputs.<dep>.<tool>` | The tool's structured result type, a `TypedDict`. |
+
+### Call a tool
+
+```python
+from holon.apps import apps
+
+async def total(id: str) -> float:
+    order = await apps.orders.tools.lookup({"id": id}, timeout=5.0)
+    return order["total"]
+```
+
+Arguments are one mapping, validated before sending; the result is validated against the output schema and returned. `timeout` is in seconds.
+
+### Handle errors
+
+`tools.<tool>` raises `ToolCallError` when the tool reports an error or asks for more input:
+
+```python
+from holon.client import ToolCallError
+
+try:
+    order = await apps.orders.tools.lookup({"id": id})
+except ToolCallError as error:
+    error.code     # "tool_error" or "input_required"
+    error.result   # the original MCP result
+```
+
+Invalid arguments or a result that does not match the schema raise `ValueError`; transport failures propagate from the MCP client.
+
+### Read the whole result
+
+`call_tool` returns the full MCP result instead of raising:
+
+```python
+result = await apps.orders.call_tool("lookup", {"id": id})
+if result.is_error:
+    ...                          # inspect result.content
+else:
+    result.structured_content    # typed as Outputs.orders.lookup
+```
+
+It also accepts `input_responses`, `request_state` and `meta`. A dependency the CLI could not obtain a contract for offers only `call_tool`, untyped.
+
+## Bind a dependency
+
+By default a client reads its endpoint from an environment variable named after the dependency, upper-cased, with `-` as `_`:
+
+```sh
+ORDERS_MCP_URL=http://127.0.0.1:3001/mcp uv run python server.py
+```
+
+For authentication or a custom HTTP client, bind explicitly. `http_client` is a factory called once per call; the client it returns is closed afterwards:
+
+```python
+import os
+import httpx2
+from holon.apps import create_apps
+
+apps = create_apps({
+    "orders": {
+        "endpoint": "https://orders.example.com/mcp",
+        "http_client": lambda: httpx2.AsyncClient(
+            headers={"Authorization": f"Bearer {os.environ['ORDERS_TOKEN']}"},
+        ),
+    },
+})
+```
+
+Every call opens and closes its own session; there is nothing to close. `holon.binding.set_default_binding` exists for hosts that bind every app at startup; apps do not need it.
+
+## Serve an MCP App view
+
+`holon.view.app_view` registers a built HTML file as an MCP App resource:
+
+```python
+from holon.view import app_view
+
+server.add_resource(app_view(
+    "ui://checkout/index.html", "Checkout", "dist/index.html",
+    connect_domains=["https://orders.example.com"],
+))
+```
+
+The file is read on first request and cached. `connect_domains` and `resource_domains` become the view's content security policy. The page itself uses [`holon-ui`](https://github.com/holon-sh/sdk-ui).
+
+## Development
+
+The package test uses committed clients in `tests/fixtures/caller/holon/apps`.
+To refresh them, install the [holon CLI](https://github.com/holon-sh/cli) and run:
+
+```sh
+./scripts/fixtures.sh
+```
+
+This runs `holon types generate ../orders` from the caller fixture. The CLI
+extracts `tests/fixtures/orders/server.py` without starting the server.
+
+## License
+
+MIT

holon_sh-0.0.1.dev2/README.md

@@ -0,0 +1,127 @@
+# holon-sh
+
+The Python runtime for typed MCP clients. The [`holon` CLI](https://github.com/holon-sh/cli) reads the MCP servers your server calls and generates `holon.apps`, a typed client module, into your project. This package is what that module runs on: it connects over Streamable HTTP, validates arguments and results against each tool's JSON Schema, and raises on tool errors.
+
+Start with the [CLI README](https://github.com/holon-sh/cli) for the walkthrough. This page is the Python API.
+
+## Install
+
+```sh
+uv add --prerelease allow holon-sh
+uv add --dev mypy==2.4.0     # holon types check runs mypy from the app's .venv
+```
+
+The distribution is `holon-sh`; the import package is `holon`, a namespace package shared with your generated module. Do not create `holon/__init__.py` in your app, and do not edit `holon/apps/__init__.py`: the CLI rewrites it on every run.
+
+## The generated module
+
+```python
+from holon.apps import Inputs, Outputs, apps, create_apps
+```
+
+| Name | What it is |
+|---|---|
+| `apps` | One client per dependency in `server.json` (`apps.orders`), bound through `<NAME>_MCP_URL`. |
+| `create_apps(bindings)` | Clients bound explicitly, for only the dependencies you pass. |
+| `Inputs.<dep>.<tool>` | The tool's argument type, a `TypedDict`. |
+| `Outputs.<dep>.<tool>` | The tool's structured result type, a `TypedDict`. |
+
+### Call a tool
+
+```python
+from holon.apps import apps
+
+async def total(id: str) -> float:
+    order = await apps.orders.tools.lookup({"id": id}, timeout=5.0)
+    return order["total"]
+```
+
+Arguments are one mapping, validated before sending; the result is validated against the output schema and returned. `timeout` is in seconds.
+
+### Handle errors
+
+`tools.<tool>` raises `ToolCallError` when the tool reports an error or asks for more input:
+
+```python
+from holon.client import ToolCallError
+
+try:
+    order = await apps.orders.tools.lookup({"id": id})
+except ToolCallError as error:
+    error.code     # "tool_error" or "input_required"
+    error.result   # the original MCP result
+```
+
+Invalid arguments or a result that does not match the schema raise `ValueError`; transport failures propagate from the MCP client.
+
+### Read the whole result
+
+`call_tool` returns the full MCP result instead of raising:
+
+```python
+result = await apps.orders.call_tool("lookup", {"id": id})
+if result.is_error:
+    ...                          # inspect result.content
+else:
+    result.structured_content    # typed as Outputs.orders.lookup
+```
+
+It also accepts `input_responses`, `request_state` and `meta`. A dependency the CLI could not obtain a contract for offers only `call_tool`, untyped.
+
+## Bind a dependency
+
+By default a client reads its endpoint from an environment variable named after the dependency, upper-cased, with `-` as `_`:
+
+```sh
+ORDERS_MCP_URL=http://127.0.0.1:3001/mcp uv run python server.py
+```
+
+For authentication or a custom HTTP client, bind explicitly. `http_client` is a factory called once per call; the client it returns is closed afterwards:
+
+```python
+import os
+import httpx2
+from holon.apps import create_apps
+
+apps = create_apps({
+    "orders": {
+        "endpoint": "https://orders.example.com/mcp",
+        "http_client": lambda: httpx2.AsyncClient(
+            headers={"Authorization": f"Bearer {os.environ['ORDERS_TOKEN']}"},
+        ),
+    },
+})
+```
+
+Every call opens and closes its own session; there is nothing to close. `holon.binding.set_default_binding` exists for hosts that bind every app at startup; apps do not need it.
+
+## Serve an MCP App view
+
+`holon.view.app_view` registers a built HTML file as an MCP App resource:
+
+```python
+from holon.view import app_view
+
+server.add_resource(app_view(
+    "ui://checkout/index.html", "Checkout", "dist/index.html",
+    connect_domains=["https://orders.example.com"],
+))
+```
+
+The file is read on first request and cached. `connect_domains` and `resource_domains` become the view's content security policy. The page itself uses [`holon-ui`](https://github.com/holon-sh/sdk-ui).
+
+## Development
+
+The package test uses committed clients in `tests/fixtures/caller/holon/apps`.
+To refresh them, install the [holon CLI](https://github.com/holon-sh/cli) and run:
+
+```sh
+./scripts/fixtures.sh
+```
+
+This runs `holon types generate ../orders` from the caller fixture. The CLI
+extracts `tests/fixtures/orders/server.py` without starting the server.
+
+## License
+
+MIT

holon_sh-0.0.1.dev2/holon/binding.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import NotRequired, TypedDict
+
+import httpx2
+
+
+class Binding(TypedDict):
+    """Connection settings for an MCP dependency.
+
+    Attributes:
+        endpoint: Streamable HTTP MCP URL.
+        http_client: Factory returning a fresh ``httpx2.AsyncClient`` for each
+            call. Configure authentication headers or a custom transport here.
+            The SDK closes the returned client when the call finishes.
+        scoped: Compatibility setting. Python always opens and closes a session
+            per call, regardless of this value.
+    """
+
+    endpoint: str
+    http_client: NotRequired[Callable[[], httpx2.AsyncClient]]
+    # Python clients open one session per call, so every binding already behaves as scoped.
+    scoped: NotRequired[bool]
+
+
+_resolver: Callable[[str], Binding | None] | None = None
+
+
+def set_default_binding(resolve: Callable[[str], Binding | None]) -> None:
+    """Register the default binding resolver for app clients.
+
+    Args:
+        resolve: Process-wide callback receiving the dependency name. Return a
+            binding or ``None`` to use the environment fallback. Explicit
+            bindings take precedence. Register during application startup.
+    """
+    global _resolver
+    _resolver = resolve
+
+
+def resolve_default_binding(app: str) -> Binding | None:
+    """Return the registered resolver's binding for an app.
+
+    Args:
+        app: Dependency name passed unchanged to the resolver.
+
+    Returns:
+        The resolved binding, or ``None`` if none is available.
+    """
+    return _resolver(app) if _resolver is not None else None

{holon_sh-0.0.1.dev1 → holon_sh-0.0.1.dev2}/holon/client.py

@@ -2,6 +2,8 @@ from __future__ import annotations
 
 import os
 from collections.abc import Mapping
+from functools import partial
+from types import SimpleNamespace
 from typing import Any, Generic, Literal, Protocol, TypeAlias, TypeVar
 
 import httpx2
@@ -30,6 +32,8 @@ Output = TypeVar("Output")
 
 
 class CompleteResult(Protocol, Generic[Output]):
+    """Successful tool result with contract-typed structured content."""
+
     result_type: Literal["complete"]
     is_error: Literal[False]
     structured_content: Output
@@ -38,6 +42,8 @@ class CompleteResult(Protocol, Generic[Output]):
 
 
 class ErrorResult(Protocol):
+    """Completed tool result reporting an application error."""
+
     result_type: Literal["complete"]
     is_error: Literal[True]
     structured_content: object
@@ -51,6 +57,16 @@ _result = TypeAdapter(CallToolResult | InputRequiredResult)
 
 
 class ToolCallError(RuntimeError):
+    """Raised by ``tools.<name>`` for tool errors or additional input requests.
+
+    Attributes:
+        app: Dependency name.
+        tool: Requested tool name.
+        result: Original MCP error or input-required result.
+        code: ``tool_error`` or ``input_required``. Use ``call_tool`` when you
+            need to inspect these results and submit additional input.
+    """
+
     def __init__(
         self, app: str, tool: str, result: CallToolResult | InputRequiredResult
     ) -> None:
@@ -94,7 +110,13 @@ class _App:
             if contract is None
             else {tool["name"]: tool for tool in contract["tools"]}
         )
-        self.tools = _Tools(self)
+        self.tools = SimpleNamespace(
+            **{
+                name: partial(self._call_tool, name)
+                for name in self._definitions or ()
+                if not name.startswith("_")
+            }
+        )
 
     async def call_tool(
         self,
@@ -106,6 +128,27 @@ class _App:
         request_state: str | None = None,
         meta: RequestParamsMeta | None = None,
     ) -> CallToolResult | InputRequiredResult:
+        """Call a dependency tool and return its full MCP result.
+
+        Args:
+            name: Tool name. Contracted dependencies reject unknown tools.
+            arguments: Tool arguments, validated against the contract if present.
+            timeout: Request read timeout in seconds, or the MCP client default.
+            input_responses: Responses to a previous input-required result.
+            request_state: Continuation state returned by the server.
+            meta: Optional MCP request metadata.
+
+        Returns:
+            A complete or input-required result. Tool error results are returned
+            unchanged; successful structured output is contract-validated.
+
+        Raises:
+            ValueError: Unknown tool, invalid input/output, or undeclared dependency.
+            RuntimeError: Endpoint resolution failed.
+
+        Transport and protocol exceptions propagate. Each call closes its HTTP
+        client and MCP session, including when an exception occurs.
+        """
         definition = None
         if self._definitions is not None:
             definition = self._definitions.get(name)
@@ -127,12 +170,10 @@ class _App:
             raise RuntimeError(
                 f"Dependency {self._name} is unavailable ({variable}). Set the endpoint or supply a binding."
             )
-        http = (
-            binding["http_client"]()
-            if binding and "http_client" in binding
-            else httpx2.AsyncClient(trust_env=False)
-        )
-        async with http:
+        http_client = partial(httpx2.AsyncClient, trust_env=False)
+        async with (
+            binding.get("http_client", http_client) if binding else http_client
+        )() as http:
             transport = streamable_http_client(endpoint, http_client=http)
             async with Client(
                 transport,
@@ -167,28 +208,41 @@ class _App:
             )
         return result
 
+    async def _call_tool(
+        self,
+        name: str,
+        arguments: Mapping[str, object],
+        *,
+        timeout: float | None = None,
+    ) -> object:
+        result = await self.call_tool(name, arguments, timeout=timeout)
+        if isinstance(result, InputRequiredResult) or result.is_error:
+            raise ToolCallError(self._name, name, result)
+        return result.structured_content
 
-class _Tools:
-    def __init__(self, client: _App) -> None:
-        self._client = client
 
-    def __getattr__(self, name: str) -> Any:
-        definitions = self._client._definitions
-        if name.startswith("_") or definitions is None or name not in definitions:
-            raise AttributeError(name)
+class Apps:
+    """Create the dependency collection used by generated Python clients.
 
-        async def call(
-            arguments: Mapping[str, object], *, timeout: float | None = None
-        ) -> object:
-            result = await self._client.call_tool(name, arguments, timeout=timeout)
-            if isinstance(result, InputRequiredResult) or result.is_error:
-                raise ToolCallError(self._client._name, name, result)
-            return result.structured_content
+    Applications typically use ``apps`` or ``create_apps`` from ``holon.apps``.
 
-        return call
+    Args:
+        identity: Application name, version, and declared ``requires`` mapping.
+        contracts: Dependency contracts with a ``tools`` list, or ``None`` for
+            untyped dependencies.
+        bindings: Explicit bindings. When supplied, only these dependencies are
+            included; an empty mapping selects none. Otherwise all declared
+            dependencies and contracts are available.
 
+    Raises:
+        ValueError: A binding names an unknown dependency.
+
+    Access a client with ``clients[name]`` or ``clients.name``. Its
+    ``tools.<name>(arguments, timeout=seconds)`` methods return structured output
+    and raise :class:`ToolCallError` for tool errors or additional input requests.
+    Use its ``call_tool`` method for the full result envelope.
+    """
 
-class Apps:
     def __init__(
         self,
         identity: dict[str, Any],
@@ -196,19 +250,14 @@ class Apps:
         bindings: Mapping[str, Binding] | None = None,
     ) -> None:
         # Every declared dependency gets a client; those without a contract are untyped.
-        available: dict[str, dict[str, Any] | None] = {
-            name: None for name in identity["requires"]
-        }
-        available.update(contracts)
-        selected = available if bindings is None else {}
-        for name in bindings or ():
+        available = dict.fromkeys(identity["requires"]) | contracts
+        self._apps = {}
+        for name in available if bindings is None else bindings:
             if name not in available:
                 raise ValueError(f"Unknown app binding: {name}")
-            selected[name] = available[name]
-        self._apps = {
-            name: _App(name, identity, contract, bindings[name] if bindings else None)
-            for name, contract in selected.items()
-        }
+            self._apps[name] = _App(
+                name, identity, available[name], bindings[name] if bindings else None
+            )
 
     def __getitem__(self, name: str) -> _App:
         return self._apps[name]

holon_sh-0.0.1.dev2/holon/view.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from mcp.server.apps import APP_MIME_TYPE
+from mcp.server.mcpserver.resources import FunctionResource
+
+
+def app_view(
+    uri: str,
+    name: str,
+    file: Path | str,
+    *,
+    connect_domains: list[str] | None = None,
+    resource_domains: list[str] | None = None,
+) -> FunctionResource:
+    """Create a server resource serving a built MCP App HTML file.
+
+    Args:
+        uri: Resource URI, normally starting with ``ui://``.
+        name: Human-readable resource name.
+        file: HTML file to read lazily on the first resource request.
+        connect_domains: Domains allowed for network connections by the view.
+        resource_domains: Domains allowed for external view assets.
+
+    Returns:
+        A ``FunctionResource`` ready for the MCP server's resource manager.
+        Successful reads are cached for the lifetime of this resource instance.
+
+    Raises:
+        OSError: Reading the HTML file failed.
+
+    Example:
+        ``resource = app_view("ui://app/index.html", "App", "dist/index.html")``
+    """
+    page = Path(file)
+    csp = {
+        "connectDomains": connect_domains or [],
+        "resourceDomains": resource_domains or [],
+    }
+    built: list[str] = []
+
+    def read() -> str:
+        # Concurrent first reads must all return the first cached build.
+        if not built:
+            built.append(page.read_text())
+        return built[0]
+
+    return FunctionResource.from_function(
+        read,
+        uri,
+        name=name,
+        mime_type=APP_MIME_TYPE,
+        meta={"ui": {"csp": csp}},
+    )

{holon_sh-0.0.1.dev1 → holon_sh-0.0.1.dev2}/pyproject.toml

@@ -4,8 +4,9 @@ build-backend = "hatchling.build"
 
 [project]
 name = "holon-sh"
-version = "0.0.1.dev1"
+version = "0.0.1.dev2"
 description = "Typed MCP clients, bindings, and app views"
+readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
 requires-python = ">=3.11"
@@ -25,6 +26,7 @@ testpaths = ["tests"]
 
 [tool.ruff]
 target-version = "py311"
+extend-exclude = ["tests/fixtures"]
 
 [dependency-groups]
-dev = ["mcptype==0.0.6", "mypy==2.4.0", "pytest==9.1.1", "ruff==0.16.8", "types-jsonschema", "hatchling>=1.27,<2"]
+dev = ["mypy==2.4.0", "pytest==9.1.1", "ruff==0.16.8", "types-jsonschema", "hatchling>=1.27,<2"]

holon_sh-0.0.1.dev2/scripts/fixtures.sh

@@ -0,0 +1,7 @@
+#!/bin/sh
+set -eu
+
+# Run from any directory with the holon CLI on PATH. The orders server is
+# statically extracted; no running server or installed fixture dependencies are needed.
+cd "$(dirname "$0")/../tests/fixtures/caller"
+exec holon types generate ../orders

holon_sh-0.0.1.dev2/scripts/verify_distribution.py

@@ -0,0 +1,37 @@
+"""Install and test each built distribution in an isolated uv environment."""
+
+import subprocess
+import sys
+from importlib.metadata import version
+from pathlib import Path
+
+root = Path(__file__).resolve().parents[1]
+artifacts = sorted(root.glob("dist/holon_sh-*.whl")) + sorted(
+    root.glob("dist/holon_sh-*.tar.gz")
+)
+if len(artifacts) != 2:
+    raise RuntimeError("Build exactly one wheel and one sdist before verification.")
+for artifact in artifacts:
+    subprocess.run(
+        [
+            "uv",
+            "run",
+            "--isolated",
+            "--no-project",
+            "--no-config",
+            "--python",
+            sys.executable,
+            "--with",
+            str(artifact),
+            "--with",
+            f"pytest=={version('pytest')}",
+            "--with",
+            f"mypy=={version('mypy')}",
+            "python",
+            "-m",
+            "pytest",
+            str(root / "tests/test_package.py"),
+        ],
+        cwd=root / "dist",
+        check=True,
+    )

holon_sh-0.0.1.dev2/tests/fixtures/caller/holon/apps/__init__.py

@@ -0,0 +1,55 @@
+# holon-generated-apps-v1 app=caller
+from __future__ import annotations
+
+import json as _json
+
+from mcp.types import InputResponses as _InputResponses
+from mcp.types import RequestParamsMeta as _RequestParamsMeta
+
+from holon.client import Apps as _Apps
+from holon.client import Binding as _Binding
+from holon.client import ToolResult as _ToolResult
+
+import builtins as _builtins
+import typing as _typing
+
+_Shape0 = _typing.TypedDict("_Shape0", {"id": _builtins.str})
+
+_Shape1 = _typing.TypedDict("_Shape1", {"total": _builtins.float})
+
+class Inputs:
+    class orders:
+        read: _typing.TypeAlias = _Shape0
+
+class Outputs:
+    class orders:
+        read: _typing.TypeAlias = _Shape1
+
+class InputTypes:
+    class orders:
+        class read:
+            pass
+
+class OutputTypes:
+    class orders:
+        class read:
+            pass
+
+class _Tools0(_typing.Protocol):
+    async def read(self, arguments: _Shape0, *, timeout: _builtins.float | None = ...) -> _Shape1: ...
+
+class _App0(_typing.Protocol):
+    tools: _Tools0
+    async def call_tool(self, name: _typing.Literal["read"], arguments: _Shape0, *, timeout: _builtins.float | None = ..., input_responses: _InputResponses | None = ..., request_state: _builtins.str | None = ..., meta: _RequestParamsMeta | None = ...) -> _ToolResult[_Shape1]: ...
+
+class _Clients(_typing.Protocol):
+    orders: _App0
+    def __getitem__(self, name: _typing.Literal["orders"]) -> _App0: ...
+
+
+_identity, _contracts = _json.loads('[{"name":"fixtures/caller","requires":{"orders":{"name":"fixtures/orders","version":"1"}},"version":"1"},{"orders":{"tools":[{"name":"read","inputSchema":{"properties":{"id":{"type":"string"}},"required":["id"],"type":"object"},"outputSchema":{"properties":{"total":{"type":"number"}},"required":["total"],"type":"object"}}]}}]')
+
+apps = _typing.cast(_Clients, _Apps(_identity, _contracts))
+
+def create_apps(bindings: _typing.Mapping[str, _Binding]) -> _Clients:
+    return _typing.cast(_Clients, _Apps(_identity, _contracts, bindings))

holon_sh-0.0.1.dev2/tests/fixtures/caller/requirements.txt

@@ -0,0 +1 @@
+holon-sh

holon_sh-0.0.1.dev2/tests/fixtures/caller/server.json

@@ -0,0 +1,5 @@
+{
+  "name": "fixtures/caller",
+  "version": "1",
+  "description": "Consumer of the orders package fixture."
+}

holon_sh-0.0.1.dev2/tests/fixtures/orders/server.json

@@ -0,0 +1,5 @@
+{
+  "name": "fixtures/orders",
+  "version": "1",
+  "description": "Orders contract for the Python package fixture."
+}

holon_sh-0.0.1.dev2/tests/fixtures/orders/server.py

@@ -0,0 +1,14 @@
+from typing import TypedDict
+
+from mcp.server import MCPServer
+
+server = MCPServer("orders")
+
+
+class Order(TypedDict):
+    total: float
+
+
+@server.tool()
+def read(id: str) -> Order:
+    return {"total": 42.0}

holon_sh-0.0.1.dev2/tests/test_package.py

@@ -0,0 +1,40 @@
+"""Consumer contracts at the generated namespace boundary."""
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+def test_generated_namespace_combines_app_types_with_installed_runtime(tmp_path):
+    # Refresh with scripts/fixtures.sh; generation is tested in holon-sh/cli.
+    shutil.copytree(Path(__file__).parent / "fixtures/caller", tmp_path, dirs_exist_ok=True)
+    (tmp_path / "check.py").write_text("""from pathlib import Path
+import holon
+import holon.client
+from holon.apps import apps, Inputs, Outputs
+
+async def run() -> float:
+    arguments: Inputs.orders.read = {"id": "order-1"}
+    output: Outputs.orders.read = await apps.orders.tools.read(arguments)
+    return output["total"]
+
+async def invalid() -> None:
+    await apps.orders.tools.read({"id": 1})  # type: ignore
+    await apps.orders.tools.read({})  # type: ignore
+    apps.missing  # type: ignore
+
+assert holon.__file__ is None
+assert Path(holon.client.__file__).parent != Path(__file__).parent / "holon"
+""")
+    # Runtime and typing must agree across the two namespace portions. No
+    # MYPYPATH/PYTHONPATH override is allowed to hide packaging problems.
+    env = os.environ.copy()
+    env.pop("MYPYPATH", None)
+    env.pop("PYTHONPATH", None)
+    for command in [
+        [sys.executable, "-m", "mypy", "--strict", "--no-incremental", "check.py"],
+        [sys.executable, "check.py"],
+    ]:
+        subprocess.run(command, cwd=tmp_path, env=env, check=True)

{holon_sh-0.0.1.dev1 → holon_sh-0.0.1.dev2}/tests/test_runtime.py

@@ -10,6 +10,28 @@ import holon.binding
 from holon.binding import set_default_binding
 from holon.client import Apps, ToolCallError
 
+CONTRACT = {
+    "tools": [
+        {
+            "name": "read",
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "id": {"type": "string"},
+                    "limit": {"type": "integer", "default": 5},
+                },
+                "required": ["id"],
+                "additionalProperties": False,
+            },
+            "outputSchema": {
+                "type": "object",
+                "properties": {"total": {"type": "number"}},
+                "required": ["total"],
+            },
+        }
+    ]
+}
+
 
 def test_clients_preserve_mcp_results_validate_and_cancel(monkeypatch):
     async def exercise():
@@ -44,14 +66,17 @@ def test_clients_preserve_mcp_results_validate_and_cancel(monkeypatch):
         app = server.streamable_http_app(stateless_http=True)
         requests = []
         clients = []
+        headers = []
 
         async def record(request):
+            headers.append(request.headers.get("authorization"))
             if request.method == "POST":
                 requests.append(json.loads(await request.aread()))
 
         def http_client():
             client = httpx2.AsyncClient(
                 transport=httpx2.ASGITransport(app=app),
+                headers={"Authorization": "Bearer external"},
                 event_hooks={"request": [record]},
             )
             clients.append(client)
@@ -66,41 +91,15 @@ def test_clients_preserve_mcp_results_validate_and_cancel(monkeypatch):
                 else None
             )
         )
-        contract = {
-            "tools": [
-                {
-                    "name": "read",
-                    "inputSchema": {
-                        "type": "object",
-                        "properties": {
-                            "id": {"type": "string"},
-                            "limit": {"type": "integer", "default": 5},
-                        },
-                        "required": ["id"],
-                        "additionalProperties": False,
-                    },
-                    "outputSchema": {
-                        "type": "object",
-                        "properties": {"total": {"type": "number"}},
-                        "required": ["total"],
-                    },
-                }
-            ]
-        }
         identity = {"name": "checkout", "version": "1", "requires": {"orders": {}}}
-        apps = Apps(identity, {"orders": contract})
-        repr(apps)
-        repr(apps.orders.tools)
-        with pytest.raises(TypeError):
-            await apps.orders
-        with pytest.raises(TypeError):
-            json.dumps(apps.orders)
+        apps = Apps(identity, {"orders": CONTRACT})
+        other = Apps({**identity, "name": "other"}, {"orders": CONTRACT})
         assert not requests
         async with app.router.lifespan_context(app):
             arguments = {"id": "good"}
             output, raw = await asyncio.gather(
                 apps.orders.tools.read(arguments),
-                apps.orders.call_tool("read", {"id": "good", "limit": 2}),
+                other.orders.call_tool("read", {"id": "good", "limit": 2}),
             )
             assert output == {"total": 5}
             assert arguments == {"id": "good"}
@@ -108,10 +107,6 @@ def test_clients_preserve_mcp_results_validate_and_cancel(monkeypatch):
             assert raw.content[0].text == "Order"
             assert raw.meta["preserved"] is True
             assert not any(request["method"] == "tools/list" for request in requests)
-            other = Apps({**identity, "name": "other"}, {"orders": contract})
-            await asyncio.gather(
-                apps.orders.tools.read(arguments), other.orders.tools.read(arguments)
-            )
             callers = [
                 request["params"]["_meta"]["io.modelcontextprotocol/clientInfo"]["name"]
                 for request in requests
@@ -149,84 +144,25 @@ def test_clients_preserve_mcp_results_validate_and_cancel(monkeypatch):
             assert not hasattr(untyped.orders.tools, "read")
             with pytest.raises(RuntimeError, match=r"unavailable \(MISSING_MCP_URL\)"):
                 await untyped.missing.call_tool("read", {})
-        assert all(client.is_closed for client in clients)
-
-    async def bounded():
-        async with asyncio.timeout(15):
-            await exercise()
-
-    asyncio.run(bounded())
-
-
-def test_endpoint_bindings_call_without_the_runtime(monkeypatch):
-    async def exercise():
-        server = MCPServer("orders")
-        headers = []
-
-        @server.tool()
-        async def read(id: str) -> CallToolResult:
-            return CallToolResult(
-                content=[TextContent(type="text", text=id)],
-                structured_content={"total": 1},
+            # Explicit bindings work without a declaration and override the resolver.
+            set_default_binding(
+                lambda _: {"endpoint": "http://unavailable.invalid/mcp"}
             )
-
-        app = server.streamable_http_app(stateless_http=True)
-
-        async def record(request):
-            headers.append(request.headers.get("authorization"))
-
-        def http_client():
-            return httpx2.AsyncClient(
-                transport=httpx2.ASGITransport(app=app),
-                headers={"Authorization": "Bearer external"},
-                event_hooks={"request": [record]},
-            )
-
-        monkeypatch.delenv("ORDERS_MCP_URL", raising=False)
-        monkeypatch.setattr(holon.binding, "_resolver", None)
-        contract = {
-            "tools": [
-                {
-                    "name": "read",
-                    "inputSchema": {
-                        "type": "object",
-                        "properties": {"id": {"type": "string"}},
-                        "required": ["id"],
-                        "additionalProperties": False,
-                    },
-                    "outputSchema": {
-                        "type": "object",
-                        "properties": {"total": {"type": "number"}},
-                        "required": ["total"],
-                    },
-                }
-            ]
-        }
-        identity = {"name": "script", "version": "1", "requires": {}}
-        with pytest.raises(ValueError, match="Unknown app binding"):
-            Apps(identity, {"orders": contract}, {"missing": {"endpoint": "http://x"}})
-        bound = Apps(
-            identity,
-            {"orders": contract},
-            {
-                "orders": {
-                    "endpoint": "http://127.0.0.1:8000/mcp",
-                    "http_client": http_client,
-                }
-            },
-        )
-        async with app.router.lifespan_context(app):
-            assert await bound.orders.tools.read({"id": "a"}) == {"total": 1}
-            with pytest.raises(ValueError, match="arguments"):
-                await bound.orders.tools.read({"id": 1})
+            script = {**identity, "requires": {}}
+            binding = {
+                "endpoint": "http://127.0.0.1:8000/mcp",
+                "http_client": http_client,
+            }
+            with pytest.raises(ValueError, match="Unknown app binding"):
+                Apps(script, {"orders": CONTRACT}, {"missing": binding})
+            bound = Apps(script, {"orders": CONTRACT}, {"orders": binding})
+            assert await bound.orders.tools.read({"id": "good"}) == {"total": 5}
+            set_default_binding(lambda _: None)
             with pytest.raises(ValueError, match="not declared"):
-                await Apps(identity, {"orders": contract}).orders.tools.read(
-                    {"id": "a"}
+                await Apps(script, {"orders": CONTRACT}).orders.tools.read(
+                    {"id": "good"}
                 )
         assert headers and all(value == "Bearer external" for value in headers)
+        assert all(client.is_closed for client in clients)
 
-    async def bounded():
-        async with asyncio.timeout(15):
-            await exercise()
-
-    asyncio.run(bounded())
+    asyncio.run(asyncio.wait_for(exercise(), timeout=15))

holon_sh-0.0.1.dev1/PKG-INFO

@@ -1,11 +0,0 @@
-Metadata-Version: 2.5
-Name: holon-sh
-Version: 0.0.1.dev1
-Summary: Typed MCP clients, bindings, and app views
-Project-URL: Repository, https://github.com/holon-sh/sdk-py
-License-Expression: MIT
-License-File: LICENSE
-Requires-Python: >=3.11
-Requires-Dist: httpx2<3,>=2.10
-Requires-Dist: jsonschema<5,>=4.26
-Requires-Dist: mcp<3,>=2.3

holon_sh-0.0.1.dev1/holon/binding.py

@@ -1,30 +0,0 @@
-from __future__ import annotations
-
-from collections.abc import Callable
-from typing import NotRequired, TypedDict
-
-import httpx2
-
-
-class Binding(TypedDict):
-    endpoint: str
-    http_client: NotRequired[Callable[[], httpx2.AsyncClient]]
-    # Python clients open one session per call, so every binding already behaves as scoped.
-    scoped: NotRequired[bool]
-
-
-_resolver: Callable[[str], Binding | None] | None = None
-
-
-def set_default_binding(resolve: Callable[[str], Binding | None]) -> None:
-    """Resolve bindings for app clients that were not bound with ``create_apps``.
-
-    Without a resolver, or when it returns ``None``, a client falls back to its
-    ``<NAME>_MCP_URL`` environment variable.
-    """
-    global _resolver
-    _resolver = resolve
-
-
-def resolve_default_binding(app: str) -> Binding | None:
-    return _resolver(app) if _resolver is not None else None

holon_sh-0.0.1.dev1/holon/view.py

@@ -1,35 +0,0 @@
-from __future__ import annotations
-
-from pathlib import Path
-
-from mcp.server.apps import APP_MIME_TYPE
-from mcp.server.mcpserver.resources import FunctionResource
-
-
-def app_view(
-    uri: str,
-    name: str,
-    file: Path | str,
-    *,
-    connect_domains: list[str] | None = None,
-    resource_domains: list[str] | None = None,
-) -> FunctionResource:
-    page = Path(file)
-    csp = {
-        "connectDomains": connect_domains or [],
-        "resourceDomains": resource_domains or [],
-    }
-    built: list[str] = []
-
-    def read() -> str:
-        if not built:
-            built.append(page.read_text())
-        return built[0]
-
-    return FunctionResource.from_function(
-        read,
-        uri,
-        name=name,
-        mime_type=APP_MIME_TYPE,
-        meta={"ui": {"csp": csp}},
-    )

holon_sh-0.0.1.dev1/scripts/verify_distribution.py

@@ -1,91 +0,0 @@
-"""Install each built distribution in an isolated environment and test it.
-
-Dependency packages are copied from the invoking development environment to
-avoid network access. The holon namespace is excluded so only the installed
-artifact can satisfy the runtime imports.
-"""
-
-from __future__ import annotations
-
-import shutil
-import subprocess
-import sys
-import sysconfig
-import tempfile
-import venv
-from pathlib import Path
-
-
-def verify(root: Path) -> None:
-    artifacts = sorted(root.glob("dist/holon_sh-*.whl")) + sorted(
-        root.glob("dist/holon_sh-*.tar.gz")
-    )
-    if len(artifacts) != 2:
-        raise RuntimeError("Build exactly one wheel and one sdist before verification.")
-    for artifact in artifacts:
-        with tempfile.TemporaryDirectory(prefix="holon-sh-consumer-") as temporary:
-            directory = Path(temporary)
-            environment = directory / "venv"
-            venv.create(environment, with_pip=False)
-            python = environment / (
-                "Scripts/python.exe" if sys.platform == "win32" else "bin/python"
-            )
-            installed = Path(
-                subprocess.check_output(
-                    [
-                        str(python),
-                        "-c",
-                        "import sysconfig; print(sysconfig.get_path('purelib'))",
-                    ],
-                    text=True,
-                ).strip()
-            )
-            for source in Path(sysconfig.get_path("purelib")).iterdir():
-                if (
-                    source.name.startswith(("holon", "_holon"))
-                    or source.suffix == ".pth"
-                ):
-                    continue
-                target = installed / source.name
-                if source.is_dir():
-                    shutil.copytree(source, target, dirs_exist_ok=True)
-                else:
-                    shutil.copy2(source, target)
-            subprocess.run(
-                [
-                    "uv",
-                    "pip",
-                    "install",
-                    "--python",
-                    str(python),
-                    "--no-deps",
-                    "--no-build-isolation",
-                    str(artifact),
-                ],
-                check=True,
-            )
-            subprocess.run(
-                [
-                    str(python),
-                    "-c",
-                    "import holon, holon.client; assert holon.__file__ is None; print(holon.client.__file__)",
-                ],
-                cwd=directory,
-                check=True,
-            )
-            subprocess.run(
-                [
-                    str(python),
-                    "-m",
-                    "pytest",
-                    str(root / "tests/test_package.py"),
-                    "-k",
-                    "generated_namespace",
-                ],
-                cwd=directory,
-                check=True,
-            )
-
-
-if __name__ == "__main__":
-    verify(Path(__file__).resolve().parents[1])

holon_sh-0.0.1.dev1/tests/test_package.py

@@ -1,83 +0,0 @@
-"""Consumer contracts at the generated namespace boundary."""
-
-import os
-import subprocess
-import sys
-
-from mcptype.compiler import generate
-
-
-def test_generated_namespace_combines_app_types_with_installed_runtime(tmp_path):
-    identity = {"name": "caller", "version": "1"}
-    contract = {
-        "tools": [
-            {
-                "name": "read",
-                "inputSchema": {
-                    "type": "object",
-                    "properties": {"id": {"type": "string"}},
-                    "required": ["id"],
-                    "additionalProperties": False,
-                },
-                "outputSchema": {
-                    "type": "object",
-                    "properties": {"total": {"type": "number"}},
-                    "required": ["total"],
-                },
-            }
-        ]
-    }
-    result = generate(
-        {
-            "target": "python",
-            "identity": identity,
-            "requires": {"orders": {"name": "orders", "version": "1"}},
-            "contracts": {"orders": contract},
-            "python_module": "holon/apps/__init__.py",
-            "python_runtime_module": "holon.client",
-            "banner": "holon-generated-apps-v1 app=caller",
-        }
-    )
-    for name, content in result["files"].items():
-        path = tmp_path / name
-        path.parent.mkdir(parents=True, exist_ok=True)
-        path.write_bytes(content)
-    assert not (tmp_path / "holon/__init__.py").exists()
-    (tmp_path / "check.py").write_text("""from pathlib import Path
-import holon
-import holon.client
-from holon.apps import apps, Inputs, Outputs
-from holon.binding import Binding, set_default_binding
-
-binding: Binding = {"endpoint": "https://example.com/mcp"}
-set_default_binding(lambda name: binding)
-
-async def run() -> float:
-    arguments: Inputs.orders.read = {"id": "order-1"}
-    output: Outputs.orders.read = await apps.orders.tools.read(arguments)
-    return output["total"]
-
-async def invalid() -> None:
-    await apps.orders.tools.read({"id": 1})  # type: ignore
-    await apps.orders.tools.read({})  # type: ignore
-    apps.missing  # type: ignore
-
-assert holon.__file__ is None
-assert not (Path(__file__).parent / "holon/client.py").exists()
-assert Path(holon.client.__file__).parent != Path(__file__).parent / "holon"
-""")
-    # Runtime and typing must agree across the two namespace portions. No
-    # MYPYPATH/PYTHONPATH override is allowed to hide packaging problems.
-    env = {
-        key: value
-        for key, value in os.environ.items()
-        if key not in {"MYPYPATH", "PYTHONPATH"}
-    }
-    for command in [
-        [sys.executable, "-m", "mypy", "--strict", "--no-incremental", "check.py"],
-        [sys.executable, "check.py"],
-    ]:
-        checked = subprocess.run(
-            command, cwd=tmp_path, env=env, text=True, capture_output=True, check=False
-        )
-        assert checked.returncode == 0, checked.stdout + checked.stderr