netra-zen 1.0.8__py3-none-any.whl → 1.0.10__py3-none-any.whl

{netra_zen-1.0.8.dist-info → netra_zen-1.0.10.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: netra-zen
-Version: 1.0.8
+Version: 1.0.10
 Summary: Multi-instance Claude orchestrator for parallel task execution
 Home-page: https://github.com/netra-systems/zen
 Author:  Systems

{netra_zen-1.0.8.dist-info → netra_zen-1.0.10.dist-info}/RECORD

@@ -1,10 +1,10 @@
 zen_orchestrator.py,sha256=JAxmSaXsF9xF7sVGHmjtEfWBMgomsO-vuJ2RsZ0Paiw,151118
 agent_interface/__init__.py,sha256=OsbOKzElHsxhVgak87oOx_u46QNgKmz-Reis-plAMwk,525
 agent_interface/base_agent.py,sha256=GNskG9VaZgno7X24lQTpFdxUoQE0yJHLh0UPFJvOPn4,11098
-netra_zen-1.0.8.dist-info/licenses/LICENSE.md,sha256=t6LtOzAE2hgIIv5WbaN0wOcU3QCnGtAkMGNclHrKTOs,79
+netra_zen-1.0.10.dist-info/licenses/LICENSE.md,sha256=t6LtOzAE2hgIIv5WbaN0wOcU3QCnGtAkMGNclHrKTOs,79
 scripts/__init__.py,sha256=FxMRmQuf7CAoQFpNqJcugEqDoi-hSpq9IwjxCmC6Ays,51
 scripts/__main__.py,sha256=41cdZ5GkvQ7ndWYUVJ6BnBi6haaa6SRQmBaYjUzOW3g,155
-scripts/agent_cli.py,sha256=c9qmAx1Fk2XNidveD2zhpF7ndj5hwgVwUcAEGY5kjJM,295129
+scripts/agent_cli.py,sha256=pz3tdk6kOp064jf72EFKO9QVhuIs0ZZMdrggojdKt0U,320550
 scripts/agent_logs.py,sha256=AzSPA9nCvh2toC6pa5mzv4l3F-jTOHUg-G8NQRbguAo,10830
 scripts/bump_version.py,sha256=fjABzzRVXJ00CbYMpUIUMwcOHwafLYtFL6NvUga-i6M,4183
 scripts/demo_log_collection.py,sha256=8T7qfgiYc33apBtu2ATN2DDYZtzt_HM7D2PCNf8TcfI,5274
@@ -19,10 +19,10 @@ token_transparency/claude_pricing_engine.py,sha256=9zWQJS3HJEs_lljil-xT1cUvG-Jf3
 zen/__init__.py,sha256=_1gd3iYHH2ekLrCvZQ4DEA2bZ-OK0vlLfxBb3KlZALU,206
 zen/__main__.py,sha256=zoXi9DiNt_WznQvnJ249ZvF-OcEoAnHmxeoKRFiPNo8,170
 zen/telemetry/__init__.py,sha256=QiW8p9TBDwPxtmYTszMyccblLHKrlVTsKLFIBvMHKx8,305
-zen/telemetry/embedded_credentials.py,sha256=K6i9LOGnBx6DXpaVBKmZYpvJ9LIYlAjQVXyjiKIF9x0,1657
+zen/telemetry/embedded_credentials.py,sha256=0ktJEeAwj_oLeSottOaCPEOnBXfqF7OYyAihiUOoRbA,3925
 zen/telemetry/manager.py,sha256=TtrIPOvRvq1OOhNAO_Tp-dz7EiS2xXfqnpKQduLwYoI,9731
-netra_zen-1.0.8.dist-info/METADATA,sha256=qO5AJ79GelX3ZmHMIS1sxy833cCKzIWAvGnVCZGoWn8,43383
-netra_zen-1.0.8.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-netra_zen-1.0.8.dist-info/entry_points.txt,sha256=oDehCnPGZezG0m9ZWspxjHLHyQ3eERX87eojR4ljaRo,45
-netra_zen-1.0.8.dist-info/top_level.txt,sha256=OhiyXmoXftBijCF6ck-RS1dN2NBJv9wdd7kBG1Es7zA,77
-netra_zen-1.0.8.dist-info/RECORD,,
+netra_zen-1.0.10.dist-info/METADATA,sha256=cxNP2UyMYb7LUBno5ID8VtTKzsW7Du4c6_5OD19J-Ic,43384
+netra_zen-1.0.10.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+netra_zen-1.0.10.dist-info/entry_points.txt,sha256=oDehCnPGZezG0m9ZWspxjHLHyQ3eERX87eojR4ljaRo,45
+netra_zen-1.0.10.dist-info/top_level.txt,sha256=OhiyXmoXftBijCF6ck-RS1dN2NBJv9wdd7kBG1Es7zA,77
+netra_zen-1.0.10.dist-info/RECORD,,

scripts/agent_cli.py

@@ -61,7 +61,7 @@ if not _stream_logs_active:
         logger.disabled = True
 
 from typing import Optional, Dict, Any, List
-from datetime import datetime, timedelta
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
 import aiohttp
 import websockets
@@ -1626,6 +1626,7 @@ class Config:
     skip_timeout_validation: bool = False  # Issue #2483: Skip timeout hierarchy validation
     json_mode: bool = False  # ISSUE #2766: JSON output mode - suppress console output
     ci_mode: bool = False  # ISSUE #2766: CI mode - suppress Rich terminal output
+    use_backend_threads: bool = True  # SSOT: Use backend for thread ID management (can disable for backward compat)
 
     def get_websocket_url(self) -> str:
         """Get WebSocket URL for compatibility with test framework"""
@@ -2600,6 +2601,11 @@ class WebSocketClient:
         # ISSUE #2417 Phase 2: Store thread_id for filtering backend logs
         self.current_thread_id: Optional[str] = None
 
+        # SSOT: Thread management cache for performance
+        self.thread_cache_file = self._get_platform_cache_path()
+        self.thread_cache: Dict[str, Dict[str, Any]] = {}
+        self._load_thread_cache()
+
         # Log forwarding configuration
         self.send_logs = send_logs
         self.logs_count = logs_count
@@ -2855,9 +2861,25 @@ class WebSocketClient:
                         DebugLevel.BASIC,
                         style="green"
                     )
