browserrig 0.1.0__py3-none-any.whl

browserrig/__init__.py

@@ -0,0 +1,158 @@
+from .activity import Activity
+from .agent import Agent  # smelt: ignore[SMT106] -- public facade
+from .browser import (
+    Browser,
+    Chrome,
+    ChromeBrowser,
+    Connect,
+    Launch,
+    SessionSetup,
+    Viewport,
+)
+from .choreography import InputVisualization, TabStrip
+from .completion import Done
+from .composition import (  # smelt: ignore[SMT106] -- public facade
+    ContextCompaction,
+    WindowRatio,
+    browser_kit,
+    browser_plugins,
+)
+from .core import Point
+from .files import FileSystem, FileSystemOptions
+from .handoff import HandoffCallback, HandoffReceipt, HumanHandoff, HumanResponse
+from .kinds import MouseEventKind
+from .nudges import Nudges
+from .observation import (
+    CaptureContent,
+    CaptureStrategy,
+    DomCapture,
+    DomElementHandle,
+    DomReferences,
+    DomRenderer,
+    ElementHandle,
+    ElementInfo,
+    ElementRef,
+    ImageContext,
+    ImageRetention,
+    Observe,
+    PageContent,
+    References,
+    Renderer,
+    Screenshots,
+    ScreenshotTrigger,
+    ScrollableElement,
+    ScrollStep,
+    TrimInBatches,
+    UntilCompaction,
+)
+from .pacing import InputPacing
+from .readiness import (
+    CheckReadiness,
+    DomReady,
+    DownloadReadiness,
+    Readiness,
+    ReadinessCheck,
+    ReadinessContext,
+    ReadinessOptions,
+    ReadinessPolicy,
+    ReadinessStrategy,
+    SelectReadiness,
+    wait_for_page,
+)
+from .secrets import Secret, Secrets, SecretValue, Totp, env
+from .terminal import TerminalEvents
+from .tools import (
+    Actions,
+    DialogTools,
+    DomActionChains,
+    FileTools,
+    FindTools,
+    FormTools,
+    JavaScriptTools,
+    KeyboardTools,
+    NavigationTools,
+    ObserveAfterInput,
+    PointerTools,
+    TabTools,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Agent",
+    "ContextCompaction",
+    "CheckReadiness",
+    "DownloadReadiness",
+    "ReadinessCheck",
+    "SelectReadiness",
+    "Done",
+    "HandoffCallback",
+    "HandoffReceipt",
+    "HumanHandoff",
+    "HumanResponse",
+    "CaptureContent",
+    "CaptureStrategy",
+    "DomCapture",
+    "DomElementHandle",
+    "DomReferences",
+    "ElementHandle",
+    "ElementInfo",
+    "PageContent",
+    "ElementRef",
+    "References",
+    "ScrollableElement",
+    "ScrollStep",
+    "DomRenderer",
+    "ImageContext",
+    "ImageRetention",
+    "TrimInBatches",
+    "UntilCompaction",
+    "Renderer",
+    "Screenshots",
+    "ScreenshotTrigger",
+    "DomReady",
+    "ReadinessContext",
+    "ReadinessPolicy",
+    "ReadinessStrategy",
+    "FindTools",
+    "DialogTools",
+    "FileTools",
+    "JavaScriptTools",
+    "InputVisualization",
+    "TabStrip",
+    "FormTools",
+    "PointerTools",
+    "KeyboardTools",
+    "NavigationTools",
+    "TabTools",
+    "ObserveAfterInput",
+    "DomActionChains",
+    "Activity",
+    "Actions",
+    "Point",
+    "MouseEventKind",
+    "Browser",
+    "Chrome",
+    "ChromeBrowser",
+    "Connect",
+    "FileSystem",
+    "FileSystemOptions",
+    "Launch",
+    "SessionSetup",
+    "Nudges",
+    "Observe",
+    "InputPacing",
+    "Readiness",
+    "ReadinessOptions",
+    "Secret",
+    "SecretValue",
+    "Secrets",
+    "Totp",
+    "env",
+    "Viewport",
+    "WindowRatio",
+    "TerminalEvents",
+    "browser_plugins",
+    "browser_kit",
+    "wait_for_page",
+]

browserrig/activity/__init__.py

@@ -0,0 +1,5 @@
+from browserrig.core import ActivityKind, ActivityOutcome
+
+from .plugin import Activity
+
+__all__ = ["Activity", "ActivityKind", "ActivityOutcome"]

browserrig/activity/models.py

@@ -0,0 +1,93 @@
+from collections.abc import Iterable
+from dataclasses import dataclass
+from time import monotonic
+from typing import assert_never
+
+from harnessed.events import SessionEvent, StepOutcome, TurnOutcome
+
+from browserrig.core import ActivityKind, ActivityOutcome
+from browserrig.events import ActivityFinishedEvent, ActivityStartedEvent
+
+
+@dataclass(frozen=True, slots=True)
+class ActivityKey:
+    """Correlated request/tool/readiness slots and a singleton pause slot."""
+
+    kind: ActivityKind
+    correlation_id: str = ""
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "kind", ActivityKind(self.kind))
+        if not isinstance(self.correlation_id, str):
+            raise TypeError("Activity correlation IDs must be strings")
+        correlated = self.kind != ActivityKind.PAUSED
+        if bool(self.correlation_id) != correlated:
+            raise ValueError(
+                "Model, tool, readiness and compaction activities require a correlation ID"
+            )
+
+
+def step_outcome(reason: StepOutcome) -> ActivityOutcome:
+    match reason:
+        case StepOutcome.COMPLETED:
+            return ActivityOutcome.COMPLETED
+        case StepOutcome.INTERRUPTED:
+            return ActivityOutcome.INTERRUPTED
+        case StepOutcome.ABORTED:
+            return ActivityOutcome.ABORTED
+        case StepOutcome.CONTEXT_LIMIT:
+            return ActivityOutcome.CONTEXT_LIMIT
+        case _:
+            assert_never(reason)
+
+
+def turn_outcome(reason: TurnOutcome) -> ActivityOutcome:
+    match reason:
+        case TurnOutcome.COMPLETED:
+            outcome = ActivityOutcome.COMPLETED
+        case TurnOutcome.INTERRUPTED:
+            outcome = ActivityOutcome.INTERRUPTED
+        case TurnOutcome.STOPPED:
+            outcome = ActivityOutcome.STOPPED
+        case TurnOutcome.MAX_STEPS:
+            outcome = ActivityOutcome.MAX_STEPS
+        case TurnOutcome.TOKEN_BUDGET:
+            outcome = ActivityOutcome.TOKEN_BUDGET
+        case TurnOutcome.REJECTED:
+            outcome = ActivityOutcome.REJECTED
+        case TurnOutcome.ABORTED:
+            outcome = ActivityOutcome.ABORTED
+        case TurnOutcome.DISCARDED:
+            outcome = ActivityOutcome.DISCARDED
+        case _:
+            assert_never(reason)
+    return outcome
+
+
+def project_intervals(
+    records: Iterable[SessionEvent], *, now: float | None = None
+) -> tuple[ActivityFinishedEvent, ...]:
+    """Read live or restored facts without depending on a mounted Activity instance."""
+    completed: list[ActivityFinishedEvent] = []
+    opened: dict[str, ActivityStartedEvent] = {}
+    for record in records:
+        match record:
+            case ActivityStartedEvent(interval_id=interval_id):
+                opened[interval_id] = record
+            case ActivityFinishedEvent(interval_id=interval_id):
+                completed.append(record)
+                opened.pop(interval_id, None)
+    timestamp = monotonic() if now is None else now
+    completed.extend(
+        ActivityFinishedEvent(
+            interval_id=event.interval_id,
+            kind=event.kind,
+            cause_id=event.cause_id,
+            started_at=event.at,
+            at=timestamp,
+            outcome=ActivityOutcome.RUNNING,
+            epoch_id=event.epoch_id,
+        )
+        for event in opened.values()
+    )
+    return tuple(completed)

browserrig/activity/plugin.py

@@ -0,0 +1,247 @@
+from typing import assert_never
+from uuid import uuid4
+
+from harnessed import Context, Plugin, PluginState, SessionLog, ToolStatus, hook
+from harnessed.events import (
+    AgentControlChangedEvent,
+    AssistantMessageEvent,
+    CompactionFinishedEvent,
+    CompactionOutcome,
+    CompactionStartedEvent,
+    ControlState,
+    ModelRequestedEvent,
+    ModelRequestFailedEvent,
+    ModelRequestOutcome,
+    StepEndedEvent,
+    ToolExecutionFinishedEvent,
+    ToolExecutionStartedEvent,
+    TurnEndedEvent,
+)
+from harnessed.kernel import dependency
+
+from browserrig.core import ActivityKind, ActivityOutcome
+from browserrig.events import (
+    ACTIVITY_EVENTS,
+    ActivityFinishedEvent,
+    ActivityStartedEvent,
+    HandoffFinishedEvent,
+    HandoffRequestedEvent,
+    ReadinessCancelledEvent,
+    ReadinessDegradedEvent,
+    ReadinessEndedEvent,
+    ReadinessFailedEvent,
+    ReadinessStartedEvent,
+    ReadyEvent,
+)
+
+from .models import ActivityKey, project_intervals, step_outcome, turn_outcome
+from .state import ActivityState
+
+_PAUSE = ActivityKey(ActivityKind.PAUSED)
+
+
+class Activity(Plugin, slot="browserrig.activity", provides=True):
+    events = ACTIVITY_EVENTS
+    _state = PluginState(ActivityState)
+    _log = dependency(SessionLog)
+
+    async def setup(self, ctx: Context) -> None:
+        ctx.effect(self._close_all)
+
+    def intervals(
+        self, *, now: float | None = None
+    ) -> tuple[ActivityFinishedEvent, ...]:
+        return project_intervals(self._state.records, now=now)
+
+    async def _start(self, key: ActivityKey, *, cause_id: str) -> None:
+        """A new interval in the same slot supersedes only that slot's previous interval."""
+        await self._finish(key, ActivityOutcome.SUPERSEDED)
+        event = ActivityStartedEvent(
+            interval_id=uuid4().hex,
+            kind=key.kind,
+            cause_id=cause_id,
+            epoch_id=self._state.epoch,
+        )
+        self._state.open[key] = event
+        self._state.records.append(event)
+        await self._log.emit(event)
+
+    async def _finish(
+        self,
+        key: ActivityKey,
+        outcome: ActivityOutcome = ActivityOutcome.COMPLETED,
+        *,
+        reason: str = "",
+    ) -> None:
+        event = self._state.open.pop(key, None)
+        if event is None:
+            return
+        finished = ActivityFinishedEvent(
+            interval_id=event.interval_id,
+            kind=event.kind,
+            cause_id=event.cause_id,
+            started_at=event.at,
+            outcome=outcome,
+            reason=reason,
+            epoch_id=event.epoch_id,
+        )
+        self._state.records.append(finished)
+        await self._log.emit(finished)
+
+    async def _close_all(self) -> None:
+        for key in tuple(self._state.open):
+            await self._finish(key, ActivityOutcome.CLOSED)
+
+    @hook(ModelRequestedEvent)
+    async def _on_model(self, event: ModelRequestedEvent) -> None:
+        await self._start(
+            ActivityKey(ActivityKind.LLM, event.request_id), cause_id=event.request_id
+        )
+
+    @hook(AssistantMessageEvent)
+    async def _on_assistant(self, event: AssistantMessageEvent) -> None:
+        await self._finish(
+            ActivityKey(ActivityKind.LLM, event.request_id),
+            ActivityOutcome.INTERRUPTED
+            if event.interrupted
+            else ActivityOutcome.COMPLETED,
+        )
+
+    @hook(ModelRequestFailedEvent)
+    async def _on_model_failed(self, event: ModelRequestFailedEvent) -> None:
+        match event.outcome:
+            case ModelRequestOutcome.FAILED:
+                outcome = ActivityOutcome.FAILED
+            case ModelRequestOutcome.CANCELLED:
+                outcome = ActivityOutcome.CANCELLED
+            case ModelRequestOutcome.CONTEXT_EXCEEDED:
+                outcome = ActivityOutcome.CONTEXT_LIMIT
+            case _:
+                assert_never(event.outcome)
+        await self._finish(
+            ActivityKey(ActivityKind.LLM, event.request_id),
+            outcome,
+            reason=event.outcome.value,
+        )
+
+    @hook(CompactionStartedEvent)
+    async def _on_compaction(self, event: CompactionStartedEvent) -> None:
+        await self._start(
+            ActivityKey(ActivityKind.COMPACTION, event.compaction_id),
+            cause_id=event.compaction_id,
+        )
+
+    @hook(CompactionFinishedEvent)
+    async def _on_compaction_finished(self, event: CompactionFinishedEvent) -> None:
+        outcome = {
+            CompactionOutcome.APPLIED: ActivityOutcome.COMPLETED,
+            CompactionOutcome.DISCARDED: ActivityOutcome.DISCARDED,
+            CompactionOutcome.FAILED: ActivityOutcome.FAILED,
+            CompactionOutcome.CANCELLED: ActivityOutcome.CANCELLED,
+        }[event.outcome]
+        await self._finish(
+            ActivityKey(ActivityKind.COMPACTION, event.compaction_id),
+            outcome,
+            reason=event.outcome.value,
+        )
+
+    @hook(ToolExecutionStartedEvent)
+    async def _on_tool(self, event: ToolExecutionStartedEvent) -> None:
+        await self._start(
+            ActivityKey(ActivityKind.TOOL, event.call_id), cause_id=event.call_id
+        )
+
+    @hook(ToolExecutionFinishedEvent)
+    async def _on_tool_finished(self, event: ToolExecutionFinishedEvent) -> None:
+        reason = event.result.status.value if event.result.is_error else ""
+        if event.result.exit_code not in (None, 0):
+            reason = f"{event.result.status.value}; exit_code={event.result.exit_code}"
+        if event.result.status is ToolStatus.CANCELLED:
+            outcome = ActivityOutcome.CANCELLED
+        elif event.result.status is ToolStatus.TIMEOUT:
+            outcome = ActivityOutcome.TIMEOUT
+        else:
+            outcome = (
+                ActivityOutcome.FAILED
+                if event.result.is_error
+                else ActivityOutcome.COMPLETED
+            )
+        await self._finish(
+            ActivityKey(ActivityKind.TOOL, event.call_id),
+            outcome,
+            reason=reason,
+        )
+
+    @hook(HandoffRequestedEvent)
+    async def _on_handoff(self, event: HandoffRequestedEvent) -> None:
+        if event.call_id:
+            await self._finish(ActivityKey(ActivityKind.TOOL, event.call_id))
+            await self._start(
+                ActivityKey(ActivityKind.HANDOFF, event.handoff_id),
+                cause_id=event.handoff_id,
+            )
+
+    @hook(HandoffFinishedEvent)
+    async def _on_handoff_finished(self, event: HandoffFinishedEvent) -> None:
+        if event.call_id:
+            outcome = {
+                "done": ActivityOutcome.COMPLETED,
+                "declined": ActivityOutcome.REJECTED,
+                "timeout": ActivityOutcome.TIMEOUT,
+                "cancelled": ActivityOutcome.CANCELLED,
+                "failed": ActivityOutcome.FAILED,
+                "resumed": ActivityOutcome.COMPLETED,
+            }[event.status]
+            await self._finish(
+                ActivityKey(ActivityKind.HANDOFF, event.handoff_id),
+                outcome,
+                reason=event.status,
+            )
+            await self._start(
+                ActivityKey(ActivityKind.TOOL, event.call_id), cause_id=event.call_id
+            )
+
+    @hook(ReadinessStartedEvent)
+    async def _on_readiness(self, event: ReadinessStartedEvent) -> None:
+        await self._start(
+            ActivityKey(ActivityKind.READINESS, event.readiness_id),
+            cause_id=event.readiness_id,
+        )
+
+    @hook(ReadinessEndedEvent)
+    async def _on_ready(self, event: ReadinessEndedEvent) -> None:
+        match event:
+            case ReadyEvent():
+                outcome = ActivityOutcome.COMPLETED
+            case ReadinessDegradedEvent():
+                outcome = ActivityOutcome.DEGRADED
+            case ReadinessFailedEvent():
+                outcome = ActivityOutcome.FAILED
+            case ReadinessCancelledEvent():
+                outcome = ActivityOutcome.CANCELLED
+            case _:
+                raise TypeError(f"Unsupported readiness event: {type(event).__name__}")
+        await self._finish(
+            ActivityKey(ActivityKind.READINESS, event.readiness_id),
+            outcome,
+            reason=event.reason,
+        )
+
+    @hook(AgentControlChangedEvent)
+    async def _on_control(self, event: AgentControlChangedEvent) -> None:
+        if event.state == ControlState.PAUSED:
+            await self._start(_PAUSE, cause_id=self._state.epoch)
+        elif event.state == ControlState.ACTIVE:
+            await self._finish(_PAUSE)
+
+    @hook(StepEndedEvent)
+    async def _on_step(self, event: StepEndedEvent) -> None:
+        for key in tuple(self._state.open):
+            if key.kind is ActivityKind.LLM:
+                await self._finish(key, step_outcome(event.reason))
+
+    @hook(TurnEndedEvent)
+    async def _on_turn(self, event: TurnEndedEvent) -> None:
+        for key in tuple(self._state.open):
+            if key.kind != ActivityKind.PAUSED:
+                await self._finish(key, turn_outcome(event.reason))

browserrig/activity/state.py

@@ -0,0 +1,16 @@
+from dataclasses import dataclass, field
+from uuid import uuid4
+
+from browserrig.events import ActivityFinishedEvent, ActivityStartedEvent
+
+from .models import ActivityKey
+
+
+@dataclass
+class ActivityState:
+    open: dict[ActivityKey, ActivityStartedEvent] = field(default_factory=dict)
+    # The session log only holds the open turn, so intervals keep their own record.
+    records: list[ActivityStartedEvent | ActivityFinishedEvent] = field(
+        default_factory=list
+    )
+    epoch: str = field(default_factory=lambda: uuid4().hex)

browserrig/agent.py

@@ -0,0 +1,55 @@
+from collections.abc import Iterable
+
+import harnessed
+from harnessed import (
+    Kit,
+    Plugin,
+    PluginValidation,
+    SystemPrompt,
+)
+from harnessed.kernel import PluginLike
+from harnessed.models import Model
+from harnessed.sessions import SessionStore
+
+from .browser import BrowserOptions
+from .composition import browser_kit
+
+DEFAULT_PROMPT = "Complete the requested browser task using the observed page state."
+
+
+class Agent(harnessed.Agent):
+    """A harnessed agent with browserrig's default browser plugins.
+
+    `plugins` replace the defaults they match and add the rest, and `without`
+    drops defaults by type; see `browser_kit`. Explicit provider clients
+    remain caller-owned. Conversations stay in memory by default; pass `store`
+    to reopen them by ID, or continue with an explicit `SessionState`. Long runs
+    summarize older steps once the request fills 80% of the model's context window,
+    or 100k tokens when the model reports none. Pass `without=(ContextCompaction,)`
+    to keep everything, or a configured `ContextCompaction`. Input is paced like a
+    person and streamed for people
+    watching; pass `without=(InputPacing, InputVisualization)` to work at full speed unseen.
+    """
+
+    def __init__(
+        self,
+        *,
+        model: Model | str | None = None,
+        browser: BrowserOptions | None = None,
+        plugins: Iterable[PluginLike | Kit | None] = (),
+        without: Iterable[type[Plugin]] = (),
+        instructions: str | None = DEFAULT_PROMPT,
+        prompt: SystemPrompt | None = None,
+        store: SessionStore | None = None,
+        plugin_validation: PluginValidation = PluginValidation.ERROR,
+    ) -> None:
+        kit = browser_kit(browser=browser)
+        kit = kit.without(*without)
+        super().__init__(
+            model=model,
+            instructions=instructions,
+            prompt=prompt,
+            plugins=[kit, *plugins],
+            store=store,
+            plugin_validation=plugin_validation,
+        )

browserrig/browser/__init__.py

@@ -0,0 +1,33 @@
+from browserrig.files import Download, DownloadState
+
+from .base import Browser, BrowserEvents
+from .chrome import ChromeBrowser
+from .config import BrowserOptions, Connect, Launch, Viewport
+from .frame import Frame
+from .images import screenshot
+from .models import TabInfo
+from .plugin import Chrome, TabChanged
+from .setup import SessionSetup
+from .tab import Tab, validated_url
+from .tabs import Tabs
+
+__all__ = [
+    "Browser",
+    "BrowserEvents",
+    "BrowserOptions",
+    "Chrome",
+    "ChromeBrowser",
+    "Connect",
+    "Frame",
+    "Download",
+    "DownloadState",
+    "Launch",
+    "SessionSetup",
+    "Tab",
+    "TabChanged",
+    "TabInfo",
+    "Tabs",
+    "Viewport",
+    "screenshot",
+    "validated_url",
+]

browserrig/browser/base.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from dataclasses import replace
+from typing import TYPE_CHECKING, Protocol
+
+from browserrig.events import BrowserEvent, LiveEvent
+from browserrig.files import Download, FileSystem
+from browserrig.input import Input, Keyboard, Mouse
+
+from .tab import Tab
+
+if TYPE_CHECKING:
+    from .tabs import Tabs
+
+type EventSink = Callable[[BrowserEvent | LiveEvent], Awaitable[None]]
+type EventFilter = Callable[[BrowserEvent | LiveEvent], BrowserEvent | LiveEvent]
+
+
+class BrowserEvents:
+    """Publish events stamped with the browser that produced them.
+
+    Filters rewrite each event before it reaches the sink, e.g. to redact secrets.
+    """
+
+    def __init__(self, browser_id: str, sink: EventSink) -> None:
+        self.browser_id = browser_id
+        self._sink = sink
+        self._filters: list[EventFilter] = []
+
+    def add_filter(self, event_filter: EventFilter) -> Callable[[], None]:
+        """Apply `event_filter` to later events; the returned callable removes it."""
+        self._filters.append(event_filter)
+
+        def remove() -> None:
+            if event_filter in self._filters:
+                self._filters.remove(event_filter)
+
+        return remove
+
+    async def emit(self, event: BrowserEvent | LiveEvent) -> None:
+        event = replace(event, browser_id=self.browser_id)
+        for event_filter in tuple(self._filters):
+            event = event_filter(event)
+        await self._sink(event)
+
+
+class Browser(Protocol):
+    # Shared by Observe and Actions; it cannot live in either without a dependency cycle.
+    action_lock: asyncio.Lock
+    files: FileSystem | None
+    # The browser's one mouse and keyboard; they act on the active tab.
+    input: Input
+    tabs: Tabs
+
+    @property
+    def active_tab(self) -> Tab: ...
+
+    @property
+    def mouse(self) -> Mouse: ...
+
+    @property
+    def keyboard(self) -> Keyboard: ...
+
+    async def downloads(self) -> tuple[Download, ...]: ...
+
+
+async def _discard(_event: BrowserEvent | LiveEvent) -> None:
+    pass