@qawolf/cli 1.29.0 → 1.30.0

package/dist/runner-sdk.js

@@ -9463,15 +9463,14 @@ var makeContractsV1 = (ids) => {
 };
 var publicContractsV1 = makeContractsV1(defaultIdSchemas);
 
-// src/core/pluralize.ts
-function pluralize(count, singular, plural = `${singular}s`) {
-  return `${String(count)} ${count === 1 ? singular : plural}`;
-}
-
 // src/core/formatSeconds.ts
 function formatSeconds(ms) {
   return `${Math.round(ms / 1000)}s`;
 }
+// src/core/pluralize.ts
+function pluralize(count, singular, plural = `${singular}s`) {
+  return `${String(count)} ${count === 1 ? singular : plural}`;
+}
 
 // src/core/messages/authErrors.ts
 var authErrorMessages = {
@@ -9665,7 +9664,7 @@ var flowsMessages = {
     extractingBundle: "Extracting bundle",
     downloadingTeamStorageAssets: "Downloading team-storage assets",
     downloadingTeamStorageAssetsProgress: (current, total) => `Downloading team-storage assets (${String(current)}/${String(total)})`,
-    teamStorageRequiresTeamKey: "Team storage requires a team API key; organization keys are not supported here.",
+    teamStorageRequiresTeam: "Team storage needs a team. Pull an environment to name its team, choose a workspace with 'qawolf auth switch', or use a team API key.",
     summary: (result, assetsAbs) => {
       const flows = pluralize(result.flowCount, "flow");
       const envVars = result.envVarCount === 0 ? "" : ` and ${pluralize(result.envVarCount, "environment variable")}`;
@@ -9815,17 +9814,18 @@ var interactMessages = {
 };
 
 // src/core/messages/interactiveRunner/lifecycle.ts
+var pageAt = (url) => `Its runner page is at ${url}`;
 var noRunnerId = "No runner id. Pass --runner, set QAWOLF_RUNNER_ID, or run qawolf runner launch first.";
 var lifecycleMessages = {
-  alreadyRunning: (id) => `Runner ${id} was already running.`,
+  alreadyRunning: (id, url) => `Runner ${id} was already running. ${pageAt(url)}`,
   defaultNotRemembered: (id) => `Runner ${id} could not be written to .qawolf as this directory's default, so later commands will not find it on their own. Pass --runner ${id}, or set QAWOLF_RUNNER_ID=${id}.`,
   defaultNotForgotten: (id) => `Runner ${id} was terminated, but it could not be removed from .qawolf as this directory's default, so later commands will still be sent to it. Pass --runner, or launch a new runner.`,
   envRunnerIdShadowsLaunch: (launchedId, envId) => `QAWOLF_RUNNER_ID=${envId} is still set, so commands that omit --runner will keep targeting it instead of the runner just launched. Pass --runner ${launchedId} to address this one.`,
   keptAlive: (id) => `Runner ${id} is alive, and its inactivity clock has been reset.`,
   launchFailed: (id, error) => `Launching runner ${id} failed. ${error}`,
   launchLost: (id, error) => `Launching runner ${id} failed. ${error}. The request may still have reached QA Wolf and started a runner, so relaunch the same id with qawolf runner launch --id ${id} to attach to it rather than start a second one, or terminate it with qawolf runner terminate --runner ${id}.`,
-  launched: (id) => `Launched runner ${id}.`,
-  launchedForCommand: (id) => `No runner was given, so launched ${id} for this command. Its browser is fresh: nothing has been run on it and nothing is signed in. It bills until it is terminated or idles out, so terminate it with qawolf runner terminate --runner ${id} when you are done.`,
+  launched: (id, url) => `Launched runner ${id}. ${pageAt(url)}`,
+  launchedForCommand: (id, url) => `No runner was given, so launched ${id} for this command. Its browser is fresh: nothing has been run on it and nothing is signed in. It bills until it is terminated or idles out, so terminate it with qawolf runner terminate --runner ${id} when you are done. ${pageAt(url)}`,
   noRunnerIdForImport: `${noRunnerId} An install also needs a live run to go into, which a runner gets from qawolf runner run.`,
   noRunnerIdForHighlight: `${noRunnerId} Highlighting also needs a live page to draw on, which a runner gets from its first run: run a flow on it with qawolf runner run.`,
   noRunnerIdForInspect: `${noRunnerId} Inspecting also needs a page, which a runner gets from its first run: run a flow on it with qawolf runner run.`,
@@ -10017,7 +10017,8 @@ async function listRunners(ctx, deps) {
     id: runner.id,
     isDefault: runner.id === defaultRunnerId,
     launchedHere: heldIds.has(runner.id),
-    runnerName: runner.runnerName
+    runnerName: runner.runnerName,
+    url: runner.url
   }));
   return {
     items: items.sort((left, right) => rank(left) - rank(right) || left.id.localeCompare(right.id)),
@@ -11057,6 +11058,37 @@ import { join as join3 } from "node:path";
 var qawolfDir = ".qawolf";
 var defaultOutputDir = `${qawolfDir}/output`;
 
+// src/core/parseJson.ts
+function parseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return;
+  }
+}
+
+// src/shell/jsonFile.ts
+var pendingWrites = 0;
+async function readJsonFile(fs, path, schema) {
+  const contents = await fs.readFile(path).catch(() => {
+    return;
+  });
+  if (contents === undefined)
+    return;
+  const parsed = schema.safeParse(parseJson(contents));
+  return parsed.success ? parsed.data : undefined;
+}
+async function writeJsonFileAtomically(fs, path, value) {
+  const pendingPath = `${path}.${String(process.pid)}.${String(++pendingWrites)}.tmp`;
+  try {
+    await fs.writeFile(pendingPath, `${JSON.stringify(value, undefined, 2)}
+`);
+    await fs.rename(pendingPath, path);
+  } finally {
+    await fs.rm(pendingPath, { force: true }).catch(() => {});
+  }
+}
+
 // src/shell/interactiveRunner/runFilesManifest.ts
 var manifestFileName = "runner-files.json";
 var manifestSchema = object({
@@ -11067,33 +11099,14 @@ var manifestSchema = object({
 function makeRunFilesManifestStore(options) {
   const directory = join3(options.cwd, qawolfDir);
   const path = join3(directory, manifestFileName);
-  let pendingWrites = 0;
   return {
-    async read() {
-      const contents = await options.fs.readFile(path).catch(() => {
-        return;
-      });
-      if (contents === undefined)
-        return;
-      const parsed = manifestSchema.safeParse(parseJson(contents));
-      return parsed.success ? parsed.data : undefined;
-    },
+    read: () => readJsonFile(options.fs, path, manifestSchema),
     async write(manifest) {
-      const pendingPath = `${path}.${String(process.pid)}.${String(++pendingWrites)}.tmp`;
       await options.fs.mkdir(directory, { recursive: true });
-      await options.fs.writeFile(pendingPath, `${JSON.stringify(manifest, undefined, 2)}
-`);
-      await options.fs.rename(pendingPath, path);
+      await writeJsonFileAtomically(options.fs, path, manifest);
     }
   };
 }
-function parseJson(text) {
-  try {
-    return JSON.parse(text);
-  } catch {
-    return;
-  }
-}
 
 // src/shell/interactiveRunner/runnerStore.ts
 import { join as join4 } from "node:path";
@@ -11106,34 +11119,15 @@ var storedRunnerSchema = object({
 var storeSchema = object({
   defaultRunnerId: string2().optional()
 });
-function parseJson2(text) {
-  try {
-    return JSON.parse(text);
-  } catch {
-    return;
-  }
-}
-var pendingWrites = 0;
 function makeRunnerStore(options) {
   const directory = join4(options.cwd, qawolfDir);
   const path = join4(directory, storeFileName);
   const runnersDir = join4(directory, runnersDirName);
-  const nextPendingPath = (target) => `${target}.${process.pid}.${++pendingWrites}.tmp`;
   const runnerPath = (runnerId) => join4(runnersDir, `${encodeURIComponent(runnerId)}.json`);
-  const writeAtomically = async (target, contents) => {
-    const pendingPath = nextPendingPath(target);
-    await options.fs.writeFile(pendingPath, `${JSON.stringify(contents, undefined, 2)}
-`);
-    await options.fs.rename(pendingPath, target);
-  };
+  const writeAtomically = (target, contents) => writeJsonFileAtomically(options.fs, target, contents);
   const readDefaultRunnerId = async () => {
-    const contents = await options.fs.readFile(path).catch(() => {
-      return;
-    });
-    if (contents === undefined)
-      return;
-    const parsed = storeSchema.safeParse(parseJson2(contents));
-    return parsed.success ? parsed.data.defaultRunnerId : undefined;
+    const stored = await readJsonFile(options.fs, path, storeSchema);
+    return stored?.defaultRunnerId;
   };
   const writeDefaultRunnerId = async (runnerId) => {
     await options.fs.mkdir(directory, { recursive: true });
@@ -11155,15 +11149,7 @@ function makeRunnerStore(options) {
     },
     readDefaultRunnerId,
     async readRunners() {
-      const runners = await Promise.all((await readRunnerFileNames()).map(async (name) => {
-        const contents = await options.fs.readFile(join4(runnersDir, name)).catch(() => {
-          return;
-        });
-        if (contents === undefined)
-          return;
-        const parsed = storedRunnerSchema.safeParse(parseJson2(contents));
-        return parsed.success ? parsed.data : undefined;
-      }));
+      const runners = await Promise.all((await readRunnerFileNames()).map((name) => readJsonFile(options.fs, join4(runnersDir, name), storedRunnerSchema)));
       return runners.filter((runner) => !!runner).sort((left, right) => left.id.localeCompare(right.id));
     },
     async rememberLaunch(runner) {
@@ -11181,7 +11167,7 @@ function makeRunnerStore(options) {
         });
         if (contents === undefined)
           return;
-        if (storedRunnerSchema.safeParse(parseJson2(contents)).success)
+        if (storedRunnerSchema.safeParse(parseJson(contents)).success)
           return;
         await options.fs.rm(runnerFile, { force: true });
       }));
@@ -12800,7 +12786,8 @@ var environmentListItemSchema = object({
   slug: string2()
 });
 var environmentWithVariablesResponseSchema = object({
-  environmentVariables: record(string2(), string2())
+  environmentVariables: record(string2(), string2()),
+  teamId: string2()
 });
 var flowListItemSchema = object({
   flowId: string2(),
@@ -13077,7 +13064,10 @@ async function writeTeamStorageAssets(args, deps) {
 
 // src/shell/platform/teamStorageMethods.ts
 function createTeamStorageMethods(trpc, deps, fs, getIdentity) {
-  async function list() {
+  async function list(opts) {
+    if (opts?.teamId !== undefined) {
+      return listTeamStorageFiles(trpc, { teamId: opts.teamId }, deps);
+    }
     if (deps.workspaceId !== undefined) {
       return listTeamStorageFiles(trpc, { teamId: deps.workspaceId }, deps);
     }
@@ -13087,7 +13077,7 @@ function createTeamStorageMethods(trpc, deps, fs, getIdentity) {
     if (!("team" in identity.value)) {
       return {
         ok: false,
-        error: flowsMessages.pull.teamStorageRequiresTeamKey
+        error: flowsMessages.pull.teamStorageRequiresTeam
       };
     }
     return listTeamStorageFiles(trpc, { teamId: identity.value.team.id }, deps);
@@ -13095,7 +13085,7 @@ function createTeamStorageMethods(trpc, deps, fs, getIdentity) {
   return {
     listTeamStorageFiles: list,
     async syncTeamStorageAssets(assetsAbs, opts) {
-      const files = await list();
+      const files = await list({ teamId: opts?.teamId });
       if (!files.ok)
         return files;
       return downloadTeamStorageAssets({ assetsAbs, files: files.value }, { fetch: deps.fetch, fs, onProgress: opts?.onProgress });
@@ -13125,16 +13115,14 @@ function createPlatformClient(apiKey, deps) {
     ...createTeamStorageMethods(trpc, deps, fs, identityMethods.getIdentity),
     getFlowsBundleUrl: getFlowsBundleUrlImpl,
     callPublicApi: makeCallPublicApiMethod(trpc, deps, requestBackoffMs2),
-    async getEnvVars(envId) {
+    async getEnvironmentWithVariables(envId) {
       const result = await requestWithRetry({
         call: () => trpc.query("environment.getEnvironmentWithVariables", { id: envId }, environmentWithVariablesResponseSchema),
         backoffMs: requestBackoffMs2,
         describe: (err) => describeRequestError(err, deps.baseUrl, "env-vars"),
         sleep: deps.sleep
       });
-      if (!result.ok)
-        return result;
-      return { ok: true, value: result.value.environmentVariables };
+      return result;
     },
     async downloadBundle(envId) {
       const urlResult = await getFlowsBundleUrlImpl(envId);
@@ -13863,4 +13851,4 @@ export {
   createRunnerSdk
 };
 
-//# debugId=A460E98091C1C6D964756E2164756E21
+//# debugId=395E9F8ECC554DB664756E2164756E21

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

@@ -124,6 +124,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.30.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/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
@@ -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
@@ -586,7 +594,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