browser-use-bridge 1.0.0__py3-none-any.whl

browser_use_bridge/__init__.py

@@ -0,0 +1,22 @@
+from browser_use_bridge.agent import Agent
+from browser_use_bridge.config import BrowserProfile, BrowserUseConfig, BrowserViewport, load_config
+from browser_use_bridge.browser import BrowserSession, SessionManager
+from browser_use_bridge.checkpoint import Checkpoint, CheckpointManager, resume_from_checkpoint
+from browser_use_bridge.tui import BrowserUseTUI, DashboardState
+from browser_use_bridge.tools import Tools
+
+__all__ = [
+    "BrowserProfile",
+    "BrowserSession",
+    "BrowserUseTUI",
+    "BrowserUseConfig",
+    "BrowserViewport",
+    "Checkpoint",
+    "CheckpointManager",
+    "Agent",
+    "DashboardState",
+    "SessionManager",
+    "Tools",
+    "load_config",
+    "resume_from_checkpoint",
+]

browser_use_bridge/__main__.py

@@ -0,0 +1,5 @@
+from browser_use_bridge.cli import main
+
+
+if __name__ == "__main__":
+    main()

browser_use_bridge/agent/__init__.py

@@ -0,0 +1,12 @@
+from browser_use_bridge.agent.message_manager import MessageManager
+from browser_use_bridge.agent.service import Agent
+from browser_use_bridge.agent.views import ActionLoopDetector, AgentHistory, AgentHistoryList, AgentOutput
+
+__all__ = [
+    "ActionLoopDetector",
+    "Agent",
+    "AgentHistory",
+    "AgentHistoryList",
+    "AgentOutput",
+    "MessageManager",
+]

browser_use_bridge/agent/controller.py

@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+import inspect
+import uuid
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from browser_use_bridge.agent.planner import Plan, PlanStep
+
+
+class ControllerState(Enum):
+    PLANNING = "planning"
+    EXECUTING = "executing"
+    VERIFYING = "verifying"
+    REPLANNING = "replanning"
+    DONE = "done"
+    FAILED = "failed"
+
+
+class StateTransition(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    state: ControllerState
+    reason: str = ""
+
+
+class StepResult(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    pending_action_id: str
+    sub_goal: str
+    action: dict[str, Any]
+    result: Any = None
+    verified: bool = False
+    attempts: int = 1
+    reason: str = ""
+
+
+class ControllerResult(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    success: bool
+    step_results: list[StepResult] = Field(default_factory=list)
+    failure_reason: str | None = None
+
+
+class Controller(BaseModel):
+    """Executes planned actions and records observable state transitions."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    tools: Any
+    planner: Any | None = None
+    browser_session: Any | None = None
+    state: ControllerState = ControllerState.PLANNING
+    transition_history: list[StateTransition] = Field(default_factory=list)
+    step_results: list[StepResult] = Field(default_factory=list)
+    current_plan: Plan | None = None
+    failure_reason: str | None = None
+
+    async def execute_plan(self, plan: Plan) -> ControllerResult:
+        self.current_plan = plan
+        self.failure_reason = None
+        self._transition(ControllerState.PLANNING, "plan accepted")
+        active_plan = plan
+
+        while True:
+            replan_requested = False
+            for step in active_plan.steps:
+                step_result = await self._execute_step(step)
+                self.step_results.append(step_result)
+                if step_result.verified:
+                    continue
+                if step.fallback_strategy == "replan" and self.planner is not None:
+                    self._transition(ControllerState.REPLANNING, step_result.reason)
+                    active_plan = await self._revise_plan(active_plan, step, step_result.reason)
+                    self.current_plan = active_plan
+                    replan_requested = True
+                    break
+                self.abort(step_result.reason or f"Step failed: {step.sub_goal}")
+                return ControllerResult(
+                    success=False,
+                    step_results=self.step_results,
+                    failure_reason=self.failure_reason,
+                )
+            if replan_requested:
+                continue
+            self._transition(ControllerState.DONE, "plan complete")
+            return ControllerResult(success=True, step_results=self.step_results)
+
+    def step_result(self, pending_action_id: str) -> StepResult:
+        for result in self.step_results:
+            if result.pending_action_id == pending_action_id:
+                return result
+        raise KeyError(pending_action_id)
+
+    def abort(self, reason: str = "aborted") -> None:
+        self.failure_reason = reason
+        self._transition(ControllerState.FAILED, reason)
+
+    def checkpoint(self) -> dict[str, Any]:
+        return {
+            "state": self.state.value,
+            "failure_reason": self.failure_reason,
+            "plan": self.current_plan.model_dump() if self.current_plan else None,
+            "step_results": [result.model_dump() for result in self.step_results],
+            "transition_history": [entry.model_dump() for entry in self.transition_history],
+        }
+
+    async def _execute_step(self, step: PlanStep) -> StepResult:
+        pending_action_id = f"step-{uuid.uuid4().hex[:12]}"
+        attempts = step.max_retries + 1
+        last_result: Any = None
+        last_reason = ""
+        for attempt in range(1, attempts + 1):
+            self._transition(ControllerState.EXECUTING, step.sub_goal)
+            last_result = await self._execute_action(step.action)
+            self._transition(ControllerState.VERIFYING, step.expected_state)
+            verified, last_reason = self._verify_result(step.expected_state, last_result)
+            if verified:
+                return StepResult(
+                    pending_action_id=pending_action_id,
+                    sub_goal=step.sub_goal,
+                    action=step.action,
+                    result=last_result,
+                    verified=True,
+                    attempts=attempt,
+                )
+        return StepResult(
+            pending_action_id=pending_action_id,
+            sub_goal=step.sub_goal,
+            action=step.action,
+            result=last_result,
+            verified=False,
+            attempts=attempts,
+            reason=last_reason,
+        )
+
+    async def _execute_action(self, action: dict[str, Any]) -> Any:
+        executor = getattr(self.tools, "execute_action", None)
+        if executor is None:
+            raise TypeError("tools must provide execute_action(action, **kwargs)")
+        kwargs: dict[str, Any] = {}
+        parameters = inspect.signature(executor).parameters
+        if "browser_session" in parameters or any(
+            parameter.kind == inspect.Parameter.VAR_KEYWORD for parameter in parameters.values()
+        ):
+            kwargs["browser_session"] = self.browser_session
+        result = executor(action, **kwargs)
+        if inspect.isawaitable(result):
+            return await result
+        return result
+
+    async def _revise_plan(self, plan: Plan, failed_step: PlanStep, reason: str) -> Plan:
+        revised = self.planner.revise(plan, failed_step, reason)
+        if inspect.isawaitable(revised):
+            revised = await revised
+        return revised
+
+    def _transition(self, state: ControllerState, reason: str = "") -> None:
+        self.state = state
+        self.transition_history.append(StateTransition(state=state, reason=reason))
+
+    @classmethod
+    def _verify_result(cls, expected_state: str, result: Any) -> tuple[bool, str]:
+        if cls._result_failed(result):
+            return False, "action result was not ok"
+        expected = expected_state.strip()
+        if not expected:
+            return True, ""
+        expected_lower = expected.lower()
+        result_text = cls._result_text(result)
+        if expected_lower in {"ok", "ok is true", "success", "success is true"}:
+            return (not cls._result_failed(result), "") if result is not None else (True, "")
+        if expected_lower.startswith("text contains "):
+            needle = expected[len("text contains ") :].strip().lower()
+            return (needle in result_text, "") if needle in result_text else (False, f"text did not contain {needle!r}")
+        if expected_lower.startswith("url contains "):
+            needle = expected[len("url contains ") :].strip().lower()
+            return (needle in result_text, "") if needle in result_text else (False, f"url did not contain {needle!r}")
+        return (expected_lower in result_text, "") if expected_lower in result_text else (False, f"expected state not observed: {expected}")
+
+    @staticmethod
+    def _result_failed(result: Any) -> bool:
+        return isinstance(result, dict) and result.get("ok") is False
+
+    @staticmethod
+    def _result_text(result: Any) -> str:
+        if isinstance(result, dict):
+            return " ".join(str(value) for value in result.values()).lower()
+        return str(result).lower()
+
+
+__all__ = [
+    "Controller",
+    "ControllerResult",
+    "ControllerState",
+    "StateTransition",
+    "StepResult",
+]

browser_use_bridge/agent/message_manager/__init__.py

@@ -0,0 +1,254 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from browser_use_bridge.agent.views import AgentHistory
+from browser_use_bridge.browser.views import BrowserStateSummary
+
+
+class MessageManager(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    task: str
+    max_tokens: int = 4000
+    keep_recent_steps: int = 3
+    histories: list[AgentHistory] = Field(default_factory=list)
+    memory_store: Any | None = None
+    memory_top_k: int = 5
+
+    def add_history(self, history: AgentHistory) -> None:
+        self.histories.append(history)
+
+    def build_messages(
+        self,
+        current_state: BrowserStateSummary,
+        nudge: str | None = None,
+        screenshots: list[Any] | None = None,
+    ) -> list[dict[str, Any]]:
+        content = "\n\n".join(
+            part for part in self._build_content_parts(current_state, nudge) if part
+        )
+        content = self._fit_to_budget(content)
+        user_content: str | list[dict[str, Any]]
+        if screenshots:
+            user_content = [{"type": "text", "text": content}]
+            user_content.extend(self._format_screenshot_parts(screenshots))
+        else:
+            user_content = content
+        return [
+            {
+                "role": "system",
+                "content": (
+                    "You are a browser automation agent. Return structured output "
+                    "with thinking, evaluation, memory, next_goal, and actions."
+                ),
+            },
+            {"role": "user", "content": user_content},
+        ]
+
+    def build_planner_messages(
+        self,
+        task: str,
+        browser_state: BrowserStateSummary,
+        history: Any | None = None,
+    ) -> list[dict[str, Any]]:
+        original_task = self.task
+        original_histories = self.histories
+        try:
+            self.task = task
+            if history is not None:
+                self.histories = list(getattr(history, "histories", history))
+            content = "\n\n".join(
+                part for part in self._build_content_parts(browser_state, nudge=None) if part
+            )
+            content = self._fit_to_budget(content)
+        finally:
+            self.task = original_task
+            self.histories = original_histories
+        return [
+            {
+                "role": "system",
+                "content": "You are a planner. Return structured plan steps with sub-goals and expected states.",
+            },
+            {"role": "user", "content": content},
+        ]
+
+    def build_controller_messages(
+        self,
+        plan_step: str,
+        step_results: list[Any] | None = None,
+    ) -> list[dict[str, Any]]:
+        lines = [
+            f"Plan step: {plan_step}",
+            "Step results:",
+        ]
+        for result in step_results or []:
+            if hasattr(result, "model_dump"):
+                result = result.model_dump()
+            lines.append(f"- {result}")
+        return [
+            {
+                "role": "system",
+                "content": "You are a controller. Use action results to verify planned execution.",
+            },
+            {"role": "user", "content": "\n".join(lines)},
+        ]
+
+    def _build_content_parts(
+        self,
+        current_state: BrowserStateSummary,
+        nudge: str | None,
+    ) -> list[str]:
+        older, recent = self._split_history()
+        parts = [
+            f"Task: {self.task}",
+            self._format_memory_context(),
+            self._format_current_state(current_state),
+        ]
+        if older:
+            parts.append(self._summarize_history(older))
+        if recent:
+            parts.append(self._format_recent_history(recent))
+        if nudge:
+            parts.append(f"Nudge: {nudge}")
+        return parts
+
+    def _split_history(self) -> tuple[list[AgentHistory], list[AgentHistory]]:
+        if self.keep_recent_steps <= 0:
+            return self.histories, []
+        return self.histories[:-self.keep_recent_steps], self.histories[-self.keep_recent_steps :]
+
+    def _format_current_state(self, state: BrowserStateSummary) -> str:
+        return "\n".join(
+            [
+                "Current browser state:",
+                f"- url: {state.url}",
+                f"- title: {state.title}",
+                f"- elements: {self._format_elements(state.elements)}",
+            ]
+        )
+
+    def _format_memory_context(self) -> str:
+        if self.memory_store is None:
+            return ""
+        try:
+            entries = self.memory_store.search(self.task, top_k=self.memory_top_k)
+        except Exception:
+            return ""
+        if not entries:
+            return ""
+        lines = ["Relevant memory:"]
+        for entry in entries:
+            memory_type = getattr(getattr(entry, "type", ""), "value", getattr(entry, "type", ""))
+            text = str(getattr(entry, "text", "")).strip()
+            if text:
+                lines.append(f"- [{memory_type}] {text}")
+        return "\n".join(lines)
+
+    def _summarize_history(self, histories: list[AgentHistory]) -> str:
+        lines = ["Compressed older history:"]
+        for index, history in enumerate(histories):
+            output = history.model_output
+            if output is None:
+                continue
+            summary_bits = [
+                bit
+                for bit in [
+                    output.evaluation,
+                    output.memory,
+                    output.next_goal,
+                    self._format_actions(output.actions),
+                ]
+                if bit
+            ]
+            lines.append(f"- step {index}: {' | '.join(summary_bits)}")
+        return "\n".join(lines)
+
+    def _format_recent_history(self, histories: list[AgentHistory]) -> str:
+        lines = ["Recent uncompressed history:"]
+        start = len(self.histories) - len(histories)
+        for offset, history in enumerate(histories):
+            output = history.model_output
+            state = history.state
+            lines.append(f"- step {start + offset}:")
+            if state is not None:
+                lines.append(f"  state: {state.title} ({state.url})")
+            if output is not None:
+                lines.append(f"  thinking: {output.thinking}")
+                lines.append(f"  evaluation: {output.evaluation}")
+                lines.append(f"  memory: {output.memory}")
+                lines.append(f"  next_goal: {output.next_goal}")
+                lines.append(f"  actions: {self._format_actions(output.actions)}")
+        return "\n".join(lines)
+
+    def _fit_to_budget(self, content: str) -> str:
+        max_chars = max(self.max_tokens * 4, 1000)
+        if len(content) <= max_chars:
+            return content
+        keep_head = max_chars // 3
+        keep_tail = max_chars - keep_head - 40
+        return f"{content[:keep_head]}\n...[context compressed]...\n{content[-keep_tail:]}"
+
+    @staticmethod
+    def _format_actions(actions: list[Any]) -> str:
+        return ", ".join(str(action) for action in actions)
+
+    @staticmethod
+    def _format_elements(elements: list[Any]) -> str:
+        if not elements:
+            return "[]"
+        rows: list[str] = []
+        for element in elements[:20]:
+            if hasattr(element, "model_dump"):
+                element = element.model_dump()
+            if isinstance(element, dict):
+                index = element.get("index")
+                tag = element.get("tag") or element.get("tag_name") or element.get("role") or "element"
+                text = element.get("text") or element.get("label") or element.get("aria_label") or ""
+                if index is not None:
+                    rows.append(f"[{index}] <{tag}> {text}".strip())
+                else:
+                    rows.append(str(element))
+            else:
+                rows.append(str(element))
+        return "\n".join(rows)
+
+    @staticmethod
+    def _format_screenshot_parts(screenshots: list[Any]) -> list[dict[str, Any]]:
+        parts: list[dict[str, Any]] = []
+        for screenshot in screenshots:
+            boxes = getattr(screenshot, "bounding_boxes", [])
+            box_lines = []
+            for box in boxes:
+                index = getattr(box, "index", None)
+                label = getattr(box, "label", None) or getattr(box, "text", None) or ""
+                if index is not None:
+                    box_lines.append(f"[{index}] {label}".strip())
+            parts.append(
+                {
+                    "type": "text",
+                    "text": "\n".join(
+                        [
+                            f"Annotated screenshot ({getattr(screenshot, 'content_type', 'image/jpeg')}):",
+                            *box_lines,
+                        ]
+                    ),
+                }
+            )
+            parts.append(
+                {
+                    "type": "image_url",
+                    "image_url": {
+                        "url": (
+                            f"data:{getattr(screenshot, 'content_type', 'image/jpeg')};base64,"
+                            f"{getattr(screenshot, 'base64_data', '')}"
+                        )
+                    },
+                }
+            )
+        return parts
+
+
+__all__ = ["MessageManager"]

browser_use_bridge/agent/planner.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from browser_use_bridge.agent.views import AgentHistoryList
+from browser_use_bridge.browser.views import BrowserStateSummary
+
+
+FallbackStrategy = Literal["retry", "skip", "fallback", "abort", "replan"]
+
+
+class PlanStep(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    sub_goal: str
+    expected_state: str
+    action: dict[str, Any] = Field(default_factory=dict)
+    max_retries: int = Field(default=1, ge=0)
+    fallback_strategy: FallbackStrategy = "replan"
+
+
+class Plan(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    task: str
+    steps: list[PlanStep] = Field(default_factory=list)
+
+
+class PlanningContext(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True, extra="allow")
+
+    task: str
+    browser_state: BrowserStateSummary
+    history: AgentHistoryList = Field(default_factory=AgentHistoryList)
+
+
+class Planner:
+    """Deterministic task decomposer used by the separated agent loop."""
+
+    async def decompose(self, context: PlanningContext) -> Plan:
+        action = self._choose_action(context)
+        sub_goal = self._sub_goal_for(context.task, action)
+        expected_state = self._expected_state_for(context.task, action)
+        return Plan(
+            task=context.task,
+            steps=[
+                PlanStep(
+                    sub_goal=sub_goal,
+                    expected_state=expected_state,
+                    action=action,
+                    max_retries=1,
+                    fallback_strategy="replan",
+                )
+            ],
+        )
+
+    async def revise(self, plan: Plan, failed_step: PlanStep, reason: str) -> Plan:
+        return Plan(
+            task=plan.task,
+            steps=[
+                PlanStep(
+                    sub_goal=f"Recover from failed step: {failed_step.sub_goal}",
+                    expected_state="ok is true",
+                    action={"done": {"success": False, "text": reason}},
+                    max_retries=0,
+                    fallback_strategy="abort",
+                )
+            ],
+        )
+
+    def _choose_action(self, context: PlanningContext) -> dict[str, Any]:
+        task_lower = context.task.lower()
+        for element in context.browser_state.elements:
+            element_data = self._element_dict(element)
+            text = str(element_data.get("text") or "").lower()
+            tag = str(element_data.get("tag") or element_data.get("tag_name") or "").lower()
+            index = element_data.get("index")
+            if index is None:
+                continue
+            if "click" in task_lower or "continue" in task_lower or tag in {"button", "a"}:
+                if not text or text in task_lower or "continue" in text or tag in {"button", "a"}:
+                    return {"click": {"index": index}}
+        if "http://" in context.task or "https://" in context.task or "file://" in context.task:
+            for token in context.task.split():
+                if token.startswith(("http://", "https://", "file://")):
+                    return {"navigate": {"url": token.strip(".,")}}
+        return {"done": {"success": True, "text": context.task}}
+
+    @staticmethod
+    def _sub_goal_for(task: str, action: dict[str, Any]) -> str:
+        if "click" in action:
+            return f"Click the target element for: {task}"
+        if "navigate" in action:
+            return f"Navigate to the requested page for: {task}"
+        return f"Finish task: {task}"
+
+    @staticmethod
+    def _expected_state_for(task: str, action: dict[str, Any]) -> str:
+        if "click" in action:
+            return f"task progresses toward {task}"
+        if "navigate" in action:
+            url = action["navigate"].get("url", "")
+            return f"url contains {url}"
+        return "ok is true"
+
+    @staticmethod
+    def _element_dict(element: Any) -> dict[str, Any]:
+        if hasattr(element, "model_dump"):
+            element = element.model_dump(exclude_none=True)
+        return element if isinstance(element, dict) else {}
+
+
+__all__ = ["FallbackStrategy", "Plan", "PlanStep", "Planner", "PlanningContext"]