@qawolf/cli 1.25.0 → 1.27.0

package/dist/runner-sdk.js

@@ -6993,6 +6993,10 @@ var makeEmailResourceSchema = () => resource({
   replyTo: array(namedAddressSchema).optional(),
   text: string2().optional().describe("The plain text body.")
 }, { urlFieldDescription: emailUrlFieldDescription });
+var makeEmailAddressResourceSchema = () => resource({
+  address: string2().describe("The inbox address. Mail sent to any plus-suffixed form, such as inbox+abc@example.com, lands in the same inbox."),
+  isDefault: boolean2().describe("Whether this is the workspace's default inbox address.")
+}, { urlFieldDescription: emailUrlFieldDescription });
 
 // node_modules/@qawolf/api-contracts/dist/v1/identity/organization.js
 var identityOrganization = object({
@@ -7217,6 +7221,8 @@ var runnerNameSchema = _enum([
   "android",
   "ios"
 ]);
+var runnerWorkspaceRequirement = "Required when the credential is not bound to a single workspace, such as a user API key or an OAuth connection whose organization owns several.";
+var runnerWorkspaceIdDescription = `The workspace the runner belongs to. ${runnerWorkspaceRequirement}`;
 var runnerIdSchema = string2().min(1).max(63).regex(/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/, "A runner id may contain only lowercase letters, digits and dashes, and must start and end with a letter or digit.");
 var makeRunnerSchema = () => object({
   gpuAccelerated: boolean2().describe("Whether the runner was placed on GPU hardware. Chosen by QA Wolf from the team's configuration and what the fleet can provide, not requested."),
@@ -7245,10 +7251,11 @@ var inspectRequestSchema = discriminatedUnion("what", [
     what: literal("variable")
   })
 ]);
-var makeInspectOnRunnerContract = () => {
+var makeInspectOnRunnerContract = (ids) => {
   const input = object({
     id: runnerIdSchema.describe("Id of the runner to inspect."),
-    request: inspectRequestSchema
+    request: inspectRequestSchema,
+    workspaceId: ids.workspace.optional().describe(runnerWorkspaceIdDescription)
   });
   const output = discriminatedUnion("outcome", [
     object({
@@ -7396,10 +7403,11 @@ var inspectMobileAnswerSchema = discriminatedUnion("what", [
     what: literal("elements")
   })
 ]);
-var makeInspectMobileOnRunnerContract = () => {
+var makeInspectMobileOnRunnerContract = (ids) => {
   const input = object({
     id: runnerIdSchema.describe("Id of the runner to inspect."),
-    request: inspectMobileRequestSchema
+    request: inspectMobileRequestSchema,
+    workspaceId: ids.workspace.optional().describe(runnerWorkspaceIdDescription)
   });
   const output = discriminatedUnion("outcome", [
     inspectMobileAnswerSchema,
@@ -7485,20 +7493,26 @@ var screenFailureReasons = [
 var screenNotReadyDescription = "`screen-not-ready` if the runner has a screen that cannot serve this instant. Retry in a second or two: the desktop restarts when a run changes the display size, and it serves one see-or-act request at a time, so a screenshot or action already in flight is the usual reason. Do not submit a run to clear this — a run may restart the display and discard what is on it.";
 var screenNeedsARunDescription = "`screen-needs-a-run` if the runner's virtual desktop has never started. Waiting will not change this and retrying is pointless — call `runner.runFlow` with a flow that opens a browser, then ask for the screen again. On a runner image with a browser that has never run anything, any `runner.performAction` also starts the browser itself. Evaluating a snippet does not start the desktop.";
 var runnerHasNoScreenDescription = "`runner-has-no-screen` if this runner is not one that runs a browser on a virtual desktop. Nothing about it can be seen or driven, and retrying will never help — launch a `playwright` runner instead.";
+var screenshotImageSchema = string2().min(1).describe("The screenshot, as a base64-encoded JPEG. Decode it and write the bytes to a `.jpg` file — writing this string to the file leaves you with base64 text rather than an image.");
 
 // node_modules/@qawolf/api-contracts/dist/v1/runner/performAction.js
 var unreachableDescription = "`runner-unreachable` if the runner could not be reached: it may still be starting, it may have terminated after inactivity, or it may have stopped answering mid-action. This does not mean the action was not performed — take a screenshot before repeating it.";
 var notSupportedOnMobileDescription = "`action-not-supported-on-mobile` if the runner is a mobile device and this action has no touchscreen equivalent: `double_click`, `scroll`, `move`, `keypress` and `navigate`, and a `click` whose `button` is not `left`, are all pointer-device concepts a touchscreen has nothing to offer for. `click` taps, `drag` swipes between its path's first and last point, and `type` types into whatever the last tap focused.";
+var withScreenshotDescription = "With `withScreenshot: true`, the answer also carries `imageJpegBase64`: a screenshot taken after the action, once the screen has changed from just before it or half a second has passed, whichever comes first. One call instead of `runner.performAction` followed by `runner.takeScreenshot`, with no fixed wait in between. Anything animating on the page counts as a change. The action itself is performed exactly as without the option; if the screen could serve no frame after it — a display restart, or a `navigate` on a desktop that is still starting — the action's result comes back without `imageJpegBase64`, so take a screenshot separately rather than repeating the action. On a mobile runner the screenshot is the device's own, taken right after a performed action.";
 var maxActionErrorMessageLength = 1000;
-var makePerformActionOnRunnerContract = () => {
+var makePerformActionOnRunnerContract = (ids) => {
   const input = object({
     action: browserActionSchema.describe("The action to perform. Coordinates are pixels on the screenshot's own coordinate space."),
-    id: runnerIdSchema.describe("Id of the runner to act on.")
+    id: runnerIdSchema.describe("Id of the runner to act on."),
+    withScreenshot: boolean2().optional().describe("Also answer with a screenshot taken after the action, once the screen has changed or half a second has passed. Saves the separate `runner.takeScreenshot` call and its fixed wait."),
+    workspaceId: ids.workspace.optional().describe(runnerWorkspaceIdDescription)
   });
+  const screenshotAfterAction = screenshotImageSchema.optional();
   const failure = discriminatedUnion("failureReason", [
     object({
       errorMessage: string2().max(maxActionErrorMessageLength).describe("What stopped the action from taking effect."),
       failureReason: literal("action-failed"),
+      imageJpegBase64: screenshotAfterAction,
       outcome: literal("failure")
     }),
     makeRunnerFailureSchema([
@@ -7508,11 +7522,14 @@ var makePerformActionOnRunnerContract = () => {
     ])
   ]);
   const output = discriminatedUnion("outcome", [
-    object({ outcome: literal("success") }),
+    object({
+      imageJpegBase64: screenshotAfterAction,
+      outcome: literal("success")
+    }),
     failure
   ]);
   return {
-    description: `Perform one raw browser action on an interactive runner: click, double_click, move, drag, scroll, keypress, type, or navigate. Coordinates are whole pixels on the runner's virtual desktop, in the same space as \`runner.takeScreenshot\`. One action per request, and the runner serves one at a time. The action shapes follow the computer-use vocabulary, minus \`screenshot\` (use \`runner.takeScreenshot\`) and \`wait\` (delay on the caller's side). A success means the action took effect. \`action-failed\`, with a reason, if it reached the runner and did not take effect. On a runner image with a browser, the first action on a runner that has never run anything starts its browser and waits for it, so it can take up to a minute to answer — no \`runner.runFlow\` is needed before acting; if the browser is still starting when the wait runs out, the answer is \`screen-not-ready\` and retrying converges. On a mobile runner, the same \`screen-needs-a-run\` and \`screen-not-ready\` outcomes mean no Appium session has started yet, or it did not answer this instant; \`runner.runFlow\` is what starts one, same as a browser. \`screen-needs-a-run\` if the browser could not be started that way — usually a runner whose runs all finished without starting its desktop; call \`runner.runFlow\` with a flow that opens a browser. ${screenNotReadyDescription} A \`navigate\` does not go through the screen, so a screen that is not ready does not stop it. ${runnerHasNoScreenDescription} ${notSupportedOnMobileDescription} ${unreachableDescription}`,
+    description: `Perform one raw browser action on an interactive runner: click, double_click, move, drag, scroll, keypress, type, or navigate. Coordinates are whole pixels on the runner's virtual desktop, in the same space as \`runner.takeScreenshot\`. One action per request, and the runner serves one at a time. The action shapes follow the computer-use vocabulary, minus \`screenshot\` (use \`runner.takeScreenshot\`) and \`wait\` (delay on the caller's side). A success means the action took effect. \`action-failed\`, with a reason, if it reached the runner and did not take effect. On a runner image with a browser, the first action on a runner that has never run anything starts its browser and waits for it, so it can take up to a minute to answer — no \`runner.runFlow\` is needed before acting; if the browser is still starting when the wait runs out, the answer is \`screen-not-ready\` and retrying converges. On a mobile runner, the same \`screen-needs-a-run\` and \`screen-not-ready\` outcomes mean no Appium session has started yet, or it did not answer this instant; \`runner.runFlow\` is what starts one, same as a browser. \`screen-needs-a-run\` if the browser could not be started that way — usually a runner whose runs all finished without starting its desktop; call \`runner.runFlow\` with a flow that opens a browser. ${screenNotReadyDescription} A \`navigate\` does not go through the screen, so a screen that is not ready does not stop it. ${runnerHasNoScreenDescription} ${notSupportedOnMobileDescription} ${withScreenshotDescription} ${unreachableDescription}`,
     input,
     kind: "write",
     name: "runner.performAction",
@@ -7538,9 +7555,11 @@ var makeAgentGetContract = (ids) => {
     replies: array(agentReplySchema).describe("Everything the AI has said so far, oldest first. A reply carrying choices is a question the work is blocked on."),
     sessionId: ids.chatSession,
     status: agentSessionStatusSchema
-  }, { urlFieldDescription: "Absolute URL of the session in the QA Wolf app." });
+  }, {
+    urlFieldDescription: "Absolute URL of the live session in the QA Wolf app."
+  });
   return {
-    description: 'Read what the QA Wolf AI has said and whether it is still working. Poll this after agent.send until the status settles. A status of "waiting-for-you" means the last reply is a question the work is blocked on, and answering it with agent.send is what unblocks it. Replies accumulate, so a caller that polls repeatedly sees the earlier ones again.',
+    description: '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.',
     input,
     kind: "read",
     name: "agent.get",
@@ -7559,9 +7578,11 @@ var makeAgentSendContract = (ids) => {
   const output = resource({
     sessionId: ids.chatSession.describe("Follow the work by passing this to agent.get."),
     status: agentSessionStatusSchema
-  }, { urlFieldDescription: "Absolute URL of the session in the QA Wolf app." });
+  }, {
+    urlFieldDescription: "Absolute URL of the live session in the QA Wolf app."
+  });
   return {
-    description: "Ask the QA Wolf AI to do a piece of work in plain language, such as covering a user journey, investigating a failing run, or fixing a broken flow. This is the one verb that starts work from nothing: every other write acts on a flow, run or issue that already exists. Answers as soon as the request is accepted, with the id to follow it by, because the work runs for minutes to tens of minutes. Poll agent.get for progress, and send here again to answer a question or add context to work already running.",
+    description: "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.",
     input,
     kind: "write",
     name: "agent.send",
@@ -7664,10 +7685,7 @@ var makeListEmailAddressesContract = (ids) => {
     ...makePaginationInputFields({ defaultLimit: 20, maxLimit: 50 })
   });
   const output = object({
-    addresses: array(resource({
-      address: string2().describe("The inbox address. Mail sent to any plus-suffixed form, such as inbox+abc@example.com, lands in the same inbox."),
-      isDefault: boolean2().describe("Whether this is the workspace's default inbox address.")
-    }, { urlFieldDescription: emailUrlFieldDescription })).describe("The workspace's permanent inbox addresses, alphabetical."),
+    addresses: array(makeEmailAddressResourceSchema()).describe("The workspace's permanent inbox addresses, alphabetical."),
     nextCursor: nextCursorSchema
   });
   return {
@@ -7679,6 +7697,28 @@ var makeListEmailAddressesContract = (ids) => {
   };
 };
 
+// node_modules/@qawolf/api-contracts/dist/v1/email/registerAddress.js
+var hasNoPlusSuffix = (address) => {
+  const [localPart] = address.split("@");
+  return localPart !== undefined && !localPart.includes("+");
+};
+var makeRegisterEmailAddressContract = (ids) => {
+  const input = object({
+    address: email2().refine(hasNoPlusSuffix, {
+      message: "Register the base address. Mail to a plus-suffixed form lands in the base inbox."
+    }).describe("The inbox address to register. Its domain must be one QA Wolf serves for the workspace."),
+    workspaceId: ids.workspace.optional().describe("The workspace to register the address in. Required when authenticating with an organization or user API key.")
+  });
+  const output = makeEmailAddressResourceSchema();
+  return {
+    description: "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.",
+    input,
+    kind: "write",
+    name: "email.registerAddress",
+    output
+  };
+};
+
 // node_modules/@qawolf/api-contracts/dist/v1/email/send.js
 var recipientsSchema = array(email2()).max(50);
 var maxAttachments = 10;
@@ -8319,14 +8359,31 @@ var makeReattemptRunContract = (ids) => {
   };
 };
 
+// node_modules/@qawolf/api-contracts/dist/v1/run/stop.js
+var makeStopRunContract = (ids) => {
+  const input = object({ runId: ids.run });
+  const output = resource({
+    runId: ids.run,
+    status: _enum(["accepted", "already-finished", "execution-not-found"]).describe('"accepted" means stopping was requested; poll run.get for the final result. "already-finished" means the run has already finished and its result is unchanged. "execution-not-found" means the run exists but no execution was found to stop; it may still be starting or may no longer be available. No stop request was accepted in that case.')
+  }, { urlFieldDescription: "Absolute URL of the run page." });
+  return {
+    description: "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.",
+    input,
+    kind: "write",
+    name: "run.stop",
+    output
+  };
+};
+
 // node_modules/@qawolf/api-contracts/dist/v1/runner/evaluateSnippet.js
 var maxSnippetCodeLength = 64 * 1024;
-var makeEvaluateSnippetOnRunnerContract = () => {
+var makeEvaluateSnippetOnRunnerContract = (ids) => {
   const input = object({
     code: string2().min(1).max(maxSnippetCodeLength).describe("The code to evaluate against the runner's live page, in the scope of `filePath` when one is given."),
     filePath: runFilePathSchema.optional().describe("Path of the file the snippet is evaluated in the scope of. Omit to evaluate a snippet that imports nothing of yours."),
     files: runFilesSchema.optional().describe("The file named by `filePath` and everything it imports. A runner holds no copy of your project, so a snippet's scope has to travel with it."),
-    id: runnerIdSchema.describe("Id of the runner to evaluate the snippet on.")
+    id: runnerIdSchema.describe("Id of the runner to evaluate the snippet on."),
+    workspaceId: ids.workspace.optional().describe(runnerWorkspaceIdDescription)
   }).refine((request) => request.filePath === undefined || Object.hasOwn(request.files ?? {}, request.filePath), {
     error: "A snippet naming a file must carry that file in files.",
     path: ["files"]
@@ -8352,9 +8409,10 @@ var makeEvaluateSnippetOnRunnerContract = () => {
 };
 
 // node_modules/@qawolf/api-contracts/dist/v1/runner/get.js
-var makeGetRunnerContract = () => {
+var makeGetRunnerContract = (ids) => {
   const input = object({
-    id: runnerIdSchema.describe("Id of the runner to look up.")
+    id: runnerIdSchema.describe("Id of the runner to look up."),
+    workspaceId: ids.workspace.optional().describe(runnerWorkspaceIdDescription)
   });
   const output = object({
     id: runnerIdSchema.describe("Id of the runner the call addressed."),
@@ -8372,10 +8430,11 @@ var makeGetRunnerContract = () => {
 
 // node_modules/@qawolf/api-contracts/dist/v1/runner/highlightSelector.js
 var maxHighlightSelectorLength = 2000;
-var makeHighlightSelectorOnRunnerContract = () => {
+var makeHighlightSelectorOnRunnerContract = (ids) => {
   const input = object({
     id: runnerIdSchema.describe("Id of the runner to highlight on."),
-    selector: string2().max(maxHighlightSelectorLength).describe("The selector to highlight. An empty string clears whatever is highlighted.")
+    selector: string2().max(maxHighlightSelectorLength).describe("The selector to highlight. An empty string clears whatever is highlighted."),
+    workspaceId: ids.workspace.optional().describe(runnerWorkspaceIdDescription)
   });
   const output = discriminatedUnion("outcome", [
     object({
@@ -8410,12 +8469,13 @@ var makeHighlightSelectorOnRunnerContract = () => {
 // node_modules/@qawolf/api-contracts/dist/v1/runner/importPackage.js
 var maxPackageNameLength = 214;
 var maxPackageVersionLength = 256;
-var makeImportPackageOnRunnerContract = () => {
+var makeImportPackageOnRunnerContract = (ids) => {
   const input = object({
     id: runnerIdSchema.describe("Id of the runner to install into."),
     npmDependencies: record(string2(), string2()).describe("The run's current npm dependencies, so the install resolves against them."),
     packageName: string2().min(1).max(maxPackageNameLength),
-    packageVersion: string2().min(1).max(maxPackageVersionLength)
+    packageVersion: string2().min(1).max(maxPackageVersionLength),
+    workspaceId: ids.workspace.optional().describe(runnerWorkspaceIdDescription)
   });
   const output = discriminatedUnion("outcome", [
     object({ outcome: literal("success") }),
@@ -8435,10 +8495,11 @@ var makeImportPackageOnRunnerContract = () => {
 };
 
 // node_modules/@qawolf/api-contracts/dist/v1/runner/index.js
-var makeLaunchRunnerContract = () => {
+var makeLaunchRunnerContract = (ids) => {
   const input = object({
     id: runnerIdSchema.describe("Id to launch the runner under, chosen by the caller. Launching the same id again returns the runner already running under it."),
-    runnerName: runnerNameSchema.optional().describe("The runner family to launch. Defaults to the standard web family, playwright.")
+    runnerName: runnerNameSchema.optional().describe("The runner family to launch. Defaults to the standard web family, playwright."),
+    workspaceId: ids.workspace.optional().describe(`The workspace to launch the runner in. ${runnerWorkspaceRequirement}`)
   });
   const output = makeRunnerSchema().extend({
     alreadyRunning: boolean2().describe("True when a runner was already running under this id and was returned unchanged, so no second runner was started and nothing new is billed. Not an error either way."),
@@ -8452,9 +8513,10 @@ var makeLaunchRunnerContract = () => {
     output
   };
 };
-var makeTerminateRunnerContract = () => {
+var makeTerminateRunnerContract = (ids) => {
   const input = object({
-    id: runnerIdSchema.describe("Id of the runner to terminate.")
+    id: runnerIdSchema.describe("Id of the runner to terminate."),
+    workspaceId: ids.workspace.optional().describe(runnerWorkspaceIdDescription)
   });
   const output = object({
     id: runnerIdSchema.describe("Id of the runner the call addressed."),
@@ -8471,14 +8533,16 @@ var makeTerminateRunnerContract = () => {
 };
 
 // node_modules/@qawolf/api-contracts/dist/v1/runner/list.js
-var makeListRunnersContract = () => {
-  const input = object({});
+var makeListRunnersContract = (ids) => {
+  const input = object({
+    workspaceId: ids.workspace.optional().describe(`The workspace whose runners to list. ${runnerWorkspaceRequirement}`)
+  });
   const output = object({
     outcome: literal("success"),
     runners: array(makeRunnerSchema()).describe("The runners running right now, in no particular order. Each entry carries the same fields a launch reports, so any of them can be addressed like a runner you launched yourself.")
   });
   return {
-    description: "List the runners running on the caller's team right now. Takes no arguments: the API key already names the team. A runner that was terminated, or that terminated on its own after inactivity, is not listed, because the run system keeps no record of a runner once it is gone. This is a lookup: it never starts a runner, and it does not reset a runner's inactivity clock the way reading its journal does. It is how to find a runner launched from another machine or in an earlier session, when the id it was launched under is no longer at hand.",
+    description: "List the runners running on the caller's team right now. A team API key already names the team and sends nothing; a credential bound to no single workspace names one in `workspaceId`. A runner that was terminated, or that terminated on its own after inactivity, is not listed, because the run system keeps no record of a runner once it is gone. This is a lookup: it never starts a runner, and it does not reset a runner's inactivity clock the way reading its journal does. It is how to find a runner launched from another machine or in an earlier session, when the id it was launched under is no longer at hand.",
     input,
     kind: "read",
     name: "runner.list",
@@ -8488,11 +8552,12 @@ var makeListRunnersContract = () => {
 
 // node_modules/@qawolf/api-contracts/dist/v1/runner/promoteSnapshot.js
 var maxSnapshotPathLength = 1024;
-var makePromoteSnapshotOnRunnerContract = () => {
+var makePromoteSnapshotOnRunnerContract = (ids) => {
   const input = object({
     baselinePath: string2().min(1).max(maxSnapshotPathLength).describe("The baseline to replace, as named in the image diff."),
     id: runnerIdSchema.describe("Id of the runner holding the screenshot."),
-    screenshotPath: string2().min(1).max(maxSnapshotPathLength).describe("The screenshot to promote, as named in the image diff.")
+    screenshotPath: string2().min(1).max(maxSnapshotPathLength).describe("The screenshot to promote, as named in the image diff."),
+    workspaceId: ids.workspace.optional().describe(runnerWorkspaceIdDescription)
   });
   const output = discriminatedUnion("outcome", [
     object({ outcome: literal("success") }),
@@ -8515,10 +8580,11 @@ var makePromoteSnapshotOnRunnerContract = () => {
 };
 
 // node_modules/@qawolf/api-contracts/dist/v1/runner/readJournal.js
-var makeReadRunnerJournalContract = () => {
+var makeReadRunnerJournalContract = (ids) => {
   const input = readJournalRequestSchema.extend({
     id: runnerIdSchema.describe("Id of the runner to read the journal of."),
-    stream: journalStreamSchema.describe(`The stream to read. QA Wolf writes ${knownJournalStreams.join(", ")}; an unwritten stream reads as empty rather than as an error.`)
+    stream: journalStreamSchema.describe(`The stream to read. QA Wolf writes ${knownJournalStreams.join(", ")}; an unwritten stream reads as empty rather than as an error.`),
+    workspaceId: ids.workspace.optional().describe(runnerWorkspaceIdDescription)
   });
   const output = discriminatedUnion("outcome", [
     readJournalResponseSchema.extend({ outcome: literal("success") }),
@@ -8553,7 +8619,8 @@ var makeRunFlowOnRunnerContract = (ids) => {
     files: runFilesSchema.describe("Every file the run needs keyed by its path — the flow file, everything it imports, package.json and tsconfig.json. A runner holds no copy of your project, so what runs is exactly what is sent here."),
     id: runnerIdSchema.describe("Id of the runner to run the flow on."),
     selection: runSelectionSchema.optional().describe("Run only these lines, inside the page the runner is already on, instead of running the whole flow from a fresh browser. Omit to run the whole entry point."),
-    unchangedFiles: unchangedFilesSchema.optional().describe("Files this runner already holds from an earlier run, keyed by path with a hex SHA-256 of the content it should hold. Send this to make `files` only what changed. The runner refuses with `needs-full-sync` if it holds none of a referenced path, so it never runs something other than what was asked for. Omit it to send every file.")
+    unchangedFiles: unchangedFilesSchema.optional().describe("Files this runner already holds from an earlier run, keyed by path with a hex SHA-256 of the content it should hold. Send this to make `files` only what changed. The runner refuses with `needs-full-sync` if it holds none of a referenced path, so it never runs something other than what was asked for. Omit it to send every file."),
+    workspaceId: ids.workspace.optional().describe(runnerWorkspaceIdDescription)
   }).refine((request) => request.env === undefined || request.environmentId === undefined, {
     error: "Send env or environmentId, not both. An environment's variables are taken as they are stored, so there is no order in which the two would combine.",
     path: ["environmentId"]
@@ -8605,9 +8672,10 @@ var makeRunFlowOnRunnerContract = (ids) => {
 };
 
 // node_modules/@qawolf/api-contracts/dist/v1/runner/stopRun.js
-var makeStopRunOnRunnerContract = () => {
+var makeStopRunOnRunnerContract = (ids) => {
   const input = object({
-    id: runnerIdSchema.describe("Id of the runner to stop the run on.")
+    id: runnerIdSchema.describe("Id of the runner to stop the run on."),
+    workspaceId: ids.workspace.optional().describe(runnerWorkspaceIdDescription)
   });
   const output = discriminatedUnion("outcome", [
     object({
@@ -8626,13 +8694,14 @@ var makeStopRunOnRunnerContract = () => {
 };
 
 // node_modules/@qawolf/api-contracts/dist/v1/runner/takeScreenshot.js
-var makeTakeScreenshotOnRunnerContract = () => {
+var makeTakeScreenshotOnRunnerContract = (ids) => {
   const input = object({
-    id: runnerIdSchema.describe("Id of the runner to take a screenshot of.")
+    id: runnerIdSchema.describe("Id of the runner to take a screenshot of."),
+    workspaceId: ids.workspace.optional().describe(runnerWorkspaceIdDescription)
   });
   const output = discriminatedUnion("outcome", [
     object({
-      imageJpegBase64: string2().min(1).describe("The screenshot, as a base64-encoded JPEG. Decode it and write the bytes to a `.jpg` file — writing this string to the file leaves you with base64 text rather than an image."),
+      imageJpegBase64: screenshotImageSchema,
       outcome: literal("success")
     }),
     makeRunnerFailureSchema([
@@ -8686,6 +8755,7 @@ var makeContractsV1 = (ids) => {
       get: makeGetEmailContract(resolvedIds),
       getAttachment: makeGetEmailAttachmentContract(resolvedIds),
       listAddresses: makeListEmailAddressesContract(resolvedIds),
+      registerAddress: makeRegisterEmailAddressContract(resolvedIds),
       send: makeSendEmailContract(resolvedIds)
     },
     environment: {
@@ -8717,24 +8787,25 @@ var makeContractsV1 = (ids) => {
       diagnose: makeDiagnoseRunContract(resolvedIds),
       find: makeFindRunsContract(resolvedIds),
       get: makeGetRunContract(resolvedIds),
-      reattempt: makeReattemptRunContract(resolvedIds)
+      reattempt: makeReattemptRunContract(resolvedIds),
+      stop: makeStopRunContract(resolvedIds)
     },
     runner: {
-      evaluateSnippet: makeEvaluateSnippetOnRunnerContract(),
-      get: makeGetRunnerContract(),
-      highlightSelector: makeHighlightSelectorOnRunnerContract(),
-      importPackage: makeImportPackageOnRunnerContract(),
-      inspect: makeInspectOnRunnerContract(),
-      inspectMobile: makeInspectMobileOnRunnerContract(),
-      launch: makeLaunchRunnerContract(),
-      list: makeListRunnersContract(),
-      performAction: makePerformActionOnRunnerContract(),
-      promoteSnapshot: makePromoteSnapshotOnRunnerContract(),
-      readJournal: makeReadRunnerJournalContract(),
+      evaluateSnippet: makeEvaluateSnippetOnRunnerContract(resolvedIds),
+      get: makeGetRunnerContract(resolvedIds),
+      highlightSelector: makeHighlightSelectorOnRunnerContract(resolvedIds),
+      importPackage: makeImportPackageOnRunnerContract(resolvedIds),
+      inspect: makeInspectOnRunnerContract(resolvedIds),
+      inspectMobile: makeInspectMobileOnRunnerContract(resolvedIds),
+      launch: makeLaunchRunnerContract(resolvedIds),
+      list: makeListRunnersContract(resolvedIds),
+      performAction: makePerformActionOnRunnerContract(resolvedIds),
+      promoteSnapshot: makePromoteSnapshotOnRunnerContract(resolvedIds),
+      readJournal: makeReadRunnerJournalContract(resolvedIds),
       runFlow: makeRunFlowOnRunnerContract(resolvedIds),
-      stopRun: makeStopRunOnRunnerContract(),
-      takeScreenshot: makeTakeScreenshotOnRunnerContract(),
-      terminate: makeTerminateRunnerContract()
+      stopRun: makeStopRunOnRunnerContract(resolvedIds),
+      takeScreenshot: makeTakeScreenshotOnRunnerContract(resolvedIds),
+      terminate: makeTerminateRunnerContract(resolvedIds)
     },
     tag: {
       create: makeCreateTagContract(resolvedIds),
@@ -9039,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.",
@@ -9051,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.`,
@@ -10482,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() {
@@ -12323,6 +12426,34 @@ async function writeTeamStorageAssets(args, deps) {
   }
 }
 
+// src/shell/platform/teamStorageMethods.ts
+function createTeamStorageMethods(trpc, deps, fs, getIdentity) {
+  async function list() {
+    if (deps.workspaceId !== undefined) {
+      return listTeamStorageFiles(trpc, { teamId: deps.workspaceId }, deps);
+    }
+    const identity = await getIdentity();
+    if (!identity.ok)
+      return identity;
+    if (!("team" in identity.value)) {
+      return {
+        ok: false,
+        error: flowsMessages.pull.teamStorageRequiresTeamKey
+      };
+    }
+    return listTeamStorageFiles(trpc, { teamId: identity.value.team.id }, deps);
+  }
+  return {
+    listTeamStorageFiles: list,
+    async syncTeamStorageAssets(assetsAbs, opts) {
+      const files = await list();
+      if (!files.ok)
+        return files;
+      return downloadTeamStorageAssets({ assetsAbs, files: files.value }, { fetch: deps.fetch, fs, onProgress: opts?.onProgress });
+    }
+  };
+}
+
 // src/shell/platform/createPlatformClient.ts
 var requestBackoffMs2 = [500, 1500];
 function createPlatformClient(apiKey, deps) {
@@ -12339,8 +12470,10 @@ function createPlatformClient(apiKey, deps) {
       return result;
     return { ok: true, value: { signedUrl: result.value.url } };
   }
+  const identityMethods = createIdentityMethods(apiKey, deps, requestBackoffMs2);
   return {
-    ...createIdentityMethods(apiKey, deps, requestBackoffMs2),
+    ...identityMethods,
+    ...createTeamStorageMethods(trpc, deps, fs, identityMethods.getIdentity),
     getFlowsBundleUrl: getFlowsBundleUrlImpl,
     callPublicApi: makeCallPublicApiMethod(trpc, deps, requestBackoffMs2),
     async getEnvVars(envId) {
@@ -12354,24 +12487,6 @@ function createPlatformClient(apiKey, deps) {
         return result;
       return { ok: true, value: result.value.environmentVariables };
     },
-    async listTeamStorageFiles() {
-      const identity = await this.getIdentity();
-      if (!identity.ok)
-        return identity;
-      if (!("team" in identity.value)) {
-        return {
-          ok: false,
-          error: flowsMessages.pull.teamStorageRequiresTeamKey
-        };
-      }
-      return listTeamStorageFiles(trpc, { teamId: identity.value.team.id }, deps);
-    },
-    async syncTeamStorageAssets(assetsAbs, opts) {
-      const files = await this.listTeamStorageFiles();
-      if (!files.ok)
-        return files;
-      return downloadTeamStorageAssets({ assetsAbs, files: files.value }, { fetch: deps.fetch, fs, onProgress: opts?.onProgress });
-    },
     async downloadBundle(envId) {
       const urlResult = await getFlowsBundleUrlImpl(envId);
       if (!urlResult.ok)
@@ -12492,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,
@@ -13094,4 +13214,4 @@ export {
   createRunnerSdk
 };
 
-//# debugId=DD6DEC33C9C6693F64756E2164756E21
+//# 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.25.0",
+  "version": "1.27.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.47.0",
+    "@qawolf/api-contracts": "0.52.0",
     "@qawolf/emails": "1.1.1",
     "@qawolf/flow-targets": "1.0.0",
     "@qawolf/flows": "0.1.4",