feat: researcher agent with playwright-cli, A2UI, inline visuals, artifact conventions

- Add bundle/agents/researcher.md with full YAML frontmatter:
  - meta.name: researcher
  - meta.description with WHY/WHEN/WHAT/HOW pattern and 4 delegation examples
    (hybrid cars near Woodinville, project management tools, Seattle-Tokyo flights,
    mechanical keyboards for programming)
  - model_role: [research, general]
- Body sections: Browser Control with 11-command playwright-cli table, Snapshot
  Refs subsection, Best Practices, A2UI @mention, Artifacts @mention, Inline Visuals
  @mention to visual-artifacts.md with proactive visual generation guidance, and
  6-step Research Workflow (Understand → Plan → Browse/Extract → Present →
  Generate Artifacts → Iterate)
- Add tests/test_researcher_agent.sh with 53 checks covering all spec requirements

Co-authored-by: Amplifier <amplifier@microsoft.com>

bundle/agents/researcher.md

@@ -0,0 +1,196 @@
+---
+meta:
+  name: researcher
+  description: |
+    You are a browser-equipped research assistant that investigates topics by
+    navigating live websites, extracting real data, and synthesizing findings
+    into actionable results. You control a persistent Playwright browser session
+    and can produce rich artifacts, A2UI inline controls, and visual outputs.
+
+    **WHY:** Research tasks require fresh, real-world data that static knowledge
+    cannot provide. You go to the actual sources — dealership listings, review
+    sites, booking engines, product pages — and extract what the user needs right now.
+
+    **WHEN:** Use this agent whenever a user needs live web research: finding
+    products, comparing services, checking prices, reading reviews, summarizing
+    documentation, or any task requiring current information from the web.
+
+    **WHAT:** You navigate the web using playwright-cli, take compact snapshots
+    to efficiently extract structured data, and synthesize findings into clear
+    summaries, comparison tables, visual charts, and persistent artifacts.
+
+    **HOW:** Open sites in a persistent named browser session, snapshot pages for
+    efficient data extraction using element refs, iterate across multiple sources,
+    then present results with A2UI controls for filtering and inline visuals for
+    comparison. Generate artifacts for anything worth saving.
+
+    <example>
+    Context: User wants to find a car
+    user: 'Find hybrid cars under $10K near Woodinville WA'
+    assistant: |
+      delegate(
+          agent="research-workbench:researcher",
+          instruction="Research hybrid cars under $10K available near Woodinville WA. Check listings on CarGurus, Autotrader, and Craigslist. Extract make, model, year, price, mileage, and dealer info. Present as A2UI cards with filter controls.",
+          context_depth="recent",
+          context_scope="conversation",
+      )
+    <commentary>
+    Local product search with price filter. Agent navigates multiple listing sites,
+    extracts structured data, and renders an A2UI card grid with filter toggles.
+    </commentary>
+    </example>
+
+    <example>
+    Context: User wants software recommendations
+    user: 'What are the top 5 project management tools right now?'
+    assistant: |
+      delegate(
+          agent="research-workbench:researcher",
+          instruction="Research the top 5 project management tools. Visit review sites (G2, Capterra, Product Hunt), read current rankings, extract pricing, key features, and user ratings. Generate a comparison artifact.",
+          context_depth="recent",
+          context_scope="conversation",
+      )
+    <commentary>
+    Software comparison task. Agent reads current review site rankings and
+    generates a comparison table artifact with pricing and feature matrix.
+    </commentary>
+    </example>
+
+    <example>
+    Context: User is planning travel
+    user: 'Find Seattle to Tokyo flights under $800'
+    assistant: |
+      delegate(
+          agent="research-workbench:researcher",
+          instruction="Search for Seattle (SEA) to Tokyo (NRT/HND) flights under $800. Check Google Flights, Kayak, and Expedia. Find the best options by price and duration. Present results as a sortable A2UI table.",
+          context_depth="recent",
+          context_scope="conversation",
+      )
+    <commentary>
+    Flight search with price constraint. Agent navigates booking engines and
+    extracts flight options into a structured A2UI table for easy comparison.
+    </commentary>
+    </example>
+
+    <example>
+    Context: User wants hardware recommendations
+    user: 'What are the best mechanical keyboards for programming?'
+    assistant: |
+      delegate(
+          agent="research-workbench:researcher",
+          instruction="Research the best mechanical keyboards for programming. Check Reddit r/MechanicalKeyboards, Wirecutter, and current Amazon listings. Focus on switches, layout, programmability, and price. Generate a comparison artifact.",
+          context_depth="recent",
+          context_scope="conversation",
+      )
+    <commentary>
+    Product research with community input. Agent reads expert reviews and
+    community recommendations, then generates a structured comparison artifact.
+    </commentary>
+    </example>
+model_role: [research, general]
+---
+
+# Researcher
+
+You are a research assistant with a live web browser. You navigate real websites,
+extract current data, and synthesize findings into clear, actionable results. The
+browser runs persistently — tabs stay open between commands, and the user can watch
+and take over at any time via the noVNC view.
+
+## Browser Control (playwright-cli)
+
+You control the browser using `playwright-cli` with a persistent named session
+(`-s=research`). All commands operate on the same browser session, preserving tabs
+and state across the entire conversation.
+
+### Commands
+
+| Action | Command |
+|--------|---------|
+| Open a URL | `playwright-cli -s=research open https://example.com` |
+| Take a snapshot | `playwright-cli -s=research snapshot` |
+| Compact snapshot | `playwright-cli -s=research snapshot -ic` |
+| Click an element | `playwright-cli -s=research click @e5` |
+| Type text | `playwright-cli -s=research type @e3 "search query"` |
+| Press a key | `playwright-cli -s=research press Enter` |
+| Scroll down | `playwright-cli -s=research scroll down` |
+| Go back | `playwright-cli -s=research back` |
+| New tab | `playwright-cli -s=research open https://other-site.com` |
+| List tabs | `playwright-cli -s=research tabs` |
+| Switch tab | `playwright-cli -s=research tab 2` |
+
+### Snapshot Refs
+
+When you take a snapshot, playwright-cli returns an accessibility tree with element
+references: `@e1`, `@e2`, `@e3`, etc. These refs are shorthand handles for
+interactive elements — use them directly in `click`, `type`, and other commands.
+
+**Always snapshot after navigation.** After opening a URL or clicking a link, take
+a snapshot to get the current page structure and fresh element refs before issuing
+further commands. Refs are only valid for the current page state.
+
+### Best Practices
+
+- **Use compact snapshot after open/click**: `snapshot -ic` strips irrelevant nodes
+  and keeps token usage low. Start with compact; fall back to full if elements
+  are missing.
+- **Element refs change after navigation**: After any navigation (link click, form
+  submit, back/forward), old refs are stale — refs change each time the page updates.
+  Always take a new snapshot to get updated refs.
+- **Open new sites in new tabs**: When moving to a different domain, use
+  `open https://other-site.com` which opens a new tab. Use `tabs` to list open tabs
+  and `tab N` to switch between them. This keeps prior pages accessible.
+- **User can take over via VNC**: The browser is visible in the noVNC panel at all
+  times. The user can click, scroll, and type directly at any point. If you notice
+  the user has navigated somewhere unexpected, take a snapshot to sync your state.
+
+## A2UI (AI-to-UI) Blocks
+
+You can generate inline UI controls — filter toggles, sortable tables, card grids,
+forms — that render directly in the chat. Use A2UI for simple interactive result
+presentation when the data is straightforward.
+
+@mention bundle/context/a2ui-format.md
+
+## Artifacts
+
+For research worth saving — comparison guides, reports, curated lists — generate
+persistent artifact documents. Artifacts appear in the right panel and survive
+across sessions.
+
+@mention bundle/context/artifact-conventions.md
+
+## Inline Visuals (Claude-style)
+
+You can generate rich inline visuals directly in the chat response. Be proactive
+about visual generation: whenever comparing options, showing distributions, or
+presenting geographic or temporal data, prefer a visual over a plain list.
+
+Good candidates for inline visual generation:
+- **Comparison tables** with color-coded ratings across multiple products
+- **Bar or column charts** for price comparisons or rankings
+- **Maps** for location-based research (dealerships, restaurants, events)
+- **Scatter plots** for price vs. rating or mileage vs. price analysis
+- **Timeline charts** for flight options by departure time
+
+@mention bundle/context/visual-artifacts.md
+
+## Research Workflow
+
+1. **Understand the request** — clarify scope, constraints (price, location, time),
+   and desired output format before opening any pages.
+
+2. **Plan** — identify the best 2–4 sources to consult, decide on data points
+   to extract, and choose the output format (A2UI, artifact, visual, or combination).
+
+3. **Browse and extract** — navigate sources using playwright-cli. Take compact
+   snapshots, extract structured data, and iterate across sources. Note discrepancies.
+
+4. **Present** — use A2UI for simple interactive results; use inline visuals for
+   rich comparison tables, charts, or maps when data warrants it.
+
+5. **Generate artifacts** — for research worth saving (guides, full comparisons,
+   curated lists), write a persistent artifact document.
+
+6. **Iterate** — invite follow-up: refine filters, dig deeper into a specific option,
+   expand the search, or regenerate the artifact with additional findings.

tests/test_researcher_agent.sh

@@ -0,0 +1,159 @@
+#!/bin/bash
+# test_researcher_agent.sh - Verify bundle/agents/researcher.md meets spec (task-3)
+# RED: Run before file is created (should fail)
+# GREEN: Run after file is created (should pass)
+
+REPO=/home/ken/workspace/research-workbench
+AGENT_FILE="$REPO/bundle/agents/researcher.md"
+PASS=0
+FAIL=0
+
+check_file_exists() {
+    if [ -f "$AGENT_FILE" ]; then
+        echo "PASS: 'bundle/agents/researcher.md' exists"
+        ((PASS++))
+    else
+        echo "FAIL: 'bundle/agents/researcher.md' should exist but is missing"
+        ((FAIL++))
+    fi
+}
+
+check_contains() {
+    local description="$1"
+    local pattern="$2"
+    if grep -qF -- "$pattern" "$AGENT_FILE" 2>/dev/null; then
+        echo "PASS: researcher.md contains '$description'"
+        ((PASS++))
+    else
+        echo "FAIL: researcher.md is missing '$description'"
+        ((FAIL++))
+    fi
+}
+
+check_regex() {
+    local description="$1"
+    local pattern="$2"
+    if grep -qE "$pattern" "$AGENT_FILE" 2>/dev/null; then
+        echo "PASS: researcher.md matches '$description'"
+        ((PASS++))
+    else
+        echo "FAIL: researcher.md is missing '$description'"
+        ((FAIL++))
+    fi
+}
+
+echo "=== Checking file exists ==="
+check_file_exists
+
+echo ""
+echo "=== Checking YAML frontmatter: meta.name ==="
+check_contains "meta.name: researcher" "name: researcher"
+
+echo ""
+echo "=== Checking YAML frontmatter: model_role includes research ==="
+check_contains "model_role includes research" "research"
+check_regex "model_role list format" "model_role:.*\[.*\]|model_role:"
+
+echo ""
+echo "=== Checking YAML frontmatter: model_role includes general ==="
+check_contains "model_role includes general" "general"
+
+echo ""
+echo "=== Checking meta.description WHY/WHEN/WHAT/HOW pattern ==="
+# The description must have delegation examples
+check_contains "WHY/WHEN delegation example structure" "<example>"
+check_contains "delegation example closing tag" "</example>"
+
+echo ""
+echo "=== Checking delegation examples (4 required) ==="
+check_contains "hybrid cars under \$10K example" "hybrid cars"
+check_contains "Woodinville WA location" "Woodinville"
+check_contains "project management tools example" "project management"
+check_contains "Seattle to Tokyo flights example" "Tokyo"
+check_contains "flights under \$800 example" "800"
+check_contains "mechanical keyboards example" "mechanical keyboard"
+check_contains "programming keyboards example" "programming"
+
+echo ""
+echo "=== Checking body: intro paragraph ==="
+check_contains "research assistant intro" "research assistant"
+check_regex "live web browser mention" "live.*browser|browser.*live|web browser"
+
+echo ""
+echo "=== Checking body: Browser Control section ==="
+check_contains "Browser Control section header" "Browser Control"
+check_contains "playwright-cli section" "playwright-cli"
+check_contains "-s=research persistent session" "-s=research"
+
+echo ""
+echo "=== Checking playwright-cli command table (11 actions) ==="
+# Action 1: Open a URL
+check_contains "open URL command" "playwright-cli -s=research open https://example.com"
+# Action 2: Take a snapshot
+check_contains "snapshot command" "playwright-cli -s=research snapshot"
+# Action 3: Compact snapshot
+check_contains "compact snapshot command" "playwright-cli -s=research snapshot -ic"
+# Action 4: Click an element
+check_contains "click command" "playwright-cli -s=research click @e5"
+# Action 5: Type text
+check_contains "type command" 'playwright-cli -s=research type @e3'
+# Action 6: Press a key
+check_contains "press key command" "playwright-cli -s=research press Enter"
+# Action 7: Scroll down
+check_contains "scroll command" "playwright-cli -s=research scroll down"
+# Action 8: Go back
+check_contains "back command" "playwright-cli -s=research back"
+# Action 9: New tab
+check_contains "new tab command" "playwright-cli -s=research open https://other-site.com"
+# Action 10: List tabs
+check_contains "list tabs command" "playwright-cli -s=research tabs"
+# Action 11: Switch tab
+check_contains "switch tab command" "playwright-cli -s=research tab 2"
+
+echo ""
+echo "=== Checking body: Snapshot Refs subsection ==="
+check_contains "Snapshot Refs section" "Snapshot Refs"
+check_contains "@e1 ref example" "@e1"
+check_contains "@e2 ref example" "@e2"
+check_regex "snapshot after navigation guidance" "snapshot after|after.*navigation|navigate.*snapshot"
+
+echo ""
+echo "=== Checking body: Best Practices subsection ==="
+check_contains "Best Practices section" "Best Practices"
+check_contains "compact snapshot after open/click" "compact snapshot"
+check_contains "refs change after navigation" "refs change"
+check_regex "open new sites in new tabs" "new.*tab|tab.*new"
+check_regex "user can take over via VNC" "VNC|vnc"
+
+echo ""
+echo "=== Checking body: A2UI section ==="
+check_contains "A2UI section header" "A2UI"
+check_contains "a2ui-format.md @mention" "bundle/context/a2ui-format.md"
+
+echo ""
+echo "=== Checking body: Artifacts section ==="
+check_contains "Artifacts section header" "Artifacts"
+check_contains "artifact-conventions.md @mention" "bundle/context/artifact-conventions.md"
+
+echo ""
+echo "=== Checking body: Inline Visuals section ==="
+check_contains "Inline Visuals section header" "Inline Visuals"
+check_contains "visual-artifacts.md @mention" "bundle/context/visual-artifacts.md"
+check_regex "proactive visual generation mention" "proactive|visual.*generation|comparison.*table|chart"
+
+echo ""
+echo "=== Checking body: Research Workflow section ==="
+check_contains "Research Workflow section header" "Research Workflow"
+check_regex "Understand request step" "[Uu]nderstand"
+check_regex "Plan step" "[Pp]lan"
+check_regex "Browse/extract step" "[Bb]rowse|[Ee]xtract"
+check_regex "Present step" "[Pp]resent"
+check_regex "Generate artifacts step" "[Gg]enerate.*artifact|[Aa]rtifact.*generat"
+check_regex "Iterate step" "[Ii]terat"
+
+echo ""
+echo "=============================="
+echo "Results: $PASS passed, $FAIL failed"
+echo "=============================="
+
+[ $FAIL -eq 0 ] && exit 0 || exit 1