@qawolf/cli 1.25.0 → 1.26.0

package/dist/cli.js

@@ -9083,25 +9083,32 @@ function exit(code, message, proc = process) {
   }
   return proc.exit(code);
 }
-function flushAndExit(code, proc = process, scheduleBackstop = (fn) => {
-  setTimeout(fn, 2000).unref();
+var backstopMs = 2000;
+function exitWhenIdle(code, proc = process, scheduleBackstop = (fn) => {
+  setTimeout(fn, backstopMs).unref();
 }) {
-  let exited = false;
-  const exitOnce = () => {
-    if (exited)
-      return;
-    exited = true;
-    proc.exit(code);
-  };
-  let pending = 2;
-  const onFlushed = () => {
-    pending -= 1;
-    if (pending === 0)
-      exitOnce();
+  proc.exitCode = code;
+  scheduleBackstop(() => proc.exit(code));
+}
+var signalExitCodes = {
+  SIGINT: 130,
+  SIGTERM: 143
+};
+var signalGraceMs = 150;
+function scheduleSignalGrace(fn) {
+  return setTimeout(fn, signalGraceMs);
+}
+function createSignalExit(deps) {
+  const proc = deps.proc ?? process;
+  const scheduleGrace = deps.scheduleGrace ?? scheduleSignalGrace;
+  let signalled = false;
+  return (signal) => () => {
+    const code = signalExitCodes[signal];
+    if (signalled)
+      proc.exit(code);
+    signalled = true;
+    deps.shutdown(signal).catch(() => {}).finally(() => exitWhenIdle(code, proc, scheduleGrace));
   };
-  proc.stdout.write("", onFlushed);
-  proc.stderr.write("", onFlushed);
-  scheduleBackstop(exitOnce);
 }
 
 // src/shell/fs.ts
@@ -16384,6 +16391,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({
@@ -16607,6 +16618,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."),
@@ -16634,10 +16647,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({
@@ -16784,10 +16798,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,
@@ -16871,20 +16886,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([
@@ -16894,11 +16915,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",
@@ -16924,9 +16948,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",
@@ -16945,9 +16971,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",
@@ -17050,10 +17078,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 {
@@ -17065,6 +17090,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;
@@ -17705,14 +17752,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"]
@@ -17738,9 +17802,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."),
@@ -17758,10 +17823,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({
@@ -17796,12 +17862,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") }),
@@ -17821,10 +17888,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."),
@@ -17838,9 +17906,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."),
@@ -17857,14 +17926,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",
@@ -17874,11 +17945,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") }),
@@ -17901,10 +17973,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") }),
@@ -17939,7 +18012,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"]
@@ -17991,9 +18065,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({
@@ -18012,13 +18087,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([
@@ -18072,6 +18148,7 @@ var makeContractsV1 = (ids) => {
       get: makeGetEmailContract(resolvedIds),
       getAttachment: makeGetEmailAttachmentContract(resolvedIds),
       listAddresses: makeListEmailAddressesContract(resolvedIds),
+      registerAddress: makeRegisterEmailAddressContract(resolvedIds),
       send: makeSendEmailContract(resolvedIds)
     },
     environment: {
@@ -18103,24 +18180,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),
@@ -18523,6 +18601,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) {
@@ -18539,8 +18645,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) {
@@ -18554,24 +18662,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)
@@ -20372,9 +20462,11 @@ var registryUrl = "https://registry.npmjs.org";
 var timeoutMs4 = 3000;
 async function fetchLatestVersion(packageName, deps = {}) {
   const fetchFn = deps.fetchFn ?? globalThis.fetch;
+  const deadline = AbortSignal.timeout(timeoutMs4);
+  const signal = deps.signal ? AbortSignal.any([deps.signal, deadline]) : deadline;
   try {
     const response = await fetchFn(`${registryUrl}/${packageName}/latest`, {
-      signal: AbortSignal.timeout(timeoutMs4)
+      signal
     });
     if (!response.ok)
       return;
@@ -20423,14 +20515,16 @@ function startUpdateCheck(deps) {
   if (deps.env["QAWOLF_NO_UPDATE_CHECK"]) {
     return noopNotifier;
   }
+  const controller = new AbortController;
   let latest;
-  deps.fetchLatestVersion().then((version) => {
+  deps.fetchLatestVersion(controller.signal).then((version) => {
     latest = version;
   }, () => {
     return;
   });
   return {
     async notifyIfOutdated() {
+      controller.abort();
       if (latest === undefined)
         return;
       if (!isNewerVersion(deps.currentVersion, latest))
@@ -20457,7 +20551,7 @@ function startUpdateCheck(deps) {
 // package.json
 var package_default = {
   name: "@qawolf/cli",
-  version: "1.25.0",
+  version: "1.26.0",
   description: "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   keywords: [
     "automation",
@@ -20528,7 +20622,7 @@ var package_default = {
     "@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",
@@ -20594,7 +20688,7 @@ function buildBaseContext(command, signals) {
     currentVersion: package_default.version,
     configDir: getConfigDir(),
     fs,
-    fetchLatestVersion: () => fetchLatestVersion(package_default.name),
+    fetchLatestVersion: (signal) => fetchLatestVersion(package_default.name, { signal }),
     renderNotice: (body, title) => ui.note(body, title)
   });
   return {
@@ -34541,21 +34635,12 @@ function createProgram({
 
 // src/main.ts
 var signals = createSignalRegistry();
-var forced = false;
-var onSignal = (sig) => () => {
-  const code = sig === "SIGINT" ? 130 : 143;
-  if (forced)
-    process.exit(code);
-  forced = true;
-  signals.shutdown(sig).finally(() => {
-    process.exit(code);
-  });
-};
+var onSignal = createSignalExit({ shutdown: (sig) => signals.shutdown(sig) });
 process.on("SIGINT", onSignal("SIGINT"));
 process.on("SIGTERM", onSignal("SIGTERM"));
 createProgram({ signals }).parseAsync().catch(() => {
   if (process.exitCode === undefined)
     process.exitCode = 1;
-}).finally(() => flushAndExit(typeof process.exitCode === "number" ? process.exitCode : 0));
+}).finally(() => exitWhenIdle(typeof process.exitCode === "number" ? process.exitCode : 0));
 
-//# debugId=DA8D4A9E373CFE5C64756E2164756E21
+//# debugId=D197CB13AEBF087464756E2164756E21

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),
@@ -12323,6 +12394,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 +12438,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 +12455,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)
@@ -13094,4 +13177,4 @@ export {
   createRunnerSdk
 };
 
-//# debugId=DD6DEC33C9C6693F64756E2164756E21
+//# debugId=1D5281D81CC3C81164756E2164756E21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qawolf/cli",
-  "version": "1.25.0",
+  "version": "1.26.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",

package/skills/qawolf-cli/SKILL.md

@@ -125,8 +125,8 @@ that `url`; never guess a route and never send a repository link in its place.
 <!-- prettier-ignore -->
 | Command | Kind | What it does |
 | --- | --- | --- |
-| `qawolf agent get` | read | 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. |
-| `qawolf agent send` | write | 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. |
+| `qawolf agent get` | read | Monitor a QA Wolf AI session by reading its status and replies. After agent.send, share the returned session URL before monitoring. Wait 30 to 60 seconds between checks; do not call this in a tight loop. Replies accumulate, so compare them with what you have already seen. Continue monitoring silently when the status and replies are unchanged; do not narrate waiting, announce the next check, or ask whether to keep monitoring. Report only substantive new progress, questions, blockers, or the final outcome. A status of "waiting-for-you" means the last reply is a question the work is blocked on, and answering it with agent.send is what unblocks it. Surface an explicit request for user input even if the status still says "working". Include the session URL when reporting a blocker or final outcome. On "completed", stop status checks and verify the requested result before claiming success. For new flows, validation, publication in the target environment, and readiness are separate checks; a Git push or final reply does not prove the flow is active. If every requested result is verified but status remains "working", report the mismatch and stop monitoring. Stop on "failed" or "cancelled" and report any confirmed partial result. |
+| `qawolf agent send` | write | Start or continue work with the QA Wolf AI and return a live session URL to share with the user. Use it to cover a user journey, investigate a failing run, or fix a broken flow. This is the one verb that starts work from nothing: every other write acts on a flow, run or issue that already exists. Returns sessionId, status, and url as soon as the request is accepted; work can take minutes to tens of minutes. After each send, make the next action a normal user-visible assistant message containing the exact returned url, before any tool call or wait. Tool output and internal reasoning do not count as sharing the link. Do not run a timer or monitoring call alongside this send. Acceptance does not mean the work is complete. Then monitor the session with agent.get, reporting new progress, blockers, and the final outcome rather than unchanged status. Send here again to answer a question or add context to the same session. |
 | `qawolf auth login` | local | Authenticate with QA Wolf in a browser or with an API key |
 | `qawolf auth logout` | local | Remove stored credentials |
 | `qawolf auth switch` | local | Choose which workspace to work in |
@@ -137,6 +137,7 @@ that `url`; never guess a route and never send a repository link in its place.
 | `qawolf email get` | read | Read one email of the workspace, with its plain text and HTML bodies. Use it to pull a sign-in code or a verification link out of a message. |
 | `qawolf email getAttachment` | read | Read one attachment of a workspace email as base64 content, by file name or by position. email.get lists both. |
 | `qawolf email listAddresses` | read | List the workspace's inbox addresses, alphabetical. A flow can sign up with a plus-suffixed form of any of them, and email.find reads what arrives. |
+| `qawolf email registerAddress` | write | Register an inbox address for the workspace. Registering an address the workspace already has changes nothing. A refusal names the domains the workspace can use. |
 | `qawolf email send` | write | Send an email from one of the workspace's inbox addresses, for example to exercise a flow that reacts to incoming mail. Returns the sent email; read it back with email.get. |
 | `qawolf environment create` | write | Create an environment on the caller's team and return it in the environment.get shape. |
 | `qawolf environment deleteVariable` | write | Remove one environment variable by name. Succeeds whether or not the variable existed. |
@@ -168,6 +169,7 @@ that `url`; never guess a route and never send a repository link in its place.
 | `qawolf run find` | read | List an environment's recent runs, newest first. |
 | `qawolf run get` | read | Get a run's status, per-flow results, and links. |
 | `qawolf run reattempt` | write | Request new attempts for a run's flows, in the same run. A flow is eligible once its result is failed or canceled and QA Wolf's automatic retries have finished. A fully investigated run no longer accepts reattempts. Attempts run with the latest flow code. Poll run.get for results. |
+| `qawolf run stop` | write | Stop a run, including its queued flows and automatic retries. Stopping is asynchronous. Repeated requests are safe, and finished runs keep their results. A run that is still being created returns not found; retry once run.get returns the run. If run.get returns a different runId, use that ID. Poll run.get for results. |
 | `qawolf runner act` | write | Perform one raw action on a runner's screen: click, double_click, scroll, move, drag, keypress, navigate or type. Use - to read a whole action as JSON from stdin. On a mobile runner only click (button left), drag and type have a touchscreen equivalent; the rest answer action-not-supported-on-mobile |
 | `qawolf runner events` | read | Print a runner's journal, one entry per line. QA Wolf writes console, recorder, run-events, run-logs, run-status |
 | `qawolf runner exec` | write | Evaluate a snippet against a runner's live page. Use - to read the snippet from stdin |