@qawolf/cli 1.26.0 → 1.27.0

package/dist/cli.js

@@ -8787,7 +8787,17 @@ var interactMessages = {
   actionMayHaveHappened: "The runner could not be reached, which does not mean the action was not performed: it may have stopped answering mid-action. Take a screenshot before repeating it.",
   actionNotJson: `Stdin did not hold a JSON action. Pipe one object, for example '{"type":"click","button":"left","x":480,"y":260}'.`,
   actionNotSupportedOnMobile: (type) => `A mobile runner has a touchscreen, so it cannot perform ${type} as asked. It taps with a left-button click, swipes with drag, and types into whatever the last tap focused.`,
+  actionFailedScreenshotToStdout: "Its screen was written to stdout as a JPEG, so look at that rather than sending the action again.",
+  actionFailedScreenshotUnwritten: (detail) => `Its screen could not be written, because ${detail}, so take one with qawolf runner screenshot rather than sending the action again.`,
+  actionFailedScreenshotWritten: (path) => `Its screen was written to ${path}, so look at that rather than sending the action again.`,
+  actionFailedWithoutScreenshot: "The runner answered without a screen, so nothing was written; take one with qawolf runner screenshot rather than sending the action again.",
   actionPerformed: (type) => `Performed ${type}.`,
+  actionPerformedScreenshotNotAnImage: (type) => `Performed ${type}, but the screen that came with the answer was not a JPEG, so nothing was written. The action took effect, so do not repeat it: take the screen with qawolf runner screenshot instead, and report it if it keeps happening.`,
+  actionPerformedScreenshotToStdout: (type) => `Performed ${type} and wrote the runner's screen to stdout as a JPEG. Stdout holds the image bytes alone; this line, and the JSON with --json, is on stderr.`,
+  actionPerformedScreenshotStdoutUnwritable: (type, detail) => `Performed ${type}, but its screen could not be written to stdout: ${detail}. The action took effect, so do not repeat it: keep the pipe reading stdout open, or take the screen with qawolf runner screenshot --out <file>.`,
+  actionPerformedScreenshotUnwritable: (type, path, detail) => `Performed ${type}, but its screen could not be written to "${path}": ${detail}. The action took effect, so do not repeat it: take the screen with qawolf runner screenshot, giving --out a path this process can write to.`,
+  actionPerformedScreenshotWritten: (type, path) => `Performed ${type} and wrote the runner's screen to ${path}.`,
+  actionPerformedWithoutScreenshot: (type) => `Performed ${type}, but the runner answered without the screen it was asked for. The action took effect, so do not repeat it: take the screen with qawolf runner screenshot instead. If this keeps happening, the platform or this CLI is behind the other: upgrade with npm install -g @qawolf/cli.`,
   actionAnsweredUnknown: (failureReason) => `The runner answered "${failureReason}", which this version of the CLI does not know how to report. Upgrade with npm install -g @qawolf/cli.`,
   screenshotAnsweredUnknown: (failureReason) => `The runner answered "${failureReason}", which this version of the CLI does not know how to report. Upgrade with npm install -g @qawolf/cli.`,
   runnerHasNoScreen: "This runner does not run a browser on a virtual desktop, so there is nothing about it to see or drive. Retrying will never help: launch a playwright runner instead.",
@@ -8799,8 +8809,11 @@ var interactMessages = {
   screenNeedsARun: "This runner has not run anything yet, so its screen has never started. Waiting will not clear this and there is nothing to retry: run a flow on it with qawolf runner run, then ask again. Evaluating a snippet does not start a screen.",
   screenNotReady: "The runner has a screen and cannot serve this yet. Its virtual desktop restarts when a run changes the display size, and it serves one request at a time, so something already in flight is the usual reason. Retry in a second or two.",
   screenshotNotAnImage: "The screen was captured but did not arrive as a JPEG, so nothing was written. Nothing about the command needs changing: try it again, and report it if it keeps happening.",
+  stdoutIsATerminal: (flag) => `Stdout is a terminal, so the JPEG bytes would have nowhere to go. Redirect stdout to a file or pipe it into a reader, or give ${flag} a file path instead of "-".`,
+  screenshotStdoutUnwritable: (detail) => `The screen was captured but could not be written to stdout: ${detail}. Keep the pipe reading stdout open, or give --out a file path instead of "-".`,
   screenshotUnwritable: (path, detail) => `The screen was captured but could not be written to "${path}": ${detail}. Give --out a path this process can write to.`,
   screenshotWritten: (path) => `Wrote the runner's screen to ${path}.`,
+  screenshotWrittenToStdout: "Wrote the runner's screen to stdout as a JPEG. Stdout holds the image bytes alone; this line, and the JSON with --json, is on stderr.",
   snippetEmpty: (path) => `"${path}" holds no code to evaluate.`,
   snippetErrored: (errorMessage) => errorMessage === undefined ? "The snippet threw and reported no message." : `The snippet threw: ${errorMessage}`,
   snippetFileUnreadable: (path) => `Could not read "${path}". Name a readable file, or "-" to read the snippet from stdin.`,
@@ -20551,7 +20564,7 @@ function startUpdateCheck(deps) {
 // package.json
 var package_default = {
   name: "@qawolf/cli",
-  version: "1.26.0",
+  version: "1.27.0",
   description: "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   keywords: [
     "automation",
@@ -32308,6 +32321,28 @@ function registerPublicApiCommands(program, signals, options = {}) {
   }
 }
 
+// src/domains/interactiveRunner/evaluateSnippetFailure.ts
+function describeEvaluateSnippetFailure(failure) {
+  const { failureReason } = failure;
+  switch (failureReason) {
+    case "runner-cannot-evaluate-snippets":
+      return {
+        error: interactiveRunnerMessages.runnerCannotEvaluateSnippets,
+        exitCode: exitCodes.invalidArgs
+      };
+    case "runner-unreachable":
+      return {
+        error: interactiveRunnerMessages.snippetRunnerUnreachable,
+        exitCode: exitCodes.network
+      };
+    default:
+      return {
+        error: interactiveRunnerMessages.snippetAnsweredUnknown(failureReason),
+        exitCode: exitCodes.network
+      };
+  }
+}
+
 // src/domains/interactiveRunner/runnerCallOptions.ts
 var runnerCallOptions = { timeoutMs: 90000 };
 
@@ -32420,67 +32455,138 @@ function announceRunner(ctx, resolved) {
   }
 }
 
-// src/domains/interactiveRunner/highlightSelector.ts
-async function handleRunnerHighlightSelector(ctx, options, deps) {
-  const resolved = await resolveRunner(ctx, {
-    autoLaunch: false,
-    noRunnerIdMessage: interactiveRunnerMessages.noRunnerIdForHighlight,
-    runner: options.runner
-  }, deps);
+// src/core/interactiveRunner/runFiles.ts
+import { isAbsolute as isAbsolute5, relative as relative10, resolve as resolve11, sep as sep5 } from "node:path";
+function toCollectedPath(cwd, path) {
+  const absolute = isAbsolute5(path) ? path : resolve11(cwd, path);
+  return relative10(cwd, absolute).split(sep5).join("/");
+}
+var namedLargestFileCount = 3;
+function largestFiles(files) {
+  return Object.entries(files).map(([path, content]) => ({
+    byteLength: runFilesByteLength({ [path]: content }),
+    path
+  })).sort((a, b) => b.byteLength - a.byteLength).slice(0, namedLargestFileCount);
+}
+function checkPresenceAndSize(files, requiredPath) {
+  if (!Object.hasOwn(files, requiredPath)) {
+    return { path: requiredPath, type: "missing-file" };
+  }
+  const byteLength = runFilesByteLength(files);
+  if (byteLength > maxRunFilesByteLength) {
+    return {
+      byteLength,
+      largest: largestFiles(files),
+      maxByteLength: maxRunFilesByteLength,
+      type: "too-large"
+    };
+  }
+  const encodedByteLength = Buffer.byteLength(JSON.stringify({ files, path: requiredPath }), "utf8");
+  if (encodedByteLength > maxRunnerRequestEncodedByteLength) {
+    return {
+      byteLength: encodedByteLength,
+      maxByteLength: maxRunnerRequestEncodedByteLength,
+      type: "request-too-large"
+    };
+  }
+  return { type: "ok" };
+}
+function checkRunFiles(files, entryPointPath) {
+  const present = checkPresenceAndSize(files, entryPointPath);
+  if (present.type !== "ok")
+    return present;
+  if (!Object.hasOwn(files, runPackageJsonPath)) {
+    return { type: "missing-package-json" };
+  }
+  return { type: "ok" };
+}
+function checkSnippetFiles(files, contextFilePath) {
+  return checkPresenceAndSize(files, contextFilePath);
+}
+function describeRunFilesCheck(check) {
+  switch (check.type) {
+    case "missing-file":
+      return interactiveRunnerMessages.fileNotCollected(check.path);
+    case "missing-package-json":
+      return interactiveRunnerMessages.missingPackageJson;
+    case "too-large":
+      return interactiveRunnerMessages.filesTooLarge(check.byteLength, check.maxByteLength, check.largest);
+    case "request-too-large":
+      return interactiveRunnerMessages.requestTooLarge(check.byteLength, check.maxByteLength);
+  }
+}
+
+// src/domains/interactiveRunner/snippetScope.ts
+async function resolveSnippetScope(contextFile, deps) {
+  if (contextFile === undefined) {
+    return { filePath: undefined, files: undefined, ok: true };
+  }
+  const filePath = toCollectedPath(deps.cwd, contextFile);
+  const { files } = await deps.collectRunFiles([filePath]);
+  const check = checkSnippetFiles(files, filePath);
+  if (check.type !== "ok") {
+    return { error: describeRunFilesCheck(check), ok: false };
+  }
+  return { filePath, files, ok: true };
+}
+
+// src/domains/interactiveRunner/evaluateSnippet.ts
+var stdinArgument = "-";
+async function readCode(source, deps) {
+  const code = source === stdinArgument ? await deps.readStdin() : await deps.readFile(source).catch(() => {
+    return;
+  });
+  if (code === undefined) {
+    return {
+      error: interactiveRunnerMessages.snippetFileUnreadable(source),
+      ok: false
+    };
+  }
+  if (code.trim() === "") {
+    return source === stdinArgument ? { error: interactiveRunnerMessages.stdinEmptySnippet, ok: false } : { error: interactiveRunnerMessages.snippetEmpty(source), ok: false };
+  }
+  return { code, ok: true };
+}
+async function handleRunnerExec(ctx, options, deps) {
+  const code = await readCode(options.source, deps);
+  if (!code.ok)
+    return { error: code.error, exitCode: exitCodes.invalidArgs };
+  const scope = await resolveSnippetScope(options.contextFile, deps);
+  if (!scope.ok)
+    return { error: scope.error, exitCode: exitCodes.invalidArgs };
+  const resolved = await resolveRunner(ctx, { autoLaunch: true, runner: options.runner }, deps);
   if (resolved.type === "failed") {
     return { ...failureFields(resolved), exitCode: resolved.exitCode };
   }
-  const selector = options.selector ?? "";
-  const result = await ctx.platformClient.callPublicApi(publicContractsV1.runner.highlightSelector, { id: resolved.runnerId, selector }, runnerCallOptions);
+  announceRunner(ctx, resolved);
+  const result = await ctx.platformClient.callPublicApi(publicContractsV1.runner.evaluateSnippet, {
+    code: code.code,
+    id: resolved.runnerId,
+    ...scope.filePath === undefined ? {} : { filePath: scope.filePath },
+    ...scope.files === undefined ? {} : { files: scope.files }
+  }, runnerCallOptions);
   if (!result.ok) {
-    return { ...failureFields(result), exitCode: exitCodes.network };
+    return {
+      ...failureFields(result),
+      exitCode: result.exitCode ?? exitCodes.network
+    };
   }
-  const { outcome } = result.value;
-  switch (outcome) {
-    case "cleared":
-      ctx.ui.output(result.value, interactiveRunnerMessages.highlightCleared);
-      return;
-    case "success": {
-      const answer = result.value;
-      if (answer.status === "invalid") {
-        return {
-          error: interactiveRunnerMessages.highlightSelectorInvalid(answer.selector),
-          exitCode: exitCodes.invalidArgs
-        };
-      }
-      ctx.ui.output(answer, answer.status === "empty" ? interactiveRunnerMessages.highlightMatchedNothing(answer.selector) : interactiveRunnerMessages.highlightMatched(answer.matchCount, answer.targetPage));
-      return;
-    }
-    case "failure":
-      return describeFailure(result.value.failureReason);
-    default:
-      return {
-        error: interactiveRunnerMessages.highlightAnsweredUnknown(outcome),
-        exitCode: exitCodes.network
-      };
+  if (result.value.outcome === "failure") {
+    return describeEvaluateSnippetFailure(result.value);
   }
-}
-function describeFailure(failureReason) {
-  switch (failureReason) {
-    case "no-answer":
-      return {
-        error: interactiveRunnerMessages.highlightNoAnswer,
-        exitCode: exitCodes.network
-      };
-    case "runner-cannot-highlight-selectors":
-      return {
-        error: interactiveRunnerMessages.runnerCannotHighlightSelectors,
-        exitCode: exitCodes.invalidArgs
-      };
-    case "runner-unreachable":
+  switch (result.value.result) {
+    case "success":
+      ctx.ui.output({ outcome: "evaluated", result: "success" }, interactiveRunnerMessages.snippetRan);
+      return;
+    case "stopped":
       return {
-        error: interactiveRunnerMessages.runnerUnreachable,
-        exitCode: exitCodes.network
+        error: interactiveRunnerMessages.snippetStopped,
+        exitCode: exitCodes.testFailure
       };
-    default:
+    case "error":
       return {
-        error: interactiveRunnerMessages.highlightAnsweredUnknown(failureReason),
-        exitCode: exitCodes.network
+        error: interactiveRunnerMessages.snippetErrored(result.value.errorMessage),
+        exitCode: exitCodes.testFailure
       };
   }
 }
@@ -32823,19 +32929,38 @@ function makeRunnerStore(options) {
 // src/shell/interactiveRunner/writeScreenshot.ts
 import { dirname as dirname16 } from "node:path";
 var jpegStartOfImage = [255, 216, 255];
+var stdoutPath = "-";
 async function writeScreenshot(options) {
   const bytes = Buffer.from(options.imageJpegBase64, "base64");
   if (jpegStartOfImage.some((byte, index) => bytes[index] !== byte)) {
     return { ok: false, reason: "not-a-jpeg" };
   }
   try {
-    await options.fs.mkdir(dirname16(options.path), { recursive: true });
-    await options.fs.writeFile(options.path, bytes);
+    if (options.path === stdoutPath) {
+      await writeToStdout(options.stdout ?? process.stdout, bytes);
+    } else {
+      await options.fs.mkdir(dirname16(options.path), { recursive: true });
+      await options.fs.writeFile(options.path, bytes);
+    }
   } catch (error) {
     return { detail: errorMessage(error), ok: false, reason: "unwritable" };
   }
   return { ok: true };
 }
+function writeToStdout(stdout, bytes) {
+  return new Promise((resolve, reject) => {
+    const onError = (error) => reject(error);
+    stdout.once("error", onError);
+    stdout.write(bytes, (error) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      stdout.off("error", onError);
+      resolve();
+    });
+  });
+}
 
 // src/shell/stdin.ts
 async function readStdin2() {
@@ -32876,6 +33001,81 @@ function runnerDeps(ctx) {
   });
 }
 
+// src/commands/runner/exec.register.ts
+var execExamples = `
+Examples:
+  $ qawolf runner exec snippet.ts
+  $ echo 'console.log(await page.title())' | qawolf runner exec -
+  $ qawolf runner exec snippet.ts --file flows/checkout.flow.ts`;
+function registerRunnerExecCommand(runner, signals) {
+  declareCommandKind(runner.command("exec <file>"), "write").description("Evaluate a snippet against a runner's live page. Use - to read the snippet from stdin").option("--file <path>", "File whose scope the snippet is evaluated in; it and the directory's other files travel with it").option("--runner <id>", runnerFlagDescription).addHelpText("after", execExamples).action((file, opts, command) => withAuthContext(signals, (ctx) => handleRunnerExec(ctx, { contextFile: opts.file, runner: opts.runner, source: file }, runnerDeps(ctx)))(opts, command));
+}
+
+// src/domains/interactiveRunner/highlightSelector.ts
+async function handleRunnerHighlightSelector(ctx, options, deps) {
+  const resolved = await resolveRunner(ctx, {
+    autoLaunch: false,
+    noRunnerIdMessage: interactiveRunnerMessages.noRunnerIdForHighlight,
+    runner: options.runner
+  }, deps);
+  if (resolved.type === "failed") {
+    return { ...failureFields(resolved), exitCode: resolved.exitCode };
+  }
+  const selector = options.selector ?? "";
+  const result = await ctx.platformClient.callPublicApi(publicContractsV1.runner.highlightSelector, { id: resolved.runnerId, selector }, runnerCallOptions);
+  if (!result.ok) {
+    return { ...failureFields(result), exitCode: exitCodes.network };
+  }
+  const { outcome } = result.value;
+  switch (outcome) {
+    case "cleared":
+      ctx.ui.output(result.value, interactiveRunnerMessages.highlightCleared);
+      return;
+    case "success": {
+      const answer = result.value;
+      if (answer.status === "invalid") {
+        return {
+          error: interactiveRunnerMessages.highlightSelectorInvalid(answer.selector),
+          exitCode: exitCodes.invalidArgs
+        };
+      }
+      ctx.ui.output(answer, answer.status === "empty" ? interactiveRunnerMessages.highlightMatchedNothing(answer.selector) : interactiveRunnerMessages.highlightMatched(answer.matchCount, answer.targetPage));
+      return;
+    }
+    case "failure":
+      return describeFailure(result.value.failureReason);
+    default:
+      return {
+        error: interactiveRunnerMessages.highlightAnsweredUnknown(outcome),
+        exitCode: exitCodes.network
+      };
+  }
+}
+function describeFailure(failureReason) {
+  switch (failureReason) {
+    case "no-answer":
+      return {
+        error: interactiveRunnerMessages.highlightNoAnswer,
+        exitCode: exitCodes.network
+      };
+    case "runner-cannot-highlight-selectors":
+      return {
+        error: interactiveRunnerMessages.runnerCannotHighlightSelectors,
+        exitCode: exitCodes.invalidArgs
+      };
+    case "runner-unreachable":
+      return {
+        error: interactiveRunnerMessages.runnerUnreachable,
+        exitCode: exitCodes.network
+      };
+    default:
+      return {
+        error: interactiveRunnerMessages.highlightAnsweredUnknown(failureReason),
+        exitCode: exitCodes.network
+      };
+  }
+}
+
 // src/commands/runner/highlightSelector.register.ts
 var highlightExamples = `
 Examples:
@@ -33265,162 +33465,10 @@ function registerRunnerInspectCommands(runner, signals) {
   registerRunnerInspectMobileCommands(inspect, signals);
 }
 
-// src/domains/interactiveRunner/evaluateSnippetFailure.ts
-function describeEvaluateSnippetFailure(failure) {
-  const { failureReason } = failure;
-  switch (failureReason) {
-    case "runner-cannot-evaluate-snippets":
-      return {
-        error: interactiveRunnerMessages.runnerCannotEvaluateSnippets,
-        exitCode: exitCodes.invalidArgs
-      };
-    case "runner-unreachable":
-      return {
-        error: interactiveRunnerMessages.snippetRunnerUnreachable,
-        exitCode: exitCodes.network
-      };
-    default:
-      return {
-        error: interactiveRunnerMessages.snippetAnsweredUnknown(failureReason),
-        exitCode: exitCodes.network
-      };
-  }
-}
-
-// src/core/interactiveRunner/runFiles.ts
-import { isAbsolute as isAbsolute5, relative as relative10, resolve as resolve11, sep as sep5 } from "node:path";
-function toCollectedPath(cwd, path) {
-  const absolute = isAbsolute5(path) ? path : resolve11(cwd, path);
-  return relative10(cwd, absolute).split(sep5).join("/");
-}
-var namedLargestFileCount = 3;
-function largestFiles(files) {
-  return Object.entries(files).map(([path, content]) => ({
-    byteLength: runFilesByteLength({ [path]: content }),
-    path
-  })).sort((a, b) => b.byteLength - a.byteLength).slice(0, namedLargestFileCount);
-}
-function checkPresenceAndSize(files, requiredPath) {
-  if (!Object.hasOwn(files, requiredPath)) {
-    return { path: requiredPath, type: "missing-file" };
-  }
-  const byteLength = runFilesByteLength(files);
-  if (byteLength > maxRunFilesByteLength) {
-    return {
-      byteLength,
-      largest: largestFiles(files),
-      maxByteLength: maxRunFilesByteLength,
-      type: "too-large"
-    };
-  }
-  const encodedByteLength = Buffer.byteLength(JSON.stringify({ files, path: requiredPath }), "utf8");
-  if (encodedByteLength > maxRunnerRequestEncodedByteLength) {
-    return {
-      byteLength: encodedByteLength,
-      maxByteLength: maxRunnerRequestEncodedByteLength,
-      type: "request-too-large"
-    };
-  }
-  return { type: "ok" };
-}
-function checkRunFiles(files, entryPointPath) {
-  const present = checkPresenceAndSize(files, entryPointPath);
-  if (present.type !== "ok")
-    return present;
-  if (!Object.hasOwn(files, runPackageJsonPath)) {
-    return { type: "missing-package-json" };
-  }
-  return { type: "ok" };
-}
-function checkSnippetFiles(files, contextFilePath) {
-  return checkPresenceAndSize(files, contextFilePath);
-}
-function describeRunFilesCheck(check) {
-  switch (check.type) {
-    case "missing-file":
-      return interactiveRunnerMessages.fileNotCollected(check.path);
-    case "missing-package-json":
-      return interactiveRunnerMessages.missingPackageJson;
-    case "too-large":
-      return interactiveRunnerMessages.filesTooLarge(check.byteLength, check.maxByteLength, check.largest);
-    case "request-too-large":
-      return interactiveRunnerMessages.requestTooLarge(check.byteLength, check.maxByteLength);
-  }
-}
-
-// src/domains/interactiveRunner/snippetScope.ts
-async function resolveSnippetScope(contextFile, deps) {
-  if (contextFile === undefined) {
-    return { filePath: undefined, files: undefined, ok: true };
-  }
-  const filePath = toCollectedPath(deps.cwd, contextFile);
-  const { files } = await deps.collectRunFiles([filePath]);
-  const check = checkSnippetFiles(files, filePath);
-  if (check.type !== "ok") {
-    return { error: describeRunFilesCheck(check), ok: false };
-  }
-  return { filePath, files, ok: true };
-}
-
-// src/domains/interactiveRunner/evaluateSnippet.ts
-var stdinArgument = "-";
-async function readCode(source, deps) {
-  const code = source === stdinArgument ? await deps.readStdin() : await deps.readFile(source).catch(() => {
-    return;
-  });
-  if (code === undefined) {
-    return {
-      error: interactiveRunnerMessages.snippetFileUnreadable(source),
-      ok: false
-    };
-  }
-  if (code.trim() === "") {
-    return source === stdinArgument ? { error: interactiveRunnerMessages.stdinEmptySnippet, ok: false } : { error: interactiveRunnerMessages.snippetEmpty(source), ok: false };
-  }
-  return { code, ok: true };
-}
-async function handleRunnerExec(ctx, options, deps) {
-  const code = await readCode(options.source, deps);
-  if (!code.ok)
-    return { error: code.error, exitCode: exitCodes.invalidArgs };
-  const scope = await resolveSnippetScope(options.contextFile, deps);
-  if (!scope.ok)
-    return { error: scope.error, exitCode: exitCodes.invalidArgs };
-  const resolved = await resolveRunner(ctx, { autoLaunch: true, runner: options.runner }, deps);
-  if (resolved.type === "failed") {
-    return { ...failureFields(resolved), exitCode: resolved.exitCode };
-  }
-  announceRunner(ctx, resolved);
-  const result = await ctx.platformClient.callPublicApi(publicContractsV1.runner.evaluateSnippet, {
-    code: code.code,
-    id: resolved.runnerId,
-    ...scope.filePath === undefined ? {} : { filePath: scope.filePath },
-    ...scope.files === undefined ? {} : { files: scope.files }
-  }, runnerCallOptions);
-  if (!result.ok) {
-    return {
-      ...failureFields(result),
-      exitCode: result.exitCode ?? exitCodes.network
-    };
-  }
-  if (result.value.outcome === "failure") {
-    return describeEvaluateSnippetFailure(result.value);
-  }
-  switch (result.value.result) {
-    case "success":
-      ctx.ui.output({ outcome: "evaluated", result: "success" }, interactiveRunnerMessages.snippetRan);
-      return;
-    case "stopped":
-      return {
-        error: interactiveRunnerMessages.snippetStopped,
-        exitCode: exitCodes.testFailure
-      };
-    case "error":
-      return {
-        error: interactiveRunnerMessages.snippetErrored(result.value.errorMessage),
-        exitCode: exitCodes.testFailure
-      };
-  }
+// src/core/sentences.ts
+function appendSentence(text, sentence) {
+  const punctuated = /[.!?]$/.test(text.trimEnd()) ? text.trimEnd() : `${text.trimEnd()}.`;
+  return `${punctuated} ${sentence}`;
 }
 
 // src/domains/interactiveRunner/performActionFailure.ts
@@ -33467,6 +33515,56 @@ function describePerformActionFailure(options) {
   }
 }
 
+// src/domains/interactiveRunner/performActionScreenshot.ts
+async function writeActionScreenshot(ctx, options, deps) {
+  const { type } = options.action;
+  if (options.imageJpegBase64 === undefined) {
+    return {
+      error: interactiveRunnerMessages.actionPerformedWithoutScreenshot(type),
+      exitCode: exitCodes.network
+    };
+  }
+  const written = await deps.writeScreenshot({
+    imageJpegBase64: options.imageJpegBase64,
+    path: options.out
+  });
+  if (!written.ok) {
+    return written.reason === "not-a-jpeg" ? {
+      error: interactiveRunnerMessages.actionPerformedScreenshotNotAnImage(type),
+      exitCode: exitCodes.network
+    } : {
+      error: options.out === stdoutPath ? interactiveRunnerMessages.actionPerformedScreenshotStdoutUnwritable(type, written.detail) : interactiveRunnerMessages.actionPerformedScreenshotUnwritable(type, options.out, written.detail),
+      exitCode: exitCodes.network
+    };
+  }
+  if (options.out === stdoutPath) {
+    ctx.ui.success(interactiveRunnerMessages.actionPerformedScreenshotToStdout(type));
+    return;
+  }
+  ctx.ui.output({ action: options.action, outcome: "success", screenshotPath: options.out }, interactiveRunnerMessages.actionPerformedScreenshotWritten(type, options.out));
+  return;
+}
+async function addFailureScreenshot(options, deps) {
+  const note = await describeFailureScreenshot(options, deps);
+  return {
+    ...options.failure,
+    error: appendSentence(options.failure.error, note)
+  };
+}
+async function describeFailureScreenshot(options, deps) {
+  if (options.imageJpegBase64 === undefined) {
+    return interactiveRunnerMessages.actionFailedWithoutScreenshot;
+  }
+  const written = await deps.writeScreenshot({
+    imageJpegBase64: options.imageJpegBase64,
+    path: options.out
+  });
+  if (!written.ok) {
+    return interactiveRunnerMessages.actionFailedScreenshotUnwritten(written.reason === "not-a-jpeg" ? "it did not arrive as a JPEG" : written.detail);
+  }
+  return options.out === stdoutPath ? interactiveRunnerMessages.actionFailedScreenshotToStdout : interactiveRunnerMessages.actionFailedScreenshotWritten(options.out);
+}
+
 // src/core/interactiveRunner/browserAction.ts
 function parseJsonPath(path) {
   try {
@@ -33531,30 +33629,56 @@ async function handleRunnerAct(ctx, options, deps) {
   const built = await readAction(options.type, options.flags, deps);
   if (!built.ok)
     return { error: built.error, exitCode: exitCodes.invalidArgs };
+  if (options.screenshot === stdoutPath && ctx.outputMode === "human") {
+    return {
+      error: interactiveRunnerMessages.stdoutIsATerminal("--screenshot"),
+      exitCode: exitCodes.invalidArgs
+    };
+  }
   const resolved = await resolveRunner(ctx, { autoLaunch: true, runner: options.runner }, deps);
   if (resolved.type === "failed") {
     return { ...failureFields(resolved), exitCode: resolved.exitCode };
   }
   announceRunner(ctx, resolved);
-  const result = await ctx.platformClient.callPublicApi(publicContractsV1.runner.performAction, { action: built.action, id: resolved.runnerId }, runnerCallOptions);
+  const result = await ctx.platformClient.callPublicApi(publicContractsV1.runner.performAction, {
+    action: built.action,
+    id: resolved.runnerId,
+    ...options.screenshot === undefined ? {} : { withScreenshot: true }
+  }, runnerCallOptions);
   if (!result.ok) {
     const fields = failureFields(result);
     return {
       ...fields,
       ...result.mayHaveArrived ? {
-        error: `${fields.error} ${interactiveRunnerMessages.actionMayHaveHappened}`
+        error: appendSentence(fields.error, interactiveRunnerMessages.actionMayHaveHappened)
       } : {},
       exitCode: exitCodes.network
     };
   }
-  if (result.value.outcome === "success") {
+  const answer = result.value;
+  if (answer.outcome === "success") {
+    if (options.screenshot !== undefined) {
+      return writeActionScreenshot(ctx, {
+        action: built.action,
+        imageJpegBase64: answer.imageJpegBase64,
+        out: options.screenshot
+      }, deps);
+    }
     ctx.ui.output({ action: built.action, outcome: "success" }, interactiveRunnerMessages.actionPerformed(built.action.type));
     return;
   }
-  return describePerformActionFailure({
+  const failure = describePerformActionFailure({
     actionType: built.action.type,
-    failure: result.value
+    failure: answer
   });
+  if (options.screenshot === undefined || answer.failureReason !== "action-failed") {
+    return failure;
+  }
+  return addFailureScreenshot({
+    failure,
+    imageJpegBase64: answer.imageJpegBase64,
+    out: options.screenshot
+  }, deps);
 }
 
 // src/domains/interactiveRunner/takeScreenshot.ts
@@ -33567,6 +33691,12 @@ async function handleRunnerScreenshot(ctx, options, deps) {
   if (resolved.type === "failed") {
     return { ...failureFields(resolved), exitCode: resolved.exitCode };
   }
+  if (options.out === stdoutPath && ctx.outputMode === "human") {
+    return {
+      error: interactiveRunnerMessages.stdoutIsATerminal("--out"),
+      exitCode: exitCodes.invalidArgs
+    };
+  }
   const result = await ctx.platformClient.callPublicApi(publicContractsV1.runner.takeScreenshot, { id: resolved.runnerId }, runnerCallOptions);
   if (!result.ok) {
     return { ...failureFields(result), exitCode: exitCodes.network };
@@ -33576,16 +33706,13 @@ async function handleRunnerScreenshot(ctx, options, deps) {
       imageJpegBase64: result.value.imageJpegBase64,
       path: options.out
     });
-    if (!written.ok) {
-      return written.reason === "not-a-jpeg" ? {
-        error: interactiveRunnerMessages.screenshotNotAnImage,
-        exitCode: exitCodes.network
-      } : {
-        error: interactiveRunnerMessages.screenshotUnwritable(options.out, written.detail),
-        exitCode: exitCodes.invalidArgs
-      };
+    if (!written.ok)
+      return describeUnwritten(written, options.out);
+    if (options.out === stdoutPath) {
+      ctx.ui.success(interactiveRunnerMessages.screenshotWrittenToStdout);
+    } else {
+      ctx.ui.output({ outcome: "success", path: options.out }, interactiveRunnerMessages.screenshotWritten(options.out));
     }
-    ctx.ui.output({ outcome: "success", path: options.out }, interactiveRunnerMessages.screenshotWritten(options.out));
     return;
   }
   const { failureReason } = result.value;
@@ -33618,13 +33745,27 @@ async function handleRunnerScreenshot(ctx, options, deps) {
     }
   }
 }
+function describeUnwritten(written, out) {
+  if (written.reason === "not-a-jpeg") {
+    return {
+      error: interactiveRunnerMessages.screenshotNotAnImage,
+      exitCode: exitCodes.network
+    };
+  }
+  return {
+    error: out === stdoutPath ? interactiveRunnerMessages.screenshotStdoutUnwritable(written.detail) : interactiveRunnerMessages.screenshotUnwritable(out, written.detail),
+    exitCode: exitCodes.invalidArgs
+  };
+}
 
 // src/commands/runner/interact.register.ts
 var defaultScreenshotPath = "screenshot.jpg";
 var screenshotExamples = `
 Examples:
   $ qawolf runner screenshot
-  $ qawolf runner screenshot --out screens/step-3.jpg`;
+  $ qawolf runner screenshot --out screens/step-3.jpg
+  $ qawolf runner screenshot --out - > step-3.jpg
+  $ qawolf runner screenshot --out - | my-vision-tool`;
 var actExamples = `
 Examples:
   $ qawolf runner act click --button left --x 480 --y 260
@@ -33632,15 +33773,12 @@ Examples:
   $ qawolf runner act keypress --keys Control a
   $ qawolf runner act navigate --url https://example.com
   $ qawolf runner act drag --path '[{"x":10,"y":20},{"x":80,"y":90}]'
-  $ echo '{"type":"click","button":"left","x":1,"y":2}' | qawolf runner act -`;
-var execExamples = `
-Examples:
-  $ qawolf runner exec snippet.ts
-  $ echo 'console.log(await page.title())' | qawolf runner exec -
-  $ qawolf runner exec snippet.ts --file flows/checkout.flow.ts`;
+  $ qawolf runner act click --button left --x 480 --y 260 --screenshot step-4.jpg
+  $ echo '{"type":"click","button":"left","x":1,"y":2}' | qawolf runner act -
+  $ echo '{"type":"click","button":"left","x":1,"y":2}' | qawolf runner act - --screenshot - > step-5.jpg`;
 function registerRunnerInteractCommands(runner, signals) {
-  declareCommandKind(runner.command("screenshot"), "read").description("Save a JPEG of an interactive runner's screen to a file").option("--out <path>", "File to write the image to", defaultScreenshotPath).option("--runner <id>", runnerFlagDescription).addHelpText("after", screenshotExamples).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerScreenshot(ctx, { out: opts.out, runner: opts.runner }, runnerDeps(ctx)))(opts, command));
-  declareCommandKind(runner.command("act <action>"), "write").description("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").option("--button <button>", "click: left, right, wheel, back or forward (mobile: left only)").option("--keys <keys...>", "keypress: modifiers and the key, e.g. Control a").option("--path <json>", "drag: JSON array of points to drag through (mobile: only the first and last are used)").option("--runner <id>", runnerFlagDescription).option("--scroll-x <delta>", "scroll: horizontal wheel delta").option("--scroll-y <delta>", "scroll: vertical wheel delta").option("--text <text>", "type: the text to type").option("--url <url>", "navigate: the http or https URL to go to").option("--x <pixels>", "pointer x, in screenshot pixels").option("--y <pixels>", "pointer y, in screenshot pixels").addHelpText("after", actExamples).action((action, opts, command) => withAuthContext(signals, (ctx) => handleRunnerAct(ctx, {
+  declareCommandKind(runner.command("screenshot"), "read").description("Save a JPEG of an interactive runner's screen to a file, or write it to stdout with --out -").option("--out <path>", "File to write the image to. - writes the JPEG bytes to stdout on their own and moves the confirmation, JSON included, to stderr", defaultScreenshotPath).option("--runner <id>", runnerFlagDescription).addHelpText("after", screenshotExamples).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerScreenshot(ctx, { out: opts.out, runner: opts.runner }, runnerDeps(ctx)))(opts, command));
+  declareCommandKind(runner.command("act <action>"), "write").description("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").option("--button <button>", "click: left, right, wheel, back or forward (mobile: left only)").option("--keys <keys...>", "keypress: modifiers and the key, e.g. Control a").option("--path <json>", "drag: JSON array of points to drag through (mobile: only the first and last are used)").option("--runner <id>", runnerFlagDescription).option("--screenshot <path>", "Also save a JPEG of the screen, taken after the action, to this file, in place of a separate screenshot. An action that did not take effect answers with one too. - writes it to stdout and moves the confirmation, JSON included, to stderr").option("--scroll-x <delta>", "scroll: horizontal wheel delta").option("--scroll-y <delta>", "scroll: vertical wheel delta").option("--text <text>", "type: the text to type").option("--url <url>", "navigate: the http or https URL to go to").option("--x <pixels>", "pointer x, in screenshot pixels").option("--y <pixels>", "pointer y, in screenshot pixels").addHelpText("after", actExamples).action((action, opts, command) => withAuthContext(signals, (ctx) => handleRunnerAct(ctx, {
     flags: {
       button: opts.button,
       keys: opts.keys,
@@ -33653,9 +33791,9 @@ function registerRunnerInteractCommands(runner, signals) {
       y: opts.y
     },
     runner: opts.runner,
+    screenshot: opts.screenshot,
     type: action
   }, runnerDeps(ctx)))(opts, command));
-  declareCommandKind(runner.command("exec <file>"), "write").description("Evaluate a snippet against a runner's live page. Use - to read the snippet from stdin").option("--file <path>", "File whose scope the snippet is evaluated in; it and the directory's other files travel with it").option("--runner <id>", runnerFlagDescription).addHelpText("after", execExamples).action((file, opts, command) => withAuthContext(signals, (ctx) => handleRunnerExec(ctx, { contextFile: opts.file, runner: opts.runner, source: file }, runnerDeps(ctx)))(opts, command));
 }
 
 // src/domains/interactiveRunner/readJournal.ts
@@ -34610,6 +34748,7 @@ function registerRunnerCommand(program, signals) {
   registerRunCommand(runner, signals);
   registerRunnerEventsCommand(runner, signals);
   registerRunnerInteractCommands(runner, signals);
+  registerRunnerExecCommand(runner, signals);
   registerRunnerInspectCommands(runner, signals);
   registerRunnerImportPackageCommand(runner, signals);
   registerRunnerHighlightSelectorCommand(runner, signals);
@@ -34643,4 +34782,4 @@ createProgram({ signals }).parseAsync().catch(() => {
     process.exitCode = 1;
 }).finally(() => exitWhenIdle(typeof process.exitCode === "number" ? process.exitCode : 0));
 
-//# debugId=D197CB13AEBF087464756E2164756E21
+//# debugId=90417CF807BBB8C264756E2164756E21

package/dist/runner-sdk.js

@@ -9110,7 +9110,17 @@ var interactMessages = {
   actionMayHaveHappened: "The runner could not be reached, which does not mean the action was not performed: it may have stopped answering mid-action. Take a screenshot before repeating it.",
   actionNotJson: `Stdin did not hold a JSON action. Pipe one object, for example '{"type":"click","button":"left","x":480,"y":260}'.`,
   actionNotSupportedOnMobile: (type) => `A mobile runner has a touchscreen, so it cannot perform ${type} as asked. It taps with a left-button click, swipes with drag, and types into whatever the last tap focused.`,
+  actionFailedScreenshotToStdout: "Its screen was written to stdout as a JPEG, so look at that rather than sending the action again.",
+  actionFailedScreenshotUnwritten: (detail) => `Its screen could not be written, because ${detail}, so take one with qawolf runner screenshot rather than sending the action again.`,
+  actionFailedScreenshotWritten: (path) => `Its screen was written to ${path}, so look at that rather than sending the action again.`,
+  actionFailedWithoutScreenshot: "The runner answered without a screen, so nothing was written; take one with qawolf runner screenshot rather than sending the action again.",
   actionPerformed: (type) => `Performed ${type}.`,
+  actionPerformedScreenshotNotAnImage: (type) => `Performed ${type}, but the screen that came with the answer was not a JPEG, so nothing was written. The action took effect, so do not repeat it: take the screen with qawolf runner screenshot instead, and report it if it keeps happening.`,
+  actionPerformedScreenshotToStdout: (type) => `Performed ${type} and wrote the runner's screen to stdout as a JPEG. Stdout holds the image bytes alone; this line, and the JSON with --json, is on stderr.`,
+  actionPerformedScreenshotStdoutUnwritable: (type, detail) => `Performed ${type}, but its screen could not be written to stdout: ${detail}. The action took effect, so do not repeat it: keep the pipe reading stdout open, or take the screen with qawolf runner screenshot --out <file>.`,
+  actionPerformedScreenshotUnwritable: (type, path, detail) => `Performed ${type}, but its screen could not be written to "${path}": ${detail}. The action took effect, so do not repeat it: take the screen with qawolf runner screenshot, giving --out a path this process can write to.`,
+  actionPerformedScreenshotWritten: (type, path) => `Performed ${type} and wrote the runner's screen to ${path}.`,
+  actionPerformedWithoutScreenshot: (type) => `Performed ${type}, but the runner answered without the screen it was asked for. The action took effect, so do not repeat it: take the screen with qawolf runner screenshot instead. If this keeps happening, the platform or this CLI is behind the other: upgrade with npm install -g @qawolf/cli.`,
   actionAnsweredUnknown: (failureReason) => `The runner answered "${failureReason}", which this version of the CLI does not know how to report. Upgrade with npm install -g @qawolf/cli.`,
   screenshotAnsweredUnknown: (failureReason) => `The runner answered "${failureReason}", which this version of the CLI does not know how to report. Upgrade with npm install -g @qawolf/cli.`,
   runnerHasNoScreen: "This runner does not run a browser on a virtual desktop, so there is nothing about it to see or drive. Retrying will never help: launch a playwright runner instead.",
@@ -9122,8 +9132,11 @@ var interactMessages = {
   screenNeedsARun: "This runner has not run anything yet, so its screen has never started. Waiting will not clear this and there is nothing to retry: run a flow on it with qawolf runner run, then ask again. Evaluating a snippet does not start a screen.",
   screenNotReady: "The runner has a screen and cannot serve this yet. Its virtual desktop restarts when a run changes the display size, and it serves one request at a time, so something already in flight is the usual reason. Retry in a second or two.",
   screenshotNotAnImage: "The screen was captured but did not arrive as a JPEG, so nothing was written. Nothing about the command needs changing: try it again, and report it if it keeps happening.",
+  stdoutIsATerminal: (flag) => `Stdout is a terminal, so the JPEG bytes would have nowhere to go. Redirect stdout to a file or pipe it into a reader, or give ${flag} a file path instead of "-".`,
+  screenshotStdoutUnwritable: (detail) => `The screen was captured but could not be written to stdout: ${detail}. Keep the pipe reading stdout open, or give --out a file path instead of "-".`,
   screenshotUnwritable: (path, detail) => `The screen was captured but could not be written to "${path}": ${detail}. Give --out a path this process can write to.`,
   screenshotWritten: (path) => `Wrote the runner's screen to ${path}.`,
+  screenshotWrittenToStdout: "Wrote the runner's screen to stdout as a JPEG. Stdout holds the image bytes alone; this line, and the JSON with --json, is on stderr.",
   snippetEmpty: (path) => `"${path}" holds no code to evaluate.`,
   snippetErrored: (errorMessage) => errorMessage === undefined ? "The snippet threw and reported no message." : `The snippet threw: ${errorMessage}`,
   snippetFileUnreadable: (path) => `Could not read "${path}". Name a readable file, or "-" to read the snippet from stdin.`,
@@ -10553,19 +10566,38 @@ function isTimeoutError(err) {
 
 // src/shell/interactiveRunner/writeScreenshot.ts
 var jpegStartOfImage = [255, 216, 255];
+var stdoutPath = "-";
 async function writeScreenshot(options) {
   const bytes = Buffer.from(options.imageJpegBase64, "base64");
   if (jpegStartOfImage.some((byte, index) => bytes[index] !== byte)) {
     return { ok: false, reason: "not-a-jpeg" };
   }
   try {
-    await options.fs.mkdir(dirname3(options.path), { recursive: true });
-    await options.fs.writeFile(options.path, bytes);
+    if (options.path === stdoutPath) {
+      await writeToStdout(options.stdout ?? process.stdout, bytes);
+    } else {
+      await options.fs.mkdir(dirname3(options.path), { recursive: true });
+      await options.fs.writeFile(options.path, bytes);
+    }
   } catch (error) {
     return { detail: errorMessage(error), ok: false, reason: "unwritable" };
   }
   return { ok: true };
 }
+function writeToStdout(stdout, bytes) {
+  return new Promise((resolve, reject) => {
+    const onError = (error) => reject(error);
+    stdout.once("error", onError);
+    stdout.write(bytes, (error) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      stdout.off("error", onError);
+      resolve();
+    });
+  });
+}
 
 // src/shell/stdin.ts
 async function readStdin() {
@@ -12575,9 +12607,14 @@ function createPageVerbs({ platformClient }) {
   return {
     async act({
       action,
-      runnerId
+      runnerId,
+      withScreenshot
     }) {
-      return toSdkResult(await platformClient.callPublicApi(performAction, { action, id: runnerId }, runnerCallOptions));
+      return toSdkResult(await platformClient.callPublicApi(performAction, {
+        action,
+        id: runnerId,
+        ...withScreenshot === undefined ? {} : { withScreenshot }
+      }, runnerCallOptions));
     },
     async highlightSelector({
       highlight,
@@ -13177,4 +13214,4 @@ export {
   createRunnerSdk
 };
 
-//# debugId=1D5281D81CC3C81164756E2164756E21
+//# debugId=37E313924A61E7F564756E2164756E21

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.27.0",
   "description": "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   "keywords": [
     "automation",

package/skills/qawolf-cli/SKILL.md

@@ -187,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. |
@@ -210,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