-                    safe_console_print("SUCCESS: WebSocket connected successfully!", style="green")
-                    self.connected = True
-                    return True
+
+                    # SSOT: Perform handshake to get backend-provided thread_id
+                    handshake_success = await self._perform_handshake()
+                    if handshake_success:
+                        safe_console_print(f"✅ Connected with thread ID: {self.current_thread_id}", style="green")
+                        self.connected = True
+                        return True
+                    else:
+                        # Handshake failed - backend might be old version
+                        self.debug.debug_print(
+                            "WARNING: Handshake failed - backend may not support thread agreement",
+                            DebugLevel.BASIC,
+                            style="yellow"
+                        )
+
+                        # Still mark as connected for backward compatibility
+                        # Old backends might work without the handshake
+                        self.connected = True
+                        return True
             except Exception as e:
                 self.debug.log_connection_attempt(method_name, self.config.ws_url, success=False, error=str(e))
                 self.debug.debug_print(
@@ -2955,6 +2977,492 @@ class WebSocketClient:
         )
         return True
 
+    async def _perform_handshake(self) -> bool:
+        """
+        SSOT: Perform handshake protocol to get backend-provided thread_id.
+        This ensures both CLI and backend agree on the thread_id for proper event routing.
+
+        Protocol (tries both approaches):
+        A. New protocol: Backend sends connection_established immediately
+        B. Legacy protocol: CLI sends initial message to trigger backend response
+        """
+        try:
+            import asyncio
+
+            self.debug.debug_print(
+                "Starting handshake...",
+                DebugLevel.VERBOSE,
+                style="cyan"
+            )
+
+            # Try to receive immediately (new protocol where backend sends first)
+            try:
+                # Non-blocking check if backend sent connection_established
+                response_msg = await asyncio.wait_for(self.ws.recv(), timeout=2.0)
+                response = json.loads(response_msg)
+
+                # Process if we got a connection_established immediately
+                if response.get('type') == 'connection_established':
+                    self.debug.debug_print(
+                        "Received thread ID from backend",
+                        DebugLevel.VERBOSE,
+                        style="green"
+                    )
+                    return await self._process_connection_established(response)
+                else:
+                    # Got a different message type - log it
+                    self.debug.debug_print(
+                        f"Got {response.get('type')} instead of connection_established",
+                        DebugLevel.VERBOSE,
+                        style="yellow"
+                    )
+            except asyncio.TimeoutError:
+                # Backend didn't send immediately, try sending a trigger message
+                pass  # Silent - this is normal for backends that wait for trigger
+
+            # If we didn't get connection_established immediately, send a trigger
+            # This handles backends that wait for an initial message
+            trigger_message = {
+                "type": "handshake_request",
+                "client_type": "cli",
+                "client_version": "2.0.0",
+                "timestamp": datetime.now(timezone.utc).isoformat()
+            }
+
+            self.debug.debug_print(
+                "Sending handshake_request...",
+                DebugLevel.VERBOSE,
+                style="cyan"
+            )
+
+            await self.ws.send(json.dumps(trigger_message))
+
+            # Now wait for the response
+            try:
+                response_msg = await asyncio.wait_for(self.ws.recv(), timeout=10.0)
+                response = json.loads(response_msg)
+
+                if response.get('type') == 'connection_established':
+                    return await self._process_connection_established(response)
+                else:
+                    # Not a connection_established message - show actual response
+                    response_type = response.get('type', 'unknown')
+                    self.debug.debug_print(
+                        f"ERROR: Unexpected response type: '{response_type}'",
+                        DebugLevel.BASIC,
+                        style="red"
+                    )
+
+                    # CRITICAL: Show the actual response data for debugging
+                    self.debug.debug_print(
+                        "ACTUAL RESPONSE DATA:",
+                        DebugLevel.BASIC,
+                        style="yellow"
+                    )
+                    self.debug.debug_print(
+                        json.dumps(response, indent=2),
+                        DebugLevel.BASIC,
+                        style="cyan"
+                    )
+                    return False
+
+            except asyncio.TimeoutError:
+                # Timeout - log error concisely
+                self.debug.debug_print(
+                    "ERROR: Handshake timeout - no response from backend",
+                    DebugLevel.BASIC,
+                    style="red"
+                )
+                return False
+
+        except Exception as e:
+            # Handshake error - log but don't completely fail
+            error_msg = f"WARNING: Handshake error: {e}"
+            self.debug.log_error(e, "handshake protocol")
+            self.debug.debug_print(error_msg, DebugLevel.BASIC, style="yellow")
+            safe_console_print(error_msg, style="yellow")
+            return False
+
+    async def _process_connection_established(self, response: Dict[str, Any]) -> bool:
+        """
+        Process a connection_established message from backend.
+
+        Args:
+            response: The connection_established message from backend
+
+        Returns:
+            True if thread_id was successfully extracted and acknowledged
+        """
+        # Extract all IDs from backend response
+        backend_thread_id = response.get('thread_id')
+        backend_run_id = response.get('run_id')
+        backend_request_id = response.get('request_id')
+        backend_session_token = response.get('session_token')
+
+        if not backend_thread_id:
+            # Backend didn't provide thread_id
+            self.debug.debug_print(
+                "ERROR: Backend connection_established missing thread_id",
+                DebugLevel.BASIC,
+                style="red"
+            )
+            return False
+
+        # CRITICAL: Accept backend's thread_id as single source of truth
+        self.current_thread_id = backend_thread_id
+        self.run_id = backend_run_id  # Store run_id if provided
+        self._update_thread_cache(backend_thread_id)
+
+        self.debug.debug_print(
+            f"Thread ID: {backend_thread_id}",
+            DebugLevel.VERBOSE,
+            style="green"
+        )
+
+        # CRITICAL: Send acknowledgment with the SAME thread_id
+        ack_message = {
+            "type": "session_acknowledged",
+            "thread_id": backend_thread_id,  # Echo back the same ID
+            "timestamp": datetime.now(timezone.utc).isoformat()
+        }
+
+        await self.ws.send(json.dumps(ack_message))
+
+        return True
+
+    def _get_platform_cache_path(self) -> Path:
+        """
+        Get platform-appropriate cache directory path.
+
+        Windows: %LOCALAPPDATA%/Netra/CLI/thread_cache.json
+        macOS: ~/Library/Application Support/Netra/CLI/thread_cache.json
+        Linux: ~/.local/share/netra/cli/thread_cache.json or ~/.netra/thread_cache.json
+        """
+        import platform as stdlib_platform
+
+        system = stdlib_platform.system()
+
+        if system == "Windows":
+            # Use Windows AppData/Local directory
+            app_data = os.environ.get('LOCALAPPDATA')
+            if app_data:
+                cache_dir = Path(app_data) / "Netra" / "CLI"
+            else:
+                # Fallback to user home
+                cache_dir = Path.home() / "AppData" / "Local" / "Netra" / "CLI"
+        elif system == "Darwin":  # macOS
+            # Use macOS Application Support directory
+            cache_dir = Path.home() / "Library" / "Application Support" / "Netra" / "CLI"
+        else:  # Linux and other Unix-like systems
+            # Follow XDG Base Directory Specification
+            xdg_data_home = os.environ.get('XDG_DATA_HOME')
+            if xdg_data_home:
+                cache_dir = Path(xdg_data_home) / "netra" / "cli"
+            else:
+                # Fallback to ~/.local/share or ~/.netra for compatibility
+                local_share = Path.home() / ".local" / "share" / "netra" / "cli"
+                if local_share.parent.exists():
+                    cache_dir = local_share
+                else:
+                    # Legacy path for backward compatibility
+                    cache_dir = Path.home() / ".netra"
+
+        return cache_dir / "thread_cache.json"
+
+    def _load_thread_cache(self) -> None:
+        """
+        Load thread cache from disk for SSOT thread management.
+
+        Cache structure:
+        {
+            "user_id": {
+                "thread_id": "backend_thread_123",
+                "created_at": "2024-01-01T00:00:00",
+                "last_used": "2024-01-01T00:00:00",
+                "environment": "staging"
+            }
+        }
+        """
+        try:
+            if self.thread_cache_file.exists():
+                with open(self.thread_cache_file, 'r') as f:
+                    self.thread_cache = json.load(f)
+                    self.debug.debug_print(
+                        f"SSOT: Loaded thread cache with {len(self.thread_cache)} entries",
+                        DebugLevel.VERBOSE
+                    )
+        except Exception as e:
+            self.debug.debug_print(
+                f"SSOT: Could not load thread cache: {e}",
+                DebugLevel.TRACE
+            )
+            self.thread_cache = {}
+
+    def _save_thread_cache(self) -> None:
+        """Save thread cache to disk for persistence."""
+        try:
+            # Ensure directory exists
+            self.thread_cache_file.parent.mkdir(parents=True, exist_ok=True)
+
+            # Save cache
+            with open(self.thread_cache_file, 'w') as f:
+                json.dump(self.thread_cache, f, indent=2)
+
+            self.debug.debug_print(
+                "SSOT: Thread cache saved successfully",
+                DebugLevel.TRACE
+            )
+        except Exception as e:
+            self.debug.debug_print(
+                f"SSOT: Could not save thread cache: {e}",
+                DebugLevel.TRACE
+            )
+
+    def _get_cached_thread_id(self) -> Optional[str]:
+        """
+        Get cached thread ID for current user and environment.
+
+        SSOT: Uses cached thread but validates with backend.
+        """
+        try:
+            # Get user identifier from token
+            if not self.token:
+                return None
+
+            # Decode token to get user_id
+            payload = jwt.decode(self.token, options={"verify_signature": False})
+            user_id = payload.get('user_id') or payload.get('sub') or payload.get('email')
+
+            if not user_id:
+                return None
+
+            # Check cache for this user
+            if user_id in self.thread_cache:
+                cached_data = self.thread_cache[user_id]
+
+                # Check if cache is for same environment
+                cached_env = cached_data.get('environment')
+                current_env = self.config.environment.value if hasattr(self.config, 'environment') else None
+
+                if cached_env == current_env:
+                    thread_id = cached_data.get('thread_id')
+                    last_used = cached_data.get('last_used')
+
+                    # Check if cache is recent (within 24 hours)
+                    if last_used:
+                        last_used_dt = datetime.fromisoformat(last_used)
+                        if datetime.now() - last_used_dt < timedelta(hours=24):
+                            self.debug.debug_print(
+                                f"SSOT: Found cached thread_id: {thread_id}",
+                                DebugLevel.VERBOSE
+                            )
+                            return thread_id
+
+        except Exception as e:
+            self.debug.debug_print(
+                f"SSOT: Error accessing thread cache: {e}",
+                DebugLevel.TRACE
+            )
+
+        return None
+
+    def _update_thread_cache(self, thread_id: str) -> None:
+        """Update thread cache with new or validated thread ID."""
+        try:
+            # Get user identifier
+            payload = jwt.decode(self.token, options={"verify_signature": False})
+            user_id = payload.get('user_id') or payload.get('sub') or payload.get('email')
+
+            if user_id:
+                # Update cache entry
+                self.thread_cache[user_id] = {
+                    'thread_id': thread_id,
+                    'created_at': self.thread_cache.get(user_id, {}).get('created_at', datetime.now().isoformat()),
+                    'last_used': datetime.now().isoformat(),
+                    'environment': self.config.environment.value if hasattr(self.config, 'environment') else "unknown"
+                }
+
+                # Save to disk
+                self._save_thread_cache()
+
+                self.debug.debug_print(
+                    f"SSOT: Updated thread cache for user {user_id[:10]}...",
+                    DebugLevel.TRACE
+                )
+
+        except Exception as e:
+            self.debug.debug_print(
+                f"SSOT: Could not update thread cache: {e}",
+                DebugLevel.TRACE
+            )
+
+    async def get_or_create_thread_from_backend(self) -> Optional[str]:
+        """
+        SSOT: Get or create a thread ID from the backend.
+
+        This ensures thread IDs are managed by the backend as the single source of truth,
+        not generated locally by the client.
+
+        Returns:
+            Thread ID from backend, or None if creation fails
+        """
+        # Check if backend thread management is disabled
+        if not self.config.use_backend_threads:
+            self.debug.debug_print(
+                "SSOT: Backend thread management disabled by configuration",
+                DebugLevel.VERBOSE
+            )
+            return None
+
+        try:
+            # First check if we have a cached thread_id for this session
+            if self.current_thread_id and await self._validate_thread_with_backend(self.current_thread_id):
+                self.debug.debug_print(
+                    f"SSOT: Using existing validated thread_id: {self.current_thread_id}",
+                    DebugLevel.VERBOSE
+                )
+                self._update_thread_cache(self.current_thread_id)
+                return self.current_thread_id
+
+            # Check persistent cache for thread ID
+            cached_thread_id = self._get_cached_thread_id()
+            if cached_thread_id and await self._validate_thread_with_backend(cached_thread_id):
+                self.current_thread_id = cached_thread_id
+                self.debug.debug_print(
+                    f"SSOT: Using cached and validated thread_id: {cached_thread_id}",
+                    DebugLevel.VERBOSE
+                )
+                self._update_thread_cache(cached_thread_id)
+                return cached_thread_id
+
+            # Create a new thread via backend API
+            thread_id = await self._create_thread_on_backend()
+            if thread_id:
+                self.current_thread_id = thread_id
+                self._update_thread_cache(thread_id)
+                self.debug.debug_print(
+                    f"SSOT: Created new thread_id from backend: {thread_id}",
+                    DebugLevel.BASIC,
+                    style="green"
+                )
+                return thread_id
+
+            # Fallback: Use local generation with warning (backward compatibility)
+            self.debug.debug_print(
+                "SSOT WARNING: Backend thread creation failed, falling back to local generation",
+                DebugLevel.BASIC,
+                style="yellow"
+            )
+            return None
+
+        except Exception as e:
+            self.debug.debug_print(
+                f"SSOT ERROR: Thread management failed: {e}",
+                DebugLevel.BASIC,
+                style="red"
+            )
+            return None
+
+    async def _create_thread_on_backend(self) -> Optional[str]:
+        """
+        Create a new thread on the backend and return its ID.
+
+        SSOT: Backend is the authoritative source for thread IDs.
+        """
+        try:
+            # Construct the thread creation endpoint
+            thread_url = f"{self.config.backend_url}/api/threads/create"
+
+            headers = {
+                "Authorization": f"Bearer {self.token}",
+                "Content-Type": "application/json"
+            }
+
+            # Thread creation payload with metadata
+            payload = {
+                "source": "agent_cli",
+                "environment": self.config.environment.value if hasattr(self.config, 'environment') else "unknown",
+                "client_version": "1.0.0",  # Could be made configurable
+                "timestamp": datetime.now().isoformat()
+            }
+
+            # Use aiohttp session if available, otherwise create one
+            import aiohttp
+            async with aiohttp.ClientSession() as session:
+                async with session.post(thread_url, json=payload, headers=headers) as response:
+                    if response.status == 200 or response.status == 201:
+                        data = await response.json()
+                        thread_id = data.get("thread_id") or data.get("id")
+                        if thread_id:
+                            self.debug.debug_print(
+                                f"SSOT: Backend created thread with ID: {thread_id}",
+                                DebugLevel.VERBOSE
+                            )
+                            return thread_id
+                    else:
+                        error_text = await response.text()
+                        self.debug.debug_print(
+                            f"SSOT: Backend thread creation failed with status {response.status}: {error_text}",
+                            DebugLevel.BASIC,
+                            style="yellow"
+                        )
+
+        except aiohttp.ClientError as e:
+            # Network or connection errors - expected in some environments
+            self.debug.debug_print(
+                f"SSOT: Backend thread API not available (network error): {e}",
+                DebugLevel.VERBOSE
+            )
+        except Exception as e:
+            self.debug.debug_print(
+                f"SSOT: Unexpected error creating backend thread: {e}",
+                DebugLevel.VERBOSE
+            )
+
+        return None
+
+    async def _validate_thread_with_backend(self, thread_id: str) -> bool:
+        """
+        Validate that a thread ID exists and is valid on the backend.
+
+        SSOT: Backend validates thread existence and status.
+        """
+        try:
+            # Quick validation - check if thread exists on backend
+            validate_url = f"{self.config.backend_url}/api/threads/{thread_id}/validate"
+
+            headers = {
+                "Authorization": f"Bearer {self.token}"
+            }
+
+            import aiohttp
+            async with aiohttp.ClientSession() as session:
+                async with session.get(validate_url, headers=headers) as response:
+                    if response.status == 200:
+                        data = await response.json()
+                        is_valid = data.get("valid", False)
+                        if is_valid:
+                            self.debug.debug_print(
+                                f"SSOT: Thread {thread_id} validated successfully",
+                                DebugLevel.TRACE
+                            )
+                        return is_valid
+                    elif response.status == 404:
+                        self.debug.debug_print(
+                            f"SSOT: Thread {thread_id} not found on backend",
+                            DebugLevel.VERBOSE
+                        )
+                        return False
+
+        except Exception as e:
+            # If validation fails, assume thread is invalid
+            self.debug.debug_print(
+                f"SSOT: Thread validation failed for {thread_id}: {e}",
+                DebugLevel.TRACE
+            )
+
+        return False
+
     async def send_message(self, message: str) -> str:
         """Send a message and return the run_id"""
         if not self.ws:
