From 68ad42eb53fc3120a12076881af01765ee5fb098 Mon Sep 17 00:00:00 2001
From: rcholic <ivytony@gmail.com>
Date: Fri, 26 Dec 2025 07:43:57 -0800
Subject: [PATCH 1/5] Phase 1.1-1.2 Producer

---
 .python-version                    |   1 +
 MANIFEST.in                        |   5 +-
 sentience/__init__.py              |  31 ++-
 sentience/agent_config.py          |  43 ++++
 sentience/browser.py               |  14 ++
 sentience/cli.py                   |   2 -
 sentience/formatting.py            |  59 ++++++
 sentience/inspector.py             |   4 -
 sentience/schemas/trace_v1.json    | 216 ++++++++++++++++++++
 sentience/tracing.py               | 257 ++++++++++++++++++++++++
 sentience/utils.py                 | 257 ++++++++++++++++++++++++
 sentience_python.egg-info/PKG-INFO |   2 +-
 tests/test_agent_config.py         | 119 +++++++++++
 tests/test_formatting.py           | 219 ++++++++++++++++++++
 tests/test_inspector.py            |   2 -
 tests/test_recorder.py             |   5 +-
 tests/test_smart_selector.py       |   2 -
 tests/test_stealth.py              |   8 +-
 tests/test_tracing.py              | 209 +++++++++++++++++++
 tests/test_utils.py                | 311 +++++++++++++++++++++++++++++
 20 files changed, 1742 insertions(+), 24 deletions(-)
 create mode 100644 .python-version
 create mode 100644 sentience/agent_config.py
 create mode 100644 sentience/formatting.py
 create mode 100644 sentience/schemas/trace_v1.json
 create mode 100644 sentience/tracing.py
 create mode 100644 sentience/utils.py
 create mode 100644 tests/test_agent_config.py
 create mode 100644 tests/test_formatting.py
 create mode 100644 tests/test_tracing.py
 create mode 100644 tests/test_utils.py

