@qawolf/cli 1.25.0 → 1.27.0

package/skills/qawolf-cli/SKILL.md

@@ -125,8 +125,8 @@ that `url`; never guess a route and never send a repository link in its place.
 <!-- prettier-ignore -->
 | Command | Kind | What it does |
 | --- | --- | --- |
-| `qawolf agent get` | read | Read what the QA Wolf AI has said and whether it is still working. Poll this after agent.send until the status settles. A status of "waiting-for-you" means the last reply is a question the work is blocked on, and answering it with agent.send is what unblocks it. Replies accumulate, so a caller that polls repeatedly sees the earlier ones again. |
-| `qawolf agent send` | write | Ask the QA Wolf AI to do a piece of work in plain language, such as covering a user journey, investigating a failing run, or fixing a broken flow. This is the one verb that starts work from nothing: every other write acts on a flow, run or issue that already exists. Answers as soon as the request is accepted, with the id to follow it by, because the work runs for minutes to tens of minutes. Poll agent.get for progress, and send here again to answer a question or add context to work already running. |
+| `qawolf agent get` | read | Monitor a QA Wolf AI session by reading its status and replies. After agent.send, share the returned session URL before monitoring. Wait 30 to 60 seconds between checks; do not call this in a tight loop. Replies accumulate, so compare them with what you have already seen. Continue monitoring silently when the status and replies are unchanged; do not narrate waiting, announce the next check, or ask whether to keep monitoring. Report only substantive new progress, questions, blockers, or the final outcome. A status of "waiting-for-you" means the last reply is a question the work is blocked on, and answering it with agent.send is what unblocks it. Surface an explicit request for user input even if the status still says "working". Include the session URL when reporting a blocker or final outcome. On "completed", stop status checks and verify the requested result before claiming success. For new flows, validation, publication in the target environment, and readiness are separate checks; a Git push or final reply does not prove the flow is active. If every requested result is verified but status remains "working", report the mismatch and stop monitoring. Stop on "failed" or "cancelled" and report any confirmed partial result. |
+| `qawolf agent send` | write | Start or continue work with the QA Wolf AI and return a live session URL to share with the user. Use it to cover a user journey, investigate a failing run, or fix a broken flow. This is the one verb that starts work from nothing: every other write acts on a flow, run or issue that already exists. Returns sessionId, status, and url as soon as the request is accepted; work can take minutes to tens of minutes. After each send, make the next action a normal user-visible assistant message containing the exact returned url, before any tool call or wait. Tool output and internal reasoning do not count as sharing the link. Do not run a timer or monitoring call alongside this send. Acceptance does not mean the work is complete. Then monitor the session with agent.get, reporting new progress, blockers, and the final outcome rather than unchanged status. Send here again to answer a question or add context to the same session. |
 | `qawolf auth login` | local | Authenticate with QA Wolf in a browser or with an API key |
 | `qawolf auth logout` | local | Remove stored credentials |
 | `qawolf auth switch` | local | Choose which workspace to work in |
@@ -137,6 +137,7 @@ that `url`; never guess a route and never send a repository link in its place.
 | `qawolf email get` | read | Read one email of the workspace, with its plain text and HTML bodies. Use it to pull a sign-in code or a verification link out of a message. |
 | `qawolf email getAttachment` | read | Read one attachment of a workspace email as base64 content, by file name or by position. email.get lists both. |
 | `qawolf email listAddresses` | read | List the workspace's inbox addresses, alphabetical. A flow can sign up with a plus-suffixed form of any of them, and email.find reads what arrives. |
+| `qawolf email registerAddress` | write | Register an inbox address for the workspace. Registering an address the workspace already has changes nothing. A refusal names the domains the workspace can use. |
 | `qawolf email send` | write | Send an email from one of the workspace's inbox addresses, for example to exercise a flow that reacts to incoming mail. Returns the sent email; read it back with email.get. |
 | `qawolf environment create` | write | Create an environment on the caller's team and return it in the environment.get shape. |
 | `qawolf environment deleteVariable` | write | Remove one environment variable by name. Succeeds whether or not the variable existed. |
@@ -168,6 +169,7 @@ that `url`; never guess a route and never send a repository link in its place.
 | `qawolf run find` | read | List an environment's recent runs, newest first. |
 | `qawolf run get` | read | Get a run's status, per-flow results, and links. |
 | `qawolf run reattempt` | write | Request new attempts for a run's flows, in the same run. A flow is eligible once its result is failed or canceled and QA Wolf's automatic retries have finished. A fully investigated run no longer accepts reattempts. Attempts run with the latest flow code. Poll run.get for results. |
+| `qawolf run stop` | write | Stop a run, including its queued flows and automatic retries. Stopping is asynchronous. Repeated requests are safe, and finished runs keep their results. A run that is still being created returns not found; retry once run.get returns the run. If run.get returns a different runId, use that ID. Poll run.get for results. |
 | `qawolf runner act` | write | Perform one raw action on a runner's screen: click, double_click, scroll, move, drag, keypress, navigate or type. Use - to read a whole action as JSON from stdin. On a mobile runner only click (button left), drag and type have a touchscreen equivalent; the rest answer action-not-supported-on-mobile |
 | `qawolf runner events` | read | Print a runner's journal, one entry per line. QA Wolf writes console, recorder, run-events, run-logs, run-status |
 | `qawolf runner exec` | write | Evaluate a snippet against a runner's live page. Use - to read the snippet from stdin |
@@ -185,7 +187,7 @@ that `url`; never guess a route and never send a repository link in its place.
 | `qawolf runner list` | read | List the runners running on your team |
 | `qawolf runner promote-snapshot` | write | Accept a run's screenshot as the new baseline for an image diff, on the runner that produced it |
 | `qawolf runner run` | write | Run a flow on an interactive runner, shipping the flow and what it imports |
-| `qawolf runner screenshot` | read | Save a JPEG of an interactive runner's screen to a file |
+| `qawolf runner screenshot` | read | Save a JPEG of an interactive runner's screen to a file, or write it to stdout with --out - |
 | `qawolf runner stop-run` | write | Stop what a runner is currently executing, leaving the runner up |
 | `qawolf runner terminate` | write | End an interactive runner, and the pod it runs on with it |
 | `qawolf tag create` | write | Create a tag on the caller's team. Tags select flows in run.create. |
@@ -208,6 +210,12 @@ your actions into Playwright locators), `keepalive` to hold it open, and
 when done. Everything is a plain request to one host, so a shell with an API key
 and its own vision model can close the see-and-act loop with no other tooling.
 
+When an action is followed by a look at the result, which in a see-and-act loop
+is every action, pass `--screenshot <path>` to `act` (or `-` for stdout) instead
+of calling `act` and then `screenshot`. One call performs the action and writes
+the screen the runner answers with: half the calls per step, and no delay to
+guess at between them.
+
 The full workflow is its own guide: how a runner is billed, why the first call
 must be a run, the order the commands go in, the see-and-act loop, `exec`, the
 recorder, reading history, staying alive, and an end-to-end example. **Read

package/skills/qawolf-cli/references/runner.md

@@ -127,7 +127,10 @@ vision loop on this surface.
 
 `qawolf runner screenshot --out page.jpg` writes a real JPEG to disk, decoded,
 because every coding harness can open an image file. Read it with whatever
-vision you have.
+vision you have. `--out -` writes the JPEG bytes to stdout instead, on their own,
+for a caller that is a process rather than an agent: the confirmation, and the
+JSON line under `--json`, goes to stderr so nothing follows the image on stdout.
+A terminal on stdout is refused: redirect or pipe it.
 
 `qawolf runner act <action>` performs exactly one action per call, in the
 computer-use tool vocabulary a vision model already emits: `click`,
@@ -139,6 +142,19 @@ can forward a tool call rather than translate it:
 echo '{"type":"click","button":"left","x":480,"y":260}' | qawolf runner act -
 ```
 
+Every action in a see-and-act loop is followed by a look at the result, so ask
+for it in the same call: `act ... --screenshot step-1.jpg` (or `--screenshot -`
+for stdout) performs the action and writes the screen the runner answers with.
+Prefer it over `act` and then `screenshot`: each step is one call instead of
+two, with no delay to guess at between them. The screen the runner answers with
+is taken once it has changed from just before the action or half a second has
+passed, whichever comes first. An action that reached the screen and did not
+take effect answers with one too, so a `1` from `act --screenshot` still leaves
+you a picture of why the click missed. A `4` whose message starts with
+"Performed" means the action happened and only the picture is missing: take a
+`screenshot`, never send the action again to get it. As with
+`screenshot --out -`, a terminal on stdout is refused.
+
 Coordinates are pixels on the same screenshot you just read. The runner serves
 one see-or-act request at a time, so decide what to do next from each answer
 rather than firing several. Bounds are checked before anything is sent, so an
@@ -565,10 +581,9 @@ export QAWOLF_RUNNER_ID=agent-1    # so no command below needs --runner
 qawolf runner launch --id agent-1 --json          # --id, not the variable; read .alreadyRunning
 qawolf runner run flows/smoke.flow.ts --follow    # starts the screen; exit 1 if it failed
 
-qawolf runner act navigate --url https://example.com/login
-qawolf runner screenshot --out page.jpg           # then read page.jpg yourself
-qawolf runner act click --button left --x 480 --y 260
-qawolf runner act type --text "someone@example.com"
+qawolf runner act navigate --url https://example.com/login --screenshot step-1.jpg   # then read step-1.jpg yourself
+qawolf runner act click --button left --x 480 --y 260 --screenshot step-2.jpg
+qawolf runner act type --text "someone@example.com" --screenshot step-3.jpg
 
 qawolf runner inspect element-html --selector "#email"
 qawolf runner inspect variable --name cart | jq .total