@@ -2965,12 +3473,73 @@ class WebSocketClient:
 
         # Create message payload
         # ISSUE #1671 FIX: Add thread_id for proper WebSocket event routing
-        # The WebSocket manager expects both user_id and thread_id to route events correctly
-        # ISSUE #2782: Simple UUID generation - no backend dependency
-        thread_id = f"cli_thread_{uuid.uuid4().hex[:12]}"
+        # SSOT: Thread ID from backend is REQUIRED
+        if not self.current_thread_id:
+            # Detailed error diagnostics
+            self.debug.debug_print(
+                "CRITICAL ERROR: Cannot send message - no thread ID available",
+                DebugLevel.BASIC,
+                style="red"
+            )
+            self.debug.debug_print(
+                "CAUSE: Backend handshake did not complete successfully",
+                DebugLevel.BASIC,
+                style="yellow"
+            )
 
-        # ISSUE #2417 Phase 2: Store thread_id for filtering backend logs
-        self.current_thread_id = thread_id
+            # User-facing error with actionable guidance
+            safe_console_print(
+                "\n❌ ERROR: Cannot send message - thread ID not established",
+                style="red"
+            )
+            safe_console_print(
+                "\n🔍 TROUBLESHOOTING STEPS:",
+                style="yellow"
+            )
+            safe_console_print(
+                "   1. Check if backend is running the latest version",
+                style="dim"
+            )
+            safe_console_print(
+                "   2. Verify backend has CLIHandshakeProtocol implemented",
+                style="dim"
+            )
+            safe_console_print(
+                "   3. Check backend logs for WebSocket connection errors",
+                style="dim"
+            )
+            safe_console_print(
+                "   4. Try running with --debug-level=verbose for more details",
+                style="dim"
+            )
+            safe_console_print(
+                "\n📝 WHAT HAPPENED:",
+                style="cyan"
+            )
+            safe_console_print(
+                "   • CLI connected to WebSocket successfully",
+                style="dim"
+            )
+            safe_console_print(
+                "   • Backend did not provide a thread ID during handshake",
+                style="dim"
+            )
+            safe_console_print(
+                "   • Without thread ID, events cannot be properly routed",
+                style="dim"
+            )
+
+            raise RuntimeError(
+                "Thread ID not established with backend. "
+                "See troubleshooting steps above."
+            )
+
+        thread_id = self.current_thread_id
+        self.debug.debug_print(
+            f"SSOT: Using backend-provided thread_id: {thread_id}",
+            DebugLevel.VERBOSE,
+            style="green"
+        )
 
         # ISSUE #1673 FIX: Backend expects payload structure with nested data
         # The backend AgentServiceCore._parse_message expects:
@@ -3164,6 +3733,15 @@ class WebSocketClient:
                 )
                 self.events.append(event)
 
+                # Skip connection_established - already handled in handshake
+                # This prevents duplicate processing since handshake now waits for it first
+                if event.type == 'connection_established' and self.current_thread_id:
+                    self.debug.debug_print(
+                        f"SSOT: Ignoring duplicate connection_established (thread already set: {self.current_thread_id})",
+                        DebugLevel.VERBOSE,
+                        style="dim"
+                    )
+
                 self.debug.debug_print(
                     f"GOLDEN PATH TRACE: Parsed WebSocket event type={event.type}",
                     DebugLevel.BASIC,
@@ -5475,6 +6053,26 @@ def main(argv=None):
         help="Disable WebSocket error diagnostics (opt-out)"
     )
 
+    # SSOT Thread Management Arguments
+    parser.add_argument(
+        "--handshake-timeout",
+        type=float,
+        default=5.0,
+        help="Timeout for handshake with backend (seconds, default: 5.0)"
+    )
+
+    parser.add_argument(
+        "--disable-backend-threads",
+        action="store_true",
+        help="SSOT: Disable backend thread ID management and use local generation (backward compatibility)"
+    )
+
+    parser.add_argument(
+        "--clear-thread-cache",
+        action="store_true",
+        help="SSOT: Clear cached thread IDs and force new thread creation"
+    )
+
     parser.add_argument(
         "--health-check",
         action="store_true",
@@ -5842,7 +6440,8 @@ def main(argv=None):
         enable_websocket_diagnostics=enable_diagnostics,  # Issue #2484 Phase 2: Default enabled with opt-out
         skip_timeout_validation=args.skip_timeout_validation,  # Issue #2483: Skip timeout hierarchy validation
         json_mode=json_mode,  # ISSUE #2766: Pass json_mode to config for output suppression
-        ci_mode=ci_mode  # ISSUE #2766: Pass ci_mode to config for output suppression
+        ci_mode=ci_mode,  # ISSUE #2766: Pass ci_mode to config for output suppression
+        use_backend_threads=not args.disable_backend_threads  # SSOT: Backend thread management (enabled by default)
     )
 
     # ISSUE #2839: Load validation framework imports when validation is explicitly requested