diff --git a/.python-version b/.python-version
new file mode 100644
index 0000000..9ac3804
--- /dev/null
+++ b/.python-version
@@ -0,0 +1 @@
+3.11.5
diff --git a/MANIFEST.in b/MANIFEST.in
index 921b4e2..1cc7b2a 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,4 +1 @@
-include README.md
-include LICENSE
-recursive-include spec *
-recursive-include sentience *.py
+include sentience/schemas/*.json
diff --git a/sentience/__init__.py b/sentience/__init__.py
index edec2ab..2ac9c18 100644
--- a/sentience/__init__.py
+++ b/sentience/__init__.py
@@ -4,12 +4,16 @@
 
 from .actions import click, click_rect, press, type_text
 from .agent import SentienceAgent
+from .agent_config import AgentConfig
 
 # Agent Layer (Phase 1 & 2)
 from .base_agent import BaseAgent
 from .browser import SentienceBrowser
 from .conversational_agent import ConversationalAgent
 from .expect import expect
+
+# Formatting (v0.12.0+)
+from .formatting import format_snapshot_for_llm
 from .generator import ScriptGenerator, generate
 from .inspector import Inspector, inspect
 from .llm_provider import (
@@ -39,9 +43,20 @@
 from .recorder import Recorder, Trace, TraceStep, record
 from .screenshot import screenshot
 from .snapshot import snapshot
+
+# Tracing (v0.12.0+)
+from .tracing import JsonlTraceSink, TraceEvent, Tracer, TraceSink
+
+# Utilities (v0.12.0+)
+from .utils import (
+    canonical_snapshot_loose,
+    canonical_snapshot_strict,
+    compute_snapshot_digests,
+    sha256_digest,
+)
 from .wait import wait_for
 
-__version__ = "0.11.0"
+__version__ = "0.12.0"
 
 __all__ = [
     # Core SDK
@@ -88,4 +103,18 @@
     "SnapshotOptions",
     "SnapshotFilter",
     "ScreenshotConfig",
+    # Tracing (v0.12.0+)
+    "Tracer",
+    "TraceSink",
+    "JsonlTraceSink",
+    "TraceEvent",
+    # Utilities (v0.12.0+)
+    "canonical_snapshot_strict",
+    "canonical_snapshot_loose",
+    "compute_snapshot_digests",
+    "sha256_digest",
+    # Formatting (v0.12.0+)
+    "format_snapshot_for_llm",
+    # Agent Config (v0.12.0+)
+    "AgentConfig",
 ]
diff --git a/sentience/agent_config.py b/sentience/agent_config.py
new file mode 100644
index 0000000..dbddb41
--- /dev/null
+++ b/sentience/agent_config.py
@@ -0,0 +1,43 @@
+"""
+Configuration classes for Sentience agents.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class AgentConfig:
+    """
+    Configuration for Sentience Agent execution.
+
+    This dataclass provides centralized configuration for agent behavior,
+    including snapshot limits, retry logic, verification, and screenshot capture.
+
+    Attributes:
+        snapshot_limit: Maximum elements to include in LLM context (default: 50)
+        temperature: LLM temperature 0.0-1.0 for response generation (default: 0.0)
+        max_retries: Number of retries on action failure (default: 1)
+        verify: Whether to run verification step after actions (default: True)
+        capture_screenshots: Whether to capture screenshots during execution (default: True)
+        screenshot_format: Screenshot format 'png' or 'jpeg' (default: 'jpeg')
+        screenshot_quality: JPEG quality 1-100, ignored for PNG (default: 80)
+
+    Example:
+        >>> from sentience import AgentConfig, SentienceAgent
+        >>> config = AgentConfig(
+        ...     snapshot_limit=100,
+        ...     max_retries=2,
+        ...     verify=True
+        ... )
+        >>> agent = SentienceAgent(browser, llm, config=config)
+    """
+
+    snapshot_limit: int = 50
+    temperature: float = 0.0
+    max_retries: int = 1
+    verify: bool = True
+
+    # Screenshot options
+    capture_screenshots: bool = True
+    screenshot_format: str = "jpeg"  # "png" or "jpeg"
+    screenshot_quality: int = 80  # 1-100 (for JPEG only)
diff --git a/sentience/browser.py b/sentience/browser.py
index cbeff56..b83357c 100644
--- a/sentience/browser.py
+++ b/sentience/browser.py
@@ -75,8 +75,10 @@ def start(self) -> None:
 
         if package_ext_path.exists() and (package_ext_path / "manifest.json").exists():
             extension_source = package_ext_path
+            print(f"[SentienceBrowser] Loading SDK extension from: {package_ext_path}")
         elif dev_ext_path.exists() and (dev_ext_path / "manifest.json").exists():
             extension_source = dev_ext_path
+            print(f"[SentienceBrowser] Loading SDK extension from (dev): {dev_ext_path}")
         else:
             raise FileNotFoundError(
                 f"Extension not found. Checked:\n"
@@ -85,6 +87,18 @@ def start(self) -> None:
                 "Make sure the extension is built and 'sentience/extension' directory exists."
             )
 
+        # Print extension version for debugging
+        import json
+
+        try:
+            with open(extension_source / "manifest.json") as f:
+                manifest = json.load(f)
+                print(
+                    f"[SentienceBrowser] SDK extension version: {manifest.get('version', 'unknown')}"
+                )
+        except Exception:
+            pass
+
         # Create temporary extension bundle
         # We copy it to a temp dir to avoid file locking issues and ensure clean state
         self._extension_path = tempfile.mkdtemp(prefix="sentience-ext-")
diff --git a/sentience/cli.py b/sentience/cli.py
index a7f0ef4..64112e9 100644
--- a/sentience/cli.py
+++ b/sentience/cli.py
@@ -75,11 +75,9 @@ def cmd_gen(args):
     generator = ScriptGenerator(trace)
 
     if args.lang == "py":
-        code = generator.generate_python()
         output = args.output or "generated.py"
         generator.save_python(output)
     elif args.lang == "ts":
-        code = generator.generate_typescript()
         output = args.output or "generated.ts"
         generator.save_typescript(output)
     else:
diff --git a/sentience/formatting.py b/sentience/formatting.py
new file mode 100644
index 0000000..f8961c5
--- /dev/null
+++ b/sentience/formatting.py
@@ -0,0 +1,59 @@
+"""
+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)
diff --git a/sentience/inspector.py b/sentience/inspector.py
index c6abe91..04d128e 100644
--- a/sentience/inspector.py
+++ b/sentience/inspector.py
@@ -2,11 +2,7 @@
 Inspector tool - helps developers see what the agent "sees"
 """
 
-from typing import Optional
-
 from .browser import SentienceBrowser
-from .query import find
-from .snapshot import snapshot
 
 
 class Inspector:
diff --git a/sentience/schemas/trace_v1.json b/sentience/schemas/trace_v1.json
new file mode 100644
index 0000000..5cec1de
--- /dev/null
+++ b/sentience/schemas/trace_v1.json
@@ -0,0 +1,216 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://sentience.ai/schemas/trace/v1",
+  "title": "Sentience Agent Trace Event",
+  "description": "Schema for Sentience agent trace events in JSONL format",
+  "type": "object",
+  "required": ["v", "type", "ts", "run_id", "seq", "data"],
+  "properties": {
+    "v": {
+      "type": "integer",
+      "const": 1,
+      "description": "Schema version"
+    },
+    "type": {
+      "type": "string",
+      "enum": ["run_start", "step_start", "snapshot_taken", "llm_called", "action_executed", "verification", "recovery", "step_end", "run_end", "error"],
+      "description": "Event type"
+    },
+    "ts": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp"
+    },
+    "ts_ms": {
+      "type": "integer",
+      "description": "Unix timestamp in milliseconds"
+    },
+    "run_id": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+      "description": "UUID for the agent run"
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Monotonically increasing sequence number"
+    },
+    "step_id": {
+      "type": ["string", "null"],
+      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+      "description": "UUID for the step (present for step-scoped events)"
+    },
+    "data": {
+      "type": "object",
+      "description": "Event-specific payload",
+      "oneOf": [
+        {
+          "description": "run_start data",
+          "properties": {
+            "agent": {"type": "string"},
+            "llm_model": {"type": ["string", "null"]},
+            "config": {"type": "object"}
+          }
+        },
+        {
+          "description": "step_start data",
+          "required": ["step_id", "step_index", "goal", "attempt"],
+          "properties": {
+            "step_id": {"type": "string"},
+            "step_index": {"type": "integer"},
+            "goal": {"type": "string"},
+            "attempt": {"type": "integer"},
+            "pre_url": {"type": ["string", "null"]}
+          }
+        },
+        {
+          "description": "snapshot_taken data",
+          "required": ["step_id", "snapshot_digest"],
+          "properties": {
+            "step_id": {"type": "string"},
+            "snapshot_id": {"type": ["string", "null"]},
+            "snapshot_digest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
+            "snapshot_digest_loose": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
+            "url": {"type": ["string", "null"]},
+            "element_count": {"type": "integer"}
+          }
+        },
+        {
+          "description": "llm_called data",
+          "required": ["step_id", "response_text", "response_hash"],
+          "properties": {
+            "step_id": {"type": "string"},
+            "model": {"type": ["string", "null"]},
+            "temperature": {"type": "number"},
+            "system_prompt_hash": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
+            "user_prompt_hash": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
+            "response_text": {"type": "string"},
+            "response_hash": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
+            "usage": {
+              "type": "object",
+              "properties": {
+                "prompt_tokens": {"type": "integer"},
+                "completion_tokens": {"type": "integer"},
+                "total_tokens": {"type": "integer"}
+              }
+            }
+          }
+        },
+        {
+          "description": "step_end data (StepResult)",
+          "required": ["step_id", "step_index", "goal", "attempt", "pre", "llm", "exec", "post", "verify"],
+          "properties": {
+            "v": {"type": "integer", "const": 1},
+            "step_id": {"type": "string"},
+            "step_index": {"type": "integer"},
+            "goal": {"type": "string"},
+            "attempt": {"type": "integer"},
+            "pre": {
+              "type": "object",
+              "required": ["snapshot_digest"],
+              "properties": {
+                "url": {"type": ["string", "null"]},
+                "snapshot_digest": {"type": "string"},
+                "snapshot_digest_loose": {"type": "string"}
+              }
+            },
+            "llm": {
+              "type": "object",
+              "required": ["response_text", "response_hash"],
+              "properties": {
+                "response_text": {"type": "string"},
+                "response_hash": {"type": "string"}
+              }
+            },
+            "action": {
+              "type": "object",
+              "required": ["kind"],
+              "properties": {
+                "kind": {"type": "string", "enum": ["click", "type", "press", "finish", "navigate"]},
+                "element_id": {"type": "integer"},
+                "text": {"type": "string"},
+                "key": {"type": "string"},
+                "url": {"type": "string"},
+                "raw": {"type": "string"}
+              }
+            },
+            "exec": {
+              "type": "object",
+              "required": ["success", "outcome", "duration_ms"],
+              "properties": {
+                "success": {"type": "boolean"},
+                "outcome": {"type": "string"},
+                "action": {"type": "string"},
+                "element_id": {"type": "integer"},
+                "text": {"type": "string"},
+                "key": {"type": "string"},
+                "url_changed": {"type": ["boolean", "null"]},
+                "duration_ms": {"type": "integer"}
+              }
+            },
+            "post": {
+              "type": "object",
+              "properties": {
+                "url": {"type": ["string", "null"]},
+                "snapshot_digest": {"type": "string"},
+                "snapshot_digest_loose": {"type": "string"}
+              }
+            },
+            "verify": {
+              "type": "object",
+              "required": ["passed"],
+              "properties": {
+                "policy": {"type": "string"},
+                "passed": {"type": "boolean"},
+                "signals": {"type": "object"}
+              }
+            },
+            "recovery": {
+              "type": ["object", "null"],
+              "properties": {
+                "attempted": {"type": "boolean"},
+                "success": {"type": "boolean"},
+                "strategy": {"type": "string"},
+                "attempts": {"type": "array"}
+              }
+            }
+          }
+        },
+        {
+          "description": "verification data",
+          "required": ["step_id", "passed"],
+          "properties": {
+            "step_id": {"type": "string"},
+            "passed": {"type": "boolean"},
+            "signals": {"type": "object"}
+          }
+        },
+        {
+          "description": "recovery data",
+          "required": ["step_id", "strategy"],
+          "properties": {
+            "step_id": {"type": "string"},
+            "strategy": {"type": "string"},
+            "attempt": {"type": "integer"}
+          }
+        },
+        {
+          "description": "run_end data",
+          "required": ["steps"],
+          "properties": {
+            "steps": {"type": "integer"}
+          }
+        },
+        {
+          "description": "error data",
+          "required": ["step_id", "error"],
+          "properties": {
+            "step_id": {"type": "string"},
+            "attempt": {"type": "integer"},
+            "error": {"type": "string"}
+          }
+        }
+      ]
+    }
+  }
+}
diff --git a/sentience/tracing.py b/sentience/tracing.py
new file mode 100644
index 0000000..64b37de
--- /dev/null
+++ b/sentience/tracing.py
@@ -0,0 +1,257 @@
+"""
+Trace event writer for Sentience agents.
+
+Provides abstract interface and JSONL implementation for emitting trace events.
+"""
+
+import json
+import time
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, Optional, Union
+
+
+@dataclass
+class TraceEvent:
+    """
+    Trace event data structure.
+
+    Represents a single event in the agent execution trace.
+    """
+
+    v: int  # Schema version
+    type: str  # Event type
+    ts: str  # ISO 8601 timestamp
+    run_id: str  # UUID for the run
+    seq: int  # Sequence number
+    data: dict[str, Any]  # Event payload
+    step_id: str | None = None  # UUID for the step (if step-scoped)
+    ts_ms: int | None = None  # Unix timestamp in milliseconds
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        result = {
+            "v": self.v,
+            "type": self.type,
+            "ts": self.ts,
+            "run_id": self.run_id,
+            "seq": self.seq,
+            "data": self.data,
+        }
+
+        if self.step_id is not None:
+            result["step_id"] = self.step_id
+
+        if self.ts_ms is not None:
+            result["ts_ms"] = self.ts_ms
+
+        return result
+
+
+class TraceSink(ABC):
+    """
+    Abstract interface for trace event sink.
+
+    Implementations can write to files, databases, or remote services.
+    """
+
+    @abstractmethod
+    def emit(self, event: dict[str, Any]) -> None:
+        """
+        Emit a trace event.
+
+        Args:
+            event: Event dictionary (from TraceEvent.to_dict())
+        """
+        pass
+
+    @abstractmethod
+    def close(self) -> None:
+        """Close the sink and flush any buffered data."""
+        pass
+
+
+class JsonlTraceSink(TraceSink):
+    """
+    JSONL file sink for trace events.
+
+    Writes one JSON object per line to a file.
+    """
+
+    def __init__(self, path: str | Path):
+        """
+        Initialize JSONL sink.
+
+        Args:
+            path: File path to write traces to
+        """
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Open file in append mode with line buffering
+        self._file = open(self.path, "a", encoding="utf-8", buffering=1)
+
+    def emit(self, event: dict[str, Any]) -> None:
+        """
+        Emit event as JSONL line.
+
+        Args:
+            event: Event dictionary
+        """
+        json_str = json.dumps(event, ensure_ascii=False)
+        self._file.write(json_str + "\n")
+
+    def close(self) -> None:
+        """Close the file."""
+        if hasattr(self, "_file") and not self._file.closed:
+            self._file.close()
+
+    def __enter__(self):
+        """Context manager support."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager cleanup."""
+        self.close()
+        return False
+
+
+@dataclass
+class Tracer:
+    """
+    Trace event builder and emitter.
+
+    Manages sequence numbers and provides convenient methods for emitting events.
+    """
+
+    run_id: str
+    sink: TraceSink
+    seq: int = field(default=0, init=False)
+
+    def emit(
+        self,
+        event_type: str,
+        data: dict[str, Any],
+        step_id: str | None = None,
+    ) -> None:
+        """
+        Emit a trace event.
+
+        Args:
+            event_type: Type of event (e.g., 'run_start', 'step_end')
+            data: Event-specific payload
+            step_id: Step UUID (if step-scoped event)
+        """
+        self.seq += 1
+
+        # Generate timestamps
+        ts_ms = int(time.time() * 1000)
+        ts = time.strftime("%Y-%m-%dT%H:%M:%S.000Z", time.gmtime())
+
+        event = TraceEvent(
+            v=1,
+            type=event_type,
+            ts=ts,
+            ts_ms=ts_ms,
+            run_id=self.run_id,
+            seq=self.seq,
+            step_id=step_id,
+            data=data,
+        )
+
+        self.sink.emit(event.to_dict())
+
+    def emit_run_start(
+        self,
+        agent: str,
+        llm_model: str | None = None,
+        config: dict[str, Any] | None = None,
+    ) -> None:
+        """
+        Emit run_start event.
+
+        Args:
+            agent: Agent name (e.g., 'SentienceAgent')
+            llm_model: LLM model name
+            config: Agent configuration
+        """
+        data: dict[str, Any] = {"agent": agent}
+        if llm_model is not None:
+            data["llm_model"] = llm_model
+        if config is not None:
+            data["config"] = config
+
+        self.emit("run_start", data)
+
+    def emit_step_start(
+        self,
+        step_id: str,
+        step_index: int,
+        goal: str,
+        attempt: int = 0,
+        pre_url: str | None = None,
+    ) -> None:
+        """
+        Emit step_start event.
+
+        Args:
+            step_id: Step UUID
+            step_index: Step number (1-indexed)
+            goal: Step goal description
+            attempt: Attempt number (0-indexed)
+            pre_url: URL before step
+        """
+        data = {
+            "step_id": step_id,
+            "step_index": step_index,
+            "goal": goal,
+            "attempt": attempt,
+        }
+        if pre_url is not None:
+            data["pre_url"] = pre_url
+
+        self.emit("step_start", data, step_id=step_id)
+
+    def emit_run_end(self, steps: int) -> None:
+        """
+        Emit run_end event.
+
+        Args:
+            steps: Total number of steps executed
+        """
+        self.emit("run_end", {"steps": steps})
+
+    def emit_error(
+        self,
+        step_id: str,
+        error: str,
+        attempt: int = 0,
+    ) -> None:
+        """
+        Emit error event.
+
+        Args:
+            step_id: Step UUID
+            error: Error message
+            attempt: Attempt number when error occurred
+        """
+        data = {
+            "step_id": step_id,
+            "error": error,
+            "attempt": attempt,
+        }
+        self.emit("error", data, step_id=step_id)
+
+    def close(self) -> None:
+        """Close the underlying sink."""
+        self.sink.close()
+
+    def __enter__(self):
+        """Context manager support."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager cleanup."""
+        self.close()
+        return False
diff --git a/sentience/utils.py b/sentience/utils.py
new file mode 100644
index 0000000..64a942b
--- /dev/null
+++ b/sentience/utils.py
@@ -0,0 +1,257 @@
+"""
+Digest utilities for snapshot canonicalization and hashing.
+
+Provides functions to compute stable digests of snapshots for determinism 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, Dict, List, Optional, Union
+
+
+@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: str | None, 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_python.egg-info/PKG-INFO b/sentience_python.egg-info/PKG-INFO
index fbff41c..6ea01fd 100644
--- a/sentience_python.egg-info/PKG-INFO
+++ b/sentience_python.egg-info/PKG-INFO
@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sentience-python
-Version: 0.10.8
+Version: 0.11.0
 Summary: Python SDK for Sentience AI Agent Browser Automation
 Author: Sentience Team
 License: MIT
diff --git a/tests/test_agent_config.py b/tests/test_agent_config.py
new file mode 100644
index 0000000..281592c
--- /dev/null
+++ b/tests/test_agent_config.py
@@ -0,0 +1,119 @@
+"""Tests for sentience.agent_config module"""
+
+from sentience.agent_config import AgentConfig
+
+
+def test_agent_config_defaults():
+    """Test AgentConfig with default values."""
+    config = AgentConfig()
+
+    assert config.snapshot_limit == 50
+    assert config.temperature == 0.0
+    assert config.max_retries == 1
+    assert config.verify is True
+    assert config.capture_screenshots is True
+    assert config.screenshot_format == "jpeg"
+    assert config.screenshot_quality == 80
+
+
+def test_agent_config_custom_values():
+    """Test AgentConfig with custom values."""
+    config = AgentConfig(
+        snapshot_limit=100,
+        temperature=0.5,
+        max_retries=3,
+        verify=False,
+        capture_screenshots=False,
+        screenshot_format="png",
+        screenshot_quality=95,
+    )
+
+    assert config.snapshot_limit == 100
+    assert config.temperature == 0.5
+    assert config.max_retries == 3
+    assert config.verify is False
+    assert config.capture_screenshots is False
+    assert config.screenshot_format == "png"
+    assert config.screenshot_quality == 95
+
+
+def test_agent_config_partial_override():
+    """Test AgentConfig with partial overrides."""
+    config = AgentConfig(
+        snapshot_limit=200,
+        max_retries=5,
+    )
+
+    # Overridden values
+    assert config.snapshot_limit == 200
+    assert config.max_retries == 5
+
+    # Default values
+    assert config.temperature == 0.0
+    assert config.verify is True
+    assert config.capture_screenshots is True
+    assert config.screenshot_format == "jpeg"
+    assert config.screenshot_quality == 80
+
+
+def test_agent_config_temperature_range():
+    """Test AgentConfig accepts valid temperature range."""
+    config_low = AgentConfig(temperature=0.0)
+    config_mid = AgentConfig(temperature=0.5)
+    config_high = AgentConfig(temperature=1.0)
+
+    assert config_low.temperature == 0.0
+    assert config_mid.temperature == 0.5
+    assert config_high.temperature == 1.0
+
+
+def test_agent_config_screenshot_quality_range():
+    """Test AgentConfig accepts valid screenshot quality range."""
+    config_low = AgentConfig(screenshot_quality=1)
+    config_mid = AgentConfig(screenshot_quality=50)
+    config_high = AgentConfig(screenshot_quality=100)
+
+    assert config_low.screenshot_quality == 1
+    assert config_mid.screenshot_quality == 50
+    assert config_high.screenshot_quality == 100
+
+
+def test_agent_config_screenshot_formats():
+    """Test AgentConfig accepts both screenshot formats."""
+    config_jpeg = AgentConfig(screenshot_format="jpeg")
+    config_png = AgentConfig(screenshot_format="png")
+
+    assert config_jpeg.screenshot_format == "jpeg"
+    assert config_png.screenshot_format == "png"
+
+
+def test_agent_config_immutability():
+    """Test that AgentConfig is a dataclass and can be modified."""
+    config = AgentConfig()
+
+    # Dataclasses are mutable by default
+    config.snapshot_limit = 200
+    assert config.snapshot_limit == 200
+
+    config.verify = False
+    assert config.verify is False
+
+
+def test_agent_config_repr():
+    """Test AgentConfig has a readable representation."""
+    config = AgentConfig(snapshot_limit=100, temperature=0.5)
+
+    repr_str = repr(config)
+    assert "AgentConfig" in repr_str
+    assert "snapshot_limit=100" in repr_str
+    assert "temperature=0.5" in repr_str
+
+
+def test_agent_config_equality():
+    """Test AgentConfig equality comparison."""
+    config1 = AgentConfig(snapshot_limit=100, temperature=0.5)
+    config2 = AgentConfig(snapshot_limit=100, temperature=0.5)
+    config3 = AgentConfig(snapshot_limit=200, temperature=0.5)
+
+    assert config1 == config2
+    assert config1 != config3
diff --git a/tests/test_formatting.py b/tests/test_formatting.py
new file mode 100644
index 0000000..c4406b2
--- /dev/null
+++ b/tests/test_formatting.py
@@ -0,0 +1,219 @@
+"""Tests for sentience.formatting module"""
+
+from sentience.formatting import format_snapshot_for_llm
+from sentience.models import BBox, Element, Snapshot, VisualCues
+
+
+def test_format_snapshot_basic():
+    """Test basic snapshot formatting."""
+    elements = [
+        Element(
+            id=1,
+            role="button",
+            text="Sign In",
+            bbox=BBox(x=100, y=50, width=80, height=30),
+            visual_cues=VisualCues(is_primary=True, is_clickable=True),
+            importance=10,
+        ),
+        Element(
+            id=2,
+            role="input",
+            text="Email address",
+            bbox=BBox(x=100, y=100, width=200, height=25),
+            visual_cues=VisualCues(is_primary=False, is_clickable=False),
+            importance=8,
+        ),
+    ]
+
+    snapshot = Snapshot(status="success", url="https://example.com", elements=elements)
+    result = format_snapshot_for_llm(snapshot, limit=10)
+
+    # Should contain element IDs
+    assert "[1]" in result
+    assert "[2]" in result
+
+    # Should contain roles
+    assert "<button>" in result
+    assert "<input>" in result
+
+    # Should contain text
+    assert "Sign In" in result
+    assert "Email address" in result
+
+    # Should contain visual cues
+    assert "PRIMARY" in result
+    assert "CLICKABLE" in result
+
+    # Should contain positions
+    assert "@ (100,50)" in result
+    assert "@ (100,100)" in result
+
+    # Should contain importance scores
+    assert "(Imp:10)" in result
+    assert "(Imp:8)" in result
+
+
+def test_format_snapshot_limit():
+    """Test that limit parameter works."""
+    elements = [
+        Element(
+            id=i,
+            role="button",
+            text=f"Button {i}",
+            bbox=BBox(x=0, y=0, width=10, height=10),
+            visual_cues=VisualCues(is_primary=False, is_clickable=False),
+            importance=5,
+        )
+        for i in range(1, 101)
+    ]
+
+    snapshot = Snapshot(status="success", url="https://example.com", elements=elements)
+
+    # With limit=10, should only see first 10 elements
+    result = format_snapshot_for_llm(snapshot, limit=10)
+    lines = result.split("\n")
+    assert len(lines) == 10
+    assert "[1]" in result
+    assert "[10]" in result
+    assert "[11]" not in result
+
+
+def test_format_snapshot_text_truncation():
+    """Test that long text is truncated."""
+    long_text = "a" * 100
+    elements = [
+        Element(
+            id=1,
+            role="div",
+            text=long_text,
+            bbox=BBox(x=0, y=0, width=10, height=10),
+            visual_cues=VisualCues(is_primary=False, is_clickable=False),
+            importance=5,
+        ),
+    ]
+
+    snapshot = Snapshot(status="success", url="https://example.com", elements=elements)
+    result = format_snapshot_for_llm(snapshot)
+
+    # Should contain truncated text with ellipsis
+    assert "..." in result
+    # Should not contain full text
+    assert long_text not in result
+
+
+def test_format_snapshot_empty_text():
+    """Test formatting with empty text."""
+    elements = [
+        Element(
+            id=1,
+            role="div",
+            text="",
+            bbox=BBox(x=0, y=0, width=10, height=10),
+            visual_cues=VisualCues(is_primary=False, is_clickable=False),
+            importance=5,
+        ),
+    ]
+
+    snapshot = Snapshot(status="success", url="https://example.com", elements=elements)
+    result = format_snapshot_for_llm(snapshot)
+
+    # Should still format element
+    assert "[1]" in result
+    assert "<div>" in result
+    assert '""' in result  # Empty quotes
+
+
+def test_format_snapshot_no_visual_cues():
+    """Test formatting without visual cues."""
+    elements = [
+        Element(
+            id=1,
+            role="div",
+            text="Test",
+            bbox=BBox(x=0, y=0, width=10, height=10),
+            visual_cues=VisualCues(is_primary=False, is_clickable=False),
+            importance=5,
+        ),
+    ]
+
+    snapshot = Snapshot(status="success", url="https://example.com", elements=elements)
+    result = format_snapshot_for_llm(snapshot)
+
+    # Should not contain visual cues
+    assert "PRIMARY" not in result
+    assert "CLICKABLE" not in result
+    # But should still format other fields
+    assert "[1]" in result
+    assert "Test" in result
+
+
+def test_format_snapshot_multiple_visual_cues():
+    """Test formatting with multiple visual cues."""
+    elements = [
+        Element(
+            id=1,
+            role="button",
+            text="Submit",
+            bbox=BBox(x=0, y=0, width=10, height=10),
+            visual_cues=VisualCues(is_primary=True, is_clickable=True),
+            importance=10,
+        ),
+    ]
+
+    snapshot = Snapshot(status="success", url="https://example.com", elements=elements)
+    result = format_snapshot_for_llm(snapshot)
+
+    # Should contain both cues
+    assert "PRIMARY" in result
+    assert "CLICKABLE" in result
+    # Should be comma-separated
+    assert "{PRIMARY,CLICKABLE}" in result or "{CLICKABLE,PRIMARY}" in result
+
+
+def test_format_snapshot_position_formatting():
+    """Test that positions are formatted as integers."""
+    elements = [
+        Element(
+            id=1,
+            role="button",
+            text="Test",
+            bbox=BBox(x=123.7, y=456.2, width=78, height=90),
+            visual_cues=VisualCues(is_primary=False, is_clickable=False),
+            importance=5,
+        ),
+    ]
+
+    snapshot = Snapshot(status="success", url="https://example.com", elements=elements)
+    result = format_snapshot_for_llm(snapshot)
+
+    # Should round to integers
+    assert "@ (123,456)" in result
+
+
+def test_format_snapshot_default_limit():
+    """Test that default limit is 50."""
+    elements = [
+        Element(
+            id=i,
+            role="button",
+            text=f"Button {i}",
+            bbox=BBox(x=0, y=0, width=10, height=10),
+            visual_cues=VisualCues(is_primary=False, is_clickable=False),
+            importance=5,
+        )
+        for i in range(1, 101)
+    ]
+
+    snapshot = Snapshot(status="success", url="https://example.com", elements=elements)
+    result = format_snapshot_for_llm(snapshot)  # No limit specified
+
+    lines = result.split("\n")
+    assert len(lines) == 50  # Default limit
+
+
+def test_format_snapshot_empty():
+    """Test formatting empty snapshot."""
+    snapshot = Snapshot(status="success", url="https://example.com", elements=[])
+    result = format_snapshot_for_llm(snapshot)
+
+    assert result == ""
diff --git a/tests/test_inspector.py b/tests/test_inspector.py
index f3d8786..ad0b9a4 100644
--- a/tests/test_inspector.py
+++ b/tests/test_inspector.py
@@ -2,8 +2,6 @@
 Tests for inspector functionality
 """
 
-import pytest
-
 from sentience import SentienceBrowser, inspect
 
 
diff --git a/tests/test_recorder.py b/tests/test_recorder.py
index 0d061a8..ca69d93 100644
--- a/tests/test_recorder.py
+++ b/tests/test_recorder.py
@@ -5,10 +5,7 @@
 import os
 import tempfile
 
-import pytest
-
-from sentience import SentienceBrowser, Trace, TraceStep, record
-from sentience.recorder import Recorder
+from sentience import SentienceBrowser, Trace, record
 
 
 def test_recorder_start_stop():
diff --git a/tests/test_smart_selector.py b/tests/test_smart_selector.py
index 2bd770d..b59be70 100644
--- a/tests/test_smart_selector.py
+++ b/tests/test_smart_selector.py
@@ -2,8 +2,6 @@
 Tests for smart selector inference
 """
 
-import pytest
-
 from sentience import SentienceBrowser, record, snapshot
 
 
diff --git a/tests/test_stealth.py b/tests/test_stealth.py
index 9b4235f..5675513 100644
--- a/tests/test_stealth.py
+++ b/tests/test_stealth.py
@@ -16,10 +16,10 @@
 # Add parent directory to path
 sys.path.insert(0, str(Path(__file__).parent.parent))
 
-from sentience.browser import SentienceBrowser
+from sentience.browser import SentienceBrowser  # noqa: E402
 
 
-def test_stealth_features():
+def test_stealth_features():  # noqa: C901
     """Test that stealth features are working correctly"""
     print("=" * 60)
     print("Bot Evasion / Stealth Mode Test")
@@ -41,9 +41,9 @@ def test_stealth_features():
         print("\n2. Testing window.chrome...")
         chrome_exists = page.evaluate("() => typeof window.chrome !== 'undefined'")
         if chrome_exists:
-            print(f"   ✅ window.chrome exists (stealth working)")
+            print("   ✅ window.chrome exists (stealth working)")
         else:
-            print(f"   ❌ window.chrome does not exist (detectable)")
+            print("   ❌ window.chrome does not exist (detectable)")
 
         print("\n3. Testing user-agent...")
         user_agent = page.evaluate("() => navigator.userAgent")
diff --git a/tests/test_tracing.py b/tests/test_tracing.py
new file mode 100644
index 0000000..68b7d25
--- /dev/null
+++ b/tests/test_tracing.py
@@ -0,0 +1,209 @@
+"""Tests for sentience.tracing module"""
+
+import json
+import tempfile
+from pathlib import Path
+
+from sentience.tracing import JsonlTraceSink, TraceEvent, Tracer
+
+
+def test_trace_event_to_dict():
+    """Test TraceEvent serialization to dict."""
+    event = TraceEvent(
+        v=1,
+        type="test_event",
+        ts="2024-01-01T00:00:00.000Z",
+        run_id="test-run-123",
+        seq=1,
+        data={"key": "value"},
+        step_id="step-456",
+        ts_ms=1704067200000,
+    )
+    result = event.to_dict()
+    assert result["v"] == 1
+    assert result["type"] == "test_event"
+    assert result["step_id"] == "step-456"
+    assert result["data"]["key"] == "value"
+    assert result["ts"] == "2024-01-01T00:00:00.000Z"
+    assert result["run_id"] == "test-run-123"
+    assert result["seq"] == 1
+    assert result["ts_ms"] == 1704067200000
+
+
+def test_trace_event_to_dict_optional_fields():
+    """Test TraceEvent serialization without optional fields."""
+    event = TraceEvent(
+        v=1,
+        type="test_event",
+        ts="2024-01-01T00:00:00.000Z",
+        run_id="test-run-123",
+        seq=1,
+        data={"key": "value"},
+    )
+    result = event.to_dict()
+    assert "step_id" not in result
+    assert "ts_ms" not in result
+
+
+def test_jsonl_trace_sink_emit():
+    """Test JsonlTraceSink emits valid JSONL."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        trace_path = Path(tmpdir) / "trace.jsonl"
+        sink = JsonlTraceSink(trace_path)
+
+        # Emit two events
+        sink.emit({"v": 1, "type": "event1", "seq": 1})
+        sink.emit({"v": 1, "type": "event2", "seq": 2})
+        sink.close()
+
+        # Read and verify
+        lines = trace_path.read_text().strip().split("\n")
+        assert len(lines) == 2
+
+        event1 = json.loads(lines[0])
+        assert event1["type"] == "event1"
+        assert event1["seq"] == 1
+
+        event2 = json.loads(lines[1])
+        assert event2["type"] == "event2"
+        assert event2["seq"] == 2
+
+
+def test_jsonl_trace_sink_context_manager():
+    """Test JsonlTraceSink works as context manager."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        trace_path = Path(tmpdir) / "trace.jsonl"
+
+        with JsonlTraceSink(trace_path) as sink:
+            sink.emit({"v": 1, "type": "test", "seq": 1})
+
+        # File should be closed and flushed
+        lines = trace_path.read_text().strip().split("\n")
+        assert len(lines) == 1
+        assert json.loads(lines[0])["type"] == "test"
+
+
+def test_tracer_emit():
+    """Test Tracer emits events with auto-incrementing sequence."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        trace_path = Path(tmpdir) / "trace.jsonl"
+
+        with JsonlTraceSink(trace_path) as sink:
+            tracer = Tracer(run_id="test-run-123", sink=sink)
+
+            tracer.emit("event1", {"data": "value1"})
+            tracer.emit("event2", {"data": "value2"}, step_id="step-456")
+
+        # Read and verify
+        lines = trace_path.read_text().strip().split("\n")
+        assert len(lines) == 2
+
+        event1 = json.loads(lines[0])
+        assert event1["type"] == "event1"
+        assert event1["seq"] == 1
+        assert event1["run_id"] == "test-run-123"
+        assert event1["data"]["data"] == "value1"
+        assert "step_id" not in event1
+
+        event2 = json.loads(lines[1])
+        assert event2["type"] == "event2"
+        assert event2["seq"] == 2
+        assert event2["step_id"] == "step-456"
+
+
+def test_tracer_emit_run_start():
+    """Test Tracer.emit_run_start()."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        trace_path = Path(tmpdir) / "trace.jsonl"
+
+        with JsonlTraceSink(trace_path) as sink:
+            tracer = Tracer(run_id="test-run-123", sink=sink)
+            tracer.emit_run_start(
+                agent="SentienceAgent",
+                llm_model="gpt-4",
+                config={"snapshot_limit": 50},
+            )
+
+        lines = trace_path.read_text().strip().split("\n")
+        event = json.loads(lines[0])
+
+        assert event["type"] == "run_start"
+        assert event["data"]["agent"] == "SentienceAgent"
+        assert event["data"]["llm_model"] == "gpt-4"
+        assert event["data"]["config"]["snapshot_limit"] == 50
+
+
+def test_tracer_emit_step_start():
+    """Test Tracer.emit_step_start()."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        trace_path = Path(tmpdir) / "trace.jsonl"
+
+        with JsonlTraceSink(trace_path) as sink:
+            tracer = Tracer(run_id="test-run-123", sink=sink)
+            tracer.emit_step_start(
+                step_id="step-456",
+                step_index=1,
+                goal="Click login button",
+                attempt=0,
+                pre_url="https://example.com",
+            )
+
+        lines = trace_path.read_text().strip().split("\n")
+        event = json.loads(lines[0])
+
+        assert event["type"] == "step_start"
+        assert event["step_id"] == "step-456"
+        assert event["data"]["step_id"] == "step-456"
+        assert event["data"]["step_index"] == 1
+        assert event["data"]["goal"] == "Click login button"
+        assert event["data"]["attempt"] == 0
+        assert event["data"]["pre_url"] == "https://example.com"
+
+
+def test_tracer_emit_run_end():
+    """Test Tracer.emit_run_end()."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        trace_path = Path(tmpdir) / "trace.jsonl"
+
+        with JsonlTraceSink(trace_path) as sink:
+            tracer = Tracer(run_id="test-run-123", sink=sink)
+            tracer.emit_run_end(steps=5)
+
+        lines = trace_path.read_text().strip().split("\n")
+        event = json.loads(lines[0])
+
+        assert event["type"] == "run_end"
+        assert event["data"]["steps"] == 5
+
+
+def test_tracer_emit_error():
+    """Test Tracer.emit_error()."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        trace_path = Path(tmpdir) / "trace.jsonl"
+
+        with JsonlTraceSink(trace_path) as sink:
+            tracer = Tracer(run_id="test-run-123", sink=sink)
+            tracer.emit_error(step_id="step-456", error="Element not found", attempt=1)
+
+        lines = trace_path.read_text().strip().split("\n")
+        event = json.loads(lines[0])
+
+        assert event["type"] == "error"
+        assert event["step_id"] == "step-456"
+        assert event["data"]["step_id"] == "step-456"
+        assert event["data"]["error"] == "Element not found"
+        assert event["data"]["attempt"] == 1
+
+
+def test_tracer_context_manager():
+    """Test Tracer works as context manager."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        trace_path = Path(tmpdir) / "trace.jsonl"
+
+        with JsonlTraceSink(trace_path) as sink:
+            with Tracer(run_id="test-run-123", sink=sink) as tracer:
+                tracer.emit("test_event", {"data": "value"})
+
+        # Verify file is closed and flushed
+        lines = trace_path.read_text().strip().split("\n")
+        assert len(lines) == 1
diff --git a/tests/test_utils.py b/tests/test_utils.py
new file mode 100644
index 0000000..3f447c2
--- /dev/null
+++ b/tests/test_utils.py
@@ -0,0 +1,311 @@
+"""
+Unit tests for sentience.utils module.
+
+Tests canonicalization and hashing functions for snapshot digests.
+"""
+
+from sentience.utils import (
+    BBox,
+    canonical_snapshot_loose,
+    canonical_snapshot_strict,
+    compute_snapshot_digests,
+    extract_element_fingerprint,
+    normalize_bbox,
+    normalize_text_strict,
+    sha256_digest,
+)
+
+
+class TestNormalizeText:
+    """Tests for text normalization."""
+
+    def test_normalize_text_basic(self):
+        """Test basic text normalization."""
+        text = "  Hello   World  "
+        result = normalize_text_strict(text)
+        assert result == "hello world"
+
+    def test_normalize_text_digits(self):
+        """Test digit replacement."""
+        text = "Price: $79.99"
+        result = normalize_text_strict(text)
+        assert result == "price: $#.#"
+
+    def test_normalize_text_time(self):
+        """Test time pattern normalization."""
+        text = "12:34 PM"
+        result = normalize_text_strict(text)
+        assert result == "#:# pm"
+
+    def test_normalize_text_length_cap(self):
+        """Test length capping."""
+        text = "a" * 100
+        result = normalize_text_strict(text, max_length=80)
+        assert len(result) == 80
+
+    def test_normalize_text_empty(self):
+        """Test empty text."""
+        assert normalize_text_strict(None) == ""
+        assert normalize_text_strict("") == ""
+        assert normalize_text_strict("   ") == ""
+
+    def test_normalize_text_stability(self):
+        """Test that same text produces same result."""
+        text1 = "Add to Cart"
+        text2 = "  add   TO  cart  "
+        assert normalize_text_strict(text1) == normalize_text_strict(text2)
+
+
+class TestNormalizeBBox:
+    """Tests for bbox normalization."""
+
+    def test_normalize_bbox_dict(self):
+        """Test bbox normalization from dict."""
+        bbox = {"x": 123, "y": 456, "width": 78, "height": 90}
+        result = normalize_bbox(bbox)
+        # Should round to 2px buckets (123 rounds to 124)
+        assert result == [124, 456, 78, 90]
+
+    def test_normalize_bbox_object(self):
+        """Test bbox normalization from BBox object."""
+        bbox = BBox(x=123, y=456, width=78, height=90)
+        result = normalize_bbox(bbox)
+        assert result == [124, 456, 78, 90]
+
+    def test_normalize_bbox_rounding(self):
+        """Test 2px bucket rounding."""
+        bbox = {"x": 121, "y": 122, "width": 123, "height": 124}
+        result = normalize_bbox(bbox, bucket_size=2)
+        # 121 -> 120, 122 -> 122, 123 -> 124, 124 -> 124
+        assert result == [120, 122, 124, 124]
+
+    def test_normalize_bbox_stability(self):
+        """Test that similar bboxes produce same result."""
+        bbox1 = {"x": 100, "y": 200, "width": 50, "height": 30}
+        bbox2 = {"x": 101, "y": 199, "width": 51, "height": 29}
+        # Both should round to same buckets (with 2px rounding)
+        result1 = normalize_bbox(bbox1)
+        result2 = normalize_bbox(bbox2)
+        # 100->100, 200->200, 50->50, 30->30
+        # 101->100, 199->200, 51->52, 29->28
+        assert result1 == [100, 200, 50, 30]
+        assert result2 == [100, 200, 52, 28]
+
+
+class TestExtractElementFingerprint:
+    """Tests for element fingerprint extraction."""
+
+    def test_extract_with_text(self):
+        """Test extraction with text included."""
+        element = {
+            "id": 42,
+            "role": "button",
+            "text": "Add to Cart",
+            "bbox": {"x": 100, "y": 200, "width": 80, "height": 30},
+            "visual_cues": {
+                "is_clickable": True,
+                "is_primary": False,
+            },
+        }
+
+        fingerprint = extract_element_fingerprint(element, include_text=True)
+
+        assert fingerprint.id == 42
+        assert fingerprint.role == "button"
+        assert fingerprint.text == "add to cart"
+        assert fingerprint.clickable == 1
+        assert fingerprint.primary == 0
+        assert len(fingerprint.bbox) == 4
+
+    def test_extract_without_text(self):
+        """Test extraction without text (loose digest)."""
+        element = {
+            "id": 42,
+            "role": "button",
+            "text": "Add to Cart",
+            "bbox": {"x": 100, "y": 200, "width": 80, "height": 30},
+            "visual_cues": {
+                "is_clickable": True,
+                "is_primary": True,
+            },
+        }
+
+        fingerprint = extract_element_fingerprint(element, include_text=False)
+
+        assert fingerprint.id == 42
+        assert fingerprint.text == ""  # No text in loose digest
+
+    def test_extract_missing_fields(self):
+        """Test extraction with missing fields."""
+        element = {"id": 1}
+
+        fingerprint = extract_element_fingerprint(element)
+
+        assert fingerprint.id == 1
+        assert fingerprint.role == "unknown"
+        assert fingerprint.clickable == 0
+        assert fingerprint.primary == 0
+
+
+class TestCanonicalSnapshots:
+    """Tests for canonical snapshot string generation."""
+
+    def test_canonical_strict_ordering(self):
+        """Test that elements are sorted by ID."""
+        elements = [
+            {
+                "id": 3,
+                "role": "button",
+                "text": "C",
+                "bbox": {"x": 0, "y": 0, "width": 10, "height": 10},
+                "visual_cues": {},
+            },
+            {
+                "id": 1,
+                "role": "button",
+                "text": "A",
+                "bbox": {"x": 0, "y": 0, "width": 10, "height": 10},
+                "visual_cues": {},
+            },
+            {
+                "id": 2,
+                "role": "button",
+                "text": "B",
+                "bbox": {"x": 0, "y": 0, "width": 10, "height": 10},
+                "visual_cues": {},
+            },
+        ]
+
+        canonical = canonical_snapshot_strict(elements)
+
+        # Should be sorted by ID (JSON has space after colon)
+        assert '"id": 1' in canonical
+        assert canonical.index('"id": 1') < canonical.index('"id": 2')
+        assert canonical.index('"id": 2') < canonical.index('"id": 3')
+
+    def test_canonical_loose_no_text(self):
+        """Test that loose digest has no text."""
+        elements = [
+            {
+                "id": 1,
+                "role": "button",
+                "text": "Click me",
+                "bbox": {"x": 0, "y": 0, "width": 10, "height": 10},
+                "visual_cues": {},
+            },
+        ]
+
+        canonical = canonical_snapshot_loose(elements)
+
+        # Should not contain the text
+        assert "click me" not in canonical.lower()
+
+    def test_canonical_stability(self):
+        """Test that same elements produce same canonical string."""
+        elements = [
+            {
+                "id": 1,
+                "role": "button",
+                "text": "Test",
+                "bbox": {"x": 100, "y": 200, "width": 50, "height": 30},
+                "visual_cues": {},
+            },
+        ]
+
+        canonical1 = canonical_snapshot_strict(elements)
+        canonical2 = canonical_snapshot_strict(elements)
+
+        assert canonical1 == canonical2
+
+
+class TestSHA256Digest:
+    """Tests for SHA256 hashing."""
+
+    def test_sha256_format(self):
+        """Test hash format."""
+        digest = sha256_digest("test")
+        assert digest.startswith("sha256:")
+        assert len(digest) == 71  # "sha256:" + 64 hex chars
+
+    def test_sha256_stability(self):
+        """Test that same input produces same hash."""
+        digest1 = sha256_digest("test")
+        digest2 = sha256_digest("test")
+        assert digest1 == digest2
+
+    def test_sha256_uniqueness(self):
+        """Test that different inputs produce different hashes."""
+        digest1 = sha256_digest("test1")
+        digest2 = sha256_digest("test2")
+        assert digest1 != digest2
+
+
+class TestComputeSnapshotDigests:
+    """Tests for combined digest computation."""
+
+    def test_compute_both_digests(self):
+        """Test that both digests are computed."""
+        elements = [
+            {
+                "id": 1,
+                "role": "button",
+                "text": "Click",
+                "bbox": {"x": 0, "y": 0, "width": 10, "height": 10},
+                "visual_cues": {},
+            },
+        ]
+
+        result = compute_snapshot_digests(elements)
+
+        assert "strict" in result
+        assert "loose" in result
+        assert result["strict"].startswith("sha256:")
+        assert result["loose"].startswith("sha256:")
+
+    def test_digests_differ(self):
+        """Test that strict and loose digests differ when text present."""
+        elements = [
+            {
+                "id": 1,
+                "role": "button",
+                "text": "Important Text",
+                "bbox": {"x": 0, "y": 0, "width": 10, "height": 10},
+                "visual_cues": {},
+            },
+        ]
+
+        result = compute_snapshot_digests(elements)
+
+        # Digests should differ because strict includes text
+        assert result["strict"] != result["loose"]
+
+    def test_loose_digest_stable_across_text_changes(self):
+        """Test that loose digest stays same when only text changes."""
+        elements1 = [
+            {
+                "id": 1,
+                "role": "button",
+                "text": "Text A",
+                "bbox": {"x": 100, "y": 200, "width": 50, "height": 30},
+                "visual_cues": {"is_clickable": True},
+            },
+        ]
+
+        elements2 = [
+            {
+                "id": 1,
+                "role": "button",
+                "text": "Text B",
+                "bbox": {"x": 100, "y": 200, "width": 50, "height": 30},
+                "visual_cues": {"is_clickable": True},
+            },
+        ]
+
+        digest1 = compute_snapshot_digests(elements1)
+        digest2 = compute_snapshot_digests(elements2)
+
+        # Loose digests should be same (no text)
+        assert digest1["loose"] == digest2["loose"]
+
+        # Strict digests should differ (different text)
+        assert digest1["strict"] != digest2["strict"]

From 3c8fcf25b421edb9a4a81ba42eb343134ab1de78 Mon Sep 17 00:00:00 2001
From: rcholic <ivytony@gmail.com>
Date: Fri, 26 Dec 2025 07:54:27 -0800
Subject: [PATCH 2/5] refactor agent for tracer support

---
 sentience/agent.py | 87 +++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 86 insertions(+), 1 deletion(-)

diff --git a/sentience/agent.py b/sentience/agent.py
index bd27326..97b7844 100644
--- a/sentience/agent.py
+++ b/sentience/agent.py
@@ -5,7 +5,7 @@
 
 import re
 import time
-from typing import Any, Dict, List, Optional, Union
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Union
 
 from .actions import click, press, type_text
 from .base_agent import BaseAgent
@@ -23,6 +23,10 @@
 )
 from .snapshot import snapshot
 
+if TYPE_CHECKING:
+    from .agent_config import AgentConfig
+    from .tracing import Tracer
+
 
 class SentienceAgent(BaseAgent):
     """
@@ -54,6 +58,8 @@ def __init__(
         llm: LLMProvider,
         default_snapshot_limit: int = 50,
         verbose: bool = True,
+        tracer: Optional["Tracer"] = None,
+        config: Optional["AgentConfig"] = None,
     ):
         """
         Initialize Sentience Agent
@@ -63,11 +69,15 @@ def __init__(
             llm: LLM provider (OpenAIProvider, AnthropicProvider, etc.)
             default_snapshot_limit: Default maximum elements to include in context (default: 50)
             verbose: Print execution logs (default: True)
+            tracer: Optional Tracer instance for execution tracking (default: None)
+            config: Optional AgentConfig for advanced configuration (default: None)
         """
         self.browser = browser
         self.llm = llm
         self.default_snapshot_limit = default_snapshot_limit
         self.verbose = verbose
+        self.tracer = tracer
+        self.config = config
 
         # Execution history
         self.history: list[dict[str, Any]] = []
@@ -80,6 +90,9 @@ def __init__(
             "by_action": [],
         }
 
+        # Step counter for tracing
+        self._step_count = 0
+
     def act(
         self, goal: str, max_retries: int = 2, snapshot_options: SnapshotOptions | None = None
     ) -> AgentActionResult:
@@ -107,6 +120,21 @@ def act(
             print(f"🤖 Agent Goal: {goal}")
             print(f"{'='*70}")
 
+        # Generate step ID for tracing
+        self._step_count += 1
+        step_id = f"step-{self._step_count}"
+
+        # Emit step_start trace event if tracer is enabled
+        if self.tracer:
+            pre_url = self.browser.page.url if self.browser.page else None
+            self.tracer.emit_step_start(
+                step_id=step_id,
+                step_index=self._step_count,
+                goal=goal,
+                attempt=0,
+                pre_url=pre_url,
+            )
+
         for attempt in range(max_retries + 1):
             try:
                 # 1. OBSERVE: Get refined semantic snapshot
@@ -135,6 +163,18 @@ def act(
                 if snap.status != "success":
                     raise RuntimeError(f"Snapshot failed: {snap.error}")
 
+                # Emit snapshot trace event if tracer is enabled
+                if self.tracer:
+                    self.tracer.emit(
+                        "snapshot",
+                        {
+                            "url": snap.url,
+                            "element_count": len(snap.elements),
+                            "timestamp": snap.timestamp,
+                        },
+                        step_id=step_id,
+                    )
+
                 # Apply element filtering based on goal
                 filtered_elements = self.filter_elements(snap, goal)
 
@@ -156,6 +196,19 @@ def act(
                 # 3. THINK: Query LLM for next action
                 llm_response = self._query_llm(context, goal)
 
+                # Emit LLM query trace event if tracer is enabled
+                if self.tracer:
+                    self.tracer.emit(
+                        "llm_query",
+                        {
+                            "prompt_tokens": llm_response.prompt_tokens,
+                            "completion_tokens": llm_response.completion_tokens,
+                            "model": llm_response.model,
+                            "response": llm_response.content[:200],  # Truncate for brevity
+                        },
+                        step_id=step_id,
+                    )
+
                 if self.verbose:
                     print(f"🧠 LLM Decision: {llm_response.content}")
 
@@ -186,6 +239,22 @@ def act(
                     message=result_dict.get("message"),
                 )
 
+                # Emit action execution trace event if tracer is enabled
+                if self.tracer:
+                    post_url = self.browser.page.url if self.browser.page else None
+                    self.tracer.emit(
+                        "action",
+                        {
+                            "action": result.action,
+                            "element_id": result.element_id,
+                            "success": result.success,
+                            "outcome": result.outcome,
+                            "duration_ms": duration_ms,
+                            "post_url": post_url,
+                        },
+                        step_id=step_id,
+                    )
+
                 # 5. RECORD: Track history
                 self.history.append(
                     {
@@ -202,9 +271,25 @@ def act(
                     status = "✅" if result.success else "❌"
                     print(f"{status} Completed in {duration_ms}ms")
 
+                # Emit step completion trace event if tracer is enabled
+                if self.tracer:
+                    self.tracer.emit(
+                        "step_end",
+                        {
+                            "success": result.success,
+                            "duration_ms": duration_ms,
+                            "action": result.action,
+                        },
+                        step_id=step_id,
+                    )
+
                 return result
 
             except Exception as e:
+                # Emit error trace event if tracer is enabled
+                if self.tracer:
+                    self.tracer.emit_error(step_id=step_id, error=str(e), attempt=attempt)
+
                 if attempt < max_retries:
                     if self.verbose:
                         print(f"⚠️  Retry {attempt + 1}/{max_retries}: {e}")

From 7a8e4cfd9090075d8808043eba25658de6065142 Mon Sep 17 00:00:00 2001
From: rcholic <ivytony@gmail.com>
Date: Fri, 26 Dec 2025 08:01:40 -0800
Subject: [PATCH 3/5] updated readme

---
 CHANGELOG.md | 118 +++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md    |  80 ++++++++++++++++++++++++++++++++++
 2 files changed, 198 insertions(+)
 create mode 100644 CHANGELOG.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..113c113
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,118 @@
+# Changelog
+
+All notable changes to the Sentience Python SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.12.0] - 2025-12-26
+
+### Added
+
+#### Agent Tracing & Debugging
+- **New Module: `sentience.tracing`** - Built-in tracing infrastructure for debugging and analyzing agent behavior
+  - `Tracer` class for recording agent execution
+  - `TraceSink` abstract base class for custom trace storage
+  - `JsonlTraceSink` for saving traces to JSONL files
+  - `TraceEvent` dataclass for structured trace events
+  - Trace events: `step_start`, `snapshot`, `llm_query`, `action`, `step_end`, `error`
+- **New Module: `sentience.agent_config`** - Centralized agent configuration
+  - `AgentConfig` dataclass with defaults for snapshot limits, LLM settings, screenshot options
+- **New Module: `sentience.utils`** - Snapshot digest utilities
+  - `compute_snapshot_digests()` - Generate SHA256 fingerprints for loop detection
+  - `canonical_snapshot_strict()` - Digest including element text
+  - `canonical_snapshot_loose()` - Digest excluding text (layout only)
+  - `sha256_digest()` - Hash computation helper
+- **New Module: `sentience.formatting`** - LLM prompt formatting
+  - `format_snapshot_for_llm()` - Convert snapshots to LLM-friendly text format
+- **Schema File: `sentience/schemas/trace_v1.json`** - JSON Schema for trace events, bundled with package
+
+#### Enhanced SentienceAgent
+- Added optional `tracer` parameter to `SentienceAgent.__init__()` for execution tracking
+- Added optional `config` parameter to `SentienceAgent.__init__()` for advanced configuration
+- Automatic tracing throughout `act()` method when tracer is provided
+- All tracing is **opt-in** - backward compatible with existing code
+
+### Changed
+- Bumped version from `0.11.0` to `0.12.0`
+- Updated `__init__.py` to export new modules: `AgentConfig`, `Tracer`, `TraceSink`, `JsonlTraceSink`, `TraceEvent`, and utility functions
+- Added `MANIFEST.in` to include JSON schema files in package distribution
+
+### Fixed
+- Fixed linting errors across multiple files:
+  - `sentience/cli.py` - Removed unused variable `code` (F841)
+  - `sentience/inspector.py` - Removed unused imports (F401)
+  - `tests/test_inspector.py` - Removed unused `pytest` import (F401)
+  - `tests/test_recorder.py` - Removed unused imports (F401)
+  - `tests/test_smart_selector.py` - Removed unused `pytest` import (F401)
+  - `tests/test_stealth.py` - Added `noqa` comments for intentional violations (E402, C901, F541)
+  - `tests/test_tracing.py` - Removed unused `TraceSink` import (F401)
+
+### Documentation
+- Updated `README.md` with comprehensive "Advanced Features" section covering tracing and utilities
+- Updated `docs/SDK_MANUAL.md` to v0.12.0 with new "Agent Tracing & Debugging" section
+- Added examples for:
+  - Basic tracing setup
+  - AgentConfig usage
+  - Snapshot digests for loop detection
+  - LLM prompt formatting
+  - Custom trace sinks
+
+### Testing
+- Added comprehensive test suites for new modules:
+  - `tests/test_tracing.py` - 10 tests for tracing infrastructure
+  - `tests/test_utils.py` - 22 tests for digest utilities
+  - `tests/test_formatting.py` - 9 tests for LLM formatting
+  - `tests/test_agent_config.py` - 9 tests for configuration
+- All 50 new tests passing ✅
+
+### Migration Guide
+
+#### For Existing Users
+No breaking changes! All new features are opt-in:
+
+```python
+# Old code continues to work exactly the same
+agent = SentienceAgent(browser, llm)
+agent.act("Click the button")
+
+# New optional features
+tracer = Tracer(run_id="run-123", sink=JsonlTraceSink("trace.jsonl"))
+config = AgentConfig(snapshot_limit=100, temperature=0.5)
+agent = SentienceAgent(browser, llm, tracer=tracer, config=config)
+agent.act("Click the button")  # Now traced!
+```
+
+#### Importing New Modules
+
+```python
+# Tracing
+from sentience.tracing import Tracer, JsonlTraceSink, TraceEvent, TraceSink
+
+# Configuration
+from sentience.agent_config import AgentConfig
+
+# Utilities
+from sentience.utils import (
+    compute_snapshot_digests,
+    canonical_snapshot_strict,
+    canonical_snapshot_loose,
+    sha256_digest
+)
+
+# Formatting
+from sentience.formatting import format_snapshot_for_llm
+```
+
+### Notes
+- This release focuses on developer experience and debugging capabilities
+- No changes to browser automation APIs
+- No changes to snapshot APIs
+- No changes to query/action APIs
+- Fully backward compatible with v0.11.0
+
+---
+
+## [0.11.0] - Previous Release
+
+(Previous changelog entries would go here)
diff --git a/README.md b/README.md
index 5740ad4..ad84c89 100644
--- a/README.md
+++ b/README.md
@@ -456,6 +456,86 @@ cd sentience-chrome
 - Check visibility: `element.in_viewport and not element.is_occluded`
 - Scroll to element: `browser.page.evaluate(f"window.sentience_registry[{element.id}].scrollIntoView()")`
 
+## Advanced Features (v0.12.0+)
+
+### Agent Tracing & Debugging
+
+The SDK now includes built-in tracing infrastructure for debugging and analyzing agent behavior:
+
+```python
+from sentience import SentienceBrowser, SentienceAgent
+from sentience.llm_provider import OpenAIProvider
+from sentience.tracing import Tracer, JsonlTraceSink
+from sentience.agent_config import AgentConfig
+
+# Create tracer to record agent execution
+tracer = Tracer(
+    run_id="my-agent-run-123",
+    sink=JsonlTraceSink("trace.jsonl")
+)
+
+# Configure agent behavior
+config = AgentConfig(
+    snapshot_limit=50,
+    temperature=0.0,
+    max_retries=1,
+    capture_screenshots=True
+)
+
+browser = SentienceBrowser()
+llm = OpenAIProvider(api_key="your-key", model="gpt-4o")
+
+# Pass tracer and config to agent
+agent = SentienceAgent(browser, llm, tracer=tracer, config=config)
+
+with browser:
+    browser.page.goto("https://example.com")
+
+    # All actions are automatically traced
+    agent.act("Click the sign in button")
+    agent.act("Type 'user@example.com' into email field")
+
+# Trace events saved to trace.jsonl
+# Events: step_start, snapshot, llm_query, action, step_end, error
+```
+
+**Trace Events Captured:**
+- `step_start` - Agent begins executing a goal
+- `snapshot` - Page state captured
+- `llm_query` - LLM decision made (includes tokens, model, response)
+- `action` - Action executed (click, type, press)
+- `step_end` - Step completed successfully
+- `error` - Error occurred during execution
+
+**Use Cases:**
+- Debug why agent failed or got stuck
+- Analyze token usage and costs
+- Replay agent sessions
+- Train custom models from successful runs
+- Monitor production agents
+
+### Snapshot Utilities
+
+New utility functions for working with snapshots:
+
+```python
+from sentience import snapshot
+from sentience.utils import compute_snapshot_digests, canonical_snapshot_strict
+from sentience.formatting import format_snapshot_for_llm
+
+snap = snapshot(browser)
+
+# Compute snapshot fingerprints (detect page changes)
+digests = compute_snapshot_digests(snap.elements)
+print(f"Strict digest: {digests['strict']}")  # Changes when text changes
+print(f"Loose digest: {digests['loose']}")   # Only changes when layout changes
+
+# Format snapshot for LLM prompts
+llm_context = format_snapshot_for_llm(snap, limit=50)
+print(llm_context)
+# Output: [1] <button> "Sign In" {PRIMARY,CLICKABLE} @ (100,50) (Imp:10)
+```
+
 ## Documentation
 
 - **📖 [Amazon Shopping Guide](../docs/AMAZON_SHOPPING_GUIDE.md)** - Complete tutorial with real-world example

From 411cb12536f8f329bc4cf9c2571c2fd4d57746ef Mon Sep 17 00:00:00 2001
From: rcholic <ivytony@gmail.com>
Date: Fri, 26 Dec 2025 08:46:48 -0800
Subject: [PATCH 4/5] clean up

---
 sentience/browser.py | 14 --------------
 1 file changed, 14 deletions(-)

diff --git a/sentience/browser.py b/sentience/browser.py
index b83357c..cbeff56 100644
--- a/sentience/browser.py
+++ b/sentience/browser.py
@@ -75,10 +75,8 @@ def start(self) -> None:
 
         if package_ext_path.exists() and (package_ext_path / "manifest.json").exists():
             extension_source = package_ext_path
-            print(f"[SentienceBrowser] Loading SDK extension from: {package_ext_path}")
         elif dev_ext_path.exists() and (dev_ext_path / "manifest.json").exists():
             extension_source = dev_ext_path
-            print(f"[SentienceBrowser] Loading SDK extension from (dev): {dev_ext_path}")
         else:
             raise FileNotFoundError(
                 f"Extension not found. Checked:\n"
@@ -87,18 +85,6 @@ def start(self) -> None:
                 "Make sure the extension is built and 'sentience/extension' directory exists."
             )
 
-        # Print extension version for debugging
-        import json
-
-        try:
-            with open(extension_source / "manifest.json") as f:
-                manifest = json.load(f)
-                print(
-                    f"[SentienceBrowser] SDK extension version: {manifest.get('version', 'unknown')}"
-                )
-        except Exception:
-            pass
-
         # Create temporary extension bundle
         # We copy it to a temp dir to avoid file locking issues and ensure clean state
         self._extension_path = tempfile.mkdtemp(prefix="sentience-ext-")

From 8746c6d1ad33df996ed48edf3c5c31f71b222765 Mon Sep 17 00:00:00 2001
From: rcholic <ivytony@gmail.com>
Date: Fri, 26 Dec 2025 08:49:48 -0800
Subject: [PATCH 5/5] bump version

---
 pyproject.toml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pyproject.toml b/pyproject.toml
index 2ec681f..9b518f4 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sentience-python"
-version = "0.11.0"
+version = "0.12.0"
 description = "Python SDK for Sentience AI Agent Browser Automation"
 readme = "README.md"
 requires-python = ">=3.11"