frontend-perception-engine 0.1.0__py3-none-any.whl

frontend_perception_engine-0.1.0.dist-info/METADATA

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: frontend-perception-engine
+Version: 0.1.0
+Summary: Frontend perception engine with optional CRG-powered navigation hints for Browser Use.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: browser-use>=0.13.3
+Requires-Dist: code-review-graph>=2.3.6
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: mcp>=1.0.0
+Provides-Extra: aws
+Requires-Dist: boto3>=1.35.0; extra == "aws"
+
+# Frontend Perception Engine (CRG as Optional Library)
+
+This project implements a frontend navigation layer where:
+
+- Browser Use stays the browser automation engine.
+- Code Review Graph (CRG) is used only as an optional knowledge source.
+- Browser execution continues even when CRG is unavailable.
+
+## Architecture
+
+```text
+Cursor / Claude
+   ↓
+Our MCP
+   ↓
+Frontend Navigation Layer
+   ↓
+Browser Use
+   ↓
+Browser
+```
+
+CRG is integrated behind `ICodeGraph`, so it can be replaced later by another backend such as `FrontendInteractionGraph` without changing Browser Use orchestration.
+
+## Dependency Integration
+
+CRG is integrated as a dependency (not forked, not modified):
+
+- `code-review-graph>=2.3.6`
+- `browser-use>=0.13.3`
+
+Install:
+
+```bash
+pip install -e .
+```
+
+## Frontend Perception MCP (No LLM in Server)
+
+The MCP server is deterministic runtime only (browser observation + actions + verify).  
+Your coding agent (Cursor/Claude/Codex) remains the brain.
+
+### Install
+
+Development install:
+
+```bash
+pip install -e .
+```
+
+Published package usage (when installed from index):
+
+```bash
+pip install frontend-perception-engine
+```
+
+### Run MCP server
+
+Using module entrypoint:
+
+```bash
+python -m navigation.mcp
+```
+
+Using script entrypoint:
+
+```bash
+frontend-perception-mcp
+```
+
+Using `uvx` (no local install in current environment):
+
+```bash
+uvx --from frontend-perception-engine frontend-perception-mcp
+```
+
+### Cursor MCP config
+
+```json
+{
+  "mcpServers": {
+    "frontend-perception": {
+      "command": "python",
+      "args": ["-m", "navigation.mcp"],
+      "env": {
+        "PYTHONPATH": "C:/Users/usman/Projects/frontend-perception-engine/src"
+      }
+    }
+  }
+}
+```
+
+### Runtime prerequisites
+
+- Start the sandbox app: `cd sandbox && npm run dev`
+- Default URL used by tests/tools: `http://localhost:5173`
+- No API keys are required to run the MCP path itself
+
+## CRG Documentation and Public API Notes
+
+The integration uses CRG public tool functions from:
+
+- `code_review_graph.tools.build.build_or_update_graph`
+- `code_review_graph.tools.query.query_graph`
+- `code_review_graph.tools.query.semantic_search_nodes`
+- `code_review_graph.tools.query.get_impact_radius`
+- `code_review_graph.tools.query.list_graph_stats`
+- `code_review_graph.tools.query.traverse_graph_func`
+
+### Graph lifecycle
+
+- Initialize graph (incremental/minimal): `build_or_update_graph(full_rebuild=False, postprocess="minimal")`
+- Refresh graph (incremental): `build_or_update_graph(full_rebuild=False)`
+- Rebuild graph (full): `build_or_update_graph(full_rebuild=True)`
+
+### Incremental indexing
+
+CRG incremental path is handled by `incremental_update` under the hood and can detect changed files from VCS (`base=HEAD~1` by default).
+
+### Watch mode
+
+CRG supports continuous updates via:
+
+- CLI: `code-review-graph watch`
+- API internals: `code_review_graph.incremental.watch` and `start_watch_thread`
+
+This wrapper does not require watch mode, but is compatible with repositories kept fresh by CRG watch/daemon.
+
+### Querying
+
+- Pattern queries (neighbors/file relationships): `query_graph`
+- Search (hybrid semantic + keyword): `semantic_search_nodes`
+- Blast radius / route impact: `get_impact_radius`
+- Traversal/path-like exploration: `traverse_graph_func`
+- Stats/health: `list_graph_stats`
+
+## Wrapper Layer
+
+All CRG coupling is isolated in:
+
+`src/navigation/codeGraph/`
+
+Public contract:
+
+- `initialize()`
+- `refresh()`
+- `rebuild()`
+- `search()`
+- `shortest_path()`
+- `get_neighbors()`
+- `get_component()`
+- `get_file()`
+- `get_route()`
+- `query()`
+
+Future-oriented methods are already represented on `ICodeGraph`:
+
+- `findNavigationHint(...)` style equivalent via `find_navigation_hint(...)`
+- `find_relevant_components(...)`
+- `find_likely_route(...)`
+- `find_related_files(...)`
+- `find_button_candidates(...)`
+- `find_component_hierarchy(...)`
+- `find_entry_point(...)`
+
+## Browser Use Integration
+
+`BrowserUseNavigator` provides a lightweight dry-run timeline for tests.
+
+`PerceptionAgentRunner` runs a **real Browser Use agent** with optional graph hints injected via `extend_system_message`. Graph output is never a mandatory stage — if CRG or AWS credentials are missing, the agent either skips hints or reports a clear error.
+
+### Live agent (Bedrock Nova)
+
+1. Start the sandbox:
+
+```bash
+cd sandbox && npm run dev
+```
+
+2. Configure AWS (copy `.env.example` → `.env`):
+
+```bash
+AWS_ACCESS_KEY_ID=...
+AWS_SECRET_ACCESS_KEY=...
+AWS_REGION=us-east-1
+BEDROCK_MODEL=amazon.nova-pro-v1:0
+SANDBOX_URL=http://localhost:5173
+```
+
+3. Install AWS extra and run:
+
+```bash
+pip install -e ".[aws]"
+python src/run_agent.py --task "Add Pulse Watch to cart and complete checkout"
+```
+
+Dry-run (graph hints only, no browser):
+
+```bash
+python src/run_agent.py --dry-run --task "Log in as admin and open admin report"
+```
+
+Flags:
+
+- `--no-graph` — disable CRG hints
+- `--headless` — headless browser
+- `--max-steps 25` — step limit
+- `--url http://localhost:5174` — custom sandbox URL
+
+## Demo
+
+Run:
+
+```bash
+python src/demo.py
+```
+
+Expected behavior:
+
+1. Browser Use execution starts.
+2. Optional code graph query is attempted.
+3. Browser Use continues regardless of query success.

frontend_perception_engine-0.1.0.dist-info/RECORD

@@ -0,0 +1,50 @@
+navigation/__init__.py,sha256=PFr_V0xYQhWjKk5oc83cYg_JcNZ2FEKTsjXlnxmkyB8,25
+navigation/browser_use/__init__.py,sha256=9Kn0IycRaPL_TJzhLllJ-x0IC3qX9T01cclQPTTj7pg,571
+navigation/browser_use/agent_runner.py,sha256=8b3MhnMFfuIp7EcOPH-r0sXhM_KyI_-6rCiEY7L3CYE,5515
+navigation/browser_use/hints.py,sha256=hlI7s27THrn_LPM6scXxpCG5SdQgVEGW-YXm9ly-jNs,5820
+navigation/browser_use/integration.py,sha256=isJWR4WAoUvf42UiD4-KCJnAxhcHbPXGfITaHRTyFbo,1606
+navigation/browser_use/llm.py,sha256=6avNVsUSFMQ-YnxFNcXzEocbUG7_7AsXe8oJnW4bgKQ,2264
+navigation/codeGraph/__init__.py,sha256=TxbCfLdv5W7D9iX3D17Pv7F7JvPrqepOu_aTOrNGEWo,162
+navigation/codeGraph/crg_impl.py,sha256=XufOmUj8AZRjmbkC4nifWwWzzmDjz_dwuWbGctWgc1w,7424
+navigation/codeGraph/factory.py,sha256=709P9REWEf5j1GOFgXueSOPNNQ6PIc1QkKivwtSOP3E,774
+navigation/codeGraph/interface.py,sha256=QZXalLUGN1or6YvnvW_yeAbCfpXQZoHolH55HhDsKrI,2916
+navigation/codeGraph/null_impl.py,sha256=gd8aj6tTDwEVfphkJ_D0NHX0nF70o28zKp247bwx5sw,1674
+navigation/mcp/__init__.py,sha256=K8WWeP6YjK0gb1oRSXZhpD1xl6Vi1Mik59dEhPty_g4,132
+navigation/mcp/__main__.py,sha256=Z5XW_4J0QbOX5nH0KzYtoMs2jyUz290JK-fnWD1Ak_A,82
+navigation/mcp/diff.py,sha256=i4nWWOQCRY2bigGcGmyNG-IdAB_PGx_Kj2P-IsV3dnY,1072
+navigation/mcp/envelope.py,sha256=2kf_MOnkysK2i-IpR7XhJU-dXlKObopRWKKn1FST4rw,1467
+navigation/mcp/handlers.py,sha256=9t8DHtj0KcWeQEhT5aplCGvBJGdRtz-ubrQGGcmELqg,27146
+navigation/mcp/instructions.py,sha256=glYPaoRuUCjgdSe8SKR0BZHvh9kQNT-QHEQDTfI8sDY,1932
+navigation/mcp/resources.py,sha256=Blq5P4XJwnXLaq23s1XHLqu6PQqE7cK8QSa5ZnwwABk,3371
+navigation/mcp/scan_registry.py,sha256=V0J20AaGAXG3LQhjWdGLtZ5c19aK8KX7i-1FFrOTpTA,1192
+navigation/mcp/server.py,sha256=eSkhFEt14e7YPG_7wc94vgUJPxJMCgoK4rckXAYcPeg,8444
+navigation/mcp/session_store.py,sha256=MLjts9tni3P6gNdpOM83PKIzBf82CwfbKeT3xrcJdzU,2645
+navigation/mcp/tools.py,sha256=fhnffshXwm5es4N9vp7IOaiZ_09o9Q0SHvCRjpk8zcU,14429
+navigation/perception/__init__.py,sha256=vSUXp490x56flZrnCUCSrhY--_qlhaiqwA-m443Tr10,2538
+navigation/perception/artifacts.py,sha256=Xw1R3c2sZBDvbL7VxIq0qt9gijon6KVDir8eFZEh4Nk,591
+navigation/perception/auth_gate.py,sha256=-L8iR7-zrhQKEbFm4fQOWoJ-IfFr5QgFbnA3EhTVXNU,1690
+navigation/perception/budget.py,sha256=qcjJJbN9NRLt0lKPyGcvI3165i7CG5dBM4m0CLIy0_k,2068
+navigation/perception/cdp_hub.py,sha256=QkzKX5mFS7UV3GyRi9Ci4S62hWLFWpT0UplEBBeB6iA,4797
+navigation/perception/dev_insights.py,sha256=N6DG3N_F-ZoUdVVbXPnPvU5xMFO7ygy7ibmhYRRivhk,23049
+navigation/perception/exploration.py,sha256=tYRo7JeI875qiO4vud6q9oBW9f7iz-lHeLFVp8PgLis,3017
+navigation/perception/feature_flags.py,sha256=MyyTyR3r1mPwBangnXYepUZW208v6ojrQ665s1cqaYI,2659
+navigation/perception/file_upload.py,sha256=Wb2pIcJ7Ivay564oSAPSZ3T7_xlY7oXzLiDpJOdEgcM,2795
+navigation/perception/flow_graph.py,sha256=0XoTe3b9talf4_OepK071lTSWESXObSmtUkSPq-z1l4,3979
+navigation/perception/form_probe.py,sha256=JJw-ldlbZTDAWfdeTiIY_6csbTwrl1HIN1t162mad_8,4826
+navigation/perception/iframe_context.py,sha256=JF_gqLp2bPF85juIMLep6xYUFusZMKX9-llEZqWX-ME,2358
+navigation/perception/observation.py,sha256=KwiLwpjMUsieJu0ehXU0Y80PZQJYDeNqpJG9IvB3Ee8,3415
+navigation/perception/preflight.py,sha256=CAHesJItqLwQctxDiGU6jFjfq0alTbwHVD1ufEk8Zoo,2436
+navigation/perception/rich_editors.py,sha256=n2DmvF9VtiKMXE2_WHkfFE5RSJZzE6OwfJ6yFMIypDQ,3172
+navigation/perception/route_guards.py,sha256=3OT9Iszr6ZHptebkp5Pg_53C0WZGjsAyFNMX_Z4a2LM,4475
+navigation/perception/runner.py,sha256=LekITqY8lIjTBV6RZ0OU89VeEf7V0jZefvP--ssSNTM,5477
+navigation/perception/scan.py,sha256=1NcomG4zBxHRw59pRpG7Zg9XZq-PDp-X9x109oVcQn4,2305
+navigation/perception/scripted_actions.py,sha256=rTTC8qngqWxC1umPkCF64Jrz6IJ9DsWLuPR4OORXDQA,2228
+navigation/perception/state_manager.py,sha256=018JcETIIcaReWRkNLNavh9CXNc8RfmDlmXmWuyVmYM,4013
+navigation/perception/verification.py,sha256=2_FNwvKAR7cz7ygDpDMKkbG9ZxgwWIIEfoQ8bMvlT_A,4221
+navigation/perception/virtual_scroll.py,sha256=bjvxWVcg0LupP3cxvb0e1QBiGDp1u0ETSXViJzlmnBc,2507
+navigation/perception/websocket_observer.py,sha256=UY2dUED4Xfe8oPzxJGwA6iDo3q0Jx5yzpRMBOCAHuZ4,2348
+frontend_perception_engine-0.1.0.dist-info/METADATA,sha256=_yfn-nDw0bF_OMUjDkhUxgZJXQYZN6UAfjlvgd12DQE,5859
+frontend_perception_engine-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+frontend_perception_engine-0.1.0.dist-info/entry_points.txt,sha256=Fh3U8gGnkQGRxlGbntvstQWTwR4yQ8d40PiXnrWttsU,71
+frontend_perception_engine-0.1.0.dist-info/top_level.txt,sha256=lduxtTnjhATakWa5QPv5nkzURLRdjC3F0fjz1Ea_kS0,11
+frontend_perception_engine-0.1.0.dist-info/RECORD,,

frontend_perception_engine-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

frontend_perception_engine-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+frontend-perception-mcp = navigation.mcp.server:main

frontend_perception_engine-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+navigation

navigation/__init__.py

@@ -0,0 +1 @@
+__all__: list[str] = []

navigation/browser_use/__init__.py

@@ -0,0 +1,17 @@
+from .agent_runner import AgentRunResult, PerceptionAgentRunner
+from .hints import GraphHintResolver, NavigationHint, format_hints_for_agent
+from .integration import BrowserUseNavigator, BrowserUseStep
+from .llm import create_bedrock_llm, credentials_available, get_bedrock_config
+
+__all__ = [
+    "AgentRunResult",
+    "BrowserUseNavigator",
+    "BrowserUseStep",
+    "GraphHintResolver",
+    "NavigationHint",
+    "PerceptionAgentRunner",
+    "create_bedrock_llm",
+    "credentials_available",
+    "format_hints_for_agent",
+    "get_bedrock_config",
+]

navigation/browser_use/agent_runner.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import asyncio
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from navigation.codeGraph.interface import ICodeGraph
+
+from .hints import GraphHintResolver, NavigationHint, format_hints_for_agent, hint_to_step_details
+from .integration import BrowserUseStep
+from .llm import create_bedrock_llm, credentials_available
+
+
+@dataclass(slots=True)
+class AgentRunResult:
+    task: str
+    success: bool
+    steps_taken: int
+    final_result: str | None
+    hint: NavigationHint
+    timeline: list[BrowserUseStep] = field(default_factory=list)
+    error: str | None = None
+
+    def summary(self) -> str:
+        lines = [
+            f"Task: {self.task}",
+            f"Success: {self.success}",
+            f"Steps: {self.steps_taken}",
+            f"Graph hints used: {self.hint.ok} ({len(self.hint.hits)} hits)",
+        ]
+        if self.final_result:
+            lines.append(f"Result: {self.final_result[:500]}")
+        if self.error:
+            lines.append(f"Error: {self.error}")
+        return "\n".join(lines)
+
+
+class PerceptionAgentRunner:
+    """
+    Runs a real Browser Use agent with optional CRG navigation hints.
+
+    Graph hints are injected via extend_system_message — never a hard pipeline stage.
+    If the graph or Bedrock credentials are missing, the agent still attempts the task.
+    """
+
+    def __init__(
+        self,
+        code_graph: ICodeGraph | None = None,
+        *,
+        start_url: str | None = None,
+        model: str | None = None,
+        region: str | None = None,
+        max_steps: int = 25,
+        headless: bool = False,
+        use_vision: bool = True,
+    ) -> None:
+        self.code_graph = code_graph
+        self.start_url = start_url or os.getenv("SANDBOX_URL", "http://localhost:5173")
+        self.model = model
+        self.region = region
+        self.max_steps = max_steps
+        self.headless = headless
+        self.use_vision = use_vision
+        self.hint_resolver = GraphHintResolver(code_graph)
+        self.timeline: list[BrowserUseStep] = []
+
+    def _record(self, action: str, details: dict[str, Any]) -> None:
+        self.timeline.append(BrowserUseStep(action=action, details=details))
+
+    async def run(self, task: str) -> AgentRunResult:
+        self.timeline = []
+        self._record("browser_use.start", {"task": task, "start_url": self.start_url})
+
+        hint = self.hint_resolver.resolve(task)
+        self._record("code_graph.query", hint_to_step_details(hint))
+
+        if not credentials_available():
+            self._record("browser_use.skip", {"reason": "missing_aws_credentials"})
+            return AgentRunResult(
+                task=task,
+                success=False,
+                steps_taken=0,
+                final_result=None,
+                hint=hint,
+                timeline=self.timeline,
+                error="AWS credentials not configured. Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.",
+            )
+
+        try:
+            from browser_use import Agent, BrowserProfile
+        except ImportError as exc:
+            return AgentRunResult(
+                task=task,
+                success=False,
+                steps_taken=0,
+                final_result=None,
+                hint=hint,
+                timeline=self.timeline,
+                error=f"browser-use not installed: {exc}",
+            )
+
+        llm = create_bedrock_llm(model=self.model, region=self.region)
+        graph_context = format_hints_for_agent(hint, self.start_url)
+
+        full_task = (
+            f"{task}\n\n"
+            f"Open {self.start_url} first if you are not already on the Navigation Maze app."
+        )
+
+        profile = BrowserProfile(headless=self.headless)
+
+        self._record(
+            "browser_use.agent_init",
+            {
+                "model": self.model or os.getenv("BEDROCK_MODEL", "amazon.nova-pro-v1:0"),
+                "hint_injected": hint.ok,
+                "max_steps": self.max_steps,
+            },
+        )
+
+        agent = Agent(
+            task=full_task,
+            llm=llm,
+            browser_profile=profile,
+            use_vision=self.use_vision,
+            extend_system_message=graph_context,
+            initial_actions=[{"navigate": {"url": self.start_url, "new_tab": False}}],
+        )
+
+        try:
+            history = await agent.run(max_steps=self.max_steps)
+            final = history.final_result()
+            success = bool(history.is_successful())
+            self._record(
+                "browser_use.done",
+                {
+                    "success": success,
+                    "steps": len(history.history),
+                    "final_result": (final or "")[:300],
+                },
+            )
+            return AgentRunResult(
+                task=task,
+                success=success,
+                steps_taken=len(history.history),
+                final_result=final,
+                hint=hint,
+                timeline=self.timeline,
+            )
+        except Exception as exc:
+            self._record("browser_use.error", {"error": str(exc)})
+            return AgentRunResult(
+                task=task,
+                success=False,
+                steps_taken=len(self.timeline),
+                final_result=None,
+                hint=hint,
+                timeline=self.timeline,
+                error=str(exc),
+            )
+
+    def run_sync(self, task: str) -> AgentRunResult:
+        return asyncio.run(self.run(task))

navigation/browser_use/hints.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from navigation.codeGraph.interface import GraphQueryResult, ICodeGraph
+
+
+@dataclass(slots=True)
+class NavigationHint:
+    task: str
+    summary: str
+    hits: list[dict[str, Any]] = field(default_factory=list)
+    related_files: list[str] = field(default_factory=list)
+    route_files: list[str] = field(default_factory=list)
+    ok: bool = False
+
+
+class GraphHintResolver:
+    """Resolve optional navigation hints from ICodeGraph without coupling Browser Use to CRG."""
+
+    STOP_WORDS = {
+        "the", "a", "an", "and", "or", "to", "as", "in", "on", "for", "open",
+        "navigate", "locate", "complete", "continue", "flow", "changes", "save",
+        "with", "from", "into", "then", "that", "this", "your", "user",
+    }
+
+    def __init__(self, code_graph: ICodeGraph | None) -> None:
+        self.code_graph = code_graph
+
+    @classmethod
+    def extract_keywords(cls, task: str) -> list[str]:
+        words = [w.strip(".,!?").lower() for w in task.split()]
+        return [w for w in words if w not in cls.STOP_WORDS and len(w) > 2]
+
+    NAV_PRIORITY = ("checkout", "cart", "login", "admin", "settings", "shop", "profile", "payment", "shipping")
+
+    def resolve(self, task: str) -> NavigationHint:
+        if self.code_graph is None:
+            return NavigationHint(task=task, summary="Graph unavailable", ok=False)
+
+        hits: list[dict[str, Any]] = []
+        related_files: list[str] = []
+        route_files: list[str] = []
+        summary = "No graph hints found"
+        keywords = self.extract_keywords(task)
+        priority = [k for k in self.NAV_PRIORITY if k in keywords]
+        search_order = priority + [k for k in keywords if k not in priority]
+
+        hint = self.code_graph.find_navigation_hint(task)
+        if hint.ok and (hint.payload or {}).get("results"):
+            hits = list(hint.payload["results"])
+            summary = hint.summary
+
+        if not hits:
+            for kw in search_order:
+                result = self.code_graph.search(kw, limit=5)
+                if result.ok and (result.payload or {}).get("results"):
+                    for item in result.payload["results"]:
+                        if item not in hits:
+                            hits.append(item)
+                    summary = result.summary
+                    if kw in self.NAV_PRIORITY:
+                        break
+
+        if not hits:
+            for kw in search_order[:2]:
+                result = self.code_graph.find_entry_point(kw)
+                if result.ok and (result.payload or {}).get("results"):
+                    hits = list(result.payload["results"])
+                    summary = result.summary
+                    break
+
+        for kw in search_order[:3]:
+            related = self.code_graph.find_related_files(kw)
+            if related.ok:
+                for item in (related.payload or {}).get("results") or []:
+                    fp = item.get("file_path") or item.get("name")
+                    if fp and fp not in related_files:
+                        related_files.append(fp)
+
+        keywords = self.extract_keywords(task)
+        if {"checkout", "cart", "shop"} & set(keywords):
+            route = self.code_graph.get_route(
+                changed_files=[
+                    "src/pages/shop/Cart.jsx",
+                    "src/pages/shop/checkout/ShippingStep.jsx",
+                ],
+            )
+            if route.ok:
+                route_files = list((route.payload or {}).get("impacted_files") or [])[:8]
+
+        return NavigationHint(
+            task=task,
+            summary=summary,
+            hits=hits[:8],
+            related_files=related_files[:8],
+            route_files=route_files,
+            ok=bool(hits or related_files or route_files),
+        )
+
+
+def format_hints_for_agent(hint: NavigationHint, start_url: str) -> str:
+    """Turn graph hints into advisory context for Browser Use's extend_system_message."""
+    if not hint.ok:
+        return (
+            "## Code graph hints\n"
+            "No codebase hints are available for this task. Rely on the live page only.\n"
+            f"Start URL: {start_url}\n"
+        )
+
+    lines = [
+        "## Code graph hints (advisory only)",
+        "These come from a static code graph. Prefer what you see in the browser if they conflict.",
+        f"Start URL: {start_url}",
+        f"Graph summary: {hint.summary}",
+        "",
+    ]
+
+    if hint.hits:
+        lines.append("Relevant code entities:")
+        for item in hint.hits:
+            name = item.get("name") or item.get("qualified_name") or "unknown"
+            fp = item.get("file_path") or item.get("file") or ""
+            kind = item.get("kind") or ""
+            suffix = f" ({fp})" if fp else ""
+            lines.append(f"- {name}{' [' + kind + ']' if kind else ''}{suffix}")
+
+    if hint.related_files:
+        lines.append("")
+        lines.append("Related files:")
+        for fp in hint.related_files:
+            lines.append(f"- {fp}")
+
+    if hint.route_files:
+        lines.append("")
+        lines.append("Likely route / impact files for shop-checkout flow:")
+        for fp in hint.route_files:
+            lines.append(f"- {fp}")
+
+    lines.append("")
+    lines.append("Use breadcrumbs, navbar links, buttons, and forms visible on the page.")
+    return "\n".join(lines)
+
+
+def hint_to_step_details(hint: NavigationHint, raw: GraphQueryResult | None = None) -> dict[str, Any]:
+    return {
+        "ok": hint.ok,
+        "summary": hint.summary,
+        "error": raw.error if raw else None,
+        "hits": len(hint.hits),
+        "top_hit": (hint.hits[0].get("name") if hint.hits else None),
+        "related_files": hint.related_files[:3],
+        "route_files": hint.route_files[:3],
+    }

navigation/browser_use/integration.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from navigation.codeGraph.interface import ICodeGraph
+
+from .hints import GraphHintResolver, hint_to_step_details
+
+
+@dataclass(slots=True)
+class BrowserUseStep:
+    action: str
+    details: dict[str, Any] = field(default_factory=dict)
+
+
+class BrowserUseNavigator:
+    """
+    Lightweight orchestration timeline for tests and dry-runs.
+    For real browser automation with Bedrock Nova, use PerceptionAgentRunner.
+    """
+
+    def __init__(self, code_graph: ICodeGraph | None = None) -> None:
+        self.code_graph = code_graph
+        self.timeline: list[BrowserUseStep] = []
+        self.hint_resolver = GraphHintResolver(code_graph)
+
+    def execute(self, task: str) -> list[BrowserUseStep]:
+        self.timeline.append(BrowserUseStep(action="browser_use.start", details={"task": task}))
+
+        hint = self.hint_resolver.resolve(task)
+        self.timeline.append(BrowserUseStep(action="code_graph.query", details=hint_to_step_details(hint)))
+
+        self.timeline.append(
+            BrowserUseStep(
+                action="browser_use.navigate",
+                details={
+                    "task": task,
+                    "hint_used": hint.ok,
+                    "mode": "dry_run",
+                    "note": "Use PerceptionAgentRunner for live Browser Use + Bedrock",
+                },
+            )
+        )
+        self.timeline.append(BrowserUseStep(action="browser_use.continue", details={"status": "ok"}))
+        return self.timeline