@qawolf/cli 1.29.0 → 1.31.0

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

@@ -11,6 +11,12 @@ export type RunnerSdkOptions = {
 };
 export type SdkResult<Value> = {
     error: string;
+    /**
+     * What the platform said beyond the headline, and what to do about it:
+     * the reason a runner is gone, which of `--runner`, `QAWOLF_RUNNER_ID` or
+     * the stored default named it, the command that brings one back.
+     */
+    errorDetail?: string;
     ok: false;
 } | {
     ok: true;
@@ -124,6 +130,8 @@ export type ListedRunner = {
     isDefault: boolean;
     launchedHere: boolean;
     runnerName: string;
+    /** The QA Wolf page for this runner, showing its screen once it has one. */
+    url: string;
 };
 export type KeptAlive = {
     id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qawolf/cli",
-  "version": "1.29.0",
+  "version": "1.31.0",
   "description": "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   "keywords": [
     "automation",
@@ -75,7 +75,7 @@
     "@qawolf/emails": "1.1.1",
     "@qawolf/flow-targets": "1.0.0",
     "@qawolf/flows": "0.1.4",
-    "@qawolf/testkit": "1.1.1",
+    "@qawolf/testkit": "1.2.1",
     "commander": "14.0.3",
     "env-paths": "4.0.0",
     "picomatch": "4.0.4",

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 | 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 agent get` | read | Read what the QA Wolf AI has said and whether it is still working |
+| `qawolf agent send` | write | Ask the QA Wolf AI to do a piece of work, such as covering a journey or fixing a broken flow |
 | `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 |
@@ -209,6 +209,60 @@ changes team state; `local` only affects this machine. A parenthesized
 note like `local (read with --remote)` means that flag makes the command
 call the QA Wolf API and require auth.
 
+## Asking QA Wolf to do the work: the `agent` group
+
+`qawolf agent send "<what you want>"` is the one verb that starts work from
+nothing. Every other write acts on a flow, run or issue that already exists.
+Name the journey, the part of the app it covers, and anything the AI cannot
+discover for itself, such as a test account, a feature flag, or how to reach a
+staging environment. For a long message, put it in a file and pass
+`"$(cat prompt.md)"`, so shell quoting cannot split it into arguments.
+
+`--environment-id <id-or-alias>` picks the environment and reads
+`QAWOLF_ENVIRONMENT`. A credential that is not bound to one workspace, such as
+an organization or user API key, needs `--workspace-id`.
+
+To give the AI a file, such as a spreadsheet of journeys, upload it first with
+`qawolf file requestUpload --file-name <name>`, PUT the bytes to the returned
+URL with the returned content type, then pass the returned path as
+`--file-paths <path>` on the send. The AI reads it from storage, so a plan of
+hundreds of journeys costs nothing to send. Up to 20 paths per send.
+
+The work runs for minutes to tens of minutes. **Pass `--follow` and do not poll.**
+The CLI reads the session for you, prints each reply once as it arrives, and
+exits when the session settles: 0 when the work is complete, non-zero when it
+failed or was cancelled. Looping `qawolf agent get` yourself costs a round trip
+per tick and shows you replies you have already seen.
+
+A session can stop and ask a question. With `--follow` in `--agent` or `--json`
+mode the CLI prints the question and **exits 0** — a session that asked something
+has handed the work back, it has not failed. Answer it, then pick the session
+back up:
+
+```bash
+qawolf agent send "<your answer>" --session <sessionId>
+qawolf agent get --follow
+```
+
+In `--agent` or `--json` mode a follow ends with one JSON line holding the whole
+session: `sessionId`, `status`, `url` and `replies`. It is the same object a
+plain `qawolf agent get` answers with. Read the final `status` from that line;
+the exit code alone does not tell a blocked session from a completed one.
+
+`agent send` remembers the session it started, so a later `agent get --follow`
+in the same directory needs no id. `--session <id>` or `QAWOLF_SESSION_ID`
+override that.
+
+Every session has a `url`, which the CLI prints when it starts or attaches.
+A session opens in whichever workspace the credential is pointed at, which is not
+always the one the user has open in the app, so send that `url` when you report
+on a session rather than describing where it went.
+
+Expect quiet stretches. QA Wolf reports a session as working and says nothing
+more until the AI speaks, so several minutes with no output is the session
+working, not the command hanging. `--timeout` bounds the wait; it is 30 minutes
+by default.
+
 ## Driving a browser: the `runner` group
 
 The `runner` commands drive a live cloud browser: `launch` one, `screenshot` to

package/skills/qawolf-cli/references/run-results.md

@@ -25,6 +25,14 @@ run
 `runId` in the response is canonical and can differ from the id you asked for.
 Use the returned value for follow-up calls.
 
+`run get` resolves platform runs only. A run id printed by `qawolf runner run`
+belongs to that runner, so `run get` answers exit `8` and no such run on this
+team. Read one of those with `qawolf runner events run-status --run <id>`.
+
+A run that has been requested but not yet created answers exit `8` too, and
+says it is still being created. That one clears on its own, so read the message
+rather than the code before deciding whether to poll.
+
 Poll `status` until it reaches `passed`, `failed` or `canceled`. The other
 values mean the run is still going.
 

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

@@ -13,6 +13,8 @@ of starting and billing a second one, and the answer says which happened: read
 cheap and safe pattern, and the same id with a different `--name` is refused
 rather than silently ignored.
 
+Either answer carries a `url`, which `qawolf runner launch` prints, as does a command that launched its own runner. It is a QA Wolf page showing what the runner is doing, where a person can also take over with their own mouse and keyboard. Hand it to a person who asks what your runner is up to. The page opens for anyone on the runner's team, however the runner was launched. There is nothing to see until the runner's first run starts its screen, so the page waits until then. You read the screen with `screenshot`, not with the page.
+
 Commands that target a runner find one in this order: `--runner`, then
 `QAWOLF_RUNNER_ID`, then the runner stored for the current directory (which
 `qawolf runner launch` sets). Setting the environment variable once is the most
@@ -28,8 +30,8 @@ then launched without `--id` ends up with a pod it is not addressing. Pass
 And a runner id that is set is treated as found, whether or not anything is
 running under it. So exporting `QAWOLF_RUNNER_ID=agent-1` turns off the
 auto-launch described next: instead of starting `agent-1`, commands try to reach
-it and fail with exit code `4`, which reads as "retry" and never succeeds.
-Launch that id once yourself and the rest follows.
+it and fail with exit code `8`, naming the id and saying the variable is what
+chose it. Launch that id once yourself and the rest follows.
 
 And launching an id that differs from `QAWOLF_RUNNER_ID` prints a warning on
 stderr naming both ids: the variable still outranks the directory default, so
@@ -83,6 +85,12 @@ directory did not launch it, so a harness handed a runner sees it alongside the
 ones it started itself. Use the `id` column with `--runner` to address any of
 them; addressing one does not make it the default.
 
+The table leaves out the page address, which beside a 63-character id outgrows a terminal. `--json` carries it as `url` on every runner:
+
+```sh
+qawolf runner list --json | jq -r '.[] | [.id, .url] | @tsv'
+```
+
 ## The order that matters
 
 A freshly launched runner has no screen. The virtual desktop starts with the
@@ -111,11 +119,14 @@ and says so on stderr. Everything else on this page waits for a run.
 
 Retry on the exit code, not on the message text:
 
-- `4` is usually transient. The screen is up but cannot serve this instant:
-  restarting after a display-size change, or busy with another request. Retry in
-  a second or two — but bound the retries, because `4` also covers a runner that
-  was reaped after inactivity, which no amount of retrying brings back. If `4`
-  persists past a few tries, relaunch the id.
+- `4` is transient. The screen is up but cannot serve this instant: restarting
+  after a display-size change, or busy with another request. Retry in a second
+  or two, and bound the retries.
+- `8` means there is no such runner. It was never launched, or it was
+  terminated, or it idled out. Retrying never brings one back, so stop and
+  launch the id or name one that is running. The message says which runner was
+  meant and whether `--runner`, `QAWOLF_RUNNER_ID` or this directory's stored
+  default chose it — read that line before you pick an id to launch.
 - `2` will not clear on its own. Either nothing has run on this runner yet, so
   run a flow, or the runner has no browser at all, so launch with
   `--name playwright` instead. The message says which.
@@ -216,7 +227,8 @@ what the page shows.
 One failure covers three causes, because a runner cannot tell them apart: no
 live page, no element matching the selector, no variable under that name. All
 three exit `2` and none clears by waiting, so read the message, which carries
-whatever the runner said. An unreachable runner exits `4` and is worth retrying.
+whatever the runner said. An unreachable runner exits `4` and is worth retrying;
+a runner that is not running at all exits `8` and is not.
 
 Use `inspect` before reaching for `exec`. Reading a value through a snippet
 means printing it and then fishing it back out of the `console` stream, which is
@@ -586,7 +598,7 @@ the screen, so it is not optional even though the goal here is to drive by hand.
 export QAWOLF_API_KEY=...          # the only credential
 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 launch --id agent-1 --json          # --id, not the variable; read .alreadyRunning and .url
 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 --screenshot step-1.jpg   # then read step-1.jpg yourself