spec: phase 7.0 capability-only WebSocket — devices untethered from any one AI

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Zawwarsami16

docs/superpowers/specs/2026-05-10-zhub-phase-7.0-capability-only-ws-design.md

@@ -0,0 +1,176 @@
+# Phase 7.0 — Capability-only WebSocket
+
+**Date:** 2026-05-10
+**Status:** spec
+**Goal:** generalize `connect()` so a device can expose capabilities to *any* AI on the hub, without being paired with a specific publisher's key.
+
+---
+
+## Why
+
+Today's `connect(ai_name, api_key, capabilities)` requires the device to know an AI's name and key in advance. That's right when there's a one-to-one relationship (Loki paired to ZAI), but it doesn't scale to "I have a generic device — any AI may use it":
+
+- A weather sensor wants to expose `weather_lookup` for every AI on the hub
+- A code-runner wants to expose `run_python` to anyone who can use it
+- A camera wants to expose `take_photo` once, not per-AI
+
+Capability-only WS turns devices into hub-level peripherals: register once, available to all.
+
+## Scope
+
+**In:**
+- New WS endpoint `/ws/expose` for unpaired devices
+- New envelope `register-exposure` (and helper)
+- Hub maintains an `exposures` registry separate from publishers/connections
+- Persistence: new `exposures` table mirroring `publishers` shape
+- HTTP `GET /exposures` — discovery
+- HTTP `POST /exposures/{exposure_id}/invoke` — invoke by any publisher key
+- Optional auto-injection: publisher's manifest sets `use_global_exposures: true` → hub adds global exposures to the `tools` it injects
+
+**Out:**
+- Per-AI access policies on exposures (every registered publisher can invoke for v1)
+- Capability streaming (long-running invokes)
+- Federation of exposures across peer hubs
+- Reverse direction: AI invoking exposure mid-stream during a chat (works via tool-call path; just no special syntax)
+
+## Architecture
+
+```
+[device]                                              [AI publisher]
+  │ WS /ws/expose                                       │ WS /ws/publish
+  │ register-exposure                                    │
+  ▼                                                     ▼
+  ┌──────────────────────────── hub ───────────────────────┐
+  │ exposures: {exp_id → ExposureRegistration}              │
+  │ publishers: {name → PublisherRegistration}              │
+  │ connections_by_ai: {ai → {cid → ConnectionRegistration}}│
+  └────────────────────┬────────────────────────────────────┘
+                       │ HTTP
+        ┌──────────────┼──────────────┐
+        ▼              ▼              ▼
+  GET /exposures   POST /exposures/<id>/invoke   (chat-request path injects
+  (discovery)      (Bearer <publisher_key>)        as tools when manifest opts in)
+```
+
+A device's lifecycle:
+1. Open `WS /ws/expose`
+2. Send `register-exposure` with `{name, manifest, capabilities, public: bool, desired_key?}`
+3. Hub stores in `exposures`, sends back `registered` envelope with `{exposure_id, device_key}` (a `dx_...` token)
+4. Device idles, listens for `invoke-request` envelopes
+5. On invoke, runs handler, sends `invoke-result`
+
+Re-registration: same flow as publishers — pass back the `device_key`, hub recognizes it via SQLite, restores the exposure with the same `exposure_id`.
+
+## Wire envelopes
+
+New protocol additions (in `zhub/protocol.py`):
+
+```python
+def register_exposure(name: str, manifest: dict, device_key: Optional[str] = None) -> Envelope:
+    return Envelope(type="register-exposure",
+                    payload={"name": name, "manifest": manifest, "device_key": device_key})
+
+def exposure_registered(exposure_id: str, device_key: str, name: str) -> Envelope:
+    return Envelope(type="exposure-registered",
+                    payload={"exposure_id": exposure_id, "device_key": device_key, "name": name})
+```
+
+`invoke-request` and `invoke-result` reuse existing shape. The hub injects `connection_id` as the exposure_id when routing.
+
+## Hub-side surface
+
+```python
+@dataclass
+class ExposureRegistration:
+    exposure_id: str          # "ex_..." (avoids collision with cx_)
+    name: str                  # human label e.g. "weather-sensor"
+    websocket: WebSocket
+    manifest: dict             # {capabilities: [...], public: bool, ...}
+    device_key_hash: str
+    pending: dict[str, asyncio.Future]
+    created_at: float
+
+class Hub:
+    exposures: dict[str, ExposureRegistration]              # by exposure_id
+    device_keys: dict[str, str]                              # device_key → exposure_id
+
+    async def register_exposure(name, manifest, websocket, desired_device_key) -> (id, key)
+    async def unregister_exposure(exposure_id)
+    def find_exposure_by_capability(capability_name) -> Optional[exposure_id]
+    def list_public_exposures() -> list[dict]                # for GET /exposures
+    async def invoke_exposure(exposure_id, capability, args, timeout) -> dict
+```
+
+## HTTP endpoints
+
+### `GET /exposures`
+Public-flagged exposures. Returns:
+```json
+[{
+  "exposure_id": "ex_abc",
+  "name": "weather-sensor",
+  "description": "...",
+  "capabilities": ["weather_lookup"],
+  "uptime_seconds": 142
+}]
+```
+No auth. Operators who don't want their device discoverable set `public: false`.
+
+### `POST /exposures/{exposure_id}/invoke`
+Auth: `Bearer <any registered publisher's zk_ key>`. Body: `{capability, args}`. JSON-Schema-validates against the exposure's declared schema (same plumbing as `/v1/invoke`). Returns `{ok, result}`.
+
+## Persistence
+
+New SQLite table:
+
+```sql
+CREATE TABLE exposures (
+    exposure_id     TEXT PRIMARY KEY,
+    name            TEXT NOT NULL,
+    manifest_json   TEXT NOT NULL,
+    device_key_hash TEXT NOT NULL,
+    first_seen      INTEGER NOT NULL,
+    last_seen       INTEGER NOT NULL
+);
+```
+
+Re-registration: device passes back its `dx_...` key, hub matches the hash, gives back the same `exposure_id`. `device_key` survives hub restart same as `zk_` keys.
+
+## Publisher-side auto-use (opt-in)
+
+A publisher's manifest can set `use_global_exposures: true`. When true, the hub's existing `build_tools_for(ai_name)` (Phase 1.9) ALSO appends every public exposure's capabilities to the `tools` array. The AI sees them in chat-requests; emitted `tool_calls` matching an exposure's capability route through the auto-resolve loop (Phase 1.8) into `invoke_exposure` instead of `invoke_capability`.
+
+The wire shape for the AI is identical — it doesn't know whether a tool came from a connection or an exposure.
+
+## Tests
+
+`tests/test_exposures.py`:
+1. `register_exposure_returns_id_and_key` — WS register-exposure → hub returns ex_... + dx_...
+2. `re_register_with_existing_key_preserves_id` — restart-equivalent: same device_key → same exposure_id
+3. `get_exposures_lists_public_only` — public:true is listed, public:false isn't
+4. `invoke_via_http_with_publisher_key` — POST /exposures/<id>/invoke with a publisher's zk_ → handler fires, result returns
+5. `invoke_rejects_unauthorized` — no bearer or unknown key → 401
+6. `invoke_404_when_exposure_offline` — device WS dropped → 404
+7. `tool_call_from_publisher_routes_to_exposure` — publisher with use_global_exposures:true emits tool_call matching exposure cap; hub auto-resolves via exposure path; final text returned
+
+`tests/test_exposures_persistence.py`:
+8. SQLite round-trip: add exposure, list, delete
+
+## Out of scope (future)
+
+- Per-exposure access policy (whitelist of AI names / publisher keys allowed to invoke)
+- Cross-hub exposures via federation
+- Exposure manifest signing (ed25519 like publisher manifests)
+- Capability streaming (server-sent results during long-running invokes)
+- A `dispose()` HTTP for operator-side cleanup of stale exposures
+
+## Files
+
+- `zhub/protocol.py` — `register_exposure`, `exposure_registered` helpers
+- `zhub/persistence.py` — `exposures` table + `add_exposure`, `lookup_exposure`, `all_exposures`, `remove_exposure`
+- `zhub/server.py` — `ExposureRegistration` dataclass, `Hub.register_exposure` + lookups, `/ws/expose` handler, `GET /exposures`, `POST /exposures/{id}/invoke`, opt-in injection in `build_tools_for`
+- `zhub/client.py` — new `expose()` function (mirrors `connect()`)
+- `tests/test_exposures.py`
+- `tests/test_exposures_persistence.py`
+
+Estimated ~300 LOC + tests.