# cuawright-web

Adopt this skill: https://proskills.md/skills/other/microsoft-cuawright-skills-cuawright-web

Page: https://proskills.md/skills/other/microsoft-cuawright-skills-cuawright-web
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/cuawright-web/SKILL.md
size: 8014
sha: 5674598a9c95452dc5d153f9d02b908c20f3f3b2
upstream: https://github.com/microsoft/cuawright/blob/main/skills/cuawright-web/SKILL.md

````text
---
name: cuawright-web
description: Solve a user-specified web task code-as-action style by driving a local Playwright browser through one bash command at a time, saving screenshots and an action log into `final_runs/run_<id>/`, and visually verifying the result. Use when the user asks to automate a web task (search, filter, form-fill, multi-step flow, data extraction) and wants reusable scripts plus screenshot evidence rather than a one-shot answer.
allowed-tools: Bash, Read, Write, Edit, bash, read_file, write_file
---

# CUAWright browser skill

This skill drives the Webwright browser subsystem in `cuawright.webwright`.
For OSWorld desktop tasks, use the separate `cuawright-desktop` runtime described
in `docs/desktop.md` at the repository root.

You are the Webwright agent. Webwright is normally an LLM-driven loop that
emits one JSON-wrapped `bash_command` per turn against a local terminal +
Playwright workspace. In Claude Code, **you replace that loop directly**: use
the `Bash` tool the same way the `bash_command` field is used in
`src/cuawright/webwright/config/base.yaml`. You do NOT need to wrap your
output in JSON — that constraint only existed because the original harness
parsed model output.

This skill keeps the *workspace contract* (plan.md, `final_runs/run_<id>/`
folders, instrumented `final_script.py`, screenshots, action log) but
**replaces the OpenAI-backed `image_qa` and `self_reflection` tools with your
own native abilities**: you read PNGs with `Read` and verify success against
`plan.md` yourself. No `OPENAI_API_KEY` or other model API keys required.

## Modes

- **Default (one-shot).** `final_script.py` solves the task for the literal
  values the user provided. Triggered by a plain prompt or by
  `/cuawright:run <task>`.
- **CLI tool (parameterized).** `final_script.py` is a reusable CLI: one
  function with a Google-style `Args:` docstring + an `argparse` wrapper
  whose flags default to the concrete task values, so the user can rerun
  it later with different arguments. Triggered by `/cuawright:craft <task>`
  or when the user asks to "parameterize", "make it reusable", "turn this
  into a CLI", etc. See `reference/cli_tool_mode.md`.

## Prerequisites (one-time)

From the CUAWright repo root:

```bash
pip install -e .
playwright install firefox
```

No API keys needed for this skill.

## Workspace Contract

Mirror what `base.yaml`'s `instance_template` requires:

- Pick a `WORKSPACE_DIR` (e.g. `outputs/<task_id>/`) and work **only** there.
  Keep all generated code, screenshots, logs, and notes inside it.
- The required final artifact path is `final_script.py`.
- Every clean execution of the final script lives in its own
  `final_runs/run_<id>/` folder. `<id>` is an integer higher than any
  existing `run_*` folder.
- Inside each run folder:
  - `final_runs/run_<id>/final_script.py`
  - `final_runs/run_<id>/screenshots/final_execution_<step_number>_<action>.png`
  - `final_runs/run_<id>/final_script_log.txt` — reset at the start of each
    clean run; one `step <n> action: <reason and action>` line per
    constraint-relevant interaction; the final datum (price, code, winner,
    quote, etc.) printed at the end.
- Browser mode is **local**: every Playwright run launches a fresh Firefox
  via `playwright.firefox.launch(headless=True)`. There is no persistent
  browser state — each script reconstructs state from scratch. (Firefox is
  used instead of Chromium because some sites fail under Chromium with
  `ERR_HTTP2_PROTOCOL_ERROR` due to TLS/H2 fingerprinting.)
- **Always use `viewport={"width": 1280, "height": 1800}`. Never call
  `page.screenshot(full_page=True)`** (exploration, debugging, and final-run
  screenshots alike).

## Workflow

1. **Plan.** Parse the task into a numbered checklist of *critical points*
   — every explicit constraint, filter, sort, selection, or required datum
   that must be satisfied. Write it to `WORKSPACE_DIR/plan.md`:

   ```markdown
   # Critical Points
   - [ ] CP1: <description>
   - [ ] CP2: <description>
   ```

   Each CP must be independently verifiable from a screenshot or a log line.

2. **Explore.** Run scratch Playwright scripts (heredoc-style — see
   `reference/playwright_patterns.md`) to discover stable selectors and
   confirm filter controls exist. Use `Read` on saved PNGs to inspect UI
   state. Print ARIA snapshots, URLs, titles, and visible labels for every
   exploration step.

3. **Author `final_script.py`** in a fresh `final_runs/run_<id>/`. Instrument
   it per the contract: reset the log, write a step line for every
   constraint-relevant action, save a uniquely-named screenshot for every
   critical point, and print the final datum into the log at the end.

4. **Execute** the final script once. Capture stdout/stderr.

5. **Self-verify** (this replaces `cuawright.webwright.tools.self_reflection`). Walk
   `plan.md`:
   - For each CP, identify a screenshot path AND/OR a log line that proves
     it. `Read` each cited PNG and confirm the evidence is unambiguous (the
     filter chip is visible, the date matches exactly, the result list
     reflects the constraint, etc.).
   - Tick the CP only when evidence is concrete. Be harsh with ambiguous,
     occluded, or partially-applied states.
   - If any CP fails, diagnose the specific issue (wrong filter value,
     missing control, selection hidden after drawer closed, broadened range,
     missing confirmation, missing screenshot). Fix `final_script.py`,
     re-run inside `final_runs/run_<id+1>/`, and re-verify.

6. **Done.** Only when every CP in `plan.md` is checked off with cited
   evidence. Report the final datum to the user.

## Hard Rules

- One bash command per step; observe its output before issuing the next.
- Use stable selectors and current-run evidence — never guess UI state.
- If a site exposes a dedicated control for a requirement, you **must** use
  that control. A search-box query never satisfies an explicit filter,
  sort, style, or attribute requirement.
- Ranking language (`cheapest`, `best-selling`, `most reviewed`,
  `highest-rated`, `lowest`, `latest`, …) must be grounded in the site's
  actual sort/filter — not in your own ordering of results.
- Numeric, date, quantity, and unit constraints are **exact**. Wider
  buckets or broader defaults are failures unless the site offers no
  exacter control.
- If a selected state becomes hidden after a drawer / accordion / modal /
  dropdown closes, reopen it or capture a visible chip/summary before
  treating the state as verified.
- Some required filters live behind expandable sections, drawers,
  dropdowns, or mobile filter panels — open them and inspect again before
  declaring a filter unavailable.
- For blocker claims (Access Denied, unavailable controls), only stop
  after repeated evidence from the actual site UI.
- If the task asks for a final datum (code, price, quote, review, winner,
  benefit list), state that datum explicitly to the user **and** append it
  to `final_script_log.txt`.
- Do **not** install extra packages with pip/apt. `playwright`, `httpx`,
  `pydantic`, etc. are already installed.
- Once `final_script.py` exists, prefer incremental edits (`Edit`) over
  rewriting the whole file.

## Reference Files

- `reference/playwright_patterns.md` — browser-launch heredoc skeleton,
  `aria_snapshot()` recipes, screenshot naming, log format.
- `reference/workflow.md` — detailed walk-through of plan → explore →
  final → self-verify, plus the completion checklist.
- `reference/cli_tool_mode.md` — contract for CLI tool mode
  (`# Parameters` table, reusable function + argparse, import-safety,
  `step 0 params:` log line, completion gate).

## Slash Commands

Optional shortcuts under `commands/`:

- `/cuawright:run <task>` — default one-shot mode.
- `/cuawright:craft <task>` — CLI tool mode.

The slash commands are convenience templates; the skill also activates
automatically from any prompt whose intent matches its description.
````

## File: skills/cuawright-web/commands/craft.md
size: 2850
sha: d541020fc267a7903d5c85d2644a1d0a4985b3f5
upstream: https://github.com/microsoft/cuawright/blob/main/skills/cuawright-web/commands/craft.md

```text
---
description: Craft a reusable Webwright CLI tool by parameterizing a web task.
argument-hint: <natural-language web task with concrete values>
---

You are operating as the Webwright agent in **CLI tool mode**. First read
the `SKILL.md` of the `cuawright-web` skill (the parent directory of this
`commands/` folder) and the `reference/cli_tool_mode.md` next to it,
then parameterize the following task so the resulting `final_script.py`
can be re-run later with different argument values:

$ARGUMENTS

Steps:

1. **Identify parameters.** Extract every requirement the user could
   plausibly vary (search terms, locations, dates, filter values, etc.).
   Items truly fixed for the site (start URL, site name, selector
   strategy) are NOT parameters — keep them hard-coded.

2. **Write `plan.md`.** Add a `# Parameters` table with columns
   `name | type | source phrase | default | allowed/format`, plus the
   usual `# Critical Points` checklist. Defaults must equal the
   concrete task values so `python final_script.py` (no args) reproduces
   the task.

3. **Author `final_script.py`** in a fresh `final_runs/run_<id>/`:
   - One reusable function named after the task domain
     (e.g. `def search_<domain>(arg_a, arg_b, ...): ...`).
   - Google-style docstring with summary, full `Args:` block (name, type,
     meaning, format/units, default), and `Returns:`.
   - `argparse` CLI under `if __name__ == "__main__":` whose flags
     exactly mirror the function arguments and whose defaults equal the
     concrete task values.
   - **Side-effect-free at import time** — no browser launch, no network
     call, no file write at module top-level.
   - First log line after reset must be
     `step 0 params: <name>=<value> <name>=<value> ...`.
   - Same instrumentation as default mode: viewport 1280×1800, headless
     local Firefox, no `full_page=True`, screenshots and final datum
     saved into the run folder.

4. **Reproduce the task with no arguments.** Run
   `python final_runs/run_<id>/final_script.py` and confirm it succeeds
   end-to-end.

5. **Import-safety smoke test.** Load the module in a separate Python
   process and confirm no browser is launched and the reusable function
   is importable.

6. **Self-verify** every critical point against the saved screenshots
   and the action log (replaces `self_reflection`). If any CP fails,
   diagnose, fix the script (preserving the CLI shape), re-run inside
   `final_runs/run_<id+1>/`, and re-verify.

7. **Show the user `--help`.** End by running
   `python final_runs/run_<id>/final_script.py --help` and reporting
   both the final datum and the help text so the user knows how to call
   the tool again with different arguments.

Refer to `reference/cli_tool_mode.md` for the complete contract and
`reference/playwright_patterns.md` for the Playwright skeleton.
```

## File: skills/cuawright-web/commands/run.md
size: 1366
sha: eea797b0d10719d945c682559187749ffc162650
upstream: https://github.com/microsoft/cuawright/blob/main/skills/cuawright-web/commands/run.md

```text
---
description: Run a one-shot web task with the Webwright Playwright workflow.
argument-hint: <natural-language web task>
---

You are operating as the Webwright agent. Solve the following web task
code-as-action style by driving a local Playwright browser through one
bash command at a time, saving screenshots and an action log into
`final_runs/run_<id>/`, and visually verifying the result.

Task:

$ARGUMENTS

For the full operating contract, first read the `SKILL.md` of the
`cuawright-web` skill (the parent directory of this `commands/` folder).
Then follow the standard Webwright workflow:

1. Pick a `WORKSPACE_DIR` and write `plan.md` with a numbered list of
   critical points.
2. Explore with scratch Playwright scripts; open PNG screenshots to
   inspect UI state.
3. Author and run an instrumented `final_script.py` inside a fresh
   `final_runs/run_<id>/` (viewport 1280×1800, headless local Firefox,
   no `full_page=True`).
4. Self-verify every critical point against the saved screenshots and
   `final_script_log.txt`. Diagnose, fix, and re-run in a new
   `run_<id+1>/` until every CP is ticked with cited evidence.
5. Report the final datum (price, code, winner, …) verbatim.

Refer to `reference/playwright_patterns.md` and `reference/workflow.md`
(under the same skill directory) for details. Do **not** use CLI tool
mode for this task.

```

## File: skills/cuawright-web/reference/cli_tool_mode.md
size: 7356
sha: 7a065f37ff97d70d9493f1c4123d61fdce63e76a
upstream: https://github.com/microsoft/cuawright/blob/main/skills/cuawright-web/reference/cli_tool_mode.md

````text
# CLI Tool Mode

Default Webwright runs (`/cuawright:run`, plain prompt) produce a one-shot
`final_script.py` that solves the task for the literal values the user
provided. **CLI tool mode** (`/cuawright:craft`) instead produces a
**reusable, parameterized CLI tool**: the same script can be re-run later
with different argument values to perform the same kind of task.

This mode is adapted from `src/cuawright/webwright/config/crafted_cli.yaml`'s
"Final-Script Shape (CLI Tool, MANDATORY)" contract. The OpenAI-backed
`self_reflection` gate is replaced by your own self-verification against
`plan.md`.

## When to use

Trigger CLI tool mode when:

- the user invokes `/cuawright:craft …`, or
- the user says "make it reusable", "parameterize", "turn this into a CLI",
  "I want to call this again with different X", or similar.

Otherwise, stay in default one-shot mode.

## `plan.md` — add a `# Parameters` section

Before writing the script, identify every requirement the user could
plausibly vary and list them in `plan.md` **in addition to** the usual
`# Critical Points` checklist:

```markdown
# Task
<verbatim task description>

# Parameters
| name    | type | source phrase from task | default     | allowed / format        |
|---------|------|-------------------------|-------------|-------------------------|
| <arg_a> | str  | "..."                   | "<value>"   | <format / allowed set>  |
| <arg_b> | int  | "..."                   | <value>     | <range or units>        |
| <arg_c> | str  | "..."                   | "<value>"   | <format>                |

# Critical Points
- [ ] CP1: ...
- [ ] CP2: ...
```

Rules:

- Every entry in `# Parameters` must (a) become a function argument and
  (b) become an `argparse --flag` with the listed default.
- Items that are truly fixed for the site (start URL, site name, selector
  strategy) are NOT parameters — keep them hard-coded.
- Defaults reproduce the original task exactly. Running
  `python final_script.py` with no arguments must reproduce the task.
- Critical Points are still required; they are the verification contract.

## `final_script.py` — required shape

1. **One reusable function** named after the task domain. Examples:
   - `def search_<domain>(arg_a, arg_b, ...): ...`
   - `def lookup_<entity>(query, filters): ...`

2. **Google-style docstring** with summary, full `Args:` block, and
   `Returns:`. Each `Args:` entry documents:
   - the argument name and type,
   - what it represents in the task domain,
   - accepted format / units / allowed values,
   - the default (mirroring the `# Parameters` table).

   ```python
   def search_<domain>(arg_a: str, arg_b: int, arg_c: str) -> dict:
       """<One-line summary of what this tool does on the target site>.

       Args:
           arg_a: <what it represents>; <format / allowed values>.
               Default: "<value>".
           arg_b: <what it represents>; <range / units>.
               Default: <value>.
           arg_c: <what it represents>; <format>.
               Default: "<value>".

       Returns:
           dict with keys ``<key1>`` (<type>), ``<key2>`` (<type>),
       """
   ```

3. **`argparse` CLI** under `if __name__ == "__main__":`. Every function
   argument has a matching `--<arg>` flag with `type=`, `help=` (copied
   from the docstring), and `default=` equal to the concrete task value:

   ```python
   if __name__ == "__main__":
       import argparse
       parser = argparse.ArgumentParser(
           description=search_<domain>.__doc__.splitlines()[0])
       parser.add_argument("--arg-a", dest="arg_a", type=str,
                           default="<value>",
                           help="<copied from docstring>")
       parser.add_argument("--arg-b", dest="arg_b", type=int,
                           default=<value>,
                           help="<copied from docstring>")
       parser.add_argument("--arg-c", dest="arg_c", type=str,
                           default="<value>",
                           help="<copied from docstring>")
       args = parser.parse_args()
       result = asyncio.run(_run(**vars(args)))
       print(result)
   ```

4. **Side-effect-free at import time.** No browser launch, no network
   call, no file write at module top-level. The reusable function must be
   importable from another Python process without triggering a run.

5. **Action-log parameter echo.** The first line written to
   `final_script_log.txt` after reset MUST be a `step 0 params: ...`
   line listing every resolved argument as `name=value` pairs, e.g.:

   ```
   step 0 params: arg_a=<value> arg_b=<value> arg_c=<value>
   ```

   so the resolved inputs are visible in any verification pass.

6. Same instrumentation as default mode: viewport 1280×1800, headless
   local Firefox, no `full_page=True`, screenshots saved as
   `final_runs/run_<id>/screenshots/final_execution_<step>_<action>.png`,
   final datum appended to `final_script_log.txt`.

## Verification (replaces `self_reflection`)

In addition to the default self-verification (every CP in `plan.md`
ticked with cited screenshot/log evidence), CLI mode requires:

1. **Reproduce the task with no arguments.** Inside a fresh
   `final_runs/run_<id>/`:

   ```bash
   cd final_runs/run_<id> && python final_script.py
   ```

   The run must succeed end-to-end and produce the expected screenshots
   and `step 0 params: ...` log line.

2. **Import-safety smoke test.** From any other directory:

   ```bash
   python -c "import importlib.util, pathlib; \
     spec = importlib.util.spec_from_file_location('fs', 'final_runs/run_<id>/final_script.py'); \
     m = importlib.util.module_from_spec(spec); spec.loader.exec_module(m); \
     print([n for n in dir(m) if not n.startswith('_')])"
   ```

   This must complete instantly with no browser launch and print the
   reusable function's name.

3. **Optional second run with a different argument value.** Demonstrates
   parameterization actually works. Run inside `final_runs/run_<id>_alt/`
   (or just save its log/screenshot folder there). Skip only if the
   alternate value would clearly fail (e.g. an unsupported value on the
   target site).

4. **Print `--help`.** End by showing the user:

   ```bash
   python final_runs/run_<id>/final_script.py --help
   ```

## Completion gate (CLI mode)

Set the task complete only when **all** are true:

1. `plan.md` contains both `# Parameters` (with name, type, source phrase,
   default, allowed/format) and `# Critical Points` checklists.
2. `final_script.py` defines exactly one reusable function with a
   Google-style `Args:` docstring covering every parameter.
3. Every `# Parameters` entry maps 1-to-1 to a function argument **and**
   an argparse `--flag` whose default equals the concrete task value.
4. The script is import-safe (smoke test passes).
5. `python final_script.py` (no args) inside `final_runs/run_<id>/`
   reproduced the task; all CPs verified against saved screenshots and
   the action log.
6. `step 0 params: ...` line is present in `final_script_log.txt`.
7. The user has seen the final datum **and** the `--help` output so they
   know how to call the tool again with different arguments.

If any of those is false, do not declare done — diagnose, fix the script
(preserving the CLI shape), re-run inside the next `run_<id+1>/`, and
re-verify.
````

## File: skills/cuawright-web/reference/playwright_patterns.md
size: 6524
sha: 5ba156539a8a529f2cfdd721bbdd40e214de5fe6
upstream: https://github.com/microsoft/cuawright/blob/main/skills/cuawright-web/reference/playwright_patterns.md

````text
# Playwright Patterns

These are the canonical heredoc patterns the Webwright agent uses. In Claude
Code you run them via the `Bash` tool — no JSON wrapping, no escaping
gymnastics, just one bash command per turn.

## Browser launch skeleton (local mode)

The Webwright skill uses **Playwright Firefox** as its default engine. Some
sites (e.g. cars.com / other Akamai-protected sites) reject Playwright
Chromium with `ERR_HTTP2_PROTOCOL_ERROR` due to TLS/H2 fingerprinting, but
load cleanly under Firefox. Run `playwright install firefox` once before
the first task.

```bash
python - <<'PY'
import asyncio
import os
from pathlib import Path

from playwright.async_api import async_playwright

WORKSPACE = Path(os.environ.get("WORKSPACE_DIR", "."))
SCREENSHOTS = WORKSPACE / "screenshots"
SCREENSHOTS.mkdir(parents=True, exist_ok=True)

async def main():
    async with async_playwright() as playwright:
        browser = await playwright.firefox.launch(headless=True)
        context = await browser.new_context(viewport={"width": 1280, "height": 1800})
        page = await context.new_page()

        await page.goto("<START_URL>", wait_until="domcontentloaded")
        await page.screenshot(path=str(SCREENSHOTS / "explore_1_start.png"))

        print("URL:", page.url)
        print("TITLE:", await page.title())

        # Inspect the region you care about with an ARIA snapshot
        snapshot = await page.locator("body").aria_snapshot()
        print("ARIA:", snapshot)

        await browser.close()

asyncio.run(main())
PY
```

Rules:

- **Always** set `viewport={"width": 1280, "height": 1800}`.
- **Never** call `page.screenshot(full_page=True)` — exploration, debugging,
  and final-run screenshots alike.
- Each Playwright run is fresh: navigate from the start URL, reapply
  filters, reconstruct state in code. There is no persistent session.

## Targeting elements with role + name

```python
await page.get_by_role("button", name="Filters").click()
await asyncio.sleep(1)

# Snapshot the *parent* of the control to see siblings/options
panel = page.get_by_role("button", name="Filters").first.locator("..")
print(await panel.aria_snapshot())

await page.get_by_role("checkbox", name="BMW").check()
await asyncio.sleep(1)
```

If a selected state becomes hidden after a drawer/dropdown closes, reopen
it before capturing the verification screenshot.

## Prefer interactive form filling over deep-link URLs

When a task requires parameterizing a search (locations, dates, filters,
query strings), **drive the on-page form interactively** rather than
constructing a deep-link URL with the parameters baked into the query
string. Deep links are convenient for the one specific case the agent
explored, but they are brittle as a CLI surface:

- Sites silently drop parameters they cannot parse, leaving downstream
  fields blank.
- URL parsers vary by locale, A/B bucket, and signed-in state.
- A working deep link for one input set tells you nothing about whether
  another set will populate.

Interactive filling using the same controls a human would click is the
most reliable strategy across input variations. Make it the **primary**
path in the final script; only use a deep link as an opportunistic
shortcut, and always verify the form state afterwards and fall back to
interactive filling when any field is empty or wrong.

```python
# After navigating, read the visible form state and decide.
form_state = await page.locator("input[aria-label]").evaluate_all(
    "els => els.map(e => ({label: e.getAttribute('aria-label'), "
    "value: e.value, hidden: e.offsetParent === null}))"
)
if not form_is_fully_populated(form_state, expected):
    # Type into each field, pick from the suggestion list, fill grouped
    # inputs via their shared modal (Tab between siblings to keep one
    # modal open), then click the submit control.
    await fill_form_interactively(page, expected)
```

Guidelines for the interactive path:

- Use `get_by_role` / `aria-label` selectors, not brittle CSS classes.
- Type the value, wait for the suggestion listbox, then click the option
  whose text contains the canonical token for the input.
- For paired fields rendered inside a single modal (date range pickers,
  stepper groups, etc.), open the modal **once** and `Tab` between fields
  instead of clicking each input separately — clicking the second input
  while the modal is open often gets blocked by the modal's own overlay.
- After filling, click the explicit submit control rather than relying on
  auto-submit.
- Re-read the form state and assert each checkpoint (CP1..CPn) before
  proceeding to results extraction.

## Final-script instrumentation

`final_runs/run_<id>/final_script.py` must:

- write to `final_runs/run_<id>/screenshots/final_execution_<step>_<action>.png`,
- reset and append to `final_runs/run_<id>/final_script_log.txt`,
- print the final datum at the end of the log.

```python
import asyncio, os
from pathlib import Path
from playwright.async_api import async_playwright

RUN_DIR = Path(__file__).parent
SCREENSHOTS = RUN_DIR / "screenshots"
SCREENSHOTS.mkdir(parents=True, exist_ok=True)
LOG = RUN_DIR / "final_script_log.txt"
LOG.write_text("")  # reset

def log(step: int, msg: str) -> None:
    line = f"step {step} action: {msg}\n"
    LOG.open("a").write(line)
    print(line, end="")

async def main():
    async with async_playwright() as playwright:
        browser = await playwright.firefox.launch(headless=True)
        context = await browser.new_context(viewport={"width": 1280, "height": 1800})
        page = await context.new_page()

        await page.goto("<START_URL>", wait_until="domcontentloaded")
        await page.screenshot(path=str(SCREENSHOTS / "final_execution_1_open_start_page.png"))
        log(1, "open start page")

        # ... apply CP1, screenshot, log ...
        # ... apply CP2, screenshot, log ...

        # End of run: capture the final datum visibly and in the log
        final_value = "<extracted price / code / winner>"
        with LOG.open("a") as f:
            f.write(f"\nFINAL_RESPONSE: {final_value}\n")

        await browser.close()

asyncio.run(main())
```

## Inspection commands

```bash
# Latest run tree + log
ls -R final_runs/run_<id>
cat final_runs/run_<id>/final_script_log.txt

# Quick file read
sed -n '1,220p' final_runs/run_<id>/final_script.py
```

For visual checks, use the `Read` tool on individual PNG files inside
`final_runs/run_<id>/screenshots/` rather than calling an external image-QA
service.
````

## File: skills/cuawright-web/reference/workflow.md
size: 4155
sha: 50fd005bbe70188074e5f9dc88bd6c6f5574e70d
upstream: https://github.com/microsoft/cuawright/blob/main/skills/cuawright-web/reference/workflow.md

````text
# Workflow

Detailed expansion of the six-step Webwright loop, adapted for Claude Code.
The original loop relied on `cuawright.webwright.tools.image_qa` for visual QA and
`cuawright.webwright.tools.self_reflection` for the final verdict. Both are replaced
here by your native abilities (`Read` on PNG files + reasoning against
`plan.md`). No `OPENAI_API_KEY` is required.

## 1. Plan

Parse the task into critical points (CPs) and write `WORKSPACE_DIR/plan.md`:

```markdown
# Task
<verbatim task description>

# Critical Points
- [ ] CP1: <constraint / filter / sort / selection / required datum>
- [ ] CP2: ...
```

Rules for CPs:

- One CP per independently verifiable requirement.
- Numeric, date, quantity, and unit CPs must be exact.
- Ranking CPs ("cheapest", "best-selling", "highest-rated", …) must
  reference the site's actual sort/filter control.
- If the task asks for a final datum, make it its own CP
  (e.g. `CP5: Record the displayed cheapest economy fare`).

## 2. Explore

Goal: discover stable selectors, confirm every required filter control
exists, and identify how to capture evidence for each CP.

- Run scratch Playwright scripts (see `playwright_patterns.md`) inside
  `WORKSPACE_DIR/`. Save scratch PNGs under `WORKSPACE_DIR/screenshots/`
  (separate from `final_runs/`).
- Print URL, title, and `aria_snapshot()` for the region of interest at
  every step.
- Use `Read` on saved PNGs to confirm UI state when ARIA evidence is
  ambiguous.
- If a filter looks unavailable, expand drawers / accordions / mobile
  filter panels and inspect again before concluding it doesn't exist.
- A search-box query never substitutes for a dedicated filter control.

## 3. Author `final_script.py`

Create a fresh `final_runs/run_<id>/` (use the next integer above any
existing `run_*`) and place `final_script.py` inside it. Instrument per
`playwright_patterns.md`:

- viewport 1280×1800, headless local Firefox, no `full_page`;
- one `final_execution_<step>_<action>.png` per CP;
- one `step <n> action: <reason and action>` log line per
  constraint-relevant interaction;
- the final datum printed into `final_script_log.txt` at the end.

Each screenshot should map to a CP from `plan.md` so verification is
trivial.

## 4. Execute

Run the script once. If it crashes, fix it inside the same run folder and
re-execute — but if a partial run already produced screenshots that don't
match the fixed flow, delete them so the run folder reflects a single
clean execution.

## 5. Self-verify (replaces `self_reflection`)

For every CP in `plan.md`:

1. Identify the screenshot(s) and/or log line that provide evidence.
2. `Read` each cited PNG.
3. Confirm the evidence is **unambiguous**:
   - Filter chip / selected state visibly applied (not hidden behind a
     closed drawer);
   - Numeric / date values match exactly (not broadened);
   - Sort applied via the site's control (not implied by result order);
   - Required submit / search / apply action visibly taken;
   - Final datum legibly displayed.
4. Tick the CP only when the evidence is concrete. Be harsh on partial,
   occluded, or ambiguous states.

If any CP fails, diagnose the *specific* issue — wrong filter value,
missing control, hidden chip, broadened range, missing confirmation,
missing screenshot, etc. Fix `final_script.py`, run it again inside
`final_runs/run_<id+1>/`, and re-verify against `plan.md`.

Empty result sets are acceptable when the correct filters were demonstrably
applied.

## 6. Done

Stop only when **all** of the following are true:

1. `plan.md` exists with every CP enumerated as a checklist item.
2. `final_runs/run_<id>/final_script.py` ran cleanly from scratch and
   produced `final_script_log.txt` plus all CP screenshots.
3. Every CP is checked off with a cited screenshot and/or log line.
4. The final datum (if the task asked for one) is reported to the user
   verbatim and is also present in `final_script_log.txt`.
5. `ls -R final_runs/run_<id>` and `cat final_runs/run_<id>/final_script_log.txt`
   show the expected artifacts.

If any of those is false, do not declare done — diagnose, fix, and re-run
in a new `run_<id+1>/`.
````

## File: README.md
upstream: https://github.com/microsoft/cuawright/blob/main/README.md

```text
# CUAWright

> **Webwright is now CUAWright.** Alongside browser automation, you can now run
> desktop tasks in an Ubuntu VM. Use `cuawright web` for browser tasks and
> `cuawright desktop` for desktop tasks. Existing `webwright` commands and Python
> imports still work.

<p align="center">
  <img src="assets/cuawright_logo.svg" alt="CUAWright logo" width="320">
</p>

<p align="center"><b>Turn coding models into browser and desktop agents</b></p>

<p align="center">
  <img src="https://img.shields.io/badge/python-%E2%89%A53.10-blue?logo=python&logoColor=white" alt="Python">
  <img src="https://img.shields.io/badge/playwright-chromium-green" alt="Playwright">
  <img src="https://img.shields.io/badge/backends-OpenAI%20%7C%20Anthropic%20%7C%20OpenRouter-orange" alt="Backends">
</p>

- 📄 **Paper:** [CUAWright: A Minimal Unified Interface for Digital Agents](https://arxiv.org/abs/2610.04116)
- 📝 **Blog:** [Webwright: A Terminal Is All You Need For Web Agents](https://www.microsoft.com/en-us/research/articles/webwright-a-terminal-is-all-you-need-for-web-agents/)
- 🌐 **Project Page:** [microsoft.github.io/CUAWright](https://microsoft.github.io/CUAWright/)

CUAWright gives coding models a terminal to automate browsers and desktop applications.
Use Webwright to browse the web and build reusable Playwright scripts, or run your
own desktop task and reproduce OSWorld-V2 benchmarks in an Ubuntu VM.

Start with the [browser quick start](#-browser-quick-start) or
[desktop quick start](#desktop-quick-start).

Already got your favorite agents, and wonder how to make Claude Code, Codex, Hermes more capable in browser tasks? Consider adding [CUAWright browser plugin/skill](#-use-as-a-plugin)!

---

## 📰 News

- **2026-10-03** — **Webwright → CUAWright:** renamed the project to bring browser and desktop agents together. The Webwright browser runtime is now `cuawright.webwright`, and OSWorld desktop support lives at `cuawright.desktop`. Existing `webwright` commands and imports remain compatible. See [desktop setup](docs/desktop.md).
- **2026-09-01** — Persistent step-by-step browsing and native `run_command` tool calls improve performance to **88.1% on Online-Mind2Web** and **77.5% on Odysseys**.
- **2026-07-21** — Skill Factory: every solve leaves a script behind, distilled into reusable, verified, parameterized code skills that rerun standalone with no model (~40 s, zero tokens). On WebArena, reuse lifts held-out accuracy 55% → 70% (+15 pp). See the optional [Skill Factory](#-skill-factory-turn-solved-tasks-into-runnable-code-skills).
- **2026-05-11** — Support Task2UI mode: Webwright completes the task and renders task results into an HTML-based web app you can easily view and reuse.  
- **2026-05-06** — Codex and Claude Code plugin manifests added; install via `/plugin install cuawright@cuawright`. Hermes Agent integration shipped; the same `skills/cuawright-web/` folder now loads across Claude Code, Codex, and Hermes.
- **2026-05-04** — Initial public release: ~1.5k LoC, OpenAI / Anthropic / OpenRouter backends, Playwright environment.

---

<details>
<summary><strong>💡 Motivation: Beyond Step-by-Step Web Interaction in a Stateful Browser</strong></summary>

Most web agents today treat the browser session itself as the workspace: at each step the model receives the current page state and predicts a single next operation — a click, a type, a DOM selector, or a short tool call. Whatever the format, the agent is locked into predicting one web action at a time inside a predefined interaction loop. That harness was useful when LLMs were weaker. As models get stronger at writing and debugging code, the same harness becomes a bottleneck.

Webwright takes a different stance: **separate the agent from the browser**, and treat the browser as something the agent can launch, inspect, and discard while developing a program. The persistent artifact is not the browser session — it's the **code and logs in the local workspace**.

- 🧱 **Robust, reusable interaction with web environments** — instead of fragile pixel-level actions, a coding agent with a terminal queries elements, waits for conditions, and handles dynamic behaviors like lazy loading or re-rendering. The resulting scripts can be rerun, adapted, and shared across tasks rather than rediscovered from scratch.
- ⚡ **Efficient composition of complex workflows** — multi-step interactions like selecting a date or filling a form become a compact program. Loops, functions, and abstractions let the agent generalize across similar tasks (e.g. different dates) without re-predicting the same low-level sequences. Fewer interaction rounds, faster execution, less error accumulation on long horizons.
- 🧪 **Workspace-as-state, not browser-as-state** — the agent can write exploratory scripts, spawn fresh browser sessions, and decide for itself when to capture screenshots and inspect failures, much like a human engineer iterating on an RPA script.
- 🪄 **Surprisingly effective despite being minimal** — this stripped-down setup turns out to handle complex and especially long-horizon web tasks well (see [Performance](#-performance)).

</details>

---

<details>
<summary><strong>🌟 Why Webwright</strong></summary>

Most web agent frameworks bury the actual agent loop under layers of abstractions. Webwright takes the opposite stance:

- 🪶 **Readable core** — browser agent loop, environments, models, and CLI are separate modules under `src/cuawright/webwright/`.
- 🧩 **Pluggable model backends** — OpenAI, Anthropic, and OpenRouter, each ~150–200 lines.
- 🔍 **Zero hidden frameworks** — just `httpx`, `pydantic`, `playwright`, and `typer`.
- 🔁 **Flat prompt → observe → execute script loop** — readable end-to-end, easy to debug, easy to fork.
- 🧪 **Run-artifact first** — every run writes trajectories and screenshots to disk for inspection.

If you want a minimal, easy-to-debug starting point for browser-using agents instead of another heavyweight platform, this is it.

</details>

---

<details>
<summary><strong>🆚 How Webwright Differs From Other Browser-Agent Repos</strong></summary>

How they differ at the architectural level:

|                     | **Stagehand (Browserbase)**                                  | **agent-browser (Vercel)**                                                | **browser-use**                                       | **Webwright**                                                       |
| ------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------- |
| **Paradigm**        | Hybrid: code + NL primitives (`act` / `extract` / `agent`)   | CLI tool that *another* agent (Claude Code, Codex, etc.) calls            | Autonomous LLM agent loop over DOM/AX snapshots       | **Coding agent with a terminal**; browser is just an environment it spawns |
| **Action space**    | Playwright code, or NL → LLM-translated Playwright           | Discrete subcommands (`open`, `click @e2`, `snapshot`, `eval`)            | Indexed click/type actions selected by the LLM        | **Free-form Python (writes Playwright scripts itself)**                       |
| **What is "state"?**| The browser session                                          | The browser session (held by daemon across CLI calls)                     | The browser session                                   | **The local workspace — code, screenshots, logs.** Browser is disposable. |
| **Loop shape**      | Imperative; `agent()` does multi-step when needed            | One CLI invocation per micro-step                                         | observe → predict next action → execute → repeat      | write code → execute → inspect screenshots → repair (code-as-action)      |
</details>

---

## 🎥 Demo

**CUAWright demo**

https://github.com/user-attachments/
```
