Enhance WebSocket session management by requiring assistant_id as a query parameter for connection. Update API reference documentation to reflect changes in message flow and metadata validation rules, including the introduction of whitelists for allowed metadata fields and restrictions on sensitive keys. Refactor client examples to align with the new session initiation process.

engine/examples/mic_client.py

@@ -23,6 +23,7 @@ import time
 import threading
 import queue
 from pathlib import Path
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
 
 try:
     import numpy as np
@@ -59,9 +60,8 @@ class MicrophoneClient:
         url: str,
         sample_rate: int = 16000,
         chunk_duration_ms: int = 20,
-        app_id: str = "assistant_demo",
+        assistant_id: str = "assistant_demo",
         channel: str = "mic_client",
-        config_version_id: str = "local-dev",
         input_device: int = None,
         output_device: int = None,
         track_debug: bool = False,
@@ -80,9 +80,8 @@ class MicrophoneClient:
         self.sample_rate = sample_rate
         self.chunk_duration_ms = chunk_duration_ms
         self.chunk_samples = int(sample_rate * chunk_duration_ms / 1000)
-        self.app_id = app_id
+        self.assistant_id = assistant_id
         self.channel = channel
-        self.config_version_id = config_version_id
         self.input_device = input_device
         self.output_device = output_device
         self.track_debug = track_debug
@@ -125,19 +124,21 @@ class MicrophoneClient:
             if value:
                 parts.append(f"{key}={value}")
         return f" [{' '.join(parts)}]" if parts else ""
+
+    def _session_url(self) -> str:
+        parts = urlsplit(self.url)
+        query = dict(parse_qsl(parts.query, keep_blank_values=True))
+        query["assistant_id"] = self.assistant_id
+        return urlunsplit((parts.scheme, parts.netloc, parts.path, urlencode(query), parts.fragment))
     
     async def connect(self) -> None:
         """Connect to WebSocket server."""
-        print(f"Connecting to {self.url}...")
-        self.ws = await websockets.connect(self.url)
+        session_url = self._session_url()
+        print(f"Connecting to {session_url}...")
+        self.ws = await websockets.connect(session_url)
         self.running = True
         print("Connected!")
-        
-        # WS v1 handshake: hello -> session.start
-        await self.send_command({
-            "type": "hello",
-            "version": "v1",
-        })
+
         await self.send_command({
             "type": "session.start",
             "audio": {
@@ -146,9 +147,8 @@ class MicrophoneClient:
                 "channels": 1,
             },
             "metadata": {
-                "appId": self.app_id,
                 "channel": self.channel,
-                "configVersionId": self.config_version_id,
+                "source": "mic_client",
             },
         })
     
@@ -330,7 +330,7 @@ class MicrophoneClient:
         if self.track_debug:
             print(f"[track-debug] event={event_type} trackId={event.get('trackId')}{ids}")
         
-        if event_type in {"hello.ack", "session.started"}:
+        if event_type == "session.started":
             print(f"← Session ready!{ids}")
         elif event_type == "config.resolved":
             print(f"← Config resolved: {event.get('config', {}).get('output', {})}{ids}")
@@ -609,20 +609,15 @@ async def main():
         help="Show streaming LLM response chunks"
     )
     parser.add_argument(
-        "--app-id",
+        "--assistant-id",
         default="assistant_demo",
-        help="Stable app/assistant identifier for server-side config lookup"
+        help="Assistant identifier used in websocket query parameter"
     )
     parser.add_argument(
         "--channel",
         default="mic_client",
         help="Client channel name"
     )
-    parser.add_argument(
-        "--config-version-id",
-        default="local-dev",
-        help="Optional config version identifier"
-    )
     parser.add_argument(
         "--track-debug",
         action="store_true",
@@ -638,9 +633,8 @@ async def main():
     client = MicrophoneClient(
         url=args.url,
         sample_rate=args.sample_rate,
-        app_id=args.app_id,
+        assistant_id=args.assistant_id,
         channel=args.channel,
-        config_version_id=args.config_version_id,
         input_device=args.input_device,
         output_device=args.output_device,
         track_debug=args.track_debug,