tot_agent.results

Structured action result helpers used throughout browser.py and tools.py.

Overview

All BrowserManager action methods and the dispatch() tool router return a plain dict with a consistent shape. The helpers in this module build those dicts so every call site uses the same structure.

Result shape

{
    "ok": True | False,          # success flag
    "message": "Human summary",  # always present
    "data": {...},               # method-specific payload (success only)
    "error": "Exception text",   # only present on failure
    "recoverable": True | False, # only present on failure
}

Class diagram

classDiagram
    class ActionResult {
        +ok: bool
        +message: str
        +data: dict
        +error: str
        +recoverable: bool
    }

Helper functions

Function	Returns	Description
success_result(message, **data)	dict	Build an ok=True result with optional payload fields
failure_result(message, *, error, recoverable, **data)	dict	Build an ok=False result with error detail
is_failure_result(result)	bool	Return True when a result dict signals failure

Usage pattern

from tot_agent.results import failure_result, is_failure_result, success_result

async def navigate(self, url: str) -> dict:
    try:
        await self.active_page.goto(url)
        return success_result(f"Navigated to {url}", url=url)
    except Exception as exc:
        return failure_result(f"Navigation failed: {url}", error=str(exc))

Module reference

tot_agent.results

results.py — Structured action results shared by browser and tool layers.

ActionResult dataclass

Serializable result for browser actions and tool dispatch.

Source code in src/tot_agent/results.py

@dataclass(slots=True)
class ActionResult:
    """Serializable result for browser actions and tool dispatch."""

    ok: bool
    message: str
    data: dict[str, Any] = field(default_factory=dict)
    error: str | None = None
    recoverable: bool = False

    def to_dict(self) -> dict[str, Any]:
        """Convert the result to a plain dict for API/tool transport."""
        payload: dict[str, Any] = {
            "ok": self.ok,
            "message": self.message,
        }
        if self.data:
            payload["data"] = self.data
        if self.error:
            payload["error"] = self.error
        if self.recoverable:
            payload["recoverable"] = True
        return payload

to_dict()

Convert the result to a plain dict for API/tool transport.

Source code in src/tot_agent/results.py

def to_dict(self) -> dict[str, Any]:
    """Convert the result to a plain dict for API/tool transport."""
    payload: dict[str, Any] = {
        "ok": self.ok,
        "message": self.message,
    }
    if self.data:
        payload["data"] = self.data
    if self.error:
        payload["error"] = self.error
    if self.recoverable:
        payload["recoverable"] = True
    return payload

success_result(message, **data)

Build a successful structured result.

Source code in src/tot_agent/results.py

def success_result(message: str, **data: Any) -> dict[str, Any]:
    """Build a successful structured result."""
    return ActionResult(ok=True, message=message, data=data).to_dict()

failure_result(message, *, error=None, recoverable=False, **data)

Build a failed structured result.

Source code in src/tot_agent/results.py

def failure_result(
    message: str,
    *,
    error: str | None = None,
    recoverable: bool = False,
    **data: Any,
) -> dict[str, Any]:
    """Build a failed structured result."""
    return ActionResult(
        ok=False,
        message=message,
        data=data,
        error=error,
        recoverable=recoverable,
    ).to_dict()

is_failure_result(result)

Return True when result is a structured failure payload.

Source code in src/tot_agent/results.py

def is_failure_result(result: Any) -> bool:
    """Return True when *result* is a structured failure payload."""
    return isinstance(result, dict) and result.get("ok") is False