fix(client): add run_forever()+stop() to ZhubConnection and ZhubExposure

run_forever() was referenced in the module docstring and the publish()
docstring but never implemented — any user following the quickstart
got AttributeError before a connection was even attempted.
ZhubConnection and ZhubExposure also lacked stop(), making them
impossible to shut down cleanly without touching private _task/_stop_event.

Add async run_forever() to all three classes (awaits _stop_event, unblocks
when stop() is called). Add stop() to ZhubConnection and ZhubExposure
mirroring ZhubPublication.stop(). Fix the __init__.py quickstart to use
the correct asyncio.run(main()) + await pub.run_forever() pattern.
Update the publish() docstring to describe the auto-start behaviour.

Author: Zawwarsami16

zhub/__init__.py

@@ -18,27 +18,35 @@
 Quickstart:
 
     # Inside your AI
+    import asyncio
     from zhub import publish
 
-    pub = publish(
-        name="my-ai",
-        description="A custom AI agent",
-        hub_url="https://hub.example.com",
-        chat_handler=lambda messages: "...",
-    )
-    pub.run_forever()
+    async def main():
+        pub = publish(
+            name="my-ai",
+            description="A custom AI agent",
+            hub_url="https://hub.example.com",
+            chat_handler=lambda messages: "...",
+        )
+        await pub.run_forever()
+
+    asyncio.run(main())
 
     # Inside your client (e.g., a generic device)
+    import asyncio
     from zhub import connect
 
-    conn = connect(
-        endpoint="https://hub.example.com/my-ai",
-        api_key="zk_...",
-        capabilities={
-            "send_whatsapp": (schema, handler),
-        },
-    )
-    conn.run_forever()
+    async def main():
+        conn = connect(
+            endpoint="https://hub.example.com/my-ai",
+            api_key="zk_...",
+            capabilities={
+                "send_whatsapp": (schema, handler),
+            },
+        )
+        await conn.run_forever()
+
+    asyncio.run(main())
 """
 
 from .client import (

zhub/client.py

@@ -112,6 +112,12 @@ async def stop(self) -> None:
         if self._task:
             self._task.cancel()
 
+    async def run_forever(self) -> None:
+        """Block until stop() is called. Useful as the final await in an
+        async main:  asyncio.run(main())  where main() ends with
+        ``await pub.run_forever()``."""
+        await self._stop_event.wait()
+
 
 def publish(
     name: str,
@@ -129,7 +135,11 @@ def publish(
     resources: Optional[list[dict[str, Any]]] = None,
     prompts: Optional[list[dict[str, Any]]] = None,
 ) -> ZhubPublication:
-    """Create a ZhubPublication. Call .run_forever() to actually start serving.
+    """Create a ZhubPublication and start the background reconnect loop.
+
+    In an async context the task runs immediately; call ``await pub.run_forever()``
+    to block until stop() is called.  In a script: ``asyncio.run(main())``
+    where ``main()`` ends with ``await pub.run_forever()``.
 
     If `api_key` is supplied AND the hub has a stored publisher with the
     same name and matching key hash, this is a re-registration after a hub
@@ -481,6 +491,16 @@ async def chat_stream(self, messages: list[dict[str, Any]],
         finally:
             self._streams.pop(env.request_id, None)
 
+    async def stop(self) -> None:
+        """Stop the connection loop and cancel the background task."""
+        self._stop_event.set()
+        if self._task:
+            self._task.cancel()
+
+    async def run_forever(self) -> None:
+        """Block until stop() is called."""
+        await self._stop_event.wait()
+
 
 def connect(
     ai_name: str,
@@ -616,6 +636,16 @@ class ZhubExposure:
     _ws: Any = None
     _stop_event: asyncio.Event = field(default_factory=asyncio.Event)
 
+    async def stop(self) -> None:
+        """Stop the exposure loop and cancel the background task."""
+        self._stop_event.set()
+        if self._task:
+            self._task.cancel()
+
+    async def run_forever(self) -> None:
+        """Block until stop() is called."""
+        await self._stop_event.wait()
+
 
 def expose(
     name: str,