@sentry/junior-agent-browser 0.109.0 → 0.111.0

package/README.md

@@ -1,6 +1,6 @@
 # @sentry/junior-agent-browser
 
-`@sentry/junior-agent-browser` adds browser automation workflows to Junior via the `agent-browser` CLI.
+`@sentry/junior-agent-browser` adds browser automation and visual QA workflows to Junior via the `agent-browser` CLI.
 
 Install it alongside `@sentry/junior`:
 
@@ -16,4 +16,15 @@ import { defineJuniorPlugins } from "@sentry/junior";
 export const plugins = defineJuniorPlugins(["@sentry/junior-agent-browser"]);
 ```
 
+The package includes two skills:
+
+- `/agent-browser` for general browser navigation, interaction, extraction, and capture
+- `/visual-web-qa` for evidence-driven verification of frontend, docs, layout, theme, loading, animation, and interaction changes
+
+For example:
+
+```text
+/visual-web-qa Verify the docs theme on desktop and mobile, then share the evidence.
+```
+
 Full setup guide: https://junior.sentry.dev/extend/agent-browser-plugin/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentry/junior-agent-browser",
-  "version": "0.109.0",
+  "version": "0.111.0",
   "private": false,
   "publishConfig": {
     "access": "public"

package/skills/visual-web-qa/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: visual-web-qa
+description: Verifies user-visible web changes with scoped browser evidence and reports only what the captured screenshots, videos, or state checks support. Use when frontend, docs, CSS, layout, theme, responsive, navigation, loading, animation, or interaction changes need visual validation; use agent-browser for general automation that is not specifically visual QA.
+spec_hash: 7dd651f9311c
+allowed-tools: bash sendFiles
+---
+
+# Visual Web QA
+
+Verify rendered behavior in a browser instead of inferring visual correctness from code. Choose the smallest set of evidence that directly answers the request.
+
+## Workflow
+
+1. Classify the requested behavior as stable, temporal, or exact-state verification.
+2. Resolve a valid local, preview, or explicitly requested target URL.
+3. Choose representative pages, states, viewports, and themes.
+4. Capture browser evidence with meaningful waits and fresh element refs.
+5. Share requested artifacts with `sendFiles` and verify delivery success.
+6. Report the exact target, evidence, result, findings, and limitations.
+
+## Choose Evidence
+
+| Request                                   | Primary evidence                   | Optional support                                 |
+| ----------------------------------------- | ---------------------------------- | ------------------------------------------------ |
+| Layout, CSS, content, typography          | Screenshot                         | DOM text or style check                          |
+| Light and dark themes                     | Screenshot per relevant theme      | Theme attribute check                            |
+| Responsive behavior                       | Screenshot per relevant breakpoint | Video only if resize motion matters              |
+| Loading state, animation, transition      | Short video                        | Screenshot for a distinct final-state question   |
+| Navigation or interaction sequence        | Short video                        | Screenshot for a specific defect                 |
+| Stable menu, modal, hover, or focus state | Screenshot                         | Video if the transition matters                  |
+| Exact text, route, ARIA, or attribute     | DOM check                          | Screenshot or video if the visible state matters |
+
+Use screenshots for stable rendered states. Use short videos for timing, motion, loading, or sequence. A purely temporal request may use video without a redundant screenshot. DOM checks support visual evidence; they do not replace it when the user asks how something looks.
+
+```bash
+agent-browser --session visual-qa screenshot /tmp/visual-qa.png
+agent-browser --session visual-qa screenshot --full /tmp/visual-qa-full.png
+agent-browser --session visual-qa screenshot --annotate /tmp/visual-qa-issue.png
+```
+
+## Keep Scope Representative
+
+- Check one to four representative pages or states unless the user requests broader coverage or the change spans more templates.
+- Choose the viewport-theme combinations most likely to expose the issue instead of building an exhaustive matrix by default.
+- State clearly when only part of the requested surface was verified.
+
+## Resolve The Target
+
+Use this order:
+
+1. User-provided URL
+2. Running local development server
+3. Repo-native server such as `pnpm dev`
+4. Preview deployment
+5. Production as an explicitly requested or read-only baseline
+6. `file://` output only when the site renders correctly without a server
+
+Do not check production and claim an unmerged change is present. If no valid target is reachable, report **blocked** and name the missing server, preview, build, or authentication requirement.
+
+## Capture Reliable State
+
+Wait for the state that proves progress instead of adding arbitrary delays:
+
+```bash
+agent-browser --session visual-qa wait --url "**/expected-path"
+agent-browser --session visual-qa wait --text "Expected text"
+agent-browser --session visual-qa wait --load networkidle
+agent-browser --session visual-qa wait 100
+```
+
+- Prefer URL or text waits for route and content changes.
+- Use `networkidle` only when the action triggers real network activity.
+- Use a short fixed wait only when an animation has no semantic completion signal.
+- Run `snapshot -i` after navigation or significant DOM changes before using element refs.
+
+For initial loading behavior, start recording before the first navigation:
+
+```bash
+agent-browser --session visual-qa set viewport 1440 900
+agent-browser --session visual-qa record start /tmp/visual-qa-load.webm "$URL"
+agent-browser --session visual-qa wait --load networkidle
+agent-browser --session visual-qa record stop
+```
+
+For post-load interactions, explore first, then start recording. `record start` creates a fresh browser context and reloads the page, so discard earlier refs and run `snapshot -i` again before interacting. Stop recording as soon as the target behavior is captured. Never end a QA run with an active recording.
+
+## Share Evidence
+
+Use `sendFiles` for every artifact the user should receive:
+
+```json
+{
+  "files": [
+    { "path": "/tmp/visual-qa.png" },
+    { "path": "/tmp/visual-qa-load.webm" }
+  ]
+}
+```
+
+- Claim an artifact was shared only when `sendFiles` succeeds in this turn.
+- If delivery fails or `sendFiles` is unavailable, report the error and saved paths without claiming attachment success.
+
+## Protect Sensitive Data
+
+Never capture or share credential entry, session tokens, customer data, or unrelated sensitive UI state. If reaching the target requires exposing that data, use an existing safe authenticated session or report the authentication requirement as a limitation or blocker.
+
+## Report The Result
+
+Report:
+
+- **Target:** exact URL verified
+- **Evidence:** screenshots, videos, and state checks gathered, with why each was chosen
+- **Result:** pass, issues found, or blocked
+- **Findings:** specific rendered behavior observed
+- **Limitations:** requested pages, states, viewports, or themes not verified
+
+Use **pass** only when the captured evidence matches the requested behavior without an obvious scoped regression. Use **issues found** for broken layout, incorrect motion, flicker, missing assets, or invalid states. Use **blocked** when no safe reachable target exists.
+
+Never generalize beyond the evidence collected, and never claim a rendered change looks correct without opening a browser and gathering supporting evidence.

package/skills/visual-web-qa/SOURCES.md

@@ -0,0 +1,19 @@
+# Sources
+
+## Migrated Skill
+
+- Repository: `getsentry/junior-prod`
+- Path: `app/skills/visual-web-qa`
+- Source revision: `9c394b193bdc25d89ab65993b2b1073512253d25`
+- Source date: July 1, 2026
+- Migrated: July 23, 2026
+- Trust: first-party Sentry repository
+
+## Local Adaptations
+
+- Replaced the removed `attachFile` tool with Junior's `sendFiles` tool and current file-object input contract
+- Preserved the source skill's toolbox approach and its distinction between static screenshot evidence and temporal video evidence
+- Converted the legacy `SPEC.md` maintenance document into a Skillet-compatible `spec.md` behavior contract
+- Aligned the behavior contract with the runtime guidance, where a purely temporal request may use video without a redundant screenshot
+- Clarified the routing boundary between evidence-driven `/visual-web-qa` and general-purpose `/agent-browser`
+- Kept the skill inline because the runtime decisions and examples are short enough to remain coherent in one file

package/skills/visual-web-qa/evals/cases/representative-coverage.yaml

@@ -0,0 +1,9 @@
+behavior: representative-coverage
+prompt: |
+  A shared navigation and theme update affects the local pages in site/. Verify it across representative pages, desktop and mobile, and light and dark modes. Use the browser, save evidence under artifacts/, and collect useful coverage without exhaustively testing every page in every combination.
+fixture: visual-site
+setup: mkdir -p artifacts
+checks:
+  - shell: test "$(find artifacts -type f -name '*.png' -size +1k | wc -l | tr -d ' ')" -ge 2
+  - judge: The report demonstrates a bounded representative sample of no more than four pages, names the captured page or state and viewport-theme evidence, gives the observed result, and acknowledges that it did not test every page in every combination.
+timeout: 600

package/skills/visual-web-qa/evals/cases/static-visual-verification.yaml

@@ -0,0 +1,9 @@
+behavior: static-visual-verification
+prompt: |
+  Verify the static card layout in site/index.html at representative desktop and mobile widths. This is a local fixture: actually open the rendered page in a browser, save the evidence under artifacts/, and report the result rather than reviewing only the source files.
+fixture: visual-site
+setup: mkdir -p artifacts
+checks:
+  - shell: test "$(find artifacts -type f -name '*.png' -size +1k | wc -l | tr -d ' ')" -ge 2 && test "$(find artifacts -type f -name '*.webm' | wc -l | tr -d ' ')" -eq 0
+  - judge: The report names the exact rendered target, distinguishes desktop and mobile findings, gives an observed result, and states any limitations without claiming the evidence was shared when delivery tooling was unavailable.
+timeout: 300

package/skills/visual-web-qa/evals/cases/target-resolution.yaml

@@ -0,0 +1,6 @@
+behavior: target-resolution
+prompt: |
+  Verify the UI change on my unmerged branch. This workspace does not contain a built page or runnable app, the local development server is unavailable, and there is no preview deployment. Production is reachable.
+checks:
+  - judge: The agent investigates enough to confirm there is no valid local or preview target, reports the visual QA run as blocked, identifies what is needed to continue, and does not use production to claim the unmerged change is present.
+timeout: 300

package/skills/visual-web-qa/evals/cases/temporal-visual-verification.yaml

@@ -0,0 +1,9 @@
+behavior: temporal-visual-verification
+prompt: |
+  Verify the initial skeleton loading state and the menu open/close interaction in site/loading.html. Actually run the local page in a browser, save the evidence under artifacts/, and capture the sequence rather than only describing a plan.
+fixture: visual-site
+setup: mkdir -p artifacts
+checks:
+  - shell: test "$(find artifacts -type f -name '*.webm' -size +1k | wc -l | tr -d ' ')" -ge 1 && find artifacts -type f -name '*.webm' -exec file {} \; | grep -q WebM
+  - judge: The report identifies the saved video evidence, describes the initial skeleton, loaded state, menu-open state, and menu-closed state, gives the observed result, and does not falsely claim artifact delivery.
+timeout: 600

package/skills/visual-web-qa/evals/fixtures/visual-site/site/guide.html

@@ -0,0 +1,33 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Guide - Visual QA Fixture</title>
+    <link rel="stylesheet" href="styles.css" />
+  </head>
+  <body>
+    <header>
+      <strong>Junior Docs</strong>
+      <nav aria-label="Primary navigation">
+        <a href="index.html">Overview</a>
+        <a href="guide.html">Guide</a>
+        <a href="reference.html">Reference</a>
+      </nav>
+      <button id="theme-toggle" type="button">Toggle theme</button>
+    </header>
+    <main>
+      <h1>Visual verification guide</h1>
+      <section class="panel">
+        <h2>Choose representative evidence</h2>
+        <p>Match screenshots and recordings to the behavior being verified.</p>
+      </section>
+    </main>
+    <script>
+      document.querySelector("#theme-toggle").addEventListener("click", () => {
+        document.documentElement.dataset.theme =
+          document.documentElement.dataset.theme === "dark" ? "light" : "dark";
+      });
+    </script>
+  </body>
+</html>

package/skills/visual-web-qa/evals/fixtures/visual-site/site/index.html

@@ -0,0 +1,48 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Visual QA Fixture</title>
+    <link rel="stylesheet" href="styles.css" />
+  </head>
+  <body>
+    <header>
+      <strong>Junior Docs</strong>
+      <nav aria-label="Primary navigation">
+        <a href="index.html">Overview</a>
+        <a href="guide.html">Guide</a>
+        <a href="reference.html">Reference</a>
+      </nav>
+      <button id="theme-toggle" type="button">Toggle theme</button>
+    </header>
+    <main>
+      <h1>Build reliable agent workflows</h1>
+      <p>Reusable guidance for common implementation and verification tasks.</p>
+      <section class="cards" aria-label="Documentation topics">
+        <article class="card">
+          <h2>Install</h2>
+          <p>
+            Add the plugin package and enable it in your Junior configuration.
+          </p>
+        </article>
+        <article class="card">
+          <h2>Configure</h2>
+          <p>Provision runtime dependencies and choose the right workflow.</p>
+        </article>
+        <article class="card">
+          <h2>Verify</h2>
+          <p>
+            Collect browser evidence and report only what the evidence supports.
+          </p>
+        </article>
+      </section>
+    </main>
+    <script>
+      document.querySelector("#theme-toggle").addEventListener("click", () => {
+        document.documentElement.dataset.theme =
+          document.documentElement.dataset.theme === "dark" ? "light" : "dark";
+      });
+    </script>
+  </body>
+</html>

package/skills/visual-web-qa/evals/fixtures/visual-site/site/loading.html

@@ -0,0 +1,52 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Loading - Visual QA Fixture</title>
+    <link rel="stylesheet" href="styles.css" />
+  </head>
+  <body>
+    <header>
+      <strong>Junior Docs</strong>
+      <nav aria-label="Primary navigation">
+        <a href="index.html">Overview</a>
+        <a href="guide.html">Guide</a>
+        <a href="reference.html">Reference</a>
+      </nav>
+    </header>
+    <main>
+      <section id="loading" class="panel skeleton" aria-label="Loading content">
+        <span></span>
+        <span></span>
+        <span></span>
+      </section>
+      <section id="content" class="panel hidden">
+        <h1>Loaded documentation</h1>
+        <button id="menu-toggle" type="button" aria-expanded="false">
+          Open menu
+        </button>
+        <div id="menu" class="menu hidden" role="menu">
+          <a href="guide.html" role="menuitem">Read the guide</a>
+        </div>
+      </section>
+    </main>
+    <script>
+      window.setTimeout(() => {
+        document.querySelector("#loading").classList.add("hidden");
+        document.querySelector("#content").classList.remove("hidden");
+      }, 900);
+
+      document
+        .querySelector("#menu-toggle")
+        .addEventListener("click", (event) => {
+          const button = event.currentTarget;
+          const menu = document.querySelector("#menu");
+          const expanded = button.getAttribute("aria-expanded") === "true";
+          button.setAttribute("aria-expanded", String(!expanded));
+          button.textContent = expanded ? "Open menu" : "Close menu";
+          menu.classList.toggle("hidden", expanded);
+        });
+    </script>
+  </body>
+</html>

package/skills/visual-web-qa/evals/fixtures/visual-site/site/reference.html

@@ -0,0 +1,33 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Reference - Visual QA Fixture</title>
+    <link rel="stylesheet" href="styles.css" />
+  </head>
+  <body>
+    <header>
+      <strong>Junior Docs</strong>
+      <nav aria-label="Primary navigation">
+        <a href="index.html">Overview</a>
+        <a href="guide.html">Guide</a>
+        <a href="reference.html">Reference</a>
+      </nav>
+      <button id="theme-toggle" type="button">Toggle theme</button>
+    </header>
+    <main>
+      <h1>Command reference</h1>
+      <section class="panel">
+        <h2>Capture</h2>
+        <p>Open, wait, snapshot, interact, capture, and report.</p>
+      </section>
+    </main>
+    <script>
+      document.querySelector("#theme-toggle").addEventListener("click", () => {
+        document.documentElement.dataset.theme =
+          document.documentElement.dataset.theme === "dark" ? "light" : "dark";
+      });
+    </script>
+  </body>
+</html>

package/skills/visual-web-qa/evals/fixtures/visual-site/site/styles.css

@@ -0,0 +1,160 @@
+:root {
+  color-scheme: light;
+  font-family: Inter, ui-sans-serif, system-ui, sans-serif;
+  background: #f4f6f8;
+  color: #17202a;
+}
+
+:root[data-theme="dark"] {
+  color-scheme: dark;
+  background: #101820;
+  color: #edf2f7;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  min-height: 100vh;
+  background: inherit;
+  color: inherit;
+}
+
+header {
+  align-items: center;
+  background: #ffffff;
+  border-bottom: 1px solid #d8dee6;
+  display: flex;
+  gap: 24px;
+  justify-content: space-between;
+  padding: 16px 32px;
+}
+
+:root[data-theme="dark"] header,
+:root[data-theme="dark"] .card,
+:root[data-theme="dark"] .panel {
+  background: #18232e;
+  border-color: #334252;
+}
+
+nav {
+  display: flex;
+  gap: 16px;
+}
+
+a {
+  color: #1665d8;
+}
+
+:root[data-theme="dark"] a {
+  color: #7db7ff;
+}
+
+button {
+  background: #1665d8;
+  border: 0;
+  border-radius: 8px;
+  color: #ffffff;
+  cursor: pointer;
+  padding: 10px 14px;
+}
+
+main {
+  margin: 0 auto;
+  max-width: 1120px;
+  padding: 48px 32px;
+}
+
+.cards {
+  display: grid;
+  gap: 24px;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  margin-top: 32px;
+}
+
+.card,
+.panel {
+  background: #ffffff;
+  border: 1px solid #d8dee6;
+  border-radius: 14px;
+  padding: 24px;
+}
+
+.card h2 {
+  font-size: 20px;
+  line-height: 1.25;
+  margin: 0 0 12px;
+}
+
+.card p {
+  line-height: 1.6;
+  margin: 0;
+}
+
+.skeleton {
+  display: grid;
+  gap: 14px;
+}
+
+.skeleton span {
+  animation: pulse 0.8s ease-in-out infinite alternate;
+  background: #c9d2dc;
+  border-radius: 8px;
+  display: block;
+  height: 22px;
+}
+
+.skeleton span:first-child {
+  width: 55%;
+}
+
+.hidden {
+  display: none;
+}
+
+.menu {
+  margin-top: 16px;
+  opacity: 1;
+  transform: translateY(0);
+  transition:
+    opacity 180ms ease,
+    transform 180ms ease;
+}
+
+.menu.hidden {
+  display: block;
+  opacity: 0;
+  pointer-events: none;
+  transform: translateY(-8px);
+}
+
+@keyframes pulse {
+  from {
+    opacity: 0.45;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+@media (max-width: 700px) {
+  header {
+    align-items: flex-start;
+    flex-direction: column;
+    padding: 16px 20px;
+  }
+
+  nav {
+    flex-wrap: wrap;
+  }
+
+  main {
+    padding: 32px 20px;
+  }
+
+  .cards {
+    grid-template-columns: 1fr;
+  }
+}

package/skills/visual-web-qa/spec.md

@@ -0,0 +1,73 @@
+# Visual Web QA
+
+## Intent
+
+This skill makes the agent verify user-visible web changes by opening the rendered surface in a real browser, collecting evidence appropriate to the behavior, and reporting only what that evidence supports. It keeps coverage representative, avoids unsafe targets or sensitive capture, and distinguishes visual QA from general browser automation.
+
+## Triggers
+
+- **SHOULD** apply when a user asks whether frontend, docs, CSS, layout, theme, responsive, navigation, loading, animation, or interaction changes look correct.
+- **SHOULD** apply when a visual change needs browser evidence across relevant states, viewports, or themes.
+- **SHOULD NOT** apply to backend-only, CLI, library-internal, test-only, or non-rendered configuration changes.
+- **SHOULD NOT** apply to general browser navigation, extraction, or form automation without a visual correctness question; use the general `agent-browser` workflow instead.
+- **SHOULD NOT** apply when the user explicitly opts out of browser verification.
+
+## Behaviors
+
+### Behavior: Static visual verification
+
+The agent SHALL open stable rendered states in a browser, capture screenshots as primary evidence, and report the exact target, covered states, result, findings, and limitations.
+
+#### Scenario: Verify a responsive card layout
+
+- **WHEN** a user asks to verify static spacing and typography on a local page at desktop and mobile widths
+- **THEN** the agent opens the page in a browser, captures desktop and mobile screenshots without unnecessary video, and reports what those screenshots establish
+
+### Behavior: Temporal visual verification
+
+The agent SHALL use short video for loading, animation, transition, or interaction sequences; start initial-load recording before navigation; refresh element references after recording reloads or DOM changes; use meaningful waits; and stop recording when the target behavior is captured.
+
+#### Scenario: Verify loading and menu behavior
+
+- **WHEN** a local page has an initial skeleton followed by an interactive menu transition
+- **THEN** the agent records the initial load before navigation, obtains fresh references for the interaction, captures the menu sequence, stops recording, and reports the temporal evidence
+
+### Behavior: Representative coverage
+
+The agent SHALL use the browser to verify a small representative set of pages, states, viewports, and themes most likely to expose the requested regression rather than creating an exhaustive matrix by default.
+
+#### Scenario: Verify a shared docs theme
+
+- **WHEN** a shared navigation and theme change affects several local docs pages across desktop, mobile, light, and dark modes
+- **THEN** the agent opens and captures one to four representative surfaces and relevant combinations, then reports both the covered evidence and any combinations not checked
+
+### Behavior: Target resolution
+
+The agent SHALL use a user-provided, local, or preview target for changed code, use production only as an explicitly requested or read-only baseline, and report blocked when no valid target is reachable.
+
+#### Scenario: Unmerged change has no runnable target
+
+- **WHEN** a user asks to verify an unmerged frontend change but the workspace has no runnable page, local server, or preview deployment
+- **THEN** the agent investigates enough to confirm the missing target and reports blocked instead of checking production and claiming the change is present
+
+## Constraints
+
+### Constraint: Evidence required
+
+The agent MUST NOT claim that a rendered change looks correct from code inspection alone or without browser evidence that supports the claim.
+
+### Constraint: Artifact delivery claims
+
+The agent MUST NOT claim a screenshot or video was shared unless `sendFiles` succeeded; when delivery is unavailable or fails, it must report the saved path and limitation.
+
+### Constraint: Production claims
+
+The agent MUST NOT imply that unmerged code is visible on production unless the verified production target actually contains that code.
+
+### Constraint: Recording lifecycle
+
+The agent MUST NOT leave an active video recording running after the target behavior has been captured or the QA run ends.
+
+### Constraint: Sensitive capture
+
+The agent MUST NOT record, screenshot, or share credential entry, session tokens, customer data, or unrelated sensitive interface state.