netra-zen 1.2.1__py3-none-any.whl → 1.2.3__py3-none-any.whl

scripts/verify_log_transmission.py

@@ -1,140 +1,140 @@
-#!/usr/bin/env python3
-"""
-Verification script to prove JSONL logs are bundled in payload
-"""
-
-import json
-import sys
-from pathlib import Path
-
-# Add parent directory to path
-sys.path.insert(0, str(Path(__file__).parent.parent))
-
-from scripts.agent_logs import collect_recent_logs
-
-
-def verify_log_bundling(log_path: str):
-    """
-    Verify that logs are properly collected and bundled
-
-    Args:
-        log_path: Path to JSONL file or directory
-    """
-    print("=" * 70)
-    print("JSONL LOG TRANSMISSION VERIFICATION")
-    print("=" * 70)
-    print()
-
-    # Step 1: Collect logs
-    print("Step 1: Collecting logs from file...")
-    result = collect_recent_logs(limit=1, base_path=log_path)
-
-    if not result:
-        print("❌ FAILED: No logs collected")
-        return False
-
-    logs, files_read, file_info = result
-    print(f"✓ Successfully collected {len(logs)} log entries from {files_read} file(s)")
-    print()
-
-    # Step 2: Show file details
-    print("Step 2: File details...")
-    for info in file_info:
-        print(f"  File: {info['name']}")
-        print(f"  Hash: {info['hash']}")
-        print(f"  Entries: {info['entries']}")
-    print()
-
-    # Step 3: Simulate payload creation
-    print("Step 3: Simulating WebSocket payload creation...")
-    payload = {
-        "type": "message_create",
-        "run_id": "test-run-id",
-        "payload": {
-            "message": "Test message with logs",
-            "jsonl_logs": logs  # This is where logs are added
-        }
-    }
-
-    print(f"✓ Payload created with 'jsonl_logs' key")
-    print(f"  Payload keys: {list(payload['payload'].keys())}")
-    print()
-
-    # Step 4: Verify payload size
-    print("Step 4: Calculating payload size...")
-    payload_json = json.dumps(payload)
-    payload_size_bytes = len(payload_json.encode('utf-8'))
-    payload_size_kb = payload_size_bytes / 1024
-    payload_size_mb = payload_size_kb / 1024
-
-    if payload_size_mb >= 1:
-        size_str = f"{payload_size_mb:.2f} MB"
-    elif payload_size_kb >= 1:
-        size_str = f"{payload_size_kb:.2f} KB"
-    else:
-        size_str = f"{payload_size_bytes} bytes"
-
-    print(f"✓ Total payload size: {size_str}")
-    print()
-
-    # Step 5: Show sample log entries
-    print("Step 5: Sample log entries in payload...")
-    if logs:
-        print(f"  First entry keys: {list(logs[0].keys())}")
-        print(f"  First entry timestamp: {logs[0].get('timestamp', 'N/A')}")
-        print(f"  Last entry timestamp: {logs[-1].get('timestamp', 'N/A')}")
-    print()
-
-    # Step 6: Verify transmission-ready
-    print("Step 6: Transmission verification...")
-    print(f"✓ Payload is valid JSON: {payload_json is not None}")
-    print(f"✓ Payload contains 'jsonl_logs': {'jsonl_logs' in payload['payload']}")
-    print(f"✓ Log count in payload: {len(payload['payload']['jsonl_logs'])}")
-    print()
-
-    print("=" * 70)
-    print("✅ VERIFICATION COMPLETE")
-    print("=" * 70)
-    print()
-    print("PROOF OF TRANSMISSION:")
-    print(f"  • {len(logs)} JSONL log entries are bundled in the payload")
-    print(f"  • Payload size: {size_str}")
-    print(f"  • Ready for WebSocket transmission to backend")
-    print()
-
-    # Optional: Save proof file
-    proof_file = Path("/tmp/zen_transmission_proof.json")
-    proof_payload = {
-        "verification_timestamp": "verification_run",
-        "log_count": len(logs),
-        "files_read": files_read,
-        "file_info": file_info,
-        "payload_size": size_str,
-        "sample_first_entry": logs[0] if logs else None,
-        "sample_last_entry": logs[-1] if logs else None,
-        "payload_structure": {
-            "type": payload["type"],
-            "run_id": payload["run_id"],
-            "payload_keys": list(payload["payload"].keys()),
-            "jsonl_logs_present": "jsonl_logs" in payload["payload"],
-            "jsonl_logs_count": len(payload["payload"]["jsonl_logs"])
-        }
-    }
-
-    with open(proof_file, 'w') as f:
-        json.dump(proof_payload, f, indent=2)
-
-    print(f"📝 Detailed proof saved to: {proof_file}")
-    print()
-
-    return True
-
-
-if __name__ == "__main__":
-    if len(sys.argv) < 2:
-        print("Usage: python verify_log_transmission.py <path-to-jsonl-file>")
-        sys.exit(1)
-
-    log_path = sys.argv[1]
-    success = verify_log_bundling(log_path)
-    sys.exit(0 if success else 1)
+#!/usr/bin/env python3
+"""
+Verification script to prove JSONL logs are bundled in payload
+"""
+
+import json
+import sys
+from pathlib import Path
+
+# Add parent directory to path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from scripts.agent_logs import collect_recent_logs
+
+
+def verify_log_bundling(log_path: str):
+    """
+    Verify that logs are properly collected and bundled
+
+    Args:
+        log_path: Path to JSONL file or directory
+    """
+    print("=" * 70)
+    print("JSONL LOG TRANSMISSION VERIFICATION")
+    print("=" * 70)
+    print()
+
+    # Step 1: Collect logs
+    print("Step 1: Collecting logs from file...")
+    result = collect_recent_logs(limit=1, base_path=log_path)
+
+    if not result:
+        print("❌ FAILED: No logs collected")
+        return False
+
+    logs, files_read, file_info = result
+    print(f"✓ Successfully collected {len(logs)} log entries from {files_read} file(s)")
+    print()
+
+    # Step 2: Show file details
+    print("Step 2: File details...")
+    for info in file_info:
+        print(f"  File: {info['name']}")
+        print(f"  Hash: {info['hash']}")
+        print(f"  Entries: {info['entries']}")
+    print()
+
+    # Step 3: Simulate payload creation
+    print("Step 3: Simulating WebSocket payload creation...")
+    payload = {
+        "type": "message_create",
+        "run_id": "test-run-id",
+        "payload": {
+            "message": "Test message with logs",
+            "jsonl_logs": logs  # This is where logs are added
+        }
+    }
+
+    print(f"✓ Payload created with 'jsonl_logs' key")
+    print(f"  Payload keys: {list(payload['payload'].keys())}")
+    print()
+
+    # Step 4: Verify payload size
+    print("Step 4: Calculating payload size...")
+    payload_json = json.dumps(payload)
+    payload_size_bytes = len(payload_json.encode('utf-8'))
+    payload_size_kb = payload_size_bytes / 1024
+    payload_size_mb = payload_size_kb / 1024
+
+    if payload_size_mb >= 1:
+        size_str = f"{payload_size_mb:.2f} MB"
+    elif payload_size_kb >= 1:
+        size_str = f"{payload_size_kb:.2f} KB"
+    else:
+        size_str = f"{payload_size_bytes} bytes"
+
+    print(f"✓ Total payload size: {size_str}")
+    print()
+
+    # Step 5: Show sample log entries
+    print("Step 5: Sample log entries in payload...")
+    if logs:
+        print(f"  First entry keys: {list(logs[0].keys())}")
+        print(f"  First entry timestamp: {logs[0].get('timestamp', 'N/A')}")
+        print(f"  Last entry timestamp: {logs[-1].get('timestamp', 'N/A')}")
+    print()
+
+    # Step 6: Verify transmission-ready
+    print("Step 6: Transmission verification...")
+    print(f"✓ Payload is valid JSON: {payload_json is not None}")
+    print(f"✓ Payload contains 'jsonl_logs': {'jsonl_logs' in payload['payload']}")
+    print(f"✓ Log count in payload: {len(payload['payload']['jsonl_logs'])}")
+    print()
+
+    print("=" * 70)
+    print("✅ VERIFICATION COMPLETE")
+    print("=" * 70)
+    print()
+    print("PROOF OF TRANSMISSION:")
+    print(f"  • {len(logs)} JSONL log entries are bundled in the payload")
+    print(f"  • Payload size: {size_str}")
+    print(f"  • Ready for WebSocket transmission to backend")
+    print()
+
+    # Optional: Save proof file
+    proof_file = Path("/tmp/zen_transmission_proof.json")
+    proof_payload = {
+        "verification_timestamp": "verification_run",
+        "log_count": len(logs),
+        "files_read": files_read,
+        "file_info": file_info,
+        "payload_size": size_str,
+        "sample_first_entry": logs[0] if logs else None,
+        "sample_last_entry": logs[-1] if logs else None,
+        "payload_structure": {
+            "type": payload["type"],
+            "run_id": payload["run_id"],
+            "payload_keys": list(payload["payload"].keys()),
+            "jsonl_logs_present": "jsonl_logs" in payload["payload"],
+            "jsonl_logs_count": len(payload["payload"]["jsonl_logs"])
+        }
+    }
+
+    with open(proof_file, 'w') as f:
+        json.dump(proof_payload, f, indent=2)
+
+    print(f"📝 Detailed proof saved to: {proof_file}")
+    print()
+
+    return True
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("Usage: python verify_log_transmission.py <path-to-jsonl-file>")
+        sys.exit(1)
+
+    log_path = sys.argv[1]
+    success = verify_log_bundling(log_path)
+    sys.exit(0 if success else 1)

shared/README.md

@@ -1,47 +1,47 @@
-# Shared Utilities (Vendored Subset)
-
-This directory contains a **minimal vendored subset** of the Apex `shared/` package, containing only the files required by `zen --apex` CLI functionality.
-
-## Included Files
-
-### 1. `__init__.py`
-Package initialization stub with basic documentation.
-
-### 2. `windows_encoding.py`
-Windows UTF-8 console encoding fixes. The `setup_windows_encoding()` function is called early in `agent_cli.py` startup to ensure proper Unicode handling on Windows platforms.
-
-### 3. `types/__init__.py`
-Type definitions package that re-exports WebSocket closure code utilities.
-
-### 4. `types/websocket_closure_codes.py`
-WebSocket closure code validation utilities:
-- `WebSocketClosureCode`: Enum of standard RFC 6455 closure codes
-- `WebSocketClosureCategory`: Categories for classifying closure types
-- `categorize_closure_code()`: Categorize a code into normal/client/server/infrastructure
-- `get_closure_description()`: Human-readable description of closure codes
-- `is_infrastructure_error()`: Check if a code represents infrastructure failure
-
-## Maintenance
-
-⚠️ **Important**: These files are vendored from the Apex repository. If Apex updates its closure-code definitions or Windows encoding logic, these files must be manually synchronized.
-
-### What's NOT Included
-
-Everything else under Apex's `shared/` directory is intentionally excluded because it's not referenced by `agent_cli.py`. This keeps the vendored code minimal and avoids pulling in backend logic, secrets, or unnecessary dependencies.
-
-## Usage
-
-These modules are imported by `scripts/agent_cli.py`:
-
-```python
-from shared.windows_encoding import setup_windows_encoding
-from shared.types.websocket_closure_codes import (
-    WebSocketClosureCode,
-    WebSocketClosureCategory,
-    categorize_closure_code,
-    get_closure_description,
-    is_infrastructure_error
-)
-```
-
-The `setup_windows_encoding()` function is called immediately at startup, before any console I/O operations.
+# Shared Utilities (Vendored Subset)
+
+This directory contains a **minimal vendored subset** of the Apex `shared/` package, containing only the files required by `zen --apex` CLI functionality.
+
+## Included Files
+
+### 1. `__init__.py`
+Package initialization stub with basic documentation.
+
+### 2. `windows_encoding.py`
+Windows UTF-8 console encoding fixes. The `setup_windows_encoding()` function is called early in `agent_cli.py` startup to ensure proper Unicode handling on Windows platforms.
+
+### 3. `types/__init__.py`
+Type definitions package that re-exports WebSocket closure code utilities.
+
+### 4. `types/websocket_closure_codes.py`
+WebSocket closure code validation utilities:
+- `WebSocketClosureCode`: Enum of standard RFC 6455 closure codes
+- `WebSocketClosureCategory`: Categories for classifying closure types
+- `categorize_closure_code()`: Categorize a code into normal/client/server/infrastructure
+- `get_closure_description()`: Human-readable description of closure codes
+- `is_infrastructure_error()`: Check if a code represents infrastructure failure
+
+## Maintenance
+
+⚠️ **Important**: These files are vendored from the Apex repository. If Apex updates its closure-code definitions or Windows encoding logic, these files must be manually synchronized.
+
+### What's NOT Included
+
+Everything else under Apex's `shared/` directory is intentionally excluded because it's not referenced by `agent_cli.py`. This keeps the vendored code minimal and avoids pulling in backend logic, secrets, or unnecessary dependencies.
+
+## Usage
+
+These modules are imported by `scripts/agent_cli.py`:
+
+```python
+from shared.windows_encoding import setup_windows_encoding
+from shared.types.websocket_closure_codes import (
+    WebSocketClosureCode,
+    WebSocketClosureCategory,
+    categorize_closure_code,
+    get_closure_description,
+    is_infrastructure_error
+)
+```
+
+The `setup_windows_encoding()` function is called immediately at startup, before any console I/O operations.

shared/TIMING_FIX_COMPLETE.md

@@ -1,80 +1,80 @@
-# WebSocket Timing Fix - Complete Implementation
-
-## Problem Statement
-The CLI was sending messages too early, before the server completed its lifecycle phases and entered the message processing loop (Phase 5). Messages sent before Phase 5 were lost because the server's message handler wasn't active yet.
-
-## Root Cause
-The CLI code had backward compatibility logic that allowed connections to proceed even when the handshake failed, causing messages to be sent before the server was ready.
-
-## Complete Fix Implementation
-
-### 1. Connection Method (lines 2879-2928)
-**REMOVED:** Backward compatibility code that returned `True` even when handshake failed
-**ADDED:**
-- Proper failure when handshake doesn't complete
-- Retry mechanism with 3-second delay
-- Second handshake attempt after delay
-- WebSocket closure on failure
-
-### 2. Handshake Response Processing (lines 3307-3363)
-**CHANGED:** Message type from `session_acknowledged` to `handshake_acknowledged`
-**ADDED:**
-- Wait for `handshake_complete` confirmation
-- 500ms delay after handshake_complete for server to enter Phase 5
-- Fallback delay if no handshake_complete received
-
-### 3. Message Sending Validation (lines 3703-3722)
-**ADDED:** Check for `self.connected` flag before sending messages
-- Ensures handshake is fully complete
-- Prevents messages being sent during server initialization
-- Clear error messages when connection not ready
-
-## Order of Operations (Enforced)
-
-1. **Connect** → WebSocket connection established
-2. **Wait** for `connection_established` event
-3. **Handshake** → Wait for `handshake_response`
-4. **Acknowledge** → Send `handshake_acknowledged` with thread_id
-5. **Confirm** → Wait for `handshake_complete` message
-6. **Delay** → Add 500ms for server to enter Phase 5 (Processing)
-7. **Ready** → NOW messages can be safely sent
-
-## Server Phases Reference
-
-```
-Phase 1: INITIALIZING   → Accept connection, assign ID
-Phase 2: AUTHENTICATING → Validate user credentials
-Phase 3: HANDSHAKING    → Exchange thread IDs
-Phase 4: READY          → Initialize services, register with router
-Phase 5: PROCESSING     → Message loop active ✓ (Messages accepted here!)
-Phase 6: CLEANING_UP    → Coordinated cleanup
-Phase 7: CLOSED         → Terminal state
-```
-
-## Key Benefits
-
-✓ **No Message Loss** - Messages only sent when server is ready to process them
-✓ **Proper Sequencing** - Enforces documented WebSocket lifecycle
-✓ **Retry Logic** - Handles transient delays during server startup
-✓ **Clear Errors** - Descriptive messages when connection fails
-✓ **Fail Fast** - Connection fails quickly if server isn't ready
-
-## Testing Verification
-
-The fix ensures:
-- `self.connected` is only set to `True` after full handshake completion
-- `send_message()` validates both `self.connected` and `self.current_thread_id`
-- Messages cannot be sent until server reaches Phase 5 (Processing)
-- Connection properly fails if server doesn't complete handshake
-
-## Files Modified
-
-- `scripts/agent_cli.py`:
-  - `connect()` method - lines 2879-2928
-  - `_perform_handshake()` method - lines 3057-3058
-  - `_process_handshake_response()` method - lines 3307-3363
-  - `send_message()` method - lines 3703-3722
-
-## Implementation Complete
-
+# WebSocket Timing Fix - Complete Implementation
+
+## Problem Statement
+The CLI was sending messages too early, before the server completed its lifecycle phases and entered the message processing loop (Phase 5). Messages sent before Phase 5 were lost because the server's message handler wasn't active yet.
+
+## Root Cause
+The CLI code had backward compatibility logic that allowed connections to proceed even when the handshake failed, causing messages to be sent before the server was ready.
+
+## Complete Fix Implementation
+
+### 1. Connection Method (lines 2879-2928)
+**REMOVED:** Backward compatibility code that returned `True` even when handshake failed
+**ADDED:**
+- Proper failure when handshake doesn't complete
+- Retry mechanism with 3-second delay
+- Second handshake attempt after delay
+- WebSocket closure on failure
+
+### 2. Handshake Response Processing (lines 3307-3363)
+**CHANGED:** Message type from `session_acknowledged` to `handshake_acknowledged`
+**ADDED:**
+- Wait for `handshake_complete` confirmation
+- 500ms delay after handshake_complete for server to enter Phase 5
+- Fallback delay if no handshake_complete received
+
+### 3. Message Sending Validation (lines 3703-3722)
+**ADDED:** Check for `self.connected` flag before sending messages
+- Ensures handshake is fully complete
+- Prevents messages being sent during server initialization
+- Clear error messages when connection not ready
+
+## Order of Operations (Enforced)
+
+1. **Connect** → WebSocket connection established
+2. **Wait** for `connection_established` event
+3. **Handshake** → Wait for `handshake_response`
+4. **Acknowledge** → Send `handshake_acknowledged` with thread_id
+5. **Confirm** → Wait for `handshake_complete` message
+6. **Delay** → Add 500ms for server to enter Phase 5 (Processing)
+7. **Ready** → NOW messages can be safely sent
+
+## Server Phases Reference
+
+```
+Phase 1: INITIALIZING   → Accept connection, assign ID
+Phase 2: AUTHENTICATING → Validate user credentials
+Phase 3: HANDSHAKING    → Exchange thread IDs
+Phase 4: READY          → Initialize services, register with router
+Phase 5: PROCESSING     → Message loop active ✓ (Messages accepted here!)
+Phase 6: CLEANING_UP    → Coordinated cleanup
+Phase 7: CLOSED         → Terminal state
+```
+
+## Key Benefits
+
+✓ **No Message Loss** - Messages only sent when server is ready to process them
+✓ **Proper Sequencing** - Enforces documented WebSocket lifecycle
+✓ **Retry Logic** - Handles transient delays during server startup
+✓ **Clear Errors** - Descriptive messages when connection fails
+✓ **Fail Fast** - Connection fails quickly if server isn't ready
+
+## Testing Verification
+
+The fix ensures:
+- `self.connected` is only set to `True` after full handshake completion
+- `send_message()` validates both `self.connected` and `self.current_thread_id`
+- Messages cannot be sent until server reaches Phase 5 (Processing)
+- Connection properly fails if server doesn't complete handshake
+
+## Files Modified
+
+- `scripts/agent_cli.py`:
+  - `connect()` method - lines 2879-2928
+  - `_perform_handshake()` method - lines 3057-3058
+  - `_process_handshake_response()` method - lines 3307-3363
+  - `send_message()` method - lines 3703-3722
+
+## Implementation Complete
+
 The timing issue is now fully resolved. The CLI will properly wait for the server to complete all initialization phases before sending any messages, preventing message loss and ensuring reliable communication.

shared/__init__.py

@@ -1,12 +1,12 @@
-"""
-Shared utilities package (minimal vendored subset for zen --apex CLI).
-
-This package contains only the minimal files required by agent_cli.py:
-- windows_encoding.py: Windows UTF-8 console fixes
-- types/websocket_closure_codes.py: WebSocket closure code validation
-
-TODO: Manually sync these files if Apex updates its closure-code definitions
-or Windows handling logic.
-"""
-
-__version__ = "1.0.0"
+"""
+Shared utilities package (minimal vendored subset for zen --apex CLI).
+
+This package contains only the minimal files required by agent_cli.py:
+- windows_encoding.py: Windows UTF-8 console fixes
+- types/websocket_closure_codes.py: WebSocket closure code validation
+
+TODO: Manually sync these files if Apex updates its closure-code definitions
+or Windows handling logic.
+"""
+
+__version__ = "1.0.0"

shared/types/__init__.py

@@ -1,21 +1,21 @@
-"""
-Shared type definitions (minimal vendored subset for zen --apex CLI).
-
-This package provides WebSocket closure code utilities required by agent_cli.py.
-"""
-
-from shared.types.websocket_closure_codes import (
-    WebSocketClosureCode,
-    WebSocketClosureCategory,
-    categorize_closure_code,
-    get_closure_description,
-    is_infrastructure_error
-)
-
-__all__ = [
-    'WebSocketClosureCode',
-    'WebSocketClosureCategory',
-    'categorize_closure_code',
-    'get_closure_description',
-    'is_infrastructure_error'
-]
+"""
+Shared type definitions (minimal vendored subset for zen --apex CLI).
+
+This package provides WebSocket closure code utilities required by agent_cli.py.
+"""
+
+from shared.types.websocket_closure_codes import (
+    WebSocketClosureCode,
+    WebSocketClosureCategory,
+    categorize_closure_code,
+    get_closure_description,
+    is_infrastructure_error
+)
+
+__all__ = [
+    'WebSocketClosureCode',
+    'WebSocketClosureCategory',
+    'categorize_closure_code',
+    'get_closure_description',
+    'is_infrastructure_error'
+]