From ebc44d34c5d816690a5864805b657dce1ed878b9 Mon Sep 17 00:00:00 2001
From: rcholic <ivytony@gmail.com>
Date: Fri, 2 Jan 2026 13:33:22 -0800
Subject: [PATCH 1/2] Phase 4: Modularize code

---
 sentience/__init__.py         |   3 +-
 sentience/element_filter.py   |   2 +-
 sentience/formatting.py       |  62 ++------
 sentience/utils/__init__.py   |  41 ++++++
 sentience/utils/browser.py    |  47 +++++++
 sentience/utils/element.py    | 258 ++++++++++++++++++++++++++++++++++
 sentience/utils/formatting.py |  60 ++++++++
 7 files changed, 418 insertions(+), 55 deletions(-)
 create mode 100644 sentience/utils/__init__.py
 create mode 100644 sentience/utils/browser.py
 create mode 100644 sentience/utils/element.py
 create mode 100644 sentience/utils/formatting.py

diff --git a/sentience/__init__.py b/sentience/__init__.py
index 61526a6..14b72fb 100644
--- a/sentience/__init__.py
+++ b/sentience/__init__.py
@@ -16,7 +16,7 @@
 from .expect import expect
 
 # Formatting (v0.12.0+)
-from .formatting import format_snapshot_for_llm
+from .utils.formatting import format_snapshot_for_llm
 from .generator import ScriptGenerator, generate
 from .inspector import Inspector, inspect
 from .llm_provider import (
@@ -62,6 +62,7 @@
 from .tracing import JsonlTraceSink, TraceEvent, Tracer, TraceSink
 
 # Utilities (v0.12.0+)
+# Import from utils package (re-exports from submodules for backward compatibility)
 from .utils import (
     canonical_snapshot_loose,
     canonical_snapshot_strict,
diff --git a/sentience/element_filter.py b/sentience/element_filter.py
index df117b9..6159115 100644
--- a/sentience/element_filter.py
+++ b/sentience/element_filter.py
@@ -64,7 +64,7 @@ def filter_by_importance(
     @staticmethod
     def filter_by_goal(
         snapshot: Snapshot,
-        goal: str | None,
+        goal: Optional[str],
         max_elements: int = 50,
     ) -> list[Element]:
         """
diff --git a/sentience/formatting.py b/sentience/formatting.py
index f8961c5..b8dd653 100644
--- a/sentience/formatting.py
+++ b/sentience/formatting.py
@@ -1,59 +1,15 @@
 """
 Snapshot formatting utilities for LLM prompts.
 
-Provides functions to convert Sentience snapshots into text format suitable
-for LLM consumption.
-"""
-
-from typing import List
-
-from .models import Snapshot
-
-
-def format_snapshot_for_llm(snap: Snapshot, limit: int = 50) -> str:
-    """
-    Convert snapshot elements to text format for LLM consumption.
-
-    This is the canonical way Sentience formats DOM state for LLMs.
-    The format includes element ID, role, text preview, visual cues,
-    position, and importance score.
+DEPRECATED: This module is maintained for backward compatibility only.
+New code should import from sentience.utils.formatting or sentience directly:
 
-    Args:
-        snap: Snapshot object with elements
-        limit: Maximum number of elements to include (default: 50)
-
-    Returns:
-        Formatted string with one element per line
-
-    Example:
-        >>> snap = snapshot(browser)
-        >>> formatted = format_snapshot_for_llm(snap, limit=10)
-        >>> print(formatted)
-        [1] <button> "Sign In" {PRIMARY,CLICKABLE} @ (100,50) (Imp:10)
-        [2] <input> "Email address" @ (100,100) (Imp:8)
-        ...
-    """
-    lines: list[str] = []
-
-    for el in snap.elements[:limit]:
-        # Build visual cues string
-        cues = []
-        if getattr(el.visual_cues, "is_primary", False):
-            cues.append("PRIMARY")
-        if getattr(el.visual_cues, "is_clickable", False):
-            cues.append("CLICKABLE")
-
-        cues_str = f" {{{','.join(cues)}}}" if cues else ""
-
-        # Format text preview (truncate to 50 chars)
-        text_preview = el.text or ""
-        if len(text_preview) > 50:
-            text_preview = text_preview[:50] + "..."
+    from sentience.utils.formatting import format_snapshot_for_llm
+    # or
+    from sentience import format_snapshot_for_llm
+"""
 
-        # Build element line: [ID] <role> "text" {cues} @ (x,y) (Imp:score)
-        lines.append(
-            f'[{el.id}] <{el.role}> "{text_preview}"{cues_str} '
-            f"@ ({int(el.bbox.x)},{int(el.bbox.y)}) (Imp:{el.importance})"
-        )
+# Re-export from new location for backward compatibility
+from .utils.formatting import format_snapshot_for_llm
 
-    return "\n".join(lines)
+__all__ = ["format_snapshot_for_llm"]
diff --git a/sentience/utils/__init__.py b/sentience/utils/__init__.py
new file mode 100644
index 0000000..a5d4d78
--- /dev/null
+++ b/sentience/utils/__init__.py
@@ -0,0 +1,41 @@
+"""
+Utility functions for Sentience SDK.
+
+This module re-exports all utility functions from submodules for backward compatibility.
+Users can continue using:
+    from sentience.utils import compute_snapshot_digests, canonical_snapshot_strict
+    from sentience import canonical_snapshot_strict, format_snapshot_for_llm
+"""
+
+# Re-export all functions from submodules for backward compatibility
+from .browser import save_storage_state
+from .element import (
+    BBox,
+    ElementFingerprint,
+    canonical_snapshot_loose,
+    canonical_snapshot_strict,
+    compute_snapshot_digests,
+    extract_element_fingerprint,
+    normalize_bbox,
+    normalize_text_strict,
+    sha256_digest,
+)
+from .formatting import format_snapshot_for_llm
+
+__all__ = [
+    # Browser utilities
+    "save_storage_state",
+    # Element/digest utilities
+    "BBox",
+    "ElementFingerprint",
+    "canonical_snapshot_loose",
+    "canonical_snapshot_strict",
+    "compute_snapshot_digests",
+    "extract_element_fingerprint",
+    "normalize_bbox",
+    "normalize_text_strict",
+    "sha256_digest",
+    # Formatting utilities
+    "format_snapshot_for_llm",
+]
+
diff --git a/sentience/utils/browser.py b/sentience/utils/browser.py
new file mode 100644
index 0000000..8b42271
--- /dev/null
+++ b/sentience/utils/browser.py
@@ -0,0 +1,47 @@
+"""
+Browser-related utilities for Sentience SDK.
+
+Provides functions for managing browser storage state (cookies, localStorage).
+"""
+
+import json
+from pathlib import Path
+
+from playwright.sync_api import BrowserContext
+
+
+def save_storage_state(context: BrowserContext, file_path: str | Path) -> None:
+    """
+    Save current browser storage state (cookies + localStorage) to a file.
+
+    This is useful for capturing a logged-in session to reuse later.
+
+    Args:
+        context: Playwright BrowserContext
+        file_path: Path to save the storage state JSON file
+
+    Example:
+        ```python
+        from sentience import SentienceBrowser, save_storage_state
+
+        browser = SentienceBrowser()
+        browser.start()
+
+        # User logs in manually or via agent
+        browser.goto("https://example.com")
+        # ... login happens ...
+
+        # Save session for later
+        save_storage_state(browser.context, "auth.json")
+        ```
+
+    Raises:
+        IOError: If file cannot be written
+    """
+    storage_state = context.storage_state()
+    file_path_obj = Path(file_path)
+    file_path_obj.parent.mkdir(parents=True, exist_ok=True)
+    with open(file_path_obj, "w") as f:
+        json.dump(storage_state, f, indent=2)
+    print(f"✅ [Sentience] Saved storage state to {file_path_obj}")
+
diff --git a/sentience/utils/element.py b/sentience/utils/element.py
new file mode 100644
index 0000000..6ab947c
--- /dev/null
+++ b/sentience/utils/element.py
@@ -0,0 +1,258 @@
+"""
+Element manipulation and digest utilities for Sentience SDK.
+
+Provides functions to compute stable digests of snapshots for deterministic diff.
+Two digest strategies:
+- strict: includes structure + normalized text
+- loose: structure only (no text) - detects layout changes vs content changes
+"""
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass
+from typing import Any, Optional
+
+
+@dataclass
+class BBox:
+    """Bounding box with normalized coordinates."""
+
+    x: int
+    y: int
+    width: int
+    height: int
+
+    @classmethod
+    def from_dict(cls, bbox_dict: dict[str, Any]) -> "BBox":
+        """Create BBox from dictionary."""
+        return cls(
+            x=int(bbox_dict.get("x", 0)),
+            y=int(bbox_dict.get("y", 0)),
+            width=int(bbox_dict.get("width", 0)),
+            height=int(bbox_dict.get("height", 0)),
+        )
+
+    def to_normalized(self, bucket_size: int = 2) -> list[int]:
+        """
+        Normalize bbox to fixed-size buckets to ignore minor jitter.
+
+        Args:
+            bucket_size: Pixel bucket size (default 2px)
+
+        Returns:
+            List of [x, y, width, height] rounded to buckets
+        """
+        return [
+            round(self.x / bucket_size) * bucket_size,
+            round(self.y / bucket_size) * bucket_size,
+            round(self.width / bucket_size) * bucket_size,
+            round(self.height / bucket_size) * bucket_size,
+        ]
+
+
+@dataclass
+class ElementFingerprint:
+    """Normalized element data for digest computation."""
+
+    id: int
+    role: str
+    bbox: list[int]  # Normalized
+    clickable: int  # 0 or 1
+    primary: int  # 0 or 1
+    text: str = ""  # Empty for loose digest
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        data = {
+            "id": self.id,
+            "role": self.role,
+            "bbox": self.bbox,
+            "clickable": self.clickable,
+            "primary": self.primary,
+        }
+        if self.text:  # Only include text if non-empty
+            data["text"] = self.text
+        return data
+
+
+def normalize_text_strict(text: Optional[str], max_length: int = 80) -> str:
+    """
+    Normalize text for strict digest (structure + content).
+
+    Rules:
+    - Lowercase
+    - Trim and collapse whitespace
+    - Cap length at max_length
+    - Replace digit runs with '#'
+    - Normalize currency: $79.99 -> $#
+    - Normalize time patterns: 12:34 -> #:#
+
+    Args:
+        text: Input text
+        max_length: Maximum text length (default 80)
+
+    Returns:
+        Normalized text string
+    """
+    if not text:
+        return ""
+
+    # Lowercase and trim
+    text = text.strip().lower()
+
+    # Collapse whitespace
+    text = " ".join(text.split())
+
+    # Cap length
+    text = text[:max_length]
+
+    # Replace digit runs with #
+    text = re.sub(r"\d+", "#", text)
+
+    # Normalize currency
+    text = re.sub(r"\$\s*#", "$#", text)
+
+    # Normalize time patterns (HH:MM or similar)
+    text = re.sub(r"#:#", "#:#", text)
+
+    # Normalize date patterns (YYYY-MM-DD or similar)
+    text = re.sub(r"#-#-#", "#-#-#", text)
+
+    return text
+
+
+def normalize_bbox(bbox: dict[str, Any] | BBox, bucket_size: int = 2) -> list[int]:
+    """
+    Round bbox to fixed-size buckets to ignore jitter.
+
+    Args:
+        bbox: BBox object or dict with x, y, width, height
+        bucket_size: Pixel bucket size (default 2px)
+
+    Returns:
+        List of [x, y, width, height] rounded to buckets
+    """
+    if isinstance(bbox, BBox):
+        return bbox.to_normalized(bucket_size)
+
+    bbox_obj = BBox.from_dict(bbox)
+    return bbox_obj.to_normalized(bucket_size)
+
+
+def extract_element_fingerprint(
+    element: dict[str, Any],
+    include_text: bool = True,
+) -> ElementFingerprint:
+    """
+    Extract normalized fingerprint from element dict.
+
+    Args:
+        element: Element dict from snapshot
+        include_text: Whether to include normalized text (False for loose digest)
+
+    Returns:
+        ElementFingerprint with normalized data
+    """
+    # Extract basic fields
+    element_id = element.get("id", 0)
+    role = element.get("role", "unknown")
+
+    # Extract and normalize bbox
+    bbox_data = element.get("bbox", {})
+    bbox_normalized = normalize_bbox(bbox_data)
+
+    # Extract visual cues
+    visual_cues = element.get("visual_cues", {})
+    clickable = 1 if visual_cues.get("is_clickable", False) else 0
+    primary = 1 if visual_cues.get("is_primary", False) else 0
+
+    # Extract and normalize text (if requested)
+    text = ""
+    if include_text:
+        raw_text = element.get("text", "")
+        text = normalize_text_strict(raw_text)
+
+    return ElementFingerprint(
+        id=element_id,
+        role=role,
+        bbox=bbox_normalized,
+        clickable=clickable,
+        primary=primary,
+        text=text,
+    )
+
+
+def canonical_snapshot_strict(elements: list[dict[str, Any]]) -> str:
+    """
+    Create strict snapshot digest (structure + normalized text).
+
+    Args:
+        elements: List of element dicts from snapshot
+
+    Returns:
+        Canonical JSON string for hashing
+    """
+    fingerprints = []
+
+    for element in sorted(elements, key=lambda e: e.get("id", 0)):
+        fingerprint = extract_element_fingerprint(element, include_text=True)
+        fingerprints.append(fingerprint.to_dict())
+
+    return json.dumps(fingerprints, sort_keys=True, ensure_ascii=False)
+
+
+def canonical_snapshot_loose(elements: list[dict[str, Any]]) -> str:
+    """
+    Create loose snapshot digest (structure only, no text).
+
+    This is more resistant to content churn (prices, ads, timestamps).
+    Use for detecting structural changes vs content changes.
+
+    Args:
+        elements: List of element dicts from snapshot
+
+    Returns:
+        Canonical JSON string for hashing
+    """
+    fingerprints = []
+
+    for element in sorted(elements, key=lambda e: e.get("id", 0)):
+        fingerprint = extract_element_fingerprint(element, include_text=False)
+        fingerprints.append(fingerprint.to_dict())
+
+    return json.dumps(fingerprints, sort_keys=True, ensure_ascii=False)
+
+
+def sha256_digest(canonical_str: str) -> str:
+    """
+    Compute SHA256 hash with 'sha256:' prefix.
+
+    Args:
+        canonical_str: Canonical string to hash
+
+    Returns:
+        Hash string with format: "sha256:<hex>"
+    """
+    hash_obj = hashlib.sha256(canonical_str.encode("utf-8"))
+    return f"sha256:{hash_obj.hexdigest()}"
+
+
+def compute_snapshot_digests(elements: list[dict[str, Any]]) -> dict[str, str]:
+    """
+    Compute both strict and loose digests for a snapshot.
+
+    Args:
+        elements: List of element dicts from snapshot
+
+    Returns:
+        Dict with 'strict' and 'loose' digest strings
+    """
+    canonical_strict = canonical_snapshot_strict(elements)
+    canonical_loose = canonical_snapshot_loose(elements)
+
+    return {
+        "strict": sha256_digest(canonical_strict),
+        "loose": sha256_digest(canonical_loose),
+    }
+
diff --git a/sentience/utils/formatting.py b/sentience/utils/formatting.py
new file mode 100644
index 0000000..2271477
--- /dev/null
+++ b/sentience/utils/formatting.py
@@ -0,0 +1,60 @@
+"""
+Snapshot formatting utilities for LLM prompts.
+
+Provides functions to convert Sentience snapshots into text format suitable
+for LLM consumption.
+"""
+
+from typing import List
+
+from ..models import Snapshot
+
+
+def format_snapshot_for_llm(snap: Snapshot, limit: int = 50) -> str:
+    """
+    Convert snapshot elements to text format for LLM consumption.
+
+    This is the canonical way Sentience formats DOM state for LLMs.
+    The format includes element ID, role, text preview, visual cues,
+    position, and importance score.
+
+    Args:
+        snap: Snapshot object with elements
+        limit: Maximum number of elements to include (default: 50)
+
+    Returns:
+        Formatted string with one element per line
+
+    Example:
+        >>> snap = snapshot(browser)
+        >>> formatted = format_snapshot_for_llm(snap, limit=10)
+        >>> print(formatted)
+        [1] <button> "Sign In" {PRIMARY,CLICKABLE} @ (100,50) (Imp:10)
+        [2] <input> "Email address" @ (100,100) (Imp:8)
+        ...
+    """
+    lines: list[str] = []
+
+    for el in snap.elements[:limit]:
+        # Build visual cues string
+        cues = []
+        if getattr(el.visual_cues, "is_primary", False):
+            cues.append("PRIMARY")
+        if getattr(el.visual_cues, "is_clickable", False):
+            cues.append("CLICKABLE")
+
+        cues_str = f" {{{','.join(cues)}}}" if cues else ""
+
+        # Format text preview (truncate to 50 chars)
+        text_preview = el.text or ""
+        if len(text_preview) > 50:
+            text_preview = text_preview[:50] + "..."
+
+        # Build element line: [ID] <role> "text" {cues} @ (x,y) (Imp:score)
+        lines.append(
+            f'[{el.id}] <{el.role}> "{text_preview}"{cues_str} '
+            f"@ ({int(el.bbox.x)},{int(el.bbox.y)}) (Imp:{el.importance})"
+        )
+
+    return "\n".join(lines)
+

From 9544018879b24fe13d0ec854d2fbdf18c436a2e3 Mon Sep 17 00:00:00 2001
From: rcholic <ivytony@gmail.com>
Date: Fri, 2 Jan 2026 13:56:47 -0800
Subject: [PATCH 2/2] Phase 4.2 completed

---
 sentience/__init__.py                         |   6 +-
 sentience/action_executor.py                  | 191 ++++++++++
 sentience/agent.py                            | 359 +-----------------
 sentience/element_filter.py                   |   2 +-
 sentience/llm_interaction_handler.py          | 146 +++++++
 sentience/utils/__init__.py                   |   1 -
 sentience/utils/browser.py                    |   1 -
 sentience/utils/element.py                    |   3 +-
 sentience/utils/formatting.py                 |   1 -
 tests/test_agent.py                           |  63 ++-
 tests/test_llm_provider_utils.py              |   1 -
 tests/test_llm_response_builder.py            |   1 -
 tests/test_trace_file_manager.py              |   1 -
 .../test_trace_file_manager_extract_stats.py  |   2 +-
 14 files changed, 392 insertions(+), 386 deletions(-)
 create mode 100644 sentience/action_executor.py
 create mode 100644 sentience/llm_interaction_handler.py

diff --git a/sentience/__init__.py b/sentience/__init__.py
index 14b72fb..76458db 100644
--- a/sentience/__init__.py
+++ b/sentience/__init__.py
@@ -14,9 +14,6 @@
 from .cloud_tracing import CloudTraceSink, SentienceLogger
 from .conversational_agent import ConversationalAgent
 from .expect import expect
-
-# Formatting (v0.12.0+)
-from .utils.formatting import format_snapshot_for_llm
 from .generator import ScriptGenerator, generate
 from .inspector import Inspector, inspect
 from .llm_provider import (
@@ -70,6 +67,9 @@
     save_storage_state,
     sha256_digest,
 )
+
+# Formatting (v0.12.0+)
+from .utils.formatting import format_snapshot_for_llm
 from .wait import wait_for
 
 __version__ = "0.91.1"
diff --git a/sentience/action_executor.py b/sentience/action_executor.py
new file mode 100644
index 0000000..104e255
--- /dev/null
+++ b/sentience/action_executor.py
@@ -0,0 +1,191 @@
+"""
+Action Executor for Sentience Agent.
+
+Handles parsing and execution of action commands (CLICK, TYPE, PRESS, FINISH).
+This separates action execution concerns from LLM interaction.
+"""
+
+import re
+from typing import Any
+
+from .actions import click, click_async, press, press_async, type_text, type_text_async
+from .browser import AsyncSentienceBrowser, SentienceBrowser
+from .models import Snapshot
+
+
+class ActionExecutor:
+    """
+    Executes actions and handles parsing of action command strings.
+
+    This class encapsulates all action execution logic, making it easier to:
+    - Test action execution independently
+    - Add new action types in one place
+    - Handle action parsing errors consistently
+    """
+
+    def __init__(self, browser: SentienceBrowser | AsyncSentienceBrowser):
+        """
+        Initialize action executor.
+
+        Args:
+            browser: SentienceBrowser or AsyncSentienceBrowser instance
+        """
+        self.browser = browser
+        self._is_async = isinstance(browser, AsyncSentienceBrowser)
+
+    def execute(self, action_str: str, snap: Snapshot) -> dict[str, Any]:
+        """
+        Parse action string and execute SDK call (synchronous).
+
+        Args:
+            action_str: Action string from LLM (e.g., "CLICK(42)", "TYPE(15, \"text\")")
+            snap: Current snapshot (for context, currently unused but kept for API consistency)
+
+        Returns:
+            Execution result dictionary with keys:
+            - success: bool
+            - action: str (e.g., "click", "type", "press", "finish")
+            - element_id: Optional[int] (for click/type actions)
+            - text: Optional[str] (for type actions)
+            - key: Optional[str] (for press actions)
+            - outcome: Optional[str] (action outcome)
+            - url_changed: Optional[bool] (for click actions)
+            - error: Optional[str] (if action failed)
+            - message: Optional[str] (for finish action)
+
+        Raises:
+            ValueError: If action format is unknown
+            RuntimeError: If called on async browser (use execute_async instead)
+        """
+        if self._is_async:
+            raise RuntimeError(
+                "ActionExecutor.execute() called on async browser. Use execute_async() instead."
+            )
+
+        # Parse CLICK(42)
+        if match := re.match(r"CLICK\s*\(\s*(\d+)\s*\)", action_str, re.IGNORECASE):
+            element_id = int(match.group(1))
+            result = click(self.browser, element_id)  # type: ignore
+            return {
+                "success": result.success,
+                "action": "click",
+                "element_id": element_id,
+                "outcome": result.outcome,
+                "url_changed": result.url_changed,
+            }
+
+        # Parse TYPE(42, "hello world")
+        elif match := re.match(
+            r'TYPE\s*\(\s*(\d+)\s*,\s*["\']([^"\']*)["\']\s*\)',
+            action_str,
+            re.IGNORECASE,
+        ):
+            element_id = int(match.group(1))
+            text = match.group(2)
+            result = type_text(self.browser, element_id, text)  # type: ignore
+            return {
+                "success": result.success,
+                "action": "type",
+                "element_id": element_id,
+                "text": text,
+                "outcome": result.outcome,
+            }
+
+        # Parse PRESS("Enter")
+        elif match := re.match(r'PRESS\s*\(\s*["\']([^"\']+)["\']\s*\)', action_str, re.IGNORECASE):
+            key = match.group(1)
+            result = press(self.browser, key)  # type: ignore
+            return {
+                "success": result.success,
+                "action": "press",
+                "key": key,
+                "outcome": result.outcome,
+            }
+
+        # Parse FINISH()
+        elif re.match(r"FINISH\s*\(\s*\)", action_str, re.IGNORECASE):
+            return {
+                "success": True,
+                "action": "finish",
+                "message": "Task marked as complete",
+            }
+
+        else:
+            raise ValueError(
+                f"Unknown action format: {action_str}\n"
+                f'Expected: CLICK(id), TYPE(id, "text"), PRESS("key"), or FINISH()'
+            )
+
+    async def execute_async(self, action_str: str, snap: Snapshot) -> dict[str, Any]:
+        """
+        Parse action string and execute SDK call (asynchronous).
+
+        Args:
+            action_str: Action string from LLM (e.g., "CLICK(42)", "TYPE(15, \"text\")")
+            snap: Current snapshot (for context, currently unused but kept for API consistency)
+
+        Returns:
+            Execution result dictionary (same format as execute())
+
+        Raises:
+            ValueError: If action format is unknown
+            RuntimeError: If called on sync browser (use execute() instead)
+        """
+        if not self._is_async:
+            raise RuntimeError(
+                "ActionExecutor.execute_async() called on sync browser. Use execute() instead."
+            )
+
+        # Parse CLICK(42)
+        if match := re.match(r"CLICK\s*\(\s*(\d+)\s*\)", action_str, re.IGNORECASE):
+            element_id = int(match.group(1))
+            result = await click_async(self.browser, element_id)  # type: ignore
+            return {
+                "success": result.success,
+                "action": "click",
+                "element_id": element_id,
+                "outcome": result.outcome,
+                "url_changed": result.url_changed,
+            }
+
+        # Parse TYPE(42, "hello world")
+        elif match := re.match(
+            r'TYPE\s*\(\s*(\d+)\s*,\s*["\']([^"\']*)["\']\s*\)',
+            action_str,
+            re.IGNORECASE,
+        ):
+            element_id = int(match.group(1))
+            text = match.group(2)
+            result = await type_text_async(self.browser, element_id, text)  # type: ignore
+            return {
+                "success": result.success,
+                "action": "type",
+                "element_id": element_id,
+                "text": text,
+                "outcome": result.outcome,
+            }
+
+        # Parse PRESS("Enter")
+        elif match := re.match(r'PRESS\s*\(\s*["\']([^"\']+)["\']\s*\)', action_str, re.IGNORECASE):
+            key = match.group(1)
+            result = await press_async(self.browser, key)  # type: ignore
+            return {
+                "success": result.success,
+                "action": "press",
+                "key": key,
+                "outcome": result.outcome,
+            }
+
+        # Parse FINISH()
+        elif re.match(r"FINISH\s*\(\s*\)", action_str, re.IGNORECASE):
+            return {
+                "success": True,
+                "action": "finish",
+                "message": "Task marked as complete",
+            }
+
+        else:
+            raise ValueError(
+                f"Unknown action format: {action_str}\n"
+                f'Expected: CLICK(id), TYPE(id, "text"), PRESS("key"), or FINISH()'
+            )
diff --git a/sentience/agent.py b/sentience/agent.py
index 585ab48..3238f30 100644
--- a/sentience/agent.py
+++ b/sentience/agent.py
@@ -5,15 +5,15 @@
 
 import asyncio
 import hashlib
-import re
 import time
 from typing import TYPE_CHECKING, Any, Optional
 
-from .actions import click, click_async, press, press_async, type_text, type_text_async
+from .action_executor import ActionExecutor
 from .agent_config import AgentConfig
 from .base_agent import BaseAgent, BaseAgentAsync
 from .browser import AsyncSentienceBrowser, SentienceBrowser
 from .element_filter import ElementFilter
+from .llm_interaction_handler import LLMInteractionHandler
 from .llm_provider import LLMProvider, LLMResponse
 from .models import (
     ActionHistory,
@@ -83,6 +83,10 @@ def __init__(
         self.tracer = tracer
         self.config = config or AgentConfig()
 
+        # Initialize handlers
+        self.llm_handler = LLMInteractionHandler(llm)
+        self.action_executor = ActionExecutor(browser)
+
         # Screenshot sequence counter
         # Execution history
         self.history: list[dict[str, Any]] = []
@@ -241,10 +245,10 @@ def act(  # noqa: C901
                 )
 
                 # 2. GROUND: Format elements for LLM context
-                context = self._build_context(filtered_snap, goal)
+                context = self.llm_handler.build_context(filtered_snap, goal)
 
                 # 3. THINK: Query LLM for next action
-                llm_response = self._query_llm(context, goal)
+                llm_response = self.llm_handler.query_llm(context, goal)
 
                 # Emit LLM query trace event if tracer is enabled
                 if self.tracer:
@@ -266,10 +270,10 @@ def act(  # noqa: C901
                 self._track_tokens(goal, llm_response)
 
                 # Parse action from LLM response
-                action_str = self._extract_action_from_response(llm_response.content)
+                action_str = self.llm_handler.extract_action(llm_response.content)
 
                 # 4. EXECUTE: Parse and run action
-                result_dict = self._execute_action(action_str, filtered_snap)
+                result_dict = self.action_executor.execute(action_str, filtered_snap)
 
                 duration_ms = int((time.time() - start_time) * 1000)
 
@@ -465,187 +469,6 @@ def act(  # noqa: C901
                     )
                     raise RuntimeError(f"Failed after {max_retries} retries: {e}")
 
-    def _build_context(self, snap: Snapshot, goal: str) -> str:
-        """
-        Convert snapshot elements to token-efficient prompt string
-
-        Format: [ID] <role> "text" {cues} @ (x,y) (Imp:score)
-
-        Args:
-            snap: Snapshot object
-            goal: User goal (for context)
-
-        Returns:
-            Formatted element context string
-        """
-        lines = []
-        # Note: elements are already filtered by filter_elements() in act()
-        for el in snap.elements:
-            # Extract visual cues
-            cues = []
-            if el.visual_cues.is_primary:
-                cues.append("PRIMARY")
-            if el.visual_cues.is_clickable:
-                cues.append("CLICKABLE")
-            if el.visual_cues.background_color_name:
-                cues.append(f"color:{el.visual_cues.background_color_name}")
-
-            # Format element line
-            cues_str = f" {{{','.join(cues)}}}" if cues else ""
-            text_preview = (
-                (el.text[:50] + "...") if el.text and len(el.text) > 50 else (el.text or "")
-            )
-
-            lines.append(
-                f'[{el.id}] <{el.role}> "{text_preview}"{cues_str} '
-                f"@ ({int(el.bbox.x)},{int(el.bbox.y)}) (Imp:{el.importance})"
-            )
-
-        return "\n".join(lines)
-
-    def _extract_action_from_response(self, response: str) -> str:
-        """
-        Extract action command from LLM response, handling cases where
-        the LLM adds extra explanation despite instructions.
-
-        Args:
-            response: Raw LLM response text
-
-        Returns:
-            Cleaned action command string
-        """
-        import re
-
-        # Remove markdown code blocks if present
-        response = re.sub(r"```[\w]*\n?", "", response)
-        response = response.strip()
-
-        # Try to find action patterns in the response
-        # Pattern matches: CLICK(123), TYPE(123, "text"), PRESS("key"), FINISH()
-        action_pattern = r'(CLICK\s*\(\s*\d+\s*\)|TYPE\s*\(\s*\d+\s*,\s*["\'].*?["\']\s*\)|PRESS\s*\(\s*["\'].*?["\']\s*\)|FINISH\s*\(\s*\))'
-
-        match = re.search(action_pattern, response, re.IGNORECASE)
-        if match:
-            return match.group(1)
-
-        # If no pattern match, return the original response (will likely fail parsing)
-        return response
-
-    def _query_llm(self, dom_context: str, goal: str) -> LLMResponse:
-        """
-        Query LLM with standardized prompt template
-
-        Args:
-            dom_context: Formatted element context
-            goal: User goal
-
-        Returns:
-            LLMResponse from LLM provider
-        """
-        system_prompt = f"""You are an AI web automation agent.
-
-GOAL: {goal}
-
-VISIBLE ELEMENTS (sorted by importance):
-{dom_context}
-
-VISUAL CUES EXPLAINED:
-- {{PRIMARY}}: Main call-to-action element on the page
-- {{CLICKABLE}}: Element is clickable
-- {{color:X}}: Background color name
-
-CRITICAL RESPONSE FORMAT:
-You MUST respond with ONLY ONE of these exact action formats:
-- CLICK(id) - Click element by ID
-- TYPE(id, "text") - Type text into element
-- PRESS("key") - Press keyboard key (Enter, Escape, Tab, ArrowDown, etc)
-- FINISH() - Task complete
-
-DO NOT include any explanation, reasoning, or natural language.
-DO NOT use markdown formatting or code blocks.
-DO NOT say "The next step is..." or anything similar.
-
-CORRECT Examples:
-CLICK(42)
-TYPE(15, "magic mouse")
-PRESS("Enter")
-FINISH()
-
-INCORRECT Examples (DO NOT DO THIS):
-"The next step is to click..."
-"I will type..."
-```CLICK(42)```
-"""
-
-        user_prompt = "Return the single action command:"
-
-        return self.llm.generate(system_prompt, user_prompt, temperature=0.0)
-
-    def _execute_action(self, action_str: str, snap: Snapshot) -> dict[str, Any]:
-        """
-        Parse action string and execute SDK call
-
-        Args:
-            action_str: Action string from LLM (e.g., "CLICK(42)")
-            snap: Current snapshot (for context)
-
-        Returns:
-            Execution result dictionary
-        """
-        # Parse CLICK(42)
-        if match := re.match(r"CLICK\s*\(\s*(\d+)\s*\)", action_str, re.IGNORECASE):
-            element_id = int(match.group(1))
-            result = click(self.browser, element_id)
-            return {
-                "success": result.success,
-                "action": "click",
-                "element_id": element_id,
-                "outcome": result.outcome,
-                "url_changed": result.url_changed,
-            }
-
-        # Parse TYPE(42, "hello world")
-        elif match := re.match(
-            r'TYPE\s*\(\s*(\d+)\s*,\s*["\']([^"\']*)["\']\s*\)',
-            action_str,
-            re.IGNORECASE,
-        ):
-            element_id = int(match.group(1))
-            text = match.group(2)
-            result = type_text(self.browser, element_id, text)
-            return {
-                "success": result.success,
-                "action": "type",
-                "element_id": element_id,
-                "text": text,
-                "outcome": result.outcome,
-            }
-
-        # Parse PRESS("Enter")
-        elif match := re.match(r'PRESS\s*\(\s*["\']([^"\']+)["\']\s*\)', action_str, re.IGNORECASE):
-            key = match.group(1)
-            result = press(self.browser, key)
-            return {
-                "success": result.success,
-                "action": "press",
-                "key": key,
-                "outcome": result.outcome,
-            }
-
-        # Parse FINISH()
-        elif re.match(r"FINISH\s*\(\s*\)", action_str, re.IGNORECASE):
-            return {
-                "success": True,
-                "action": "finish",
-                "message": "Task marked as complete",
-            }
-
-        else:
-            raise ValueError(
-                f"Unknown action format: {action_str}\n"
-                f'Expected: CLICK(id), TYPE(id, "text"), PRESS("key"), or FINISH()'
-            )
-
     def _track_tokens(self, goal: str, llm_response: LLMResponse):
         """
         Track token usage for analytics
@@ -772,6 +595,10 @@ def __init__(
         self.tracer = tracer
         self.config = config or AgentConfig()
 
+        # Initialize handlers
+        self.llm_handler = LLMInteractionHandler(llm)
+        self.action_executor = ActionExecutor(browser)
+
         # Screenshot sequence counter
         # Execution history
         self.history: list[dict[str, Any]] = []
@@ -930,10 +757,10 @@ async def act(  # noqa: C901
                 )
 
                 # 2. GROUND: Format elements for LLM context
-                context = self._build_context(filtered_snap, goal)
+                context = self.llm_handler.build_context(filtered_snap, goal)
 
                 # 3. THINK: Query LLM for next action
-                llm_response = self._query_llm(context, goal)
+                llm_response = self.llm_handler.query_llm(context, goal)
 
                 # Emit LLM query trace event if tracer is enabled
                 if self.tracer:
@@ -955,10 +782,10 @@ async def act(  # noqa: C901
                 self._track_tokens(goal, llm_response)
 
                 # Parse action from LLM response
-                action_str = self._extract_action_from_response(llm_response.content)
+                action_str = self.llm_handler.extract_action(llm_response.content)
 
                 # 4. EXECUTE: Parse and run action
-                result_dict = await self._execute_action(action_str, filtered_snap)
+                result_dict = await self.action_executor.execute_async(action_str, filtered_snap)
 
                 duration_ms = int((time.time() - start_time) * 1000)
 
@@ -1154,156 +981,6 @@ async def act(  # noqa: C901
                     )
                     raise RuntimeError(f"Failed after {max_retries} retries: {e}")
 
-    def _build_context(self, snap: Snapshot, goal: str) -> str:
-        """Convert snapshot elements to token-efficient prompt string (same as sync version)"""
-        lines = []
-        # Note: elements are already filtered by filter_elements() in act()
-        for el in snap.elements:
-            # Extract visual cues
-            cues = []
-            if el.visual_cues.is_primary:
-                cues.append("PRIMARY")
-            if el.visual_cues.is_clickable:
-                cues.append("CLICKABLE")
-            if el.visual_cues.background_color_name:
-                cues.append(f"color:{el.visual_cues.background_color_name}")
-
-            # Format element line
-            cues_str = f" {{{','.join(cues)}}}" if cues else ""
-            text_preview = (
-                (el.text[:50] + "...") if el.text and len(el.text) > 50 else (el.text or "")
-            )
-
-            lines.append(
-                f'[{el.id}] <{el.role}> "{text_preview}"{cues_str} '
-                f"@ ({int(el.bbox.x)},{int(el.bbox.y)}) (Imp:{el.importance})"
-            )
-
-        return "\n".join(lines)
-
-    def _extract_action_from_response(self, response: str) -> str:
-        """Extract action command from LLM response (same as sync version)"""
-        # Remove markdown code blocks if present
-        response = re.sub(r"```[\w]*\n?", "", response)
-        response = response.strip()
-
-        # Try to find action patterns in the response
-        # Pattern matches: CLICK(123), TYPE(123, "text"), PRESS("key"), FINISH()
-        action_pattern = r'(CLICK\s*\(\s*\d+\s*\)|TYPE\s*\(\s*\d+\s*,\s*["\'].*?["\']\s*\)|PRESS\s*\(\s*["\'].*?["\']\s*\)|FINISH\s*\(\s*\))'
-
-        match = re.search(action_pattern, response, re.IGNORECASE)
-        if match:
-            return match.group(1)
-
-        # If no pattern match, return the original response (will likely fail parsing)
-        return response
-
-    def _query_llm(self, dom_context: str, goal: str) -> LLMResponse:
-        """Query LLM with standardized prompt template (same as sync version)"""
-        system_prompt = f"""You are an AI web automation agent.
-
-GOAL: {goal}
-
-VISIBLE ELEMENTS (sorted by importance):
-{dom_context}
-
-VISUAL CUES EXPLAINED:
-- {{PRIMARY}}: Main call-to-action element on the page
-- {{CLICKABLE}}: Element is clickable
-- {{color:X}}: Background color name
-
-CRITICAL RESPONSE FORMAT:
-You MUST respond with ONLY ONE of these exact action formats:
-- CLICK(id) - Click element by ID
-- TYPE(id, "text") - Type text into element
-- PRESS("key") - Press keyboard key (Enter, Escape, Tab, ArrowDown, etc)
-- FINISH() - Task complete
-
-DO NOT include any explanation, reasoning, or natural language.
-DO NOT use markdown formatting or code blocks.
-DO NOT say "The next step is..." or anything similar.
-
-CORRECT Examples:
-CLICK(42)
-TYPE(15, "magic mouse")
-PRESS("Enter")
-FINISH()
-
-INCORRECT Examples (DO NOT DO THIS):
-"The next step is to click..."
-"I will type..."
-```CLICK(42)```
-"""
-
-        user_prompt = "Return the single action command:"
-
-        return self.llm.generate(system_prompt, user_prompt, temperature=0.0)
-
-    async def _execute_action(self, action_str: str, snap: Snapshot) -> dict[str, Any]:
-        """
-        Parse action string and execute SDK call (async)
-
-        Args:
-            action_str: Action string from LLM (e.g., "CLICK(42)")
-            snap: Current snapshot (for context)
-
-        Returns:
-            Execution result dictionary
-        """
-        # Parse CLICK(42)
-        if match := re.match(r"CLICK\s*\(\s*(\d+)\s*\)", action_str, re.IGNORECASE):
-            element_id = int(match.group(1))
-            result = await click_async(self.browser, element_id)
-            return {
-                "success": result.success,
-                "action": "click",
-                "element_id": element_id,
-                "outcome": result.outcome,
-                "url_changed": result.url_changed,
-            }
-
-        # Parse TYPE(42, "hello world")
-        elif match := re.match(
-            r'TYPE\s*\(\s*(\d+)\s*,\s*["\']([^"\']*)["\']\s*\)',
-            action_str,
-            re.IGNORECASE,
-        ):
-            element_id = int(match.group(1))
-            text = match.group(2)
-            result = await type_text_async(self.browser, element_id, text)
-            return {
-                "success": result.success,
-                "action": "type",
-                "element_id": element_id,
-                "text": text,
-                "outcome": result.outcome,
-            }
-
-        # Parse PRESS("Enter")
-        elif match := re.match(r'PRESS\s*\(\s*["\']([^"\']+)["\']\s*\)', action_str, re.IGNORECASE):
-            key = match.group(1)
-            result = await press_async(self.browser, key)
-            return {
-                "success": result.success,
-                "action": "press",
-                "key": key,
-                "outcome": result.outcome,
-            }
-
-        # Parse FINISH()
-        elif re.match(r"FINISH\s*\(\s*\)", action_str, re.IGNORECASE):
-            return {
-                "success": True,
-                "action": "finish",
-                "message": "Task marked as complete",
-            }
-
-        else:
-            raise ValueError(
-                f"Unknown action format: {action_str}\n"
-                f'Expected: CLICK(id), TYPE(id, "text"), PRESS("key"), or FINISH()'
-            )
-
     def _track_tokens(self, goal: str, llm_response: LLMResponse):
         """Track token usage for analytics (same as sync version)"""
         if llm_response.prompt_tokens:
diff --git a/sentience/element_filter.py b/sentience/element_filter.py
index 6159115..df117b9 100644
--- a/sentience/element_filter.py
+++ b/sentience/element_filter.py
@@ -64,7 +64,7 @@ def filter_by_importance(
     @staticmethod
     def filter_by_goal(
         snapshot: Snapshot,
-        goal: Optional[str],
+        goal: str | None,
         max_elements: int = 50,
     ) -> list[Element]:
         """
diff --git a/sentience/llm_interaction_handler.py b/sentience/llm_interaction_handler.py
new file mode 100644
index 0000000..008e155
--- /dev/null
+++ b/sentience/llm_interaction_handler.py
@@ -0,0 +1,146 @@
+"""
+LLM Interaction Handler for Sentience Agent.
+
+Handles all LLM-related operations: context building, querying, and response parsing.
+This separates LLM interaction concerns from action execution.
+"""
+
+import re
+from typing import Optional
+
+from .llm_provider import LLMProvider, LLMResponse
+from .models import Snapshot
+
+
+class LLMInteractionHandler:
+    """
+    Handles LLM queries and response parsing for Sentience Agent.
+
+    This class encapsulates all LLM interaction logic, making it easier to:
+    - Test LLM interactions independently
+    - Swap LLM providers without changing agent code
+    - Modify prompt templates in one place
+    """
+
+    def __init__(self, llm: LLMProvider):
+        """
+        Initialize LLM interaction handler.
+
+        Args:
+            llm: LLM provider instance (OpenAIProvider, AnthropicProvider, etc.)
+        """
+        self.llm = llm
+
+    def build_context(self, snap: Snapshot, goal: str | None = None) -> str:
+        """
+        Convert snapshot elements to token-efficient prompt string.
+
+        Format: [ID] <role> "text" {cues} @ (x,y) (Imp:score)
+
+        Args:
+            snap: Snapshot object
+            goal: Optional user goal (for context, currently unused but kept for API consistency)
+
+        Returns:
+            Formatted element context string
+        """
+        lines = []
+        for el in snap.elements:
+            # Extract visual cues
+            cues = []
+            if el.visual_cues.is_primary:
+                cues.append("PRIMARY")
+            if el.visual_cues.is_clickable:
+                cues.append("CLICKABLE")
+            if el.visual_cues.background_color_name:
+                cues.append(f"color:{el.visual_cues.background_color_name}")
+
+            # Format element line
+            cues_str = f" {{{','.join(cues)}}}" if cues else ""
+            text_preview = (
+                (el.text[:50] + "...") if el.text and len(el.text) > 50 else (el.text or "")
+            )
+
+            lines.append(
+                f'[{el.id}] <{el.role}> "{text_preview}"{cues_str} '
+                f"@ ({int(el.bbox.x)},{int(el.bbox.y)}) (Imp:{el.importance})"
+            )
+
+        return "\n".join(lines)
+
+    def query_llm(self, dom_context: str, goal: str) -> LLMResponse:
+        """
+        Query LLM with standardized prompt template.
+
+        Args:
+            dom_context: Formatted element context from build_context()
+            goal: User goal
+
+        Returns:
+            LLMResponse from LLM provider
+        """
+        system_prompt = f"""You are an AI web automation agent.
+
+GOAL: {goal}
+
+VISIBLE ELEMENTS (sorted by importance):
+{dom_context}
+
+VISUAL CUES EXPLAINED:
+- {{PRIMARY}}: Main call-to-action element on the page
+- {{CLICKABLE}}: Element is clickable
+- {{color:X}}: Background color name
+
+CRITICAL RESPONSE FORMAT:
+You MUST respond with ONLY ONE of these exact action formats:
+- CLICK(id) - Click element by ID
+- TYPE(id, "text") - Type text into element
+- PRESS("key") - Press keyboard key (Enter, Escape, Tab, ArrowDown, etc)
+- FINISH() - Task complete
+
+DO NOT include any explanation, reasoning, or natural language.
+DO NOT use markdown formatting or code blocks.
+DO NOT say "The next step is..." or anything similar.
+
+CORRECT Examples:
+CLICK(42)
+TYPE(15, "magic mouse")
+PRESS("Enter")
+FINISH()
+
+INCORRECT Examples (DO NOT DO THIS):
+"The next step is to click..."
+"I will type..."
+```CLICK(42)```
+"""
+
+        user_prompt = "Return the single action command:"
+
+        return self.llm.generate(system_prompt, user_prompt, temperature=0.0)
+
+    def extract_action(self, response: str) -> str:
+        """
+        Extract action command from LLM response.
+
+        Handles cases where the LLM adds extra explanation despite instructions.
+
+        Args:
+            response: Raw LLM response text
+
+        Returns:
+            Cleaned action command string (e.g., "CLICK(42)", "TYPE(15, \"text\")")
+        """
+        # Remove markdown code blocks if present
+        response = re.sub(r"```[\w]*\n?", "", response)
+        response = response.strip()
+
+        # Try to find action patterns in the response
+        # Pattern matches: CLICK(123), TYPE(123, "text"), PRESS("key"), FINISH()
+        action_pattern = r'(CLICK\s*\(\s*\d+\s*\)|TYPE\s*\(\s*\d+\s*,\s*["\'].*?["\']\s*\)|PRESS\s*\(\s*["\'].*?["\']\s*\)|FINISH\s*\(\s*\))'
+
+        match = re.search(action_pattern, response, re.IGNORECASE)
+        if match:
+            return match.group(1)
+
+        # If no pattern match, return the original response (will likely fail parsing)
+        return response
diff --git a/sentience/utils/__init__.py b/sentience/utils/__init__.py
index a5d4d78..7f8f303 100644
--- a/sentience/utils/__init__.py
+++ b/sentience/utils/__init__.py
@@ -38,4 +38,3 @@
     # Formatting utilities
     "format_snapshot_for_llm",
 ]
-
diff --git a/sentience/utils/browser.py b/sentience/utils/browser.py
index 8b42271..20a2132 100644
--- a/sentience/utils/browser.py
+++ b/sentience/utils/browser.py
@@ -44,4 +44,3 @@ def save_storage_state(context: BrowserContext, file_path: str | Path) -> None:
     with open(file_path_obj, "w") as f:
         json.dump(storage_state, f, indent=2)
     print(f"✅ [Sentience] Saved storage state to {file_path_obj}")
-
diff --git a/sentience/utils/element.py b/sentience/utils/element.py
index 6ab947c..6269f7f 100644
--- a/sentience/utils/element.py
+++ b/sentience/utils/element.py
@@ -76,7 +76,7 @@ def to_dict(self) -> dict[str, Any]:
         return data
 
 
-def normalize_text_strict(text: Optional[str], max_length: int = 80) -> str:
+def normalize_text_strict(text: str | None, max_length: int = 80) -> str:
     """
     Normalize text for strict digest (structure + content).
 
@@ -255,4 +255,3 @@ def compute_snapshot_digests(elements: list[dict[str, Any]]) -> dict[str, str]:
         "strict": sha256_digest(canonical_strict),
         "loose": sha256_digest(canonical_loose),
     }
-
diff --git a/sentience/utils/formatting.py b/sentience/utils/formatting.py
index 2271477..5b2ef19 100644
--- a/sentience/utils/formatting.py
+++ b/sentience/utils/formatting.py
@@ -57,4 +57,3 @@ def format_snapshot_for_llm(snap: Snapshot, limit: int = 50) -> str:
         )
 
     return "\n".join(lines)
-
diff --git a/tests/test_agent.py b/tests/test_agent.py
index 259042a..8a8c7e8 100644
--- a/tests/test_agent.py
+++ b/tests/test_agent.py
@@ -174,7 +174,7 @@ def test_agent_build_context():
     agent = SentienceAgent(browser, llm, verbose=False)
 
     snap = create_mock_snapshot()
-    context = agent._build_context(snap, "test goal")
+    context = agent.llm_handler.build_context(snap, "test goal")
 
     # Should contain both elements
     assert "[1]" in context
@@ -196,15 +196,15 @@ def test_agent_execute_click_action():
 
     snap = create_mock_snapshot()
 
-    # Mock click function
-    with patch("sentience.agent.click") as mock_click:
+    # Mock click function via ActionExecutor
+    with patch("sentience.action_executor.click") as mock_click:
         from sentience.models import ActionResult
 
         mock_click.return_value = ActionResult(
             success=True, duration_ms=150, outcome="dom_updated", url_changed=False
         )
 
-        result = agent._execute_action("CLICK(1)", snap)
+        result = agent.action_executor.execute("CLICK(1)", snap)
 
         assert result["success"] is True
         assert result["action"] == "click"
@@ -220,13 +220,13 @@ def test_agent_execute_type_action():
 
     snap = create_mock_snapshot()
 
-    # Mock type_text function
-    with patch("sentience.agent.type_text") as mock_type:
+    # Mock type_text function via ActionExecutor
+    with patch("sentience.action_executor.type_text") as mock_type:
         from sentience.models import ActionResult
 
         mock_type.return_value = ActionResult(success=True, duration_ms=200, outcome="dom_updated")
 
-        result = agent._execute_action('TYPE(2, "hello world")', snap)
+        result = agent.action_executor.execute('TYPE(2, "hello world")', snap)
 
         assert result["success"] is True
         assert result["action"] == "type"
@@ -243,13 +243,13 @@ def test_agent_execute_press_action():
 
     snap = create_mock_snapshot()
 
-    # Mock press function
-    with patch("sentience.agent.press") as mock_press:
+    # Mock press function via ActionExecutor
+    with patch("sentience.action_executor.press") as mock_press:
         from sentience.models import ActionResult
 
         mock_press.return_value = ActionResult(success=True, duration_ms=50, outcome="dom_updated")
 
-        result = agent._execute_action('PRESS("Enter")', snap)
+        result = agent.action_executor.execute('PRESS("Enter")', snap)
 
         assert result["success"] is True
         assert result["action"] == "press"
@@ -264,7 +264,7 @@ def test_agent_execute_finish_action():
     agent = SentienceAgent(browser, llm, verbose=False)
 
     snap = create_mock_snapshot()
-    result = agent._execute_action("FINISH()", snap)
+    result = agent.action_executor.execute("FINISH()", snap)
 
     assert result["success"] is True
     assert result["action"] == "finish"
@@ -279,7 +279,7 @@ def test_agent_execute_invalid_action():
     snap = create_mock_snapshot()
 
     with pytest.raises(ValueError, match="Unknown action format"):
-        agent._execute_action("INVALID_ACTION", snap)
+        agent.action_executor.execute("INVALID_ACTION", snap)
 
 
 def test_agent_act_full_cycle():
@@ -291,7 +291,7 @@ def test_agent_act_full_cycle():
     # Mock snapshot and click
     with (
         patch("sentience.agent.snapshot") as mock_snapshot,
-        patch("sentience.agent.click") as mock_click,
+        patch("sentience.action_executor.click") as mock_click,
     ):
         from sentience.models import ActionResult
 
@@ -389,7 +389,7 @@ def test_agent_retry_on_failure():
     # Mock snapshot and click (click will fail)
     with (
         patch("sentience.agent.snapshot") as mock_snapshot,
-        patch("sentience.agent.click") as mock_click,
+        patch("sentience.action_executor.click") as mock_click,
     ):
         mock_snapshot.return_value = create_mock_snapshot()
         # Simulate click failure
@@ -411,9 +411,9 @@ def test_agent_action_parsing_variations():
     snap = create_mock_snapshot()
 
     with (
-        patch("sentience.agent.click") as mock_click,
-        patch("sentience.agent.type_text") as mock_type,
-        patch("sentience.agent.press") as mock_press,
+        patch("sentience.action_executor.click") as mock_click,
+        patch("sentience.action_executor.type_text") as mock_type,
+        patch("sentience.action_executor.press") as mock_press,
     ):
         from sentience.models import ActionResult
 
@@ -423,11 +423,11 @@ def test_agent_action_parsing_variations():
         mock_press.return_value = mock_result
 
         # Test variations
-        agent._execute_action("click(1)", snap)  # lowercase
-        agent._execute_action("CLICK( 1 )", snap)  # extra spaces
-        agent._execute_action("TYPE(2, 'single quotes')", snap)  # single quotes
-        agent._execute_action("PRESS('Enter')", snap)  # single quotes
-        agent._execute_action("finish()", snap)  # lowercase finish
+        agent.action_executor.execute("click(1)", snap)  # lowercase
+        agent.action_executor.execute("CLICK( 1 )", snap)  # extra spaces
+        agent.action_executor.execute("TYPE(2, 'single quotes')", snap)  # single quotes
+        agent.action_executor.execute("PRESS('Enter')", snap)  # single quotes
+        agent.action_executor.execute("finish()", snap)  # lowercase finish
 
         assert mock_click.call_count == 2
         assert mock_type.call_count == 1
@@ -441,29 +441,28 @@ def test_agent_extract_action_from_llm_response():
     agent = SentienceAgent(browser, llm, verbose=False)
 
     # Test clean action (should pass through)
-    assert agent._extract_action_from_response("CLICK(42)") == "CLICK(42)"
-    assert agent._extract_action_from_response('TYPE(15, "test")') == 'TYPE(15, "test")'
-    assert agent._extract_action_from_response('PRESS("Enter")') == 'PRESS("Enter")'
-    assert agent._extract_action_from_response("FINISH()") == "FINISH()"
+    assert agent.llm_handler.extract_action("CLICK(42)") == "CLICK(42)"
+    assert agent.llm_handler.extract_action('TYPE(15, "test")') == 'TYPE(15, "test")'
+    assert agent.llm_handler.extract_action('PRESS("Enter")') == 'PRESS("Enter")'
+    assert agent.llm_handler.extract_action("FINISH()") == "FINISH()"
 
     # Test with natural language prefix (the bug case)
     assert (
-        agent._extract_action_from_response("The next step is to click the button. CLICK(42)")
+        agent.llm_handler.extract_action("The next step is to click the button. CLICK(42)")
         == "CLICK(42)"
     )
     assert (
-        agent._extract_action_from_response(
+        agent.llm_handler.extract_action(
             'The next step is to type "Sentience AI agent SDK" into the search field. TYPE(15, "Sentience AI agent SDK")'
         )
         == 'TYPE(15, "Sentience AI agent SDK")'
     )
 
     # Test with markdown code blocks
-    assert agent._extract_action_from_response("```\nCLICK(42)\n```") == "CLICK(42)"
+    assert agent.llm_handler.extract_action("```\nCLICK(42)\n```") == "CLICK(42)"
     assert (
-        agent._extract_action_from_response('```python\nTYPE(15, "test")\n```')
-        == 'TYPE(15, "test")'
+        agent.llm_handler.extract_action('```python\nTYPE(15, "test")\n```') == 'TYPE(15, "test")'
     )
 
     # Test with explanation after action
-    assert agent._extract_action_from_response("CLICK(42) to submit the form") == "CLICK(42)"
+    assert agent.llm_handler.extract_action("CLICK(42) to submit the form") == "CLICK(42)"
diff --git a/tests/test_llm_provider_utils.py b/tests/test_llm_provider_utils.py
index 4723dcc..f5f89dc 100644
--- a/tests/test_llm_provider_utils.py
+++ b/tests/test_llm_provider_utils.py
@@ -94,4 +94,3 @@ def test_handle_provider_error_generic():
     error = Exception("Network timeout")
     with pytest.raises(RuntimeError, match="Gemini generate response failed: Network timeout"):
         handle_provider_error(error, "Gemini", "generate response")
-
diff --git a/tests/test_llm_response_builder.py b/tests/test_llm_response_builder.py
index f39d2da..9ac2f14 100644
--- a/tests/test_llm_response_builder.py
+++ b/tests/test_llm_response_builder.py
@@ -93,4 +93,3 @@ def test_from_local_format(self):
         assert response.total_tokens == 30
         assert response.model_name == "Qwen/Qwen2.5-3B-Instruct"
         assert response.finish_reason is None
-
diff --git a/tests/test_trace_file_manager.py b/tests/test_trace_file_manager.py
index 014bbbe..3774299 100644
--- a/tests/test_trace_file_manager.py
+++ b/tests/test_trace_file_manager.py
@@ -112,4 +112,3 @@ def test_read_events_file_not_found(self):
         """Test that FileNotFoundError is raised for non-existent file"""
         with pytest.raises(FileNotFoundError):
             TraceFileManager.read_events(Path("/nonexistent/file.jsonl"))
-
diff --git a/tests/test_trace_file_manager_extract_stats.py b/tests/test_trace_file_manager_extract_stats.py
index 45ded88..f8fbce6 100644
--- a/tests/test_trace_file_manager_extract_stats.py
+++ b/tests/test_trace_file_manager_extract_stats.py
@@ -135,6 +135,7 @@ def test_extract_stats_uses_run_end_status():
 
 def test_extract_stats_with_custom_inference():
     """Test extract_stats uses custom status inference function."""
+
     def custom_inference(events, run_end):
         # Return a valid status value
         return "partial"
@@ -162,4 +163,3 @@ def test_extract_stats_no_timestamps():
     assert stats.duration_ms is None
     assert stats.started_at is None
     assert stats.ended_at is None
-