@@ -5890,6 +6489,31 @@ def main(argv=None):
             safe_console_print("SUCCESS: Cleared cached authentication token", style="green",
                              json_mode=json_mode, ci_mode=ci_mode)
 
+    # SSOT: Clear thread cache if requested
+    if args.clear_thread_cache:
+        # Use platform-aware cache path
+        from pathlib import Path
+        import platform as stdlib_platform
+
+        system = stdlib_platform.system()
+        if system == "Windows":
+            app_data = os.environ.get('LOCALAPPDATA', str(Path.home() / "AppData" / "Local"))
+            thread_cache_file = Path(app_data) / "Netra" / "CLI" / "thread_cache.json"
+        elif system == "Darwin":
+            thread_cache_file = Path.home() / "Library" / "Application Support" / "Netra" / "CLI" / "thread_cache.json"
+        else:
+            xdg_data = os.environ.get('XDG_DATA_HOME', str(Path.home() / ".local" / "share"))
+            thread_cache_file = Path(xdg_data) / "netra" / "cli" / "thread_cache.json"
+            # Also check legacy location
+            legacy_cache = Path.home() / ".netra" / "thread_cache.json"
+            if legacy_cache.exists():
+                legacy_cache.unlink()
+
+        if thread_cache_file.exists():
+            thread_cache_file.unlink()
+            safe_console_print("SUCCESS: Cleared cached thread IDs", style="green",
+                             json_mode=json_mode, ci_mode=ci_mode)
+
     # ISSUE #2766: json_mode and ci_mode already determined at top of main()
     json_output_file = args.json_output
 
