browserrig 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (167) hide show
  1. browserrig/__init__.py +158 -0
  2. browserrig/activity/__init__.py +5 -0
  3. browserrig/activity/models.py +93 -0
  4. browserrig/activity/plugin.py +247 -0
  5. browserrig/activity/state.py +16 -0
  6. browserrig/agent.py +55 -0
  7. browserrig/browser/__init__.py +33 -0
  8. browserrig/browser/base.py +70 -0
  9. browserrig/browser/chrome.py +242 -0
  10. browserrig/browser/config.py +119 -0
  11. browserrig/browser/downloads.py +128 -0
  12. browserrig/browser/favicon.py +119 -0
  13. browserrig/browser/frame.py +227 -0
  14. browserrig/browser/frames.py +116 -0
  15. browserrig/browser/images.py +23 -0
  16. browserrig/browser/input.py +147 -0
  17. browserrig/browser/models.py +8 -0
  18. browserrig/browser/plugin.py +44 -0
  19. browserrig/browser/process.py +144 -0
  20. browserrig/browser/setup.py +12 -0
  21. browserrig/browser/tab.py +311 -0
  22. browserrig/browser/tabs.py +366 -0
  23. browserrig/browser/worlds.py +64 -0
  24. browserrig/choreography/__init__.py +31 -0
  25. browserrig/choreography/events.py +133 -0
  26. browserrig/choreography/plugin.py +75 -0
  27. browserrig/choreography/scenes.py +167 -0
  28. browserrig/choreography/stage.py +53 -0
  29. browserrig/choreography/tabstrip.py +112 -0
  30. browserrig/completion.py +184 -0
  31. browserrig/composition.py +108 -0
  32. browserrig/core/__init__.py +61 -0
  33. browserrig/core/errors.py +18 -0
  34. browserrig/core/geometry.py +149 -0
  35. browserrig/core/ids.py +10 -0
  36. browserrig/core/kinds.py +180 -0
  37. browserrig/core/options.py +7 -0
  38. browserrig/core/tools.py +32 -0
  39. browserrig/events.py +665 -0
  40. browserrig/files/__init__.py +25 -0
  41. browserrig/files/config.py +13 -0
  42. browserrig/files/containers.py +200 -0
  43. browserrig/files/content.py +65 -0
  44. browserrig/files/data.py +80 -0
  45. browserrig/files/documents.py +248 -0
  46. browserrig/files/formats.py +84 -0
  47. browserrig/files/imaging.py +138 -0
  48. browserrig/files/kinds.py +78 -0
  49. browserrig/files/models.py +71 -0
  50. browserrig/files/reading.py +382 -0
  51. browserrig/files/spreadsheets.py +417 -0
  52. browserrig/files/system.py +204 -0
  53. browserrig/files/text.py +64 -0
  54. browserrig/files/xlsx.py +53 -0
  55. browserrig/handoff/__init__.py +4 -0
  56. browserrig/handoff/changes.py +48 -0
  57. browserrig/handoff/models.py +31 -0
  58. browserrig/handoff/plugin.py +308 -0
  59. browserrig/handoff/state.py +21 -0
  60. browserrig/input/__init__.py +35 -0
  61. browserrig/input/controller.py +69 -0
  62. browserrig/input/keyboard.py +267 -0
  63. browserrig/input/motor.py +118 -0
  64. browserrig/input/mouse.py +346 -0
  65. browserrig/input/pointer.py +84 -0
  66. browserrig/input/presenter.py +49 -0
  67. browserrig/input/target.py +67 -0
  68. browserrig/input/wheel.py +40 -0
  69. browserrig/kinds.py +33 -0
  70. browserrig/nudges/__init__.py +3 -0
  71. browserrig/nudges/plugin.py +295 -0
  72. browserrig/nudges/state.py +23 -0
  73. browserrig/observation/__init__.py +53 -0
  74. browserrig/observation/capture.py +374 -0
  75. browserrig/observation/changes.py +63 -0
  76. browserrig/observation/config.py +12 -0
  77. browserrig/observation/content.py +176 -0
  78. browserrig/observation/delta.py +69 -0
  79. browserrig/observation/dom.py +97 -0
  80. browserrig/observation/extraction/__init__.py +335 -0
  81. browserrig/observation/extraction/accessibility.py +62 -0
  82. browserrig/observation/extraction/document.py +471 -0
  83. browserrig/observation/extraction/elements.py +676 -0
  84. browserrig/observation/extraction/semantics.py +351 -0
  85. browserrig/observation/extraction/styles.py +30 -0
  86. browserrig/observation/extraction/visibility.py +108 -0
  87. browserrig/observation/find.py +152 -0
  88. browserrig/observation/handle.py +170 -0
  89. browserrig/observation/images.py +243 -0
  90. browserrig/observation/marks.py +157 -0
  91. browserrig/observation/models.py +230 -0
  92. browserrig/observation/plugin.py +413 -0
  93. browserrig/observation/redirects.py +40 -0
  94. browserrig/observation/references.py +47 -0
  95. browserrig/observation/render.py +291 -0
  96. browserrig/observation/renderer.py +76 -0
  97. browserrig/observation/state.py +37 -0
  98. browserrig/pacing/__init__.py +5 -0
  99. browserrig/pacing/plugin.py +22 -0
  100. browserrig/py.typed +0 -0
  101. browserrig/readiness/__init__.py +25 -0
  102. browserrig/readiness/config.py +12 -0
  103. browserrig/readiness/dom.py +83 -0
  104. browserrig/readiness/downloads.py +30 -0
  105. browserrig/readiness/hooks.py +27 -0
  106. browserrig/readiness/models.py +13 -0
  107. browserrig/readiness/plugin.py +170 -0
  108. browserrig/readiness/policies.py +43 -0
  109. browserrig/readiness/state.py +20 -0
  110. browserrig/readiness/strategy.py +30 -0
  111. browserrig/readiness/wait.py +238 -0
  112. browserrig/scripts/README.md +39 -0
  113. browserrig/scripts/__init__.py +186 -0
  114. browserrig/scripts/content.js +526 -0
  115. browserrig/scripts/cursor.js +57 -0
  116. browserrig/scripts/element.js +82 -0
  117. browserrig/scripts/find.js +377 -0
  118. browserrig/scripts/focused.js +15 -0
  119. browserrig/scripts/lib/composed.js +21 -0
  120. browserrig/scripts/lib/elements.js +9 -0
  121. browserrig/scripts/lib/geometry.js +13 -0
  122. browserrig/scripts/lib/hit.js +84 -0
  123. browserrig/scripts/lib/markdown.js +32 -0
  124. browserrig/scripts/lib/scroll.js +226 -0
  125. browserrig/scripts/lib/secret.js +74 -0
  126. browserrig/scripts/lib/visibility.js +42 -0
  127. browserrig/scripts/models.py +153 -0
  128. browserrig/scripts/owner_hits.js +4 -0
  129. browserrig/scripts/owner_scroll.js +7 -0
  130. browserrig/scripts/owner_size.js +11 -0
  131. browserrig/scripts/page_facts.js +9 -0
  132. browserrig/scripts/reset.js +4 -0
  133. browserrig/scripts/scroll.js +5 -0
  134. browserrig/scripts/secret_field.js +7 -0
  135. browserrig/scripts/secret_focus.js +31 -0
  136. browserrig/scripts/seed.js +13 -0
  137. browserrig/scripts/stability.js +140 -0
  138. browserrig/scripts/tab_strip.js +27 -0
  139. browserrig/scripts/viewport.js +3 -0
  140. browserrig/secrets/__init__.py +5 -0
  141. browserrig/secrets/models.py +90 -0
  142. browserrig/secrets/origin.py +95 -0
  143. browserrig/secrets/plugin.py +397 -0
  144. browserrig/secrets/redaction.py +107 -0
  145. browserrig/secrets/state.py +6 -0
  146. browserrig/secrets/totp.py +62 -0
  147. browserrig/terminal.py +120 -0
  148. browserrig/tools/__init__.py +51 -0
  149. browserrig/tools/chains.py +55 -0
  150. browserrig/tools/dialogs.py +23 -0
  151. browserrig/tools/effects.py +8 -0
  152. browserrig/tools/execution.py +333 -0
  153. browserrig/tools/files.py +411 -0
  154. browserrig/tools/find.py +125 -0
  155. browserrig/tools/forms.py +76 -0
  156. browserrig/tools/intents.py +82 -0
  157. browserrig/tools/javascript.py +37 -0
  158. browserrig/tools/keyboard.py +126 -0
  159. browserrig/tools/mouse.py +224 -0
  160. browserrig/tools/navigation.py +189 -0
  161. browserrig/tools/scrolling.py +39 -0
  162. browserrig/tools/tabs.py +81 -0
  163. browserrig/tools/targeting.py +59 -0
  164. browserrig-0.1.0.dist-info/METADATA +174 -0
  165. browserrig-0.1.0.dist-info/RECORD +167 -0
  166. browserrig-0.1.0.dist-info/WHEEL +4 -0
  167. browserrig-0.1.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,18 @@
1
+ class BrowserError(Exception):
2
+ """An actionable browser failure, without endpoint credentials."""
3
+
4
+
5
+ class BrowserClosed(BrowserError):
6
+ pass
7
+
8
+
9
+ class StaleElement(BrowserError):
10
+ pass
11
+
12
+
13
+ class ReadinessError(BrowserError):
14
+ pass
15
+
16
+
17
+ class SecretError(BrowserError):
18
+ """A secret could not be used; messages name secrets, never their values."""
@@ -0,0 +1,149 @@
1
+ from __future__ import annotations
2
+
3
+ from collections.abc import Callable
4
+ from dataclasses import dataclass
5
+
6
+ from pydantic import Field
7
+
8
+ from .options import Options
9
+
10
+
11
+ class Bounds(Options):
12
+ """A rectangle in CSS viewport pixels; clipped rectangles may have no area."""
13
+
14
+ x: float
15
+ y: float
16
+ width: float = Field(ge=0)
17
+ height: float = Field(ge=0)
18
+
19
+ def intersect(self, other: Bounds) -> Bounds:
20
+ x, y = max(self.x, other.x), max(self.y, other.y)
21
+ return Bounds(
22
+ x=x,
23
+ y=y,
24
+ width=max(0, min(self.x + self.width, other.x + other.width) - x),
25
+ height=max(0, min(self.y + self.height, other.y + other.height) - y),
26
+ )
27
+
28
+ def contains(self, x: float, y: float) -> bool:
29
+ return self.x <= x < self.x + self.width and self.y <= y < self.y + self.height
30
+
31
+
32
+ @dataclass(frozen=True, slots=True)
33
+ class FrameTransform:
34
+ """Affine map from one frame's CSS pixels to the top-level viewport.
35
+
36
+ The fields are the CSS matrix(a, b, c, d, e, f) of the frame's content box.
37
+ """
38
+
39
+ scale_x: float = 1
40
+ skew_y: float = 0
41
+ skew_x: float = 0
42
+ scale_y: float = 1
43
+ offset_x: float = 0
44
+ offset_y: float = 0
45
+
46
+ def to_viewport(self, x: float, y: float) -> tuple[float, float]:
47
+ return self.scale_x * x + self.skew_x * y + self.offset_x, (
48
+ self.skew_y * x + self.scale_y * y + self.offset_y
49
+ )
50
+
51
+ def to_local(self, x: float, y: float) -> tuple[float, float]:
52
+ determinant = self.scale_x * self.scale_y - self.skew_x * self.skew_y
53
+ if abs(determinant) < 1e-9:
54
+ raise ValueError("Frame transform has no visible area")
55
+ x, y = x - self.offset_x, y - self.offset_y
56
+ return (
57
+ (self.scale_y * x - self.skew_x * y) / determinant,
58
+ (self.scale_x * y - self.skew_y * x) / determinant,
59
+ )
60
+
61
+ def bounds_to_viewport(self, bounds: Bounds) -> Bounds:
62
+ return _enclosing(bounds, self.to_viewport)
63
+
64
+ def bounds_to_local(self, bounds: Bounds) -> Bounds:
65
+ return _enclosing(bounds, self.to_local)
66
+
67
+ def child(self, quad: list[float], width: float, height: float) -> FrameTransform:
68
+ """Compose an embedded frame's transform from its content quad in this space."""
69
+ # Perspective needs a homography. Reject it instead of dispatching a wrong click.
70
+ if any(
71
+ abs(quad[i] + quad[i + 4] - quad[i + 2] - quad[(i + 6) % 8]) > 0.5
72
+ for i in (0, 1)
73
+ ):
74
+ raise ValueError("Perspective-transformed frames are not supported")
75
+ origin = self.to_viewport(quad[0], quad[1])
76
+ right = self.to_viewport(quad[2], quad[3])
77
+ bottom = self.to_viewport(quad[6], quad[7])
78
+ return FrameTransform(
79
+ scale_x=(right[0] - origin[0]) / width,
80
+ skew_y=(right[1] - origin[1]) / width,
81
+ skew_x=(bottom[0] - origin[0]) / height,
82
+ scale_y=(bottom[1] - origin[1]) / height,
83
+ offset_x=origin[0],
84
+ offset_y=origin[1],
85
+ )
86
+
87
+
88
+ class Point(Options):
89
+ x: float = Field(ge=0)
90
+ y: float = Field(ge=0)
91
+
92
+
93
+ class ElementPoint(Point):
94
+ scrolled: bool = False
95
+ bounds: Bounds | None = None
96
+
97
+
98
+ class Geometry(Options):
99
+ x: float = Field(default=0, ge=0)
100
+ y: float = Field(default=0, ge=0)
101
+ width: float = Field(gt=0)
102
+ height: float = Field(gt=0)
103
+ scale: float = Field(default=1, gt=0)
104
+
105
+ def point(self, x: float, y: float) -> tuple[float, float]:
106
+ if not (0 <= x < self.width * self.scale and 0 <= y < self.height * self.scale):
107
+ raise ValueError("Point is outside the observed image")
108
+ return self.x + x / self.scale, self.y + y / self.scale
109
+
110
+
111
+ class Region(Options):
112
+ """A viewport area in CSS pixels, such as a screenshot crop."""
113
+
114
+ x: float = Field(ge=0)
115
+ y: float = Field(ge=0)
116
+ width: float = Field(gt=0)
117
+ height: float = Field(gt=0)
118
+
119
+ def capture(
120
+ self, viewport: Bounds, zoom: float, max_side: float
121
+ ) -> Geometry | None:
122
+ """Clip to `viewport` and cap `zoom` so no image side exceeds `max_side` pixels."""
123
+ visible = Bounds(
124
+ x=self.x, y=self.y, width=self.width, height=self.height
125
+ ).intersect(Bounds(x=0, y=0, width=viewport.width, height=viewport.height))
126
+ if visible.width < 1 or visible.height < 1:
127
+ return None
128
+ scale = max(1.0, min(zoom, max_side / max(visible.width, visible.height)))
129
+ return Geometry(
130
+ x=visible.x,
131
+ y=visible.y,
132
+ width=visible.width,
133
+ height=visible.height,
134
+ scale=scale,
135
+ )
136
+
137
+
138
+ def _enclosing(
139
+ bounds: Bounds, transform: Callable[[float, float], tuple[float, float]]
140
+ ) -> Bounds:
141
+ points = [
142
+ transform(x, y)
143
+ for x in (bounds.x, bounds.x + bounds.width)
144
+ for y in (bounds.y, bounds.y + bounds.height)
145
+ ]
146
+ xs, ys = zip(*points, strict=True)
147
+ return Bounds(
148
+ x=min(xs), y=min(ys), width=max(xs) - min(xs), height=max(ys) - min(ys)
149
+ )
browserrig/core/ids.py ADDED
@@ -0,0 +1,10 @@
1
+ """Names for the string IDs that key browser state, so a mapping says what it holds."""
2
+
3
+ type TargetId = str
4
+ """A Chrome page target; one per tab."""
5
+
6
+ type DocumentId = str
7
+ """One loaded document of a tab; a navigation starts a new one."""
8
+
9
+ type ActionId = str
10
+ """One browser action, from its started event to its finished event."""
@@ -0,0 +1,180 @@
1
+ from enum import StrEnum
2
+ from typing import Self
3
+
4
+
5
+ class ActivityKind(StrEnum):
6
+ LLM = "llm"
7
+ TOOL = "tool"
8
+ READINESS = "readiness"
9
+ COMPACTION = "compaction"
10
+ PAUSED = "paused"
11
+ HANDOFF = "handoff"
12
+
13
+
14
+ class ActivityOutcome(StrEnum):
15
+ RUNNING = "running"
16
+ COMPLETED = "completed"
17
+ SUPERSEDED = "superseded"
18
+ CLOSED = "closed"
19
+ INTERRUPTED = "interrupted"
20
+ ABORTED = "aborted"
21
+ CONTEXT_LIMIT = "context_limit"
22
+ STOPPED = "stopped"
23
+ MAX_STEPS = "max_steps"
24
+ TOKEN_BUDGET = "token_budget"
25
+ REJECTED = "rejected"
26
+ DISCARDED = "discarded"
27
+ DEGRADED = "degraded"
28
+ FAILED = "failed"
29
+ CANCELLED = "cancelled"
30
+ TIMEOUT = "timeout"
31
+
32
+
33
+ class ActionKind(StrEnum):
34
+ """Stable tool identities, independent of Python callback names and signatures."""
35
+
36
+ NAVIGATE = "navigate"
37
+ SEARCH = "search"
38
+ GO_BACK = "go_back"
39
+ GO_FORWARD = "go_forward"
40
+ RELOAD = "reload"
41
+ WAIT = "wait"
42
+ JAVASCRIPT = "javascript"
43
+ CLICK = "click"
44
+ CLICK_AT = "click_at"
45
+ MOVE_MOUSE = "move_mouse"
46
+ DOUBLE_CLICK = "double_click"
47
+ DRAG = "drag"
48
+ DRAG_AT = "drag_at"
49
+ TYPE = "type"
50
+ PRESS = "press"
51
+ SCROLL = "scroll"
52
+ SELECT = "select"
53
+ SET_DATE = "set_date"
54
+ UPLOAD = "upload"
55
+ OPEN_TAB = "open_tab"
56
+ SWITCH_TAB = "switch_tab"
57
+ CLOSE_TAB = "close_tab"
58
+ LIST_TABS = "list_tabs"
59
+ HANDLE_DIALOG = "handle_dialog"
60
+ LIST_DOWNLOADS = "list_downloads"
61
+ LIST_FILES = "list_files"
62
+ READ_FILE = "read_file"
63
+ WRITE_FILE = "write_file"
64
+ OPEN_FILE = "open_file"
65
+ OPEN_DOWNLOADED_FILE = "open_downloaded_file"
66
+ SCREENSHOT = "screenshot"
67
+ EXTRACT_CONTENT = "extract_content"
68
+ FIND_IN_PAGE = "find_in_page"
69
+ # Kept readable in existing persisted action receipts.
70
+ TAB = "tab"
71
+
72
+
73
+ class ElementOperation(StrEnum):
74
+ POINT = "point"
75
+ BOUNDS = "bounds"
76
+ FOCUS = "focus"
77
+ SELECT = "select"
78
+ SET_VALUE = "set_value"
79
+
80
+
81
+ class MouseEventKind(StrEnum):
82
+ MOVED = "mouseMoved"
83
+ PRESSED = "mousePressed"
84
+ RELEASED = "mouseReleased"
85
+ WHEEL = "mouseWheel"
86
+
87
+
88
+ class CursorStyle(StrEnum):
89
+ """CSS cursor keywords that a live viewer can draw for the agent's pointer."""
90
+
91
+ DEFAULT = "default"
92
+ POINTER = "pointer"
93
+ TEXT = "text"
94
+ VERTICAL_TEXT = "vertical-text"
95
+ CROSSHAIR = "crosshair"
96
+ CELL = "cell"
97
+ MOVE = "move"
98
+ GRAB = "grab"
99
+ GRABBING = "grabbing"
100
+ ALL_SCROLL = "all-scroll"
101
+ NOT_ALLOWED = "not-allowed"
102
+ NO_DROP = "no-drop"
103
+ COPY = "copy"
104
+ ALIAS = "alias"
105
+ CONTEXT_MENU = "context-menu"
106
+ HELP = "help"
107
+ PROGRESS = "progress"
108
+ WAIT = "wait"
109
+ ZOOM_IN = "zoom-in"
110
+ ZOOM_OUT = "zoom-out"
111
+ COL_RESIZE = "col-resize"
112
+ ROW_RESIZE = "row-resize"
113
+ N_RESIZE = "n-resize"
114
+ E_RESIZE = "e-resize"
115
+ S_RESIZE = "s-resize"
116
+ W_RESIZE = "w-resize"
117
+ NE_RESIZE = "ne-resize"
118
+ NW_RESIZE = "nw-resize"
119
+ SE_RESIZE = "se-resize"
120
+ SW_RESIZE = "sw-resize"
121
+ EW_RESIZE = "ew-resize"
122
+ NS_RESIZE = "ns-resize"
123
+ NESW_RESIZE = "nesw-resize"
124
+ NWSE_RESIZE = "nwse-resize"
125
+ NONE = "none"
126
+
127
+ @classmethod
128
+ def parse(cls, value: str) -> Self:
129
+ """Unknown, custom-image and fallback-only values show the default arrow."""
130
+ keyword = value.rsplit(",", 1)[-1].strip().lower()
131
+ try:
132
+ return cls(keyword)
133
+ except ValueError:
134
+ return cls(cls.DEFAULT)
135
+
136
+
137
+ class FileTransferDirection(StrEnum):
138
+ OPEN = "open"
139
+ UPLOAD = "upload"
140
+
141
+
142
+ class BrowserBar(StrEnum):
143
+ """Text fields of the browser itself, outside the page."""
144
+
145
+ ADDRESS = "address"
146
+ FIND = "find"
147
+
148
+
149
+ class TabGesture(StrEnum):
150
+ """Which tab-strip control the pointer presses: a tab, the new-tab button or a tab's close."""
151
+
152
+ ACTIVATE = "activate"
153
+ OPEN = "open"
154
+ CLOSE = "close"
155
+
156
+
157
+ class FileSource(StrEnum):
158
+ WORKSPACE = "workspace"
159
+ DOWNLOAD = "download"
160
+
161
+
162
+ class ReadinessStatus(StrEnum):
163
+ READY = "ready"
164
+ DEGRADED = "degraded"
165
+ BLOCKED = "blocked"
166
+ FAILED = "failed"
167
+ CANCELLED = "cancelled"
168
+
169
+
170
+ class ReadinessPhase(StrEnum):
171
+ INITIAL = "initial"
172
+ OBSERVATION = "observation"
173
+ NAVIGATION = "navigation"
174
+ ACTION = "action"
175
+ AFTER_ACTION = "after_action"
176
+
177
+
178
+ class ReadinessStage(StrEnum):
179
+ INITIAL = "initial"
180
+ ONGOING = "ongoing"
@@ -0,0 +1,7 @@
1
+ from pydantic import BaseModel, ConfigDict
2
+
3
+
4
+ class Options(BaseModel):
5
+ model_config = ConfigDict(
6
+ extra="forbid", frozen=True, allow_inf_nan=False, hide_input_in_errors=True
7
+ )
@@ -0,0 +1,32 @@
1
+ from collections.abc import Callable
2
+ from dataclasses import dataclass
3
+
4
+ from harnessed import ToolChain, tool
5
+
6
+ from .kinds import ActionKind
7
+
8
+
9
+ @dataclass(frozen=True, slots=True)
10
+ class BrowserToolMetadata:
11
+ """Process-local browser semantics captured with a Harnessed tool registration."""
12
+
13
+ kind: ActionKind
14
+ chainable: bool = False
15
+
16
+
17
+ def browser_tool[F: Callable[..., object]](
18
+ *,
19
+ description: str,
20
+ kind: ActionKind,
21
+ enabled: bool | Callable[..., bool] = True,
22
+ readonly: bool = False,
23
+ chainable: bool = False,
24
+ ) -> Callable[[F], F]:
25
+ """Declare a sequential browser tool; a fresh model decision follows by default."""
26
+ return tool(
27
+ description=description,
28
+ enabled=enabled,
29
+ readonly=readonly,
30
+ metadata=(BrowserToolMetadata(chainable=chainable, kind=kind),),
31
+ chain=ToolChain.CONTINUE if chainable else ToolChain.STOP_AFTER,
32
+ )