connectonion 0.5.1__py3-none-any.whl → 0.5.3__py3-none-any.whl

connectonion/__init__.py

@@ -1,6 +1,6 @@
 """ConnectOnion - A simple agent framework with behavior tracking."""
 
-__version__ = "0.5.1"
+__version__ = "0.5.3"
 
 # Auto-load .env files for the entire framework
 from dotenv import load_dotenv
@@ -21,6 +21,7 @@ from .decorators import replay, xray_replay
 from .useful_tools import send_email, get_emails, mark_read, mark_unread, Memory, Gmail, GoogleCalendar, Outlook, MicrosoftCalendar, WebFetch, Shell, DiffWriter, pick, yes_no, autocomplete, TodoList, SlashCommand
 from .auto_debug_exception import auto_debug_exception
 from .connect import connect, RemoteAgent
+from .host import host, create_app
 from .events import (
     after_user_input,
     before_llm,
@@ -63,6 +64,8 @@ __all__ = [
     "auto_debug_exception",
     "connect",
     "RemoteAgent",
+    "host",
+    "create_app",
     "after_user_input",
     "before_llm",
     "after_llm",

connectonion/agent.py

@@ -1,12 +1,12 @@
 """
 Purpose: Orchestrate AI agent execution with LLM calls, tool execution, and automatic logging
 LLM-Note:
-  Dependencies: imports from [llm.py, tool_factory.py, prompts.py, decorators.py, logger.py, tool_executor.py, trust.py, tool_registry.py] | imported by [__init__.py, trust.py, debug_agent/__init__.py] | tested by [tests/test_agent.py, tests/test_agent_prompts.py, tests/test_agent_workflows.py]
+  Dependencies: imports from [llm.py, tool_factory.py, prompts.py, decorators.py, logger.py, tool_executor.py, tool_registry.py] | imported by [__init__.py, debug_agent/__init__.py] | tested by [tests/test_agent.py, tests/test_agent_prompts.py, tests/test_agent_workflows.py]
   Data flow: receives user prompt: str from Agent.input() → creates/extends current_session with messages → calls llm.complete() with tool schemas → receives LLMResponse with tool_calls → executes tools via tool_executor.execute_and_record_tools() → appends tool results to messages → repeats loop until no tool_calls or max_iterations → logger logs to .co/logs/{name}.log and .co/sessions/{name}_{timestamp}.yaml → returns final response: str
-  State/Effects: modifies self.current_session['messages', 'trace', 'turn', 'iteration'] | writes to .co/logs/{name}.log and .co/sessions/ via logger.py | initializes trust agent if trust parameter provided
-  Integration: exposes Agent(name, tools, system_prompt, model, trust, log, quiet), .input(prompt), .execute_tool(name, args), .add_tool(func), .remove_tool(name), .list_tools(), .reset_conversation() | tools stored in ToolRegistry with attribute access (agent.tools.tool_name) and instance storage (agent.tools.gmail) | tool execution delegates to tool_executor module | trust system via trust.create_trust_agent() | log defaults to .co/logs/ (None), can be True (current dir), False (disabled), or custom path | quiet=True suppresses console but keeps session logging
+  State/Effects: modifies self.current_session['messages', 'trace', 'turn', 'iteration'] | writes to .co/logs/{name}.log and .co/sessions/ via logger.py
+  Integration: exposes Agent(name, tools, system_prompt, model, log, quiet), .input(prompt), .execute_tool(name, args), .add_tool(func), .remove_tool(name), .list_tools(), .reset_conversation() | tools stored in ToolRegistry with attribute access (agent.tools.tool_name) and instance storage (agent.tools.gmail) | tool execution delegates to tool_executor module | log defaults to .co/logs/ (None), can be True (current dir), False (disabled), or custom path | quiet=True suppresses console but keeps session logging | trust enforcement moved to host() for network access control
   Performance: max_iterations=10 default (configurable per-input) | session state persists across turns for multi-turn conversations | ToolRegistry provides O(1) tool lookup via .get() or attribute access
-  Errors: LLM errors bubble up | tool execution errors captured in trace and returned to LLM for retry | trust agent creation can fail if invalid trust parameter
+  Errors: LLM errors bubble up | tool execution errors captured in trace and returned to LLM for retry
 """
 
 import os
@@ -26,8 +26,7 @@ from .logger import Logger
 from .tool_executor import execute_and_record_tools, execute_single_tool
 from .events import EventHandler
 
-# Handle trust parameter - convert to trust agent
-from .trust import create_trust_agent, get_default_trust_level
+
 class Agent:
     """Agent that can use tools to complete tasks."""
     
@@ -40,7 +39,6 @@ class Agent:
         api_key: Optional[str] = None,
         model: str = "co/gemini-2.5-pro",
         max_iterations: int = 10,
-        trust: Optional[Union[str, Path, 'Agent']] = None,
         log: Optional[Union[bool, str, Path]] = None,
         quiet: bool = False,
         plugins: Optional[List[List[EventHandler]]] = None,
@@ -64,20 +62,6 @@ class Agent:
             effective_log = Path(os.getenv('CONNECTONION_LOG'))
 
         self.logger = Logger(agent_name=name, quiet=quiet, log=effective_log)
-        
-
-        
-        # If trust is None, check for environment default
-        if trust is None:
-            trust = get_default_trust_level()
-        
-        # Only create trust agent if we're not already a trust agent
-        # (to prevent infinite recursion when creating trust agents)
-        if name and name.startswith('trust_agent_'):
-            self.trust = None  # Trust agents don't need their own trust agents
-        else:
-            # Store the trust agent directly (or None)
-            self.trust = create_trust_agent(trust, api_key=api_key, model=model)
 
         # Initialize event registry
         # Note: before_each_tool/after_each_tool fire for EACH tool
@@ -145,6 +129,18 @@ class Agent:
             # - co/ models check OPENONION_API_KEY
             self.llm = create_llm(model=model, api_key=api_key)
 
+        # Print banner (if console enabled)
+        if self.logger.console:
+            # Determine log_dir if logging is enabled
+            log_dir = ".co/" if self.logger.enable_sessions else None
+            self.logger.console.print_banner(
+                agent_name=self.name,
+                model=self.llm.model,
+                tools=len(self.tools),
+                log_dir=log_dir,
+                llm=self.llm
+            )
+
     def _invoke_events(self, event_type: str):
         """Invoke all event handlers for given type. Exceptions propagate (fail fast)."""
         for handler in self.events.get(event_type, []):
@@ -180,21 +176,39 @@ class Agent:
 
         self.events[event_type].append(event_func)
 
-    def input(self, prompt: str, max_iterations: Optional[int] = None) -> str:
+    def input(self, prompt: str, max_iterations: Optional[int] = None,
+              session: Optional[Dict] = None) -> str:
         """Provide input to the agent and get response.
 
         Args:
             prompt: The input prompt or data to process
             max_iterations: Override agent's max_iterations for this request
+            session: Optional session to continue a conversation. Pass the session
+                    from a previous response to maintain context. Contains:
+                    - session_id: Conversation identifier
+                    - messages: Conversation history
+                    - trace: Execution trace for debugging
+                    - turn: Turn counter
 
         Returns:
             The agent's response after processing the input
         """
         start_time = time.time()
-        self.logger.print(f"[bold]INPUT:[/bold] {prompt[:100]}...")
+        if self.logger.console:
+            self.logger.console.print_task(prompt)
 
-        # Initialize session on first input, or continue existing conversation
-        if self.current_session is None:
+        # Session restoration: if session passed, restore it (stateless API continuation)
+        if session is not None:
+            self.current_session = {
+                'session_id': session.get('session_id'),
+                'messages': list(session.get('messages', [])),
+                'trace': list(session.get('trace', [])),
+                'turn': session.get('turn', 0)
+            }
+            # Start YAML session logging with session_id for thread safety
+            self.logger.start_session(self.system_prompt, session_id=session.get('session_id'))
+        elif self.current_session is None:
+            # Initialize new session
             self.current_session = {
                 'messages': [{"role": "system", "content": self.system_prompt}],
                 'trace': [],
@@ -236,7 +250,11 @@ class Agent:
 
         self.current_session['result'] = result
 
-        self.logger.print(f"[green]✓ Complete[/green] ({duration:.1f}s)")
+        # Print completion summary
+        if self.logger.console:
+            session_path = f".co/sessions/{self.name}.yaml" if self.logger.enable_sessions else None
+            self.logger.console.print_completion(duration, self.current_session, session_path)
+
         self._invoke_events('on_complete')
 
         # Log turn to YAML session (after on_complete so handlers can modify state)
@@ -313,9 +331,6 @@ class Agent:
         """Run the main LLM/tool iteration loop until complete or max iterations."""
         while self.current_session['iteration'] < max_iterations:
             self.current_session['iteration'] += 1
-            iteration = self.current_session['iteration']
-
-            self.logger.print(f"[dim]Iteration {iteration}/{max_iterations}[/dim]")
 
             # Get LLM response
             response = self._get_llm_decision()
@@ -339,9 +354,8 @@ class Agent:
         tool_schemas = [tool.to_function_schema() for tool in self.tools] if self.tools else None
 
         # Show request info
-        msg_count = len(self.current_session['messages'])
-        tool_count = len(self.tools) if self.tools else 0
-        self.logger.print(f"[yellow]→[/yellow] LLM Request ({self.llm.model}) • {msg_count} msgs • {tool_count} tools")
+        if self.logger.console:
+            self.logger.console.print_llm_request(self.llm.model, self.current_session, self.max_iterations)
 
         # Invoke before_llm events
         self._invoke_events('before_llm')
@@ -369,7 +383,7 @@ class Agent:
         # Invoke after_llm events (after trace entry is added)
         self._invoke_events('after_llm')
 
-        self.logger.log_llm_response(duration, len(response.tool_calls), response.usage)
+        self.logger.log_llm_response(self.llm.model, duration, len(response.tool_calls), response.usage)
 
         return response
 
@@ -434,68 +448,3 @@ class Agent:
         debugger = InteractiveDebugger(self)
         debugger.start_debug_session(prompt)
 
-    def serve(self, relay_url: str = "wss://oo.openonion.ai/ws/announce"):
-        """
-        Start serving this agent on the relay network.
-
-        This makes the agent discoverable and connectable by other agents.
-        The agent will:
-        1. Load/generate Ed25519 keys for identity
-        2. Connect to relay server
-        3. Send ANNOUNCE message with agent summary
-        4. Wait for incoming TASK messages
-        5. Process tasks and send responses
-
-        Args:
-            relay_url: WebSocket URL for relay (default: production relay)
-
-        Example:
-            >>> agent = Agent("translator", tools=[translate])
-            >>> agent.serve()  # Runs forever, processing tasks
-            ✓ Announced to relay: 0x3d4017c3...
-            Debug: https://oo.openonion.ai/agent/0x3d4017c3e843895a...
-            ♥ Sent heartbeat
-            → Received task: abc12345...
-            ✓ Sent response: abc12345...
-
-        Note:
-            This is a blocking call. The agent will run until interrupted (Ctrl+C).
-        """
-        import asyncio
-        from . import address, announce, relay
-
-        # Load or generate keys
-        co_dir = Path.cwd() / '.co'
-        addr_data = address.load(co_dir)
-
-        if addr_data is None:
-            self.logger.print("[yellow]No keys found, generating new identity...[/yellow]")
-            addr_data = address.generate()
-            address.save(addr_data, co_dir)
-            self.logger.print(f"[green]✓ Keys saved to {co_dir / 'keys'}[/green]")
-
-        # Create ANNOUNCE message
-        # Use system_prompt as summary (first 1000 chars)
-        summary = self.system_prompt[:1000] if self.system_prompt else f"{self.name} agent"
-        announce_msg = announce.create_announce_message(
-            addr_data,
-            summary,
-            endpoints=[]  # MVP: No direct endpoints yet
-        )
-
-        self.logger.print(f"\n[bold]Starting agent: {self.name}[/bold]")
-        self.logger.print(f"Address: {addr_data['address']}")
-        self.logger.print(f"Debug: https://oo.openonion.ai/agent/{addr_data['address']}\n")
-
-        # Define async task handler
-        async def task_handler(prompt: str) -> str:
-            """Handle incoming task by running through agent.input()"""
-            return self.input(prompt)
-
-        # Run serve loop
-        async def run():
-            ws = await relay.connect(relay_url)
-            await relay.serve_loop(ws, announce_msg, task_handler)
-
-        # Run the async loop
-        asyncio.run(run())

connectonion/announce.py

@@ -1,10 +1,10 @@
 """
 Purpose: Build and sign ANNOUNCE messages for agent relay network registration
 LLM-Note:
-  Dependencies: imports from [json, time, typing, address.py] | imported by [agent.py] | tested by [tests/test_announce.py]
-  Data flow: receives from Agent.serve() → create_announce_message(address_data, summary, endpoints) → builds message dict without signature → serializes to deterministic JSON (sort_keys=True) → calls address.sign() to create Ed25519 signature → returns signed message ready for relay
+  Dependencies: imports from [json, time, typing, address.py] | imported by [host.py] | tested by [tests/test_announce.py]
+  Data flow: receives from host() → create_announce_message(address_data, summary, endpoints) → builds message dict without signature → serializes to deterministic JSON (sort_keys=True) → calls address.sign() to create Ed25519 signature → returns signed message ready for relay
   State/Effects: no side effects | pure function | deterministic JSON serialization (matches server verification) | signature is hex string without 0x prefix
-  Integration: exposes create_announce_message(address_data, summary, endpoints) | used by Agent.serve() to announce agent presence to relay network | relay server verifies signature using address (public key) | heartbeat re-sends with updated timestamp
+  Integration: exposes create_announce_message(address_data, summary, endpoints) | used by host() to announce agent presence to relay network | relay server verifies signature using address (public key) | heartbeat re-sends with updated timestamp
   Performance: Ed25519 signing is fast (sub-millisecond) | JSON serialization minimal overhead | no I/O or network calls
   Errors: raises KeyError if address_data missing required keys | address.sign() errors bubble up | no validation of summary length or endpoint format
 

connectonion/asgi.py

@@ -0,0 +1,225 @@
+"""Raw ASGI utilities for HTTP/WebSocket handling.
+
+This module contains the protocol-level code for handling HTTP and WebSocket
+requests. Separated from host.py for better testing and smaller file size.
+
+Design decision: Raw ASGI instead of Starlette/FastAPI for full protocol control.
+See: docs/design-decisions/022-raw-asgi-implementation.md
+"""
+import json
+from pathlib import Path
+
+
+async def read_body(receive) -> bytes:
+    """Read complete request body from ASGI receive."""
+    body = b""
+    while True:
+        m = await receive()
+        body += m.get("body", b"")
+        if not m.get("more_body"):
+            break
+    return body
+
+
+async def send_json(send, data: dict, status: int = 200):
+    """Send JSON response via ASGI send."""
+    body = json.dumps(data).encode()
+    await send({"type": "http.response.start", "status": status,
+               "headers": [[b"content-type", b"application/json"]]})
+    await send({"type": "http.response.body", "body": body})
+
+
+async def send_html(send, html: bytes, status: int = 200):
+    """Send HTML response via ASGI send."""
+    await send({
+        "type": "http.response.start",
+        "status": status,
+        "headers": [[b"content-type", b"text/html; charset=utf-8"]],
+    })
+    await send({"type": "http.response.body", "body": html})
+
+
+async def handle_http(
+    scope,
+    receive,
+    send,
+    *,
+    handlers: dict,
+    storage,
+    trust: str,
+    result_ttl: int,
+    start_time: float,
+    blacklist: list | None = None,
+    whitelist: list | None = None,
+):
+    """Route HTTP requests to handlers.
+
+    Args:
+        scope: ASGI scope dict (method, path, headers, etc.)
+        receive: ASGI receive callable
+        send: ASGI send callable
+        handlers: Dict of handler functions (input, session, sessions, health, info, auth)
+        storage: SessionStorage instance
+        trust: Trust level (open/careful/strict)
+        result_ttl: How long to keep results in seconds
+        start_time: Server start time
+        blacklist: Blocked identities
+        whitelist: Allowed identities
+    """
+    method, path = scope["method"], scope["path"]
+
+    if method == "POST" and path == "/input":
+        body = await read_body(receive)
+        try:
+            data = json.loads(body) if body else {}
+        except json.JSONDecodeError:
+            await send_json(send, {"error": "Invalid JSON"}, 400)
+            return
+
+        prompt, identity, sig_valid, err = handlers["auth"](
+            data, trust, blacklist=blacklist, whitelist=whitelist
+        )
+        if err:
+            status = 401 if err.startswith("unauthorized") else 403 if err.startswith("forbidden") else 400
+            await send_json(send, {"error": err}, status)
+            return
+
+        # Extract session for conversation continuation
+        session = data.get("session")
+        result = handlers["input"](storage, prompt, result_ttl, session)
+        await send_json(send, result)
+
+    elif method == "GET" and path.startswith("/sessions/"):
+        result = handlers["session"](storage, path[10:])
+        await send_json(send, result or {"error": "not found"}, 404 if not result else 200)
+
+    elif method == "GET" and path == "/sessions":
+        await send_json(send, handlers["sessions"](storage))
+
+    elif method == "GET" and path == "/health":
+        await send_json(send, handlers["health"](start_time))
+
+    elif method == "GET" and path == "/info":
+        await send_json(send, handlers["info"](trust))
+
+    elif method == "GET" and path == "/docs":
+        # Serve static docs page
+        try:
+            base = Path(__file__).resolve().parent
+            html_path = base / "static" / "docs.html"
+            html = html_path.read_bytes()
+        except Exception:
+            html = b"<html><body><h1>ConnectOnion Docs</h1><p>Docs not found.</p></body></html>"
+        await send_html(send, html)
+
+    else:
+        await send_json(send, {"error": "not found"}, 404)
+
+
+async def handle_websocket(
+    scope,
+    receive,
+    send,
+    *,
+    handlers: dict,
+    trust: str,
+    blacklist: list | None = None,
+    whitelist: list | None = None,
+):
+    """Handle WebSocket connections at /ws.
+
+    Args:
+        scope: ASGI scope dict
+        receive: ASGI receive callable
+        send: ASGI send callable
+        handlers: Dict with 'ws_input' and 'auth' handlers
+        trust: Trust level
+        blacklist: Blocked identities
+        whitelist: Allowed identities
+    """
+    if scope["path"] != "/ws":
+        await send({"type": "websocket.close", "code": 4004})
+        return
+
+    await send({"type": "websocket.accept"})
+
+    while True:
+        msg = await receive()
+        if msg["type"] == "websocket.disconnect":
+            break
+        if msg["type"] == "websocket.receive":
+            try:
+                data = json.loads(msg.get("text", "{}"))
+            except json.JSONDecodeError:
+                await send({"type": "websocket.send",
+                           "text": json.dumps({"type": "ERROR", "message": "Invalid JSON"})})
+                continue
+
+            if data.get("type") == "INPUT":
+                prompt, identity, sig_valid, err = handlers["auth"](
+                    data, trust, blacklist=blacklist, whitelist=whitelist
+                )
+                if err:
+                    await send({"type": "websocket.send",
+                               "text": json.dumps({"type": "ERROR", "message": err})})
+                    continue
+                if not prompt:
+                    await send({"type": "websocket.send",
+                               "text": json.dumps({"type": "ERROR", "message": "prompt required"})})
+                    continue
+                result = handlers["ws_input"](prompt)
+                await send({"type": "websocket.send",
+                           "text": json.dumps({"type": "OUTPUT", "result": result})})
+
+
+def create_app(
+    *,
+    handlers: dict,
+    storage,
+    trust: str = "careful",
+    result_ttl: int = 86400,
+    blacklist: list | None = None,
+    whitelist: list | None = None,
+):
+    """Create ASGI application.
+
+    Args:
+        handlers: Dict of handler functions
+        storage: SessionStorage instance
+        trust: Trust level (open/careful/strict)
+        result_ttl: How long to keep results in seconds
+        blacklist: Blocked identities
+        whitelist: Allowed identities
+
+    Returns:
+        ASGI application callable
+    """
+    import time
+    start_time = time.time()
+
+    async def app(scope, receive, send):
+        if scope["type"] == "http":
+            await handle_http(
+                scope,
+                receive,
+                send,
+                handlers=handlers,
+                storage=storage,
+                trust=trust,
+                result_ttl=result_ttl,
+                start_time=start_time,
+                blacklist=blacklist,
+                whitelist=whitelist,
+            )
+        elif scope["type"] == "websocket":
+            await handle_websocket(
+                scope,
+                receive,
+                send,
+                handlers=handlers,
+                trust=trust,
+                blacklist=blacklist,
+                whitelist=whitelist,
+            )
+
+    return app

connectonion/cli/commands/deploy_commands.py

@@ -2,7 +2,7 @@
 Purpose: Deploy agent projects to ConnectOnion Cloud with git archive packaging and secrets management
 LLM-Note:
   Dependencies: imports from [os, subprocess, tempfile, time, toml, requests, pathlib, rich.console, dotenv] | imported by [cli/main.py via handle_deploy()] | calls backend at [https://oo.openonion.ai/api/v1/deploy]
-  Data flow: handle_deploy() → validates git repo and .co/config.toml → _get_api_key() loads OPENONION_API_KEY → reads config.toml for project name and secrets path → dotenv_values() loads secrets from .env → git archive creates tarball of HEAD → POST to /api/v1/deploy with tarball + secrets → polls /api/v1/deploy/status/{id} until running/error → displays agent URL
+  Data flow: handle_deploy() → validates git repo and .co/config.toml → _get_api_key() loads OPENONION_API_KEY → reads config.toml for project name and secrets path → dotenv_values() loads secrets from .env → git archive creates tarball of HEAD → POST to /api/v1/deploy with tarball + project_name + secrets → polls /api/v1/deploy/{id}/status until running/error → displays agent URL
   State/Effects: creates temporary tarball file in tempdir | reads .co/config.toml, .env files | makes network POST request | prints progress to stdout via rich.Console | does not modify project files
   Integration: exposes handle_deploy() for CLI | expects git repo with .co/config.toml containing project.name, project.secrets, deploy.entrypoint | uses Bearer token auth | returns void (prints results)
   Performance: git archive is fast | network timeout 60s for upload, 10s for status checks | polls every 3s up to 100 times (~5 min)
@@ -87,6 +87,7 @@ def handle_deploy():
             f"{API_BASE}/api/v1/deploy",
             files={"package": ("agent.tar.gz", f, "application/gzip")},
             data={
+                "project_name": project_name,
                 "secrets": str(secrets),
                 "entrypoint": entrypoint,
             },
@@ -98,13 +99,13 @@ def handle_deploy():
         console.print(f"[red]Deploy failed: {response.text}[/red]")
         return
 
-    deployment_id = response.json().get("deployment_id")
+    deployment_id = response.json().get("id")
 
     # Wait for deployment
     console.print("Building...")
     for _ in range(100):
         status_resp = requests.get(
-            f"{API_BASE}/api/v1/deploy/status/{deployment_id}",
+            f"{API_BASE}/api/v1/deploy/{deployment_id}/status",
             headers={"Authorization": f"Bearer {api_key}"},
             timeout=10,
         )
@@ -118,8 +119,8 @@ def handle_deploy():
             return
         time.sleep(3)
 
-    agent_url = response.json().get("agent_url", "")
+    url = response.json().get("url", "")
     console.print()
     console.print("[bold green]Deployed![/bold green]")
-    console.print(f"Agent URL: {agent_url}")
+    console.print(f"Agent URL: {url}")
     console.print()

connectonion/connect.py

@@ -4,7 +4,7 @@ LLM-Note:
   Dependencies: imports from [asyncio, json, uuid, websockets] | imported by [__init__.py, tests/test_connect.py, examples/] | tested by [tests/test_connect.py, tests/integration/manual/network_connect_manual.py]
   Data flow: user calls connect(address, relay_url) → creates RemoteAgent instance → user calls .input(prompt) → _send_task() creates WebSocket to relay /ws/input → sends INPUT message with {type, input_id, to, prompt} → waits for OUTPUT response from relay → returns result string OR raises ConnectionError
   State/Effects: establishes temporary WebSocket connection per task (no persistent connection) | sends INPUT messages to relay | receives OUTPUT/ERROR messages | no file I/O or global state | asyncio.run() blocks on .input(), await on .input_async()
-  Integration: exposes connect(address, relay_url), RemoteAgent class with .input(prompt, timeout), .input_async(prompt, timeout) | default relay_url="wss://oo.openonion.ai/ws/announce" | address format: 0x + 64 hex chars (Ed25519 public key) | complements Agent.serve() which listens for INPUT on relay | Protocol: INPUT type with to/prompt fields → OUTPUT type with input_id/result fields
+  Integration: exposes connect(address, relay_url), RemoteAgent class with .input(prompt, timeout), .input_async(prompt, timeout) | default relay_url="wss://oo.openonion.ai/ws/announce" | address format: 0x + 64 hex chars (Ed25519 public key) | complements host() with relay_url which listens for INPUT on relay | Protocol: INPUT type with to/prompt fields → OUTPUT type with input_id/result fields
   Performance: creates new WebSocket connection per input() call (no connection pooling) | default timeout=30s | async under the hood (asyncio.run wraps for sync API) | no caching or retry logic
   Errors: raises ImportError if websockets not installed | raises ConnectionError for ERROR responses from relay | raises ConnectionError for unexpected response types | asyncio.TimeoutError if no response within timeout | WebSocket connection errors bubble up