@@ -6285,6 +6909,15 @@ def main(argv=None):
                     sys.exit(1)
             elif args.send_logs:
                 # Handle --send-logs without --message: use default message
+                # the jsonl logs are attached in payload
+                #   {
+                #    "type": "user_message",
+                #    "payload": { 
+                #           ...
+                #   *** "jsonl_logs": [... actual logs here ...] ***
+                #    }
+                #}
+
                 default_message = "claude-code optimizer default message"
                 result = await cli.run_single_message(default_message, args.wait)
                 # ISSUE #2766: Use structured exit code from ExitCodeGenerator

zen/telemetry/embedded_credentials.py

@@ -1,50 +1,20 @@
-"""Runtime loader for telemetry credentials from environment variables."""
-
-from __future__ import annotations
+"""Embedded telemetry credentials. AUTO-GENERATED - DO NOT COMMIT."""
 
 import base64
 import json
-import os
-from pathlib import Path
-from typing import Optional
-
 from google.oauth2 import service_account
 
-_ENV_B64 = "COMMUNITY_CREDENTIALS"
-_ENV_PATH = "ZEN_COMMUNITY_TELEMETRY_FILE"
-_ENV_PROJECT = "ZEN_COMMUNITY_TELEMETRY_PROJECT"
-_DEFAULT_PROJECT = "netra-telemetry-public"
-
-
-def _load_service_account_dict() -> Optional[dict]:
-    """Load service account JSON from environment variables."""
-    encoded = os.getenv(_ENV_B64)
-    if encoded:
-        try:
-            raw = base64.b64decode(encoded)
-            return json.loads(raw)
-        except (ValueError, json.JSONDecodeError):
-            return None
-
-    path = os.getenv(_ENV_PATH)
-    if path:
-        candidate = Path(path).expanduser()
-        if candidate.exists():
-            try:
-                return json.loads(candidate.read_text())
-            except json.JSONDecodeError:
-                return None
-    return None
+_EMBEDDED_CREDENTIALS_B64 = 'ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb3VudCIsCiAgInByb2plY3RfaWQiOiAibmV0cmEtdGVsZW1ldHJ5LXB1YmxpYyIsCiAgInByaXZhdGVfa2V5X2lkIjogImVjOWM4ZGNlZGZmMTUzNjM5YTUxOTcyMzc0MjYyNjkwNjZkNzAxYTQiLAogICJwcml2YXRlX2tleSI6ICItLS0tLUJFR0lOIFBSSVZBVEUgS0VZLS0tLS1cbk1JSUV2Z0lCQURBTkJna3Foa2lHOXcwQkFRRUZBQVNDQktnd2dnU2tBZ0VBQW9JQkFRREhUcmZFOHlQdUFCTDNcbk5aS3diZ1AwamRyaWRnY0UwMUlLMks1YkZ1bWFrUHVrRGxzV0dVaUswOXEyaVNYTWVUQmJPZDF0VjFoc3VJcUhcbnpQK0pZd0NTcVp4S0pIQS8yWUdVcERqeWhHRVd3QTNtS3laVXVUUS9yUTBUK20yV0cwdEMxUzBpQzB6U211cEpcbjBNeGhUUDRjKzYreEczSDVSWEF1YjdONmx6eFFWVnJSY3FHMTYydlF5SFA2OWIrd2RidTJHM0o5UkJVN1VUK1FcbkU2RHB2K01YaEp3MnRPdHZLbFBQT3BnWm9Sb0pmeXU1WlpzbHlJZCtzY3FhUTY5ZjBaSmpIRjlYQVdlT25mUTRcbmExbmV0LzJqRjZibWpuZmQ2MjhBODA5cEluTXJEL0FwZjJzUWJJdXJIYUI4am5uTEQ0eDMrbVhXRTgyMFJLNktcbjViZ0FQanNoQWdNQkFBRUNnZ0VBQmZERVZMWVlDakFkb0pscnpyOHF0a056cEpnV3Y3ZXlQSEZHcWgraDFSbndcbjdDd0Mza0xnNlFWbFFaZFBKWHZ2dTJwYlBaYnl3MlBST2ppN25adFNNU3pseEFaM3c0bHV2YkRTNHpTYnBiZFJcbityd3F3Mi8xUFJnaCtZaFhjNWZLNjVvcHd4Zmg0VzJkWWRlYnZlTXkrRWR1cmtsV2dYTG13L1dQbkkzdExlbzlcbjV1elZjbU42Qk04YkU3azFYK1M0RURBS0VRWlprUEdzTFQ4RXN4UmdWOWtnT1Zicm5VQ1Z0dXA1Q0NGbUR3U1Bcbmg0U25wMEsvTUp3b1U3NG4reTlFMXYxUXRnajE5TkhaNHJ2dFpnUlVaandHQy9Cc3ZkcE1PazArZTJEMlgvRk9cblZnc29xS2tDaklWUzRMcG5YSEpZbU5oajZWNHRXUnZ1OW1NTXhTL3FBUUtCZ1FEb3hZenlsdEZKL242ZEQvUHlcbnZLOFRaTHd5dFdCcjBXU3ZHU2VzM0JYRGZoKzBFbU4rRHpnZGdUb0ovbkhpazM5R21QM0tLN2htOFVvaFFHRy9cbkh0SFRuS0lBQlhrSU8yd2Z3N0h0V2pPTXRocHp2dFQxcmVEVHVjVk0wc2lCMHpjTldCMjFUamdQL3JYY2Q3NWVcbklERmNBN0hTbUJDLzB4bzk3aC8wV2YvOW9RS0JnUURiTWtnbjlVR2Y2SVRMNmxTcDdrYWJGL0NuaE4yU2VTMVdcbnd3R21iRThxTTU0UitDcVRUeHk2UHBRaFVSczlHM1VpVmQ1SXZWVDhuT095ZVBZVFJEbnFCYjJ4S214SFRodlZcbnVQcTgwQXB3anBMbzh6VkFDSy9iVFVjSmlKVGFBdXFHaXI1Ykc4YUlldVpIc0pLeWJ1NmhoNkhXMldwWXVVV1BcbkZ3TTl4elpOZ1FLQmdRQzg5dHJVZVJFUVE3VGZwbnJBM09JNEdUZ2E1bG1QVFo2eDh2YmRncEY4Y2FBbEhDUitcbnlyWWdaYThMTysrU0kzRllpNHpFR2pnS0FlblBFcWdIY21xZW9uSjFGL3hJYll6NlFIRHFJYWJsblZQZUVOWnJcblY2dkQxZlRReC9FVVM3Wk9jL0V5Slh5bnAzeFZyVFB5ejZtaWJERm9xQ0E0eVpSdElDbjZ3VEZxNFFLQmdFWFJcbnAxQXErOE0rb2dYOTF3ZmxvTkhIOTF5MG9vc0VWQis5cjZuZDkvMWVRYXhCbXZZZkRleDVBRi80WUsrL0xqbElcbmxxd2V1cEpZT3VMZlNxcHFZZlFiN2djZmx5dkRRblI2SGt2RURIODd1cW0reGlobVcvV0RrT3dGZUR4VkQzVFpcbmZyYXdpelZ2eUNmdm8xcDRvVVFNV3MxL3BUTXJtRzl5aWhMRWdKU0JBb0dCQU1GWm50ZUtUUDZrVVdrVmpOcndcbmUvQzBDbjJ6dk1YNXVnZURkS1FWNkwrY25mRWlRSzdzZ3R5eFp5ek5kMC82QXJ0YnBrcS9wcVlaYXpwVzVFMkxcbkxVMUF3MmdHT25GRlh2ZXg4aXpOZXViMGdvUVE4d3BtL3lrMVNVekR6VTV1dCtPbVFFRmpsbUYrNDkza0ZYcC9cbnc1MWh2WjVVL2loL1NYbjN6cjdEWE5QYlxuLS0tLS1FTkQgUFJJVkFURSBLRVktLS0tLVxuIiwKICAiY2xpZW50X2VtYWlsIjogInplbi1jb21tdW5pdHktdGVsZW1ldHJ5QG5ldHJhLXRlbGVtZXRyeS1wdWJsaWMuaWFtLmdzZXJ2aWNlYWNjb3VudC5jb20iLAogICJjbGllbnRfaWQiOiAiMTE0NzAwMDA0NzA1MDUxODg5NTY4IiwKICAiYXV0aF91cmkiOiAiaHR0cHM6Ly9hY2NvdW50cy5nb29nbGUuY29tL28vb2F1dGgyL2F1dGgiLAogICJ0b2tlbl91cmkiOiAiaHR0cHM6Ly9vYXV0aDIuZ29vZ2xlYXBpcy5jb20vdG9rZW4iLAogICJhdXRoX3Byb3ZpZGVyX3g1MDlfY2VydF91cmwiOiAiaHR0cHM6Ly93d3cuZ29vZ2xlYXBpcy5jb20vb2F1dGgyL3YxL2NlcnRzIiwKICAiY2xpZW50X3g1MDlfY2VydF91cmwiOiAiaHR0cHM6Ly93d3cuZ29vZ2xlYXBpcy5jb20vcm9ib3QvdjEvbWV0YWRhdGEveDUwOS96ZW4tY29tbXVuaXR5LXRlbGVtZXRyeSU0MG5ldHJhLXRlbGVtZXRyeS1wdWJsaWMuaWFtLmdzZXJ2aWNlYWNjb3VudC5jb20iLAogICJ1bml2ZXJzZV9kb21haW4iOiAiZ29vZ2xlYXBpcy5jb20iCn0K'
+_CREDENTIALS_DICT = json.loads(
+    base64.b64decode(_EMBEDDED_CREDENTIALS_B64.encode("utf-8"))
+)
 
 
 def get_embedded_credentials():
-    """Return service account credentials or None."""
-    info = _load_service_account_dict()
-    if not info:
-        return None
+    """Return service account credentials."""
     try:
         return service_account.Credentials.from_service_account_info(
-            info,
+            _CREDENTIALS_DICT,
             scopes=["https://www.googleapis.com/auth/trace.append"],
         )
     except Exception:
@@ -52,8 +22,5 @@ def get_embedded_credentials():
 
 
 def get_project_id() -> str:
-    """Return GCP project ID for telemetry."""
-    info = _load_service_account_dict()
-    if info and "project_id" in info:
-        return info["project_id"]
-    return os.getenv(_ENV_PROJECT, _DEFAULT_PROJECT)
+    """Return GCP project ID."""
+    return _CREDENTIALS_DICT.get("project_id", 'netra-telemetry-public')