quash-mcp 0.2.9__py3-none-any.whl → 0.2.10__py3-none-any.whl

quash_mcp/backend_client.py

@@ -281,6 +281,77 @@ class BackendClient:
                 "error": str(e)
             }
 
+    async def finalize_session(
+        self,
+        api_key: str,
+        session_id: str,
+        task: str,
+        device_serial: str,
+        status: str,
+        final_message: Optional[str] = None,
+        error: Optional[str] = None,
+        duration_seconds: float = 0.0,
+        config: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """
+        Finalize a session and aggregate execution record.
+
+        Called when task ends for ANY reason: normal completion, max steps, error, interrupt.
+
+        Args:
+            api_key: Quash API key
+            session_id: Session identifier to finalize
+            task: Original task description
+            device_serial: Device serial number
+            status: "success", "failed", "max_steps", "error", "interrupted"
+            final_message: Final message from agent
+            error: Error message if failed
+            duration_seconds: Total execution time
+            config: Execution configuration
+
+        Returns:
+            Dict with finalization result:
+            {
+                "finalized": bool,
+                "execution_id": str,
+                "total_steps": int,
+                "total_tokens": {"prompt": int, "completion": int, "total": int},
+                "total_cost": float,
+                "error": str (if failed)
+            }
+        """
+        logger.info(f"🏁 Finalizing session {session_id} - Status: {status}")
+
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout) as client:
+                response = await client.post(
+                    f"{self.base_url}/api/agent/finalize",
+                    json={
+                        "api_key": api_key,
+                        "session_id": session_id,
+                        "task": task,
+                        "device_serial": device_serial,
+                        "status": status,
+                        "final_message": final_message,
+                        "error": error,
+                        "duration_seconds": duration_seconds,
+                        "config": config or {}
+                    }
+                )
+
+                if response.status_code == 200:
+                    result = response.json()
+                    if result.get("finalized"):
+                        logger.info(f"✅ Session finalized: {result.get('total_steps')} steps, ${result.get('total_cost', 0):.4f}")
+                    return result
+                else:
+                    logger.warning(f"Failed to finalize session: HTTP {response.status_code}")
+                    return {"finalized": False, "error": f"HTTP {response.status_code}"}
+
+        except Exception as e:
+            logger.error(f"Failed to finalize session: {e}")
+            return {"finalized": False, "error": str(e)}
+
 
 # Singleton instance
 _backend_client = None

quash_mcp/tools/execute_v3.py

@@ -1,14 +1,18 @@
 """
-Execute tool V3 - Step-by-step execution with local device access.
+Execute tool V3 - Step-by-step execution with state-change verification.
 
-AI logic runs on backend (private), device access happens locally (public).
-This hybrid approach keeps proprietary code private while allowing local device control.
+This reimplements the event-driven state verification from the original Mahoraga agent
+using a polling-based approach suitable for the client-server architecture.
+
+All state-change detection logic is contained in this file.
 """
 
 import time
 import uuid
 import asyncio
-from typing import Dict, Any, Callable, Optional
+import hashlib
+import json
+from typing import Dict, Any, Callable, Optional, Tuple
 from ..state import get_state
 from ..backend_client import get_backend_client
 from ..device.state_capture import get_device_state
@@ -29,21 +33,172 @@ except ImportError as e:
     async_to_sync = None
 
 
