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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: netra-zen
-Version: 1.0.7
+Version: 1.0.8
 Summary: Multi-instance Claude orchestrator for parallel task execution
 Home-page: https://github.com/netra-systems/zen
 Author:  Systems
@@ -30,6 +30,11 @@ Description-Content-Type: text/markdown
 License-File: LICENSE.md
 Requires-Dist: PyYAML>=6.0
 Requires-Dist: python-dateutil>=2.8.2
+Requires-Dist: aiohttp>=3.8.0
+Requires-Dist: websockets>=11.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: PyJWT>=2.8.0
+Requires-Dist: psutil>=5.9.0
 Requires-Dist: opentelemetry-sdk>=1.20.0
 Requires-Dist: opentelemetry-exporter-gcp-trace>=1.6.0
 Requires-Dist: google-cloud-trace>=1.11.0
@@ -55,17 +60,42 @@ It works by analyzing your usage logs for metadata optimizations. It is focused
 
 This is a micro startup effort, aiming to provide real value for individual devs in exchange for feedback. Our intent is to charge businesses for larger scale optimizations.
 
-The process is simple. One time install, then one command. It auto grabs the last 5 logs and provides actionable items to update going forward to get the value of the optimizations.
+The process is simple. One time install, then one command. It auto grabs the last 3 log files and provides actionable items to update going forward to get the value of the optimizations.
 
 ## Quick start
 
 1. `pip install netra-zen`
-2. `zen --apex --send-logs --message "claude code"`
+2. `zen --apex --send-logs`
 3. Read the results and update claude settings, prompts, commands, etc. as needed to benefit
 
-By default it will optimize based on logs no thought on the message is needed. Just copy and paste #2!
 See detailed install below if needed.
 
+### Log Collection Options
+
+The optimizer analyzes your Claude Code usage logs to identify optimization opportunities. You can customize what logs are sent:
+
+```bash
+# Send logs from the 3 most recent files (default)
+zen --apex --send-logs
+
+# Send logs from more files for deeper analysis
+zen --apex --send-logs --logs-count 5
+
+# Send logs from a specific project
+zen --apex --send-logs --logs-project "my-project-name"
+
+# Send logs from a custom location
+zen --apex --send-logs --logs-path "/path/to/.claude/Projects"
+
+# Combine options for targeted analysis
+zen --apex --send-logs --logs-count 3 --logs-project "production-app"
+```
+
+**Important:**
+- `--logs-count` specifies the number of **files** to read, not entries
+- Each file may contain many log entries
+- The tool will display exactly how many entries from how many files are being sent
+
 ## Example output
 ![example](https://github.com/user-attachments/assets/94ed0180-9fed-4d76-ab69-657b7d3ab1b2)
 
@@ -75,12 +105,147 @@ See detailed install below if needed.
 This was just changing a few small lines on a 400 line command.
 ![savings](https://github.com/user-attachments/assets/9298e7cc-4f15-4dc0-97e3-1f126757dde6)
 
+## Notes
+- Have an optimization idea or area you want it to focus on? Create a git issue and we can add that to our evals.
+
+## Example output from single file
+```
+zen --apex --send-logs --logs-path /Users/user/.claude/projects/-Users-Desktop-netra-apex/7ac6d7ac-abc3-4903-a482-......-1.jsonl
+
+SUCCESS: WebSocket connected successfully!
+
+============================================================
+📤 SENDING LOGS TO OPTIMIZER
+============================================================
+  Total Entries: 781
+  Files Read: 1
+  Payload Size: 5.52 MB
+
+  Files:
+    • 7ac6d7ac-abc3-4903-a482-.....jsonl (hash: 908dbc51, 781 entries)
+
+  Payload Confirmation:
+    ✓ 'jsonl_logs' key added to payload
+    ✓ First log entry timestamp: 2025-10-03T18:26:02.089Z
+    ✓ Last log entry timestamp: 2025-10-03T19:31:21.876Z
+============================================================
+
+[11:32:55.190] [DEBUG] GOLDEN PATH TRACE: Prepared WebSocket payload for run_id=cli_20251008_113255_25048, 
+thread_id=cli_thread_f887c58e7759
+[11:32:55.191] [DEBUG] ✓ TRANSMISSION PROOF: Payload contains 781 JSONL log entries in 'jsonl_logs' key
+SUCCESS: Message sent with run_id: cli_20251008_113255_25048
+⏳ Waiting 120 seconds for events...
+Receiving events...
+[11:32:55.284] [DEBUG] Listening for WebSocket events...
+[11:32:55.284] [DEBUG] GOLDEN PATH TRACE: Event listener started after successful connection
+[11:32:56.655] [DEBUG] WebSocket Event #1: raw_message_received
+[11:32:56.657] [DEBUG] GOLDEN PATH TRACE: Parsed WebSocket event type=connection_established
+[11:32:56.658] [DEBUG] WebSocket Event #2: connection_established
+[11:32:56] [CONN] Connected as: e2e-staging-2d677771
+[11:33:01.364] [DEBUG] WebSocket Event #3: raw_message_received
+[11:33:01.366] [DEBUG] GOLDEN PATH TRACE: Parsed WebSocket event type=thread_created
+[11:33:01.367] [DEBUG] WebSocket Event #4: thread_created
+[11:33:01] [EVENT] thread_created: {"type": "thread_created", "payload": {"thread_id": 
+"thread_session_969_44184cce", "timestamp": 1759...
+[11:33:02.901] [DEBUG] WebSocket Event #5: raw_message_received
+[11:33:02.903] [DEBUG] GOLDEN PATH TRACE: Parsed WebSocket event type=agent_started
+[11:33:02.904] [DEBUG] WebSocket Event #6: agent_started
+[11:33:02]     🧠 Agent: netra-assistant started (run: run_sess...)
+[11:33:04.744] [DEBUG] WebSocket Event #7: raw_message_received
+[11:33:04.746] [DEBUG] GOLDEN PATH TRACE: Parsed WebSocket event type=agent_started
+[11:33:04.747] [DEBUG] WebSocket Event #8: agent_started
+[11:33:04]     🧠 Agent: netra-assistant started (run: run_sess...)
+[11:33:06.366] [DEBUG] WebSocket Event #9: raw_message_received
+[11:33:06.368] [DEBUG] GOLDEN PATH TRACE: Parsed WebSocket event type=agent_started
+[11:33:06.369] [DEBUG] WebSocket Event #10: agent_started
+[11:33:06]     🧠 Agent: MessageHandler started (run: run_sess...)
+[11:33:14.781] [DEBUG] WebSocket Event #11: raw_message_received
+[11:33:14.783] [DEBUG] GOLDEN PATH TRACE: Parsed WebSocket event type=agent_started
+[11:33:14.784] [DEBUG] WebSocket Event #12: agent_started
+[11:33:14]     🧠 Agent: claude_code_optimizer started (run: run_sess...)
+[11:33:23.241] [DEBUG] WebSocket Event #13: raw_message_received
+[11:33:23.243] [DEBUG] GOLDEN PATH TRACE: Parsed WebSocket event type=agent_thinking
+[11:33:23.244] [DEBUG] WebSocket Event #14: agent_thinking
+[11:33:23]     💭 Thinking: Preparing optimization prompt
+⠹ 💭 Preparing optimization prompt[11:34:27.586] [DEBUG] WebSocket Event #15: raw_message_received
+[11:34:27.588] [DEBUG] GOLDEN PATH TRACE: Parsed WebSocket event type=agent_completed
+[11:34:27.589] [DEBUG] WebSocket Event #16: agent_completed
+⠹ 💭 Preparing optimization prompt
+[11:34:27]     🧠 Agent Completed: claude_code_optimizer (run: run_sess...) - {"status": "done", "result": 
+{"optimizations": [{"issue": "Repeated Full File Read", "evidence": "Th...
+╭────────────────────────────────── Final Agent Result - Optimization Pointers ──────────────────────────────────╮
+│ {                                                                                                              │
+│   "status": "done",                                                                                            │
+│   "result": {                                                                                                  │
+│     "optimizations": [                                                                                         │
+│       {                                                                                                        │
+│         "issue": "Repeated Full File Read",                                                                    │
+│         "evidence": "The file `api/src/routes/user.js` was read in its entirety using `cat` twice. The model   │
+│ read it once to understand the code, but then read the entire file again later to re-confirm a detail it had   │
+│ forgotten.",                                                                                                   │
+│         "token_waste": "High (~2.5k tokens). The entire content of the 250-line file was added to the context  │
+│ a second time, providing no new information.",                                                                 │
+│         "fix": "The model should retain the context of files it has already read within the same task. If it   │
+│ needs to re-check a specific detail, it should use a targeted tool like `grep` or `read_lines` (e.g., `grep -C │
+│ 5 'findUser' api/src/routes/user.js`) instead of re-reading the entire file.",                                 │
+│         "ideal prompt": "The user profile page isn't loading the user's name. The API endpoint is in           │
+│ `api/src/routes/user.js` and it calls the `findUser` function from `api/src/db/utils.js`. Please investigate   │
+│ the data flow between these two files and fix the issue.",                                                     │
+│         "priority": "high"                                                                                     │
+│       },                                                                                                       │
+│       {                                                                                                        │
+│         "issue": "Excessive Context Gathering",                                                                │
+│         "evidence": "The `cat` command was used on two large files (`user.js` and `utils.js`), ingesting a     │
+│ total of 400 lines of code into the context. The actual bug was confined to a small 5-line function within     │
+│ `utils.js`.",                                                                                                  │
+│         "token_waste": "High (~4k tokens). Most of the file content was irrelevant to the specific task of     │
+│ fixing the `findUser` function's return value.",                                                               │
+│         "fix": "Instead of `cat`, the model should use more precise tools to gather context. After identifying │
+│ the relevant function with `grep`, it could have used a command like `read_lines('api/src/db/utils.js',        │
+│ start_line, end_line)` or `grep -A 10 'const findUser' api/src/db/utils.js` to read only the function's        │
+│ definition and its immediate surroundings.",                                                                   │
+│         "ideal prompt": "The `findUser` function in `api/src/db/utils.js` is not returning the user's name     │
+│ field. Please add it to the return object.",                                                                   │
+│         "priority": "high"                                                                                     │
+│       },                                                                                                       │
+│       {                                                                                                        │
+│         "issue": "Inefficient Project-Wide Search",                                                            │
+│         "evidence": "A recursive grep (`grep -r \"findUser\" .`) was used to find the definition of            │
+│ `findUser`. While effective, this can be slow and return a lot of irrelevant matches (like comments, logs,     │
+│ etc.) in a large codebase, consuming tokens in the tool output.",                                              │
+│         "token_waste": "Medium (~500 tokens). The `grep` returned multiple matches, including the call site    │
+│ which was already known. In a larger project, this could return dozens of matches.",                           │
+│         "fix": "If the project structure is conventional, a more targeted search would be better. For example, │
+│ knowing `db` utilities are likely in a `db` or `utils` directory, a command like `grep 'findUser'              │
+│ api/src/db/*.js` would be more direct and produce less noise.",                                                │
+│         "ideal prompt": "The `findUser` function, defined in the `api/src/db/` directory, seems to be causing  │
+│ a bug. Can you find its definition and check what it returns?",                                                │
+│         "priority": "low"                                                                                      │
+│       }                                                                                                        │
+│     ],                                                                                                         │
+│     "summary": {                                                                                               │
+│       "total_issues": 3,                                                                                       │
+│       "estimated_savings": "~7k tokens",                                                                       │
+│       "top_priority": "Avoid repeated full file reads. The model should trust its context or use targeted      │
+│ tools like `grep` to refresh specific details instead of re-ingesting entire files."                           │
+│     }                                                                                                          │
+│   },                                                                                                           │
+│   "message": "Claude Code optimization analysis complete"                                                      │
+│ }                                                                                                              │
+╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+
+📊 Received 8 events
+```
+
+# Advanced features & detailed install guide
+
+In addition to optimizing your costs and latency,
+you can control budgets and other advanced features.
 
-# Other features & detailed install guide
 ### Orchestrator
 
-Zen allows you to:
-- Zen Orchestrator runs multiple Code CLI instances for peaceful parallel task execution.
+Orchestrator allows you to:
+- Orchestrator runs multiple Code CLI instances for peaceful parallel task execution.
 - Run multiple headless Claude Code CLI instances simultaneously.
 - Calm unified results (status, time, token usage)
 - Relax **"5-hour limit reached"** lockout fears with easy token budget limits

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

@@ -1,14 +1,15 @@
 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.7.dist-info/licenses/LICENSE.md,sha256=t6LtOzAE2hgIIv5WbaN0wOcU3QCnGtAkMGNclHrKTOs,79
+netra_zen-1.0.8.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=22Ocv-A-HLwj63H0_LBryRcAYWYck5vsGdr_Gqpq2GE,287459
-scripts/agent_logs.py,sha256=_63DXULccmsw9Js4UOsBSr9JwNzlCYUb1ea1TEymjFo,7483
+scripts/agent_cli.py,sha256=c9qmAx1Fk2XNidveD2zhpF7ndj5hwgVwUcAEGY5kjJM,295129
+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
 scripts/embed_release_credentials.py,sha256=lqlvByGZ2L8Fl4Hd1pHxcd1dmEXbHU1PwZHLQP7Syso,2028
+scripts/verify_log_transmission.py,sha256=0Pyv6_9Sk24iR2QhKMMReJGc9v54ygziaCnvSkPdIUc,4353
 token_budget/__init__.py,sha256=_2tmi72DGNtbYcZ-rGIxVKMytdkHFjzJaWz8bDhYACc,33
 token_budget/budget_manager.py,sha256=VRWxKcGDtgJfIRh-ztYQ4-wuhBvddVJJnyoGfxCBlv0,9567
 token_budget/models.py,sha256=14xFTk2-R1Ql0F9WLDof7vADrKC_5Fj7EE7UmZdoG00,2384
@@ -20,8 +21,8 @@ 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/manager.py,sha256=TtrIPOvRvq1OOhNAO_Tp-dz7EiS2xXfqnpKQduLwYoI,9731
-netra_zen-1.0.7.dist-info/METADATA,sha256=Z3pk9x6-GtUcLw4InGmO-rsqkL09WbyavpwuFh8FuGc,30997
-netra_zen-1.0.7.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-netra_zen-1.0.7.dist-info/entry_points.txt,sha256=oDehCnPGZezG0m9ZWspxjHLHyQ3eERX87eojR4ljaRo,45
-netra_zen-1.0.7.dist-info/top_level.txt,sha256=OhiyXmoXftBijCF6ck-RS1dN2NBJv9wdd7kBG1Es7zA,77
-netra_zen-1.0.7.dist-info/RECORD,,
+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,,

scripts/agent_cli.py

@@ -159,12 +159,10 @@ class SimpleConfigReader:
 try:
     from agent_output_validator import AgentOutputValidator, ValidationReport, ValidationResult
 except ImportError:
-    # Try relative import from scripts directory
-    import sys
-    import os
-    script_dir = os.path.dirname(os.path.abspath(__file__))
-    sys.path.insert(0, script_dir)
-    from agent_output_validator import AgentOutputValidator, ValidationReport, ValidationResult
+    # Module not available - create stub classes
+    AgentOutputValidator = None
+    ValidationReport = None
+    ValidationResult = None
 
 # Import WebSocket event validation framework for Issue #2177
 try:
@@ -172,14 +170,10 @@ try:
         WebSocketEventValidationFramework, EventValidationReport, ValidationResult as EventValidationResult
     )
 except ImportError:
-    # Try relative import from scripts directory
-    import sys
-    import os
-    script_dir = os.path.dirname(os.path.abspath(__file__))
-    sys.path.insert(0, script_dir)
-    from websocket_event_validation_framework import (
-        WebSocketEventValidationFramework, EventValidationReport, ValidationResult as EventValidationResult
-    )
+    # Module not available - create stub classes
+    WebSocketEventValidationFramework = None
+    EventValidationReport = None
+    EventValidationResult = None
 
 # Import business value validator for revenue protection
 # ISSUE #2414: Delay imports that trigger configuration validation
@@ -2998,18 +2992,79 @@ class WebSocketClient:
             try:
                 from scripts.agent_logs import collect_recent_logs
 
-                logs = collect_recent_logs(
+                result = collect_recent_logs(
                     limit=self.logs_count,
                     project_name=self.logs_project,
                     base_path=self.logs_path,
                     username=self.logs_user
                 )
 
-                if logs:
+                if result:
+                    logs, files_read, file_info = result
                     payload["payload"]["jsonl_logs"] = logs
+
+                    # Calculate payload size for transmission proof
+                    import logging
+                    import sys
+
+                    # Get size of logs in payload
+                    logs_json = json.dumps(logs)
+                    logs_size_bytes = len(logs_json.encode('utf-8'))
+                    logs_size_kb = logs_size_bytes / 1024
+                    logs_size_mb = logs_size_kb / 1024
+
+                    # Format size appropriately
+                    if logs_size_mb >= 1:
+                        size_str = f"{logs_size_mb:.2f} MB"
+                    elif logs_size_kb >= 1:
+                        size_str = f"{logs_size_kb:.2f} KB"
+                    else:
+                        size_str = f"{logs_size_bytes} bytes"
+
+                    # Create prominent, formatted log message
+                    separator = "=" * 60
+                    log_msg_parts = [
+                        "",
+                        separator,
+                        f"📤 SENDING LOGS TO OPTIMIZER",
+                        separator,
+                        f"  Total Entries: {len(logs)}",
+                        f"  Files Read: {files_read}",
+                        f"  Payload Size: {size_str}",
+                    ]
+
+                    if self.logs_project:
+                        log_msg_parts.append(f"  Project: {self.logs_project}")
+
+                    log_msg_parts.append("")
+                    log_msg_parts.append("  Files:")
+
+                    # Add file details with hashes
+                    for info in file_info:
+                        log_msg_parts.append(
+                            f"    • {info['name']} (hash: {info['hash']}, {info['entries']} entries)"
+                        )
+
+                    # Add payload proof
+                    log_msg_parts.append("")
+                    log_msg_parts.append("  Payload Confirmation:")
+                    log_msg_parts.append(f"    ✓ 'jsonl_logs' key added to payload")
+                    log_msg_parts.append(f"    ✓ First log entry timestamp: {logs[0].get('timestamp', 'N/A') if logs else 'N/A'}")
+                    log_msg_parts.append(f"    ✓ Last log entry timestamp: {logs[-1].get('timestamp', 'N/A') if logs else 'N/A'}")
+
+                    log_msg_parts.append(separator)
+                    log_msg_parts.append("")
+
+                    log_msg = "\n".join(log_msg_parts)
+
+                    # Log at INFO level
+                    logging.info(log_msg)
+
+                    # Also print via debug system for consistency
                     self.debug.debug_print(
-                        f"Attached {len(logs)} log entries to message payload",
-                        DebugLevel.BASIC
+                        log_msg,
+                        DebugLevel.BASIC,
+                        style="cyan"
                     )
                 else:
                     self.debug.debug_print(
@@ -3031,6 +3086,51 @@ class WebSocketClient:
             style="yellow"
         )
 
+        # Proof of logs in transmission
+        if "jsonl_logs" in payload["payload"]:
+            log_count = len(payload["payload"]["jsonl_logs"])
+            self.debug.debug_print(
+                f"✓ TRANSMISSION PROOF: Payload contains {log_count} JSONL log entries in 'jsonl_logs' key",
+                DebugLevel.BASIC,
+                style="green"
+            )
+
+            # Optional: Save payload proof to file for verification
+            if os.environ.get('ZEN_SAVE_PAYLOAD_PROOF'):
+                try:
+                    import tempfile
+                    proof_file = tempfile.NamedTemporaryFile(
+                        mode='w',
+                        prefix='zen_payload_proof_',
+                        suffix='.json',
+                        delete=False
+                    )
+
+                    # Save payload structure (with truncated logs for readability)
+                    proof_payload = {
+                        "run_id": payload.get("run_id"),
+                        "payload": {
+                            "message": payload["payload"].get("message"),
+                            "jsonl_logs": {
+                                "count": len(payload["payload"]["jsonl_logs"]),
+                                "sample_first": payload["payload"]["jsonl_logs"][0] if payload["payload"]["jsonl_logs"] else None,
+                                "sample_last": payload["payload"]["jsonl_logs"][-1] if payload["payload"]["jsonl_logs"] else None,
+                            }
+                        }
+                    }
+
+                    json.dump(proof_payload, proof_file, indent=2)
+                    proof_file.close()
+
+                    self.debug.debug_print(
+                        f"📝 Payload proof saved to: {proof_file.name}",
+                        DebugLevel.BASIC,
+                        style="cyan"
+                    )
+                except Exception as e:
+                    # Don't fail transmission if proof saving fails
+                    pass
+
         # ISSUE #1603 FIX: Add critical logging for message sending (only in diagnostic mode)
         if self.debug.debug_level >= DebugLevel.DIAGNOSTIC:
             self.debug.debug_print(f"SENDING WEBSOCKET MESSAGE: {json.dumps(payload, indent=2)}", DebugLevel.DIAGNOSTIC)
@@ -3762,7 +3862,7 @@ class AgentCLI:
         # Issue #1822: Agent output validation
         self.validate_outputs = validate_outputs
         self.output_validator: Optional[AgentOutputValidator] = None
-        if self.validate_outputs:
+        if self.validate_outputs and AgentOutputValidator is not None:
             self.output_validator = AgentOutputValidator(debug=config.debug_level.value >= 3)
 
         # Business value validation
@@ -3918,11 +4018,37 @@ class AgentCLI:
 
     async def _receive_events(self):
         """Background task to receive and display events"""
+        thinking_spinner = None
+        thinking_live = None
+
         async def handle_event(event: WebSocketEvent):
+            nonlocal thinking_spinner, thinking_live
+
+            # Stop spinner if it's running and we get any non-thinking event
+            if thinking_live and event.type != "agent_thinking":
+                thinking_live.stop()
+                thinking_live = None
+                thinking_spinner = None
+
             # Display event with enhanced formatting
             formatted_event = event.format_for_display(self.debug)
             safe_console_print(f"[{event.timestamp.strftime('%H:%M:%S')}] {formatted_event}")
 
+            # Start spinner for agent_thinking events (20-60 second wait indicator)
+            if event.type == "agent_thinking" and not thinking_live:
+                thought = event.data.get('thought', event.data.get('reasoning', ''))
+                spinner_text = truncate_with_ellipsis(thought, 60) if thought else "Processing..."
+
+                thinking_spinner = Progress(
+                    SpinnerColumn(spinner_name="dots"),
+                    TextColumn("[cyan]{task.description}"),
+                    console=Console(file=sys.stderr),
+                    transient=True
+                )
+                thinking_live = Live(thinking_spinner, console=Console(file=sys.stderr), refresh_per_second=10)
+                thinking_live.start()
+                thinking_spinner.add_task(f"💭 {spinner_text}", total=None)
+
             # Display raw data in verbose mode
             if self.debug.debug_level >= DebugLevel.DIAGNOSTIC:
                 safe_console_print(Panel(
@@ -3931,16 +4057,47 @@ class AgentCLI:
                     border_style="dim"
                 ))
 
-        await self.ws_client.receive_events(callback=handle_event)
+        try:
+            await self.ws_client.receive_events(callback=handle_event)
+        finally:
+            # Clean up spinner if it's still running
+            if thinking_live:
+                thinking_live.stop()
 
     async def _receive_events_with_display(self):
         """ISSUE #1603 FIX: Enhanced event receiver with better display for single message mode"""
+        thinking_spinner = None
+        thinking_live = None
+
         async def handle_event_with_display(event: WebSocketEvent):
+            nonlocal thinking_spinner, thinking_live
+
+            # Stop spinner if it's running and we get any non-thinking event
+            if thinking_live and event.type != "agent_thinking":
+                thinking_live.stop()
+                thinking_live = None
+                thinking_spinner = None
+
             # Display event with enhanced formatting and emojis
             formatted_event = event.format_for_display(self.debug)
             timestamp = event.timestamp.strftime('%H:%M:%S')
             safe_console_print(f"[{timestamp}] {formatted_event}")
 
+            # Start spinner for agent_thinking events (20-60 second wait indicator)
+            if event.type == "agent_thinking" and not thinking_live:
+                thought = event.data.get('thought', event.data.get('reasoning', ''))
+                spinner_text = truncate_with_ellipsis(thought, 60) if thought else "Processing..."
+
+                thinking_spinner = Progress(
+                    SpinnerColumn(spinner_name="dots"),
+                    TextColumn("[cyan]{task.description}"),
+                    console=Console(file=sys.stderr),
+                    transient=True
+                )
+                thinking_live = Live(thinking_spinner, console=Console(file=sys.stderr), refresh_per_second=10)
+                thinking_live.start()
+                thinking_spinner.add_task(f"💭 {spinner_text}", total=None)
+
             # Issue #2177: WebSocket event validation
             if self.validate_events and self.event_validator:
                 try:
@@ -4016,7 +4173,12 @@ class AgentCLI:
                     border_style="dim"
                 ))
 
-        await self.ws_client.receive_events(callback=handle_event_with_display)
+        try:
+            await self.ws_client.receive_events(callback=handle_event_with_display)
+        finally:
+            # Clean up spinner if it's still running
+            if thinking_live:
+                thinking_live.stop()
 
     def _get_event_summary(self, event: WebSocketEvent) -> str:
         """ISSUE #1603 FIX: Get a concise summary of an event for display"""
@@ -5497,9 +5659,9 @@ def main(argv=None):
     parser.add_argument(
         "--logs-count",
         type=int,
-        default=5,
+        default=3,
         metavar="N",
-        help="Number of recent log files to collect (default: 5, must be positive)"
+        help="Number of recent log files to collect (default: 3, must be positive)"
     )
 
     parser.add_argument(
@@ -6121,6 +6283,16 @@ def main(argv=None):
                 elif args.validate_outputs and result is False:
                     # Validation failed, exit with code 1 (fallback)
                     sys.exit(1)
+            elif args.send_logs:
+                # Handle --send-logs without --message: use default message
+                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
+                if hasattr(cli, 'exit_code'):
+                    sys.exit(cli.exit_code)
+                elif args.validate_outputs and result is False:
+                    # Validation failed, exit with code 1 (fallback)
+                    sys.exit(1)
             else:
                 await cli.run_interactive()
         except Exception as e:

scripts/agent_logs.py

@@ -4,6 +4,7 @@ Agent Logs Collection Helper
 Collects recent JSONL logs from .claude/Projects for agent CLI integration
 """
 
+import hashlib
 import json
 import logging
 import os
@@ -127,7 +128,7 @@ def _find_most_recent_project(projects_root: Path) -> Optional[Path]:
         return None
 
 
-def _collect_jsonl_files(project_path: Path, limit: int) -> List[Dict[str, Any]]:
+def _collect_jsonl_files(project_path: Path, limit: int) -> tuple[List[Dict[str, Any]], int, List[Dict[str, str]]]:
     """
     Collect and parse JSONL files from project directory.
 
@@ -136,11 +137,11 @@ def _collect_jsonl_files(project_path: Path, limit: int) -> List[Dict[str, Any]]
         limit: Maximum number of log files to read
 
     Returns:
-        List of parsed log entries (dicts)
+        Tuple of (list of parsed log entries, number of files read, list of file info dicts)
     """
     if not project_path.exists() or not project_path.is_dir():
         logger.warning(f"Project path does not exist: {project_path}")
-        return []
+        return [], 0, []
 
     try:
         # Find all .jsonl files
@@ -148,18 +149,32 @@ def _collect_jsonl_files(project_path: Path, limit: int) -> List[Dict[str, Any]]
 
         if not jsonl_files:
             logger.info(f"No .jsonl files found in {project_path}")
-            return []
+            return [], 0, []
 
         # Sort by modification time, most recent first
         jsonl_files.sort(key=lambda p: p.stat().st_mtime, reverse=True)
 
         # Limit number of files to read
         jsonl_files = jsonl_files[:limit]
+        files_read = len(jsonl_files)
 
         all_logs = []
+        file_info = []
 
         for jsonl_file in jsonl_files:
             try:
+                # Calculate file hash for tracking
+                hasher = hashlib.sha256()
+                entry_count = 0
+
+                with open(jsonl_file, 'rb') as f:
+                    # Read in chunks for efficient hashing
+                    for chunk in iter(lambda: f.read(4096), b''):
+                        hasher.update(chunk)
+
+                file_hash = hasher.hexdigest()[:8]  # First 8 chars of hash
+
+                # Now read and parse the file
                 with open(jsonl_file, 'r', encoding='utf-8') as f:
                     for line_num, line in enumerate(f, 1):
                         line = line.strip()
@@ -169,43 +184,50 @@ def _collect_jsonl_files(project_path: Path, limit: int) -> List[Dict[str, Any]]
                         try:
                             log_entry = json.loads(line)
                             all_logs.append(log_entry)
+                            entry_count += 1
                         except json.JSONDecodeError as e:
                             logger.debug(
                                 f"Skipping malformed JSON in {jsonl_file.name}:{line_num}: {e}"
                             )
                             continue
 
+                file_info.append({
+                    'name': jsonl_file.name,
+                    'hash': file_hash,
+                    'entries': entry_count
+                })
+
             except Exception as e:
                 logger.warning(f"Error reading {jsonl_file.name}: {e}")
                 continue
 
-        logger.info(f"Collected {len(all_logs)} log entries from {len(jsonl_files)} files")
-        return all_logs
+        logger.info(f"Collected {len(all_logs)} log entries from {files_read} files")
+        return all_logs, files_read, file_info
 
     except Exception as e:
         logger.error(f"Error collecting JSONL files: {e}")
-        return []
+        return [], 0, []
 
 
 def collect_recent_logs(
-    limit: int = 5,
+    limit: int = 3,
     project_name: Optional[str] = None,
     base_path: Optional[str] = None,
     username: Optional[str] = None,
     platform_name: Optional[str] = None
-) -> Optional[List[Dict[str, Any]]]:
+) -> Optional[tuple[List[Dict[str, Any]], int, List[Dict[str, str]]]]:
     """
     Collect recent JSONL logs from .claude/Projects directory.
 
     Args:
-        limit: Maximum number of log files to read (default: 5)
+        limit: Maximum number of log files to read (default: 3)
         project_name: Specific project name or None for most recent
-        base_path: Direct path override to logs directory
+        base_path: Direct path override to logs directory OR a specific .jsonl file
         username: Windows username override
         platform_name: Platform override for testing ('Darwin', 'Windows', 'Linux')
 
     Returns:
-        List of log entry dicts or None if no logs found
+        Tuple of (list of log entry dicts, number of files read, list of file info) or None if no logs found
 
     Raises:
         ValueError: If limit is not positive or project_name is invalid
@@ -214,7 +236,63 @@ def collect_recent_logs(
         raise ValueError(f"Limit must be positive, got {limit}")
 
     try:
-        # Resolve projects root
+        # Check if base_path points to a specific .jsonl file
+        if base_path:
+            base_path_obj = Path(base_path)
+            if base_path_obj.is_file() and base_path_obj.suffix == '.jsonl':
+                # Handle direct file path
+                logger.info(f"Reading specific log file: {base_path_obj}")
+
+                if not base_path_obj.exists():
+                    logger.warning(f"Specified log file does not exist: {base_path_obj}")
+                    return None
+
+                # Read the single file
+                all_logs = []
+                file_info = []
+
+                try:
+                    # Calculate file hash
+                    hasher = hashlib.sha256()
+                    entry_count = 0
+
+                    with open(base_path_obj, 'rb') as f:
+                        for chunk in iter(lambda: f.read(4096), b''):
+                            hasher.update(chunk)
+
+                    file_hash = hasher.hexdigest()[:8]
+
+                    # Read and parse the file
+                    with open(base_path_obj, 'r', encoding='utf-8') as f:
+                        for line_num, line in enumerate(f, 1):
+                            line = line.strip()
+                            if not line:
+                                continue
+
+                            try:
+                                log_entry = json.loads(line)
+                                all_logs.append(log_entry)
+                                entry_count += 1
+                            except json.JSONDecodeError as e:
+                                logger.debug(
+                                    f"Skipping malformed JSON in {base_path_obj.name}:{line_num}: {e}"
+                                )
+                                continue
+
+                    file_info.append({
+                        'name': base_path_obj.name,
+                        'hash': file_hash,
+                        'entries': entry_count
+                    })
+
+                    logger.info(f"Collected {len(all_logs)} log entries from {base_path_obj.name}")
+                    return all_logs, 1, file_info
+
+                except Exception as e:
+                    logger.error(f"Error reading log file {base_path_obj}: {e}")
+                    return None
+
+        # Original directory-based logic
         base = Path(base_path) if base_path else None
         projects_root = _resolve_projects_root(
             platform_name=platform_name,
@@ -237,12 +315,12 @@ def collect_recent_logs(
                 return None
 
         # Collect logs
-        logs = _collect_jsonl_files(project_path, limit)
+        logs, files_read, file_info = _collect_jsonl_files(project_path, limit)
 
         if not logs:
             return None
 
-        return logs
+        return logs, files_read, file_info
 
     except Exception as e:
         logger.error(f"Failed to collect logs: {e}")

scripts/verify_log_transmission.py

@@ -0,0 +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)