@qawolf/cli 1.26.0 → 1.28.0

package/dist/types/runnerSdk/index.d.ts

@@ -10,7 +10,7 @@ export declare function createRunnerSdk(options: RunnerSdkOptions): {
     list(): Promise<SdkResult<ListedRunner[]>>;
     evaluateSnippet({ runnerId, scope, source, }: import("./types.js").EvaluateSnippetRequest): Promise<SdkResult<import("./types.js").EvaluatedSnippet>>;
     importPackage({ name, runnerId, version, }: import("./types.js").ImportPackageRequest): Promise<SdkResult<import("./types.js").ImportedPackage>>;
-    act({ action, runnerId, }: import("./types.js").ActRequest): Promise<SdkResult<import("./types.js").PerformedAction>>;
+    act({ action, runnerId, withScreenshot, }: import("./types.js").ActRequest): Promise<SdkResult<import("./types.js").PerformedAction>>;
     highlightSelector({ highlight, runnerId, }: import("./types.js").HighlightSelectorRequest): Promise<SdkResult<import("./types.js").HighlightedSelector>>;
     inspect({ request, runnerId, }: import("./types.js").InspectRequest): Promise<SdkResult<import("./types.js").Inspected>>;
     promoteSnapshot({ baselinePath, runnerId, screenshotPath, }: import("./types.js").PromoteSnapshotRequest): Promise<SdkResult<import("./types.js").PromotedSnapshot>>;

package/dist/types/runnerSdk/types.d.ts

@@ -66,6 +66,13 @@ export type EventsRequest = RunnerRequest & {
 };
 export type ActRequest = RunnerRequest & {
     action: BrowserAction;
+    /**
+     * Ask the runner to answer with a screenshot taken after the action, on
+     * `imageJpegBase64`. One call instead of an act and a screenshot, with no
+     * fixed wait between them. An action that did not take effect answers with
+     * one too, and the screen can be absent even when asked for.
+     */
+    withScreenshot?: boolean;
 };
 export type EvaluateSnippetRequest = RunnerRequest & {
     scope: SnippetScope;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qawolf/cli",
-  "version": "1.26.0",
+  "version": "1.28.0",
   "description": "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   "keywords": [
     "automation",
@@ -71,7 +71,7 @@
     "@clack/prompts": "1.5.1",
     "@napi-rs/keyring": "1.3.0",
     "@oxc-node/core": "0.1.0",
-    "@qawolf/api-contracts": "0.52.0",
+    "@qawolf/api-contracts": "0.53.0",
     "@qawolf/emails": "1.1.1",
     "@qawolf/flow-targets": "1.0.0",
     "@qawolf/flows": "0.1.4",

package/skills/qawolf-cli/SKILL.md

@@ -125,7 +125,7 @@ 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 | 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 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. Pass the nextCursor from one response as the cursor on the next check; it then reads only what is new, and only for the session that minted it. Continue monitoring silently when the status is unchanged and no replies come back; 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 |
@@ -139,7 +139,7 @@ that `url`; never guess a route and never send a repository link in its place.
 | `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 create` | write | Create an environment on the caller's team and return it in the environment.get shape. This can also create a branch on the team's connected Git provider. |
 | `qawolf environment deleteVariable` | write | Remove one environment variable by name. Succeeds whether or not the variable existed. |
 | `qawolf environment find` | read | List the team's environments, newest first. |
 | `qawolf environment get` | read | Read a single environment's name, kind, standing run health, flow-code branch and reconciliation state, run concurrency limit, and termination state. If flowCodeBranch exists, use its syncStatus for Git reconciliation and read lastSyncedCommitHash only when syncStatus is reconciled. |
@@ -147,6 +147,8 @@ that `url`; never guess a route and never send a repository link in its place.
 | `qawolf environment listVariableNames` | read | Use this to answer which QA Wolf environment variables are available to test code. Returns names only; values never leave the server. |
 | `qawolf environment setVariable` | write | Create or replace an environment variable. If the user asks to create one for "my email" without naming it, use DEFAULT_EMAIL. The value is never returned. |
 | `qawolf environment update` | write | Update an environment owned by the caller's team and return it in the environment.get shape. Omitted fields remain unchanged. |
+| `qawolf file requestDownload` | read | Get a URL for reading a file out of the caller's team storage. Answers 404 when nothing is stored at that path. |
+| `qawolf file requestUpload` | write | Get a URL to put a file into team storage: a spreadsheet of journeys, anything too large to paste. PUT with the returned contentType, then name the path in filePaths. |
 | `qawolf flow addTag` | write | Assign an existing tag to the selected flows. Create tags with tag.create. Flows that already carry the tag are reported in skippedFlows. |
 | `qawolf flow removeTag` | write | Remove a tag from the selected flows. Succeeds whether or not each flow carried the tag; the flows that did not are reported in skippedFlows. |
 | `qawolf flow update` | write | Move a flow between draft and active readiness. The other statuses shown in the app are derived and cannot be set. |
@@ -169,7 +171,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 run stop` | write | Stop a run, including its queued flows and automatic retries. Stopping is asynchronous and can update run-status messages and commit statuses in connected integrations. 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 |
@@ -187,11 +189,18 @@ 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. |
 | `qawolf tag list` | read | List the team's tags, alphabetical by name. Tag names select flows in run.create. |
+| `qawolf trigger create` | write | Create a trigger. A schedule trigger runs a named set of flows on a cadence; a deployment trigger runs when a matching deployment is reported. |
+| `qawolf trigger delete` | write | Delete a trigger permanently. The runs it already created are kept. To stop a trigger without losing it, use trigger.pause. |
+| `qawolf trigger find` | read | List the team's triggers, newest first. |
+| `qawolf trigger get` | read | Get one trigger by id. |
+| `qawolf trigger pause` | write | Pause a trigger so it stops firing. Pausing is idempotent. A team whose triggers are all paused reports no trigger activity at all. |
+| `qawolf trigger resume` | write | Resume a paused trigger. A schedule trigger restarts from the next upcoming slot: the slots it missed while paused do not run. |
+| `qawolf trigger update` | write | Replace a trigger's configuration. Every field is written, so read the trigger first and send its configuration back with your changes applied. Pausing is separate: use trigger.pause and trigger.resume. |
 
 <!-- commands-table:end -->
 
@@ -210,6 +219,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