+def get_ui_state_hash(ui_state_dict: Dict[str, Any]) -> str:
+    """
+    Generate a stable hash of the UI state for comparison.
+
+    Uses accessibility tree structure and package name.
+    Hash will change when UI updates after an action.
+    """
+    def normalize_tree(tree):
+        """Extract stable elements from UI tree."""
+        if isinstance(tree, list):
+            normalized = []
+            for item in tree:
+                if isinstance(item, dict):
+                    element = {
+                        "className": item.get("className", ""),
+                        "text": item.get("text", ""),
+                        "resourceId": item.get("resourceId", ""),
+                        "bounds": item.get("bounds", ""),
+                    }
+                    normalized.append(element)
+
+                    children = item.get("children", [])
+                    if children:
+                        element["children"] = normalize_tree(children)
+            return normalized
+        return []
+
+    state_repr = {
+        "package": ui_state_dict.get("phone_state", {}).get("package", ""),
+        "tree": normalize_tree(ui_state_dict.get("a11y_tree", []))
+    }
+
+    state_json = json.dumps(state_repr, sort_keys=True)
+    return hashlib.sha256(state_json.encode()).hexdigest()
+
+
+def get_action_timeout(code: str) -> float:
+    """
+    Determine appropriate timeout based on action type.
+
+    Returns timeout in seconds.
+    """
+    code_lower = code.lower()
+
+    if "start_app" in code_lower:
+        return 10.0  # App launches can be slow
+    elif "tap" in code_lower or "click" in code_lower:
+        return 5.0   # Screen transitions
+    elif "swipe" in code_lower or "scroll" in code_lower:
+        return 2.0   # Scroll animations
+    elif "drag" in code_lower:
+        return 2.0
+    elif "input_text" in code_lower:
+        return 2.0   # Text input is fast
+    elif "press_back" in code_lower or "press_home" in code_lower:
+        return 3.0   # Navigation
+    elif "press_key" in code_lower:
+        return 1.0
+    else:
+        return 5.0   # Default timeout
+
+
+def wait_for_state_change(
+    get_state_func,
+    device_serial: str,
+    old_state_hash: str,
+    max_wait: float = 10.0,
+    poll_interval: float = 0.5,
+    min_wait: float = 0.3
+) -> Tuple[Dict[str, Any], bytes, bool]:
+    """
+    Poll device until UI state changes or timeout.
+
+    This is the core polling mechanism that replaces Mahoraga's event-driven approach.
+
+    Returns:
+        Tuple of (ui_state_dict, screenshot_bytes, state_changed: bool)
+    """
+    # Always wait minimum time for action to take effect
+    time.sleep(min_wait)
+
+    start_time = time.time()
+
+    while (time.time() - start_time) < max_wait:
+        # Capture current state
+        ui_state_dict, screenshot_bytes = get_state_func(device_serial)
+        current_hash = get_ui_state_hash(ui_state_dict)
+
+        # Check if state changed
+        if current_hash != old_state_hash:
+            return ui_state_dict, screenshot_bytes, True
+
+        # State hasn't changed - wait and try again
+        time.sleep(poll_interval)
+
+    # Timeout - state never changed
+    ui_state_dict, screenshot_bytes = get_state_func(device_serial)
+    return ui_state_dict, screenshot_bytes, False
+
+
+def wait_for_action_effect(
+    get_state_func,
+    device_serial: str,
+    old_ui_state: Dict[str, Any],
+    executed_code: str,
+    min_wait: float = 0.3,
+    poll_interval: float = 0.5
+) -> Tuple[Dict[str, Any], bytes, bool]:
+    """
+    Wait for an action to take effect on the device.
+
+    Returns:
+        Tuple of (new_ui_state_dict, screenshot_bytes, state_changed: bool)
+    """
+    # Check if action should change UI
+    code_lower = executed_code.lower()
+    if "get_state" in code_lower or "complete(" in code_lower:
+        # Action doesn't change UI - no need to wait
+        time.sleep(0.1)
+        return get_state_func(device_serial)[0], None, False
+
+    # Get hash of old state
+    old_hash = get_ui_state_hash(old_ui_state)
+
+    # Determine timeout based on action type
+    timeout = get_action_timeout(executed_code)
+
+    # Poll until state changes
+    new_ui_state, screenshot, changed = wait_for_state_change(
+        get_state_func,
+        device_serial,
+        old_hash,
+        max_wait=timeout,
+        poll_interval=poll_interval,
+        min_wait=min_wait
+    )
+
+    return new_ui_state, screenshot, changed
+
+
+# ============================================================
+# MAIN EXECUTION FUNCTION
+# ============================================================
+
 async def execute_v3(
     task: str,
+    max_steps: int = 15,
     progress_callback: Optional[Callable[[str], None]] = None
 ) -> Dict[str, Any]:
     """
     Execute automation task using step-by-step backend communication.
 
     Each step:
-    1. Capture device state locally (UI + optional screenshot)
+    1. Capture device state (State A)
     2. Send to backend for AI decision
     3. Execute returned action locally
-    4. Repeat until complete
+    4. POLL until state changes (State B ≠ State A) or timeout
+    5. Send State B to backend in next iteration
+    6. Repeat until complete
+
+    This ensures the backend always sees the UPDATED state after each action,
+    preventing the agent from making decisions based on stale state.
 
     Args:
         task: Natural language task description
+        max_steps: Maximum number of steps to execute (default: 15)
         progress_callback: Optional callback for progress updates
 
     Returns:
@@ -117,6 +272,7 @@ async def execute_v3(
     log_progress(f"🚀 Starting task: {task}")
     log_progress(f"📱 Device: {state.device_serial}")
     log_progress(f"🧠 Model: {config['model']}")
+    log_progress(f"🔢 Max steps: {max_steps}")
 
     # Initialize execution
     start_time = time.time()
@@ -139,7 +295,6 @@ async def execute_v3(
     if describe_tools and DEFAULT and MahoragaAdbTools:
         try:
             # Create a mahoraga AdbTools instance for tool execution
-            # This instance has all the tool methods like swipe, start_app, etc.
             mahoraga_tools = MahoragaAdbTools(
                 serial=state.device_serial,
                 use_tcp=True,
@@ -153,15 +308,26 @@ async def execute_v3(
             allowed_tool_names = DEFAULT.allowed_tools if hasattr(DEFAULT, 'allowed_tools') else []
             filtered_tools = {name: func for name, func in tool_list.items() if name in allowed_tool_names}
 
-            # Add each tool function to executor globals
+            # Add each tool function to executor globals with print wrapper
             for tool_name, tool_function in filtered_tools.items():
                 # Convert async functions to sync if needed
                 if asyncio.iscoroutinefunction(tool_function):
                     if async_to_sync:
                         tool_function = async_to_sync(tool_function)
 
-                # Add to globals so code can call it directly
-                executor_globals[tool_name] = tool_function
+                # Wrap tool function to print its return value
+                def make_printing_wrapper(func):
+                    """Wrap a tool function to print its return value."""
+                    def wrapper(*args, **kwargs):
+                        result = func(*args, **kwargs)
+                        # Print the result so stdout captures it
+                        if result is not None:
+                            print(result)
+                        return result
+                    return wrapper
+
+                # Add wrapped function to globals so code can call it directly
+                executor_globals[tool_name] = make_printing_wrapper(tool_function)
 
             log_progress(f"🔧 Loaded {len(filtered_tools)} tool functions: {list(filtered_tools.keys())}")
         except Exception as e:
@@ -175,11 +341,11 @@ async def execute_v3(
         # ============================================================
         # STEP-BY-STEP EXECUTION LOOP
         # ============================================================
-        while step_number < 15:  # Max 15 steps
+        while step_number < max_steps:  # Use user-provided max_steps
             step_number += 1
-            log_progress(f"🧠 Step {step_number}: Thinking...")
+            log_progress(f"🧠 Step {step_number}/{max_steps}: Analyzing...")
 
-            # 1. Capture device state
+            # 1. Capture device state (State A)
             try:
                 ui_state_dict, screenshot_bytes = get_device_state(state.device_serial)
 
@@ -187,15 +353,14 @@ async def execute_v3(
                 if not config["vision"]:
                     screenshot_bytes = None
 
-                # DEBUG: Log UI state
-                a11y_preview = ui_state_dict.get("a11y_tree", "")[:150]
-                log_progress(f"📱 UI State captured - A11y tree preview: {a11y_preview}...")
-                log_progress(f"📷 Screenshot: {'Present' if screenshot_bytes else 'None'}")
+                # Log current state
+                current_package = ui_state_dict.get("phone_state", {}).get("package", "unknown")
+                log_progress(f"📱 Current app: {current_package}")
 
             except Exception as e:
                 log_progress(f"⚠️ Warning: Failed to capture device state: {e}")
                 ui_state_dict = {
-                    "a11y_tree": "<hierarchy></hierarchy>",
+                    "a11y_tree": [{"index": 0, "text": "Error capturing UI", "children": []}],
                     "phone_state": {"package": "unknown"}
                 }
                 screenshot_bytes = None
@@ -240,16 +405,6 @@ async def execute_v3(
             code = action.get("code")
             reasoning = action.get("reasoning")
 
-            # DEBUG: Log full backend response
-            log_progress(f"\n📋 DEBUG - Backend Response:")
-            log_progress(f"  - Action type: {action_type}")
-            log_progress(f"  - Completed: {step_result.get('completed', False)}")
-            log_progress(f"  - Success: {step_result.get('success', None)}")
-            log_progress(f"  - Code present: {bool(code)}")
-            if code:
-                log_progress(f"  - Code: {code[:100]}..." if len(code) > 100 else f"  - Code: {code}")
-            log_progress(f"  - Assistant response: {step_result.get('assistant_response', '')[:200]}...\n")
-
             # Log reasoning
             if reasoning:
                 log_progress(f"🤔 Reasoning: {reasoning}")
@@ -296,17 +451,82 @@ async def execute_v3(
             if code and action_type == "execute_code":
                 log_progress(f"⚡ Executing action...")
 
-                try:
-                    # Execute code in sandbox
-                    exec(code, executor_globals, executor_locals)
+                # Store old UI state for comparison
+                old_ui_state = ui_state_dict.copy()
 
-                    # Get execution result
-                    execution_output = executor_locals.get("_result", "Code executed successfully")
+                try:
+                    import io
+                    import contextlib
+
+                    # Capture stdout and stderr to get tool function outputs
+                    stdout = io.StringIO()
+                    stderr = io.StringIO()
+
+                    with contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
+                        # Execute code in sandbox
+                        exec(code, executor_globals, executor_locals)
+
+                    # Get captured output
+                    execution_output = stdout.getvalue()
+                    error_output = stderr.getvalue()
+
+                    # ============================================================
+                    # CRITICAL: Wait for state change (polling-based event detection)
+                    # ============================================================
+                    log_progress(f"⏳ Waiting for UI state to update...")
+
+                    try:
+                        # Poll until state changes or timeout
+                        new_ui_state_dict, _, state_changed = wait_for_action_effect(
+                            get_device_state,
+                            state.device_serial,
+                            old_ui_state,
+                            code,
+                            min_wait=0.3,
+                            poll_interval=0.5
+                        )
+
+                        # Log what happened
+                        if state_changed:
+                            old_pkg = old_ui_state.get("phone_state", {}).get("package", "")
+                            new_pkg = new_ui_state_dict.get("phone_state", {}).get("package", "")
+
+                            if old_pkg != new_pkg:
+                                log_progress(f"✅ State changed: App switched ({old_pkg} → {new_pkg})")
+                            else:
+                                log_progress(f"✅ State changed: UI updated")
+                        else:
+                            log_progress(f"⚠️ WARNING: State did NOT change after action (timeout)")
+                            log_progress(f"   This might mean the action had no effect or took too long")
+
+                    except Exception as e:
+                        log_progress(f"⚠️ Error during state change detection: {e}")
+                        state_changed = False
+                        # Fallback: Just wait a bit
+                        time.sleep(1.5)
+
+                    # Build feedback message
+                    feedback_parts = []
+
+                    if execution_output:
+                        feedback_parts.append(f"Action output: {execution_output.strip()}")
+
+                    if state_changed:
+                        feedback_parts.append("UI state updated successfully")
+                    else:
+                        feedback_parts.append("WARNING: UI state did not change (action may have failed)")
+
+                    if error_output:
+                        feedback_parts.append(f"Warnings: {error_output.strip()}")
+
+                    feedback = " | ".join(feedback_parts) if feedback_parts else "Action executed"
+
+                    log_progress(f"✅ {feedback[:200]}")
 
                     # Add execution result to chat history
                     chat_history.append({
                         "role": "user",
-                        "content": f"Execution Result:\n```\n{execution_output}\n```"
+                        "content": f"Execution Result:\n```\n{feedback}\n```"
                     })
 
                 except Exception as e:
@@ -316,7 +536,7 @@ async def execute_v3(
                     # Add error to chat history
                     chat_history.append({
                         "role": "user",
-                        "content": f"Execution Result:\n```\n{error_msg}\n```"
+                        "content": f"Execution Error:\n```\n{error_msg}\n```"
                     })
 
             else:
@@ -328,33 +548,78 @@ async def execute_v3(
                 })
 
         # Max steps reached
-        log_progress(f"⚠️ Reached maximum steps ({step_number})")
+        log_progress(f"⚠️ Reached maximum steps ({max_steps})")
         log_progress(f"💰 Usage: {total_tokens['total']} tokens, ${total_cost:.4f}")
 
+        duration = time.time() - start_time
+
+        # Finalize session on backend to create execution record
+        await backend.finalize_session(
+            api_key=quash_api_key,
+            session_id=session_id,
+            task=task,
+            device_serial=state.device_serial,
+            status="max_steps",
+            final_message=f"Reached maximum step limit of {max_steps}",
+            error=None,
+            duration_seconds=duration,
+            config=config
+        )
+
         return {
             "status": "failed",
             "steps_taken": step_number,
-            "final_message": f"Reached maximum step limit of {step_number}",
+            "final_message": f"Reached maximum step limit of {max_steps}",
             "message": "❌ Failed: Maximum steps reached",
             "tokens": total_tokens,
             "cost": total_cost,
-            "duration_seconds": time.time() - start_time
+            "duration_seconds": duration
         }
 
     except KeyboardInterrupt:
-        log_progress("⏹️ Task interrupted by user")
+        log_progress("ℹ️ Task interrupted by user")
+        duration = time.time() - start_time
+
+        # Finalize session on backend
+        await backend.finalize_session(
+            api_key=quash_api_key,
+            session_id=session_id,
+            task=task,
+            device_serial=state.device_serial,
+            status="interrupted",
+            final_message="Task interrupted by user",
+            error=None,
+            duration_seconds=duration,
+            config=config
+        )
+
         return {
             "status": "interrupted",
-            "message": "⏹️ Task execution interrupted",
+            "message": "ℹ️ Task execution interrupted",
             "steps_taken": step_number,
             "tokens": total_tokens,
             "cost": total_cost,
-            "duration_seconds": time.time() - start_time
+            "duration_seconds": duration
         }
 
     except Exception as e:
         error_msg = str(e)
         log_progress(f"💥 Error: {error_msg}")
+        duration = time.time() - start_time
+
+        # Finalize session on backend
+        await backend.finalize_session(
+            api_key=quash_api_key,
+            session_id=session_id,
+            task=task,
+            device_serial=state.device_serial,
+            status="error",
+            final_message=None,
+            error=error_msg,
+            duration_seconds=duration,
+            config=config
+        )
+
         return {
             "status": "error",
             "message": f"💥 Execution error: {error_msg}",
@@ -362,7 +627,7 @@ async def execute_v3(
             "steps_taken": step_number,
             "tokens": total_tokens,
             "cost": total_cost,
-            "duration_seconds": time.time() - start_time
+            "duration_seconds": duration
         }
 
     finally:

{quash_mcp-0.2.9.dist-info → quash_mcp-0.2.10.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quash-mcp
-Version: 0.2.9
+Version: 0.2.10
 Summary: Model Context Protocol server for Quash - AI-powered mobile automation agent
 Project-URL: Homepage, https://quashbugs.com
 Project-URL: Repository, https://github.com/quash/quash-mcp
@@ -57,7 +57,7 @@ All dependencies (including ADB tools and device connectivity) are automatically
 
 ### 1. Get Your API Key
 
-1. Visit [quashbugs.com](https://quashbugs.com) (or your deployment URL)
+1. Visit [quashbugs.com/mcp](http://13.220.180.140.nip.io/) (or your deployment URL)
 2. Sign in with Google
 3. Go to Dashboard → API Keys
 4. Create a new API key
@@ -92,6 +92,22 @@ Add to your MCP host's config file:
 - No PATH configuration needed
 - Uses whichever Python has quash-mcp installed
 
+#### CLI Configuration (If Supported by Host)
+
+Some MCP hosts might provide a command-line interface to add servers.
+
+**Examples:**
+
+- **Claude Code:**
+  ```bash
+  claude mcp add quash quash-mcp
+  ```
+
+- **Gemini CLI:**
+  ```bash
+  gemini mcp add quash quash-mcp
+  ```
+
 #### Alternative: Direct Command (if in PATH)
 
 If `quash-mcp` is in your PATH:
@@ -220,7 +236,7 @@ User: "Show me my usage statistics"
 
 - **Python 3.11+** - Required for the MCP server
 - **Android Device** - Emulator or physical device with USB debugging enabled
-- **Quash API Key** - Get from [quashbugs.com](https://quashbugs.com)
+- **Quash API Key** - Get from [quashbugs.com/mcp](http://13.220.180.140.nip.io/)
 
 Dependencies automatically installed:
 - Android Debug Bridge (ADB) - via `adbutils`

{quash_mcp-0.2.9.dist-info → quash_mcp-0.2.10.dist-info}/RECORD

@@ -1,6 +1,6 @@
 quash_mcp/__init__.py,sha256=LImiWCRgjAbb5DZXBq2DktUEAbftvnO61Vil4Ayun9A,39
 quash_mcp/__main__.py,sha256=WCg5OlnXhr6i0XJHAUGpbhliMy3qE2SJkFzVD4wO-lw,239
-quash_mcp/backend_client.py,sha256=FvrchO5R4fByTlSh_LosFSKXOZSsPKYEsRZ3LNioDdk,9998
+quash_mcp/backend_client.py,sha256=ZqzYDO1sjD0LaPUaAY6y9dSWQRU4OBCdj-oqqmIdw6I,12793
 quash_mcp/server.py,sha256=scUGnplxjsvyYLK2q6hrjl-5Chkdnat9pODDtLzsQFY,15519
 quash_mcp/state.py,sha256=Tnt795GnZcas-h62Y6KYyIZVopeoWPM0TbRwOeVFYj4,4394
 quash_mcp/device/__init__.py,sha256=6e8CtHolt-vJKPxZUU_Vsd6-QGqos9VrFykaLTT90rk,772
@@ -14,10 +14,10 @@ quash_mcp/tools/configure.py,sha256=cv4RTolu6qae-XzyACSJUDrALfd0gYC-XE5s66_zfNk,
 quash_mcp/tools/connect.py,sha256=Kc7RGRUgtd2sR_bv6U4CB4kWSaLfsDc5kBo9u4FEjzs,4799
 quash_mcp/tools/execute.py,sha256=kR3VzIl31Lek-js4Hgxs-S_ls4YwKnbqkt79KFbvFuM,909
 quash_mcp/tools/execute_v2_backup.py,sha256=waWnaD0dEVcOJgRBbqZo3HnxME1s6YUOn8aRbm4R3X4,6081
-quash_mcp/tools/execute_v3.py,sha256=Ya3XEh2fOBgVmytIShLkiWuAbpQKE4CNGUSamwJD92I,14250
+quash_mcp/tools/execute_v3.py,sha256=8WHiEcVWUcAekh7MGaqpXKYGAzdilQ1HaNankMoAxHI,23506
 quash_mcp/tools/runsuite.py,sha256=gohLk9FpN8v7F0a69fspqOqUexTcslpYf3qU-iIZZ3s,7220
 quash_mcp/tools/usage.py,sha256=g76A6FO36fThoyRFG7q92QmS3Kh1pIKOrhYOzUdIubA,1155
-quash_mcp-0.2.9.dist-info/METADATA,sha256=l22Tc-iKIlk17y6MzziulgCopPJ4kdkKq_P_Bw470rU,8129
-quash_mcp-0.2.9.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-quash_mcp-0.2.9.dist-info/entry_points.txt,sha256=9sbDxrx0ApGDVRS-IE3mQgSao3DwKnnV_k-_ipFn9QI,52
-quash_mcp-0.2.9.dist-info/RECORD,,
+quash_mcp-0.2.10.dist-info/METADATA,sha256=fngQn032lI01_QIypgixbZFhe3bWWqA_1QqC-5qRS0w,8424
+quash_mcp-0.2.10.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+quash_mcp-0.2.10.dist-info/entry_points.txt,sha256=9sbDxrx0ApGDVRS-IE3mQgSao3DwKnnV_k-_ipFn9QI,52
+quash_mcp-0.2.10.dist-info/RECORD,,