@qawolf/cli 1.27.0 → 1.29.0

package/dist/cli.js

@@ -8805,6 +8805,7 @@ var interactMessages = {
   nothingToInspect: (errorMessage) => `The runner had nothing to inspect${errorMessage === undefined ? "" : `: ${errorMessage}`}. There is no live page, nothing matched the selector, or no variable has that name; a runner cannot tell those apart. Run a flow on it first, or check the selector or name.`,
   inspectAnsweredUnknown: (failureReason) => `The runner answered "${failureReason}", which this version of the CLI does not know how to report. Upgrade with npm install -g @qawolf/cli.`,
   inspectMobileAnsweredUnknown: (failureReason) => `The runner answered "${failureReason}", which this version of the CLI does not know how to report. Upgrade with npm install -g @qawolf/cli.`,
+  inspectMobileInvalidSelector: "The runner could not parse that selector under the strategy it was given. Retrying it unchanged will never help: correct the selector, or pick the strategy that matches it.",
   runnerIsNotMobile: "This runner is not a mobile device, so there is nothing here to inspect. Retrying will never help: launch an android or ios runner instead.",
   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.",
@@ -16409,6 +16410,72 @@ var makeEmailAddressResourceSchema = () => resource({
   isDefault: boolean2().describe("Whether this is the workspace's default inbox address.")
 }, { urlFieldDescription: emailUrlFieldDescription });
 
+// node_modules/@qawolf/api-contracts/dist/v1/file/path.js
+var uploadedFilePrefix = "uploads";
+var controlOrBackslash = /[\p{Cc}\\]/u;
+var shellMetacharacter = /["'`$;|&<>]/u;
+var segmentsOf = (path) => path.split("/");
+var teamStoragePathSchema = string2().min(1).max(200).refine((path) => !controlOrBackslash.test(path), "A path cannot carry control characters or a backslash.").refine((path) => !shellMetacharacter.test(path), "A path cannot carry a quote, a backtick, or any of $ ; | & < >. A reader passes the path to a shell, where those change what runs.").refine((path) => segmentsOf(path).every((segment) => segment.length > 0), "A path cannot start or end with a slash, or carry an empty segment.").refine((path) => segmentsOf(path).every((segment) => segment !== "." && segment !== ".."), "A path cannot climb out of the team's storage.").refine((path) => segmentsOf(path).every((segment) => segment.trim() === segment), "A path cannot have leading or trailing whitespace in a segment.");
+var uploadedFilePath = (fileName) => `${uploadedFilePrefix}/${fileName}`;
+var uploadedFileNameSchema = teamStoragePathSchema.refine((fileName) => teamStoragePathSchema.safeParse(uploadedFilePath(fileName)).success, `A name has to still be a valid path once it sits under \`${uploadedFilePrefix}/\`, which every other endpoint reads it back as.`);
+
+// node_modules/@qawolf/api-contracts/dist/v1/file/requestDownload.js
+var makeRequestFileDownloadContract = (ids) => {
+  const input = object({
+    filePath: teamStoragePathSchema.describe("The file's path in team storage, as file.requestUpload answered with."),
+    workspaceId: ids.workspace.optional().describe("The workspace the file belongs to. Required when authenticating with an organization or user API key.")
+  });
+  const output = object({
+    expiresAt: exports_iso.datetime().describe("When readUrl stops working. Request another one after it."),
+    path: string2().describe("The file's path in team storage."),
+    readUrl: string2().describe('Fetch the file\'s bytes from here, for example `curl -o journeys.csv "<readUrl>"`. Write it to a file and read that file, rather than printing the contents, so a large file costs one line of output instead of all of it.')
+  });
+  return {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: true
+    },
+    description: "Get a URL for reading a file out of the caller's team storage. Answers 404 when nothing is stored at that path.",
+    input,
+    kind: "read",
+    name: "file.requestDownload",
+    output
+  };
+};
+
+// node_modules/@qawolf/api-contracts/dist/v1/file/requestUpload.js
+var makeRequestFileUploadContract = (ids) => {
+  const input = object({
+    fileName: uploadedFileNameSchema.describe("What to call the file, such as `journeys.csv` or `q3/journeys.csv`. Spaces and non-ASCII are fine; backslashes, leading slashes and `..` segments are refused. The same name replaces the file."),
+    workspaceId: ids.workspace.optional().describe("The workspace to upload into. Required when authenticating with an organization or user API key.")
+  });
+  const output = object({
+    contentType: string2().describe("Send this as the PUT's `Content-Type` header, exactly. The URL is signed for it and refuses any other value."),
+    expiresAt: exports_iso.datetime().describe("When uploadUrl stops working. Request another one after it."),
+    path: string2().describe("Where the file lives in team storage. Send this to agent.send as a filePath, and the AI fetches it from there."),
+    uploadUrl: string2().describe(`Send the file's bytes here with a single HTTP PUT carrying the returned contentType, for example \`curl -H 'Content-Type: application/octet-stream' --upload-file "journeys.csv" "<uploadUrl>"\`. Upload the bytes from the shell rather than through this API, so a large file never has to be written out as text.`)
+  });
+  return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: false,
+      readOnlyHint: false
+    },
+    description: "Get a URL to put a file into team storage: a spreadsheet of journeys, anything too large to paste. PUT with the returned contentType, then name the path in filePaths.",
+    input,
+    kind: "write",
+    name: "file.requestUpload",
+    output
+  };
+};
+
+// node_modules/@qawolf/api-contracts/dist/v1/file/index.js
+var makeFileContracts = (ids) => ({
+  requestDownload: makeRequestFileDownloadContract(ids),
+  requestUpload: makeRequestFileUploadContract(ids)
+});
+
 // node_modules/@qawolf/api-contracts/dist/v1/identity/organization.js
 var identityOrganization = object({
   id: string2(),
@@ -16465,6 +16532,7 @@ var defaultIdSchemas = {
   flow: string2().min(1).describe("The id of the flow."),
   issue: string2().min(1).describe("The id of the issue."),
   run: string2().min(1).describe("The id of the run."),
+  trigger: string2().min(1).describe("The id of the trigger."),
   workspace: string2().min(1).describe("The id of the workspace.")
 };
 
@@ -16500,6 +16568,11 @@ var makeCreateRunContract = (ids) => {
     tracking: _enum(["registered", "failed", "not-requested"]).describe('Whether the conversation named by aiTaskId or chatSessionId will receive run status updates: "registered" when it will, "failed" when the run was created but the registration failed, "not-requested" when neither id was given or the AI task has no conversation to notify.')
   }, { urlFieldDescription: "Absolute URL of the run page." });
   return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: true,
+      readOnlyHint: false
+    },
     description: "Create a run for the selected flows and/or tags in an environment.",
     input,
     kind: "write",
@@ -16637,7 +16710,8 @@ var runnerIdSchema = string2().min(1).max(63).regex(/^[a-z0-9]([a-z0-9-]*[a-z0-9
 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."),
   id: runnerIdSchema.describe("The runner's id, as supplied when launching it."),
-  runnerName: runnerNameSchema.describe("The runner family requested when the runner was launched. QA Wolf may place it on faster hardware, reported in gpuAccelerated.")
+  runnerName: runnerNameSchema.describe("The runner family requested when the runner was launched. QA Wolf may place it on faster hardware, reported in gpuAccelerated."),
+  url: url().describe("A QA Wolf page showing what the runner is doing right now, where the person who launched it can watch and take over with their own mouse and keyboard. Opening it requires being signed in to QA Wolf.")
 });
 // node_modules/@qawolf/api-contracts/dist/v1/runner/unreachable.js
 var runnerUnreachableFailureReason = "runner-unreachable";
@@ -16682,7 +16756,12 @@ var makeInspectOnRunnerContract = (ids) => {
     })
   ]);
   return {
-    description: "Inspect one thing on an interactive runner: an element's HTML, the page's HTML simplified for a model, or a top-level variable's value as JSON. `nothing-to-inspect` means the runner had nothing to answer with: no live page, no element matching the selector, or no variable under that name. A runner cannot tell those apart, so it reports the one reason and puts whatever it did say in `errorMessage`. `runner-is-not-a-browser` on a mobile runner — call `runner.inspectMobile` for its equivalent surface instead. " + retryableRunnerUnreachableDescription,
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: false
+    },
+    description: "Inspect one thing on an interactive runner: an element's HTML, the page's HTML simplified for a model, or a top-level variable's value as JSON. This refreshes the inactivity timer and can extend the runner's billed lifetime. `nothing-to-inspect` means the runner had nothing to answer with: no live page, no element matching the selector, or no variable under that name. A runner cannot tell those apart, so it reports the one reason and puts whatever it did say in `errorMessage`. `runner-is-not-a-browser` on a mobile runner — call `runner.inspectMobile` for its equivalent surface instead. " + retryableRunnerUnreachableDescription,
     input,
     kind: "read",
     name: "runner.inspect",
@@ -16742,6 +16821,30 @@ function makeRunnerFailureSchema(reasons) {
 
 // node_modules/@qawolf/api-contracts/dist/v1/runner/inspectMobile.js
 var maxElementTextLength = 500;
+var selectorStrategySchema = _enum(["ios-predicate", "shadow", "xpath"]);
+var elementsRequestSchema = discriminatedUnion("by", [
+  object({
+    by: literal("point"),
+    context: string2().min(1).optional(),
+    what: literal("elements"),
+    x: int().min(0).describe("Whole pixels on the device's own screen."),
+    y: int().min(0).describe("Whole pixels on the device's own screen.")
+  }),
+  object({
+    by: literal("text"),
+    context: string2().min(1).optional(),
+    partial: boolean2().optional().describe("Match text containing this, rather than exactly this."),
+    text: string2().min(1).max(maxElementTextLength),
+    what: literal("elements")
+  }),
+  object({
+    by: literal("selector"),
+    context: string2().min(1).optional(),
+    selector: string2().min(1).max(maxSelectorLength).describe("Resolved the same way a screen object's own selector is."),
+    strategy: selectorStrategySchema.default("xpath"),
+    what: literal("elements")
+  })
+]).describe("Elements at a screen point, elements carrying some text, or the elements a selector resolves to.");
 var inspectMobileRequestSchema = discriminatedUnion("what", [
   object({
     what: literal("session").describe("The status of the Appium session driving the device: ready and what it is, or why not.")
@@ -16753,22 +16856,7 @@ var inspectMobileRequestSchema = discriminatedUnion("what", [
     context: string2().min(1).optional().describe("Read this context instead of whichever is current."),
     what: literal("page").describe("The page source of the device's current context, as a tree.")
   }),
-  discriminatedUnion("by", [
-    object({
-      by: literal("point"),
-      context: string2().min(1).optional(),
-      what: literal("elements"),
-      x: int().min(0).describe("Whole pixels on the device's own screen."),
-      y: int().min(0).describe("Whole pixels on the device's own screen.")
-    }),
-    object({
-      by: literal("text"),
-      context: string2().min(1).optional(),
-      partial: boolean2().optional().describe("Match text containing this, rather than exactly this."),
-      text: string2().min(1).max(maxElementTextLength),
-      what: literal("elements")
-    })
-  ]).describe("Elements at a screen point, or elements carrying some text — never both at once.")
+  elementsRequestSchema
 ]);
 var inspectMobileAnswerSchema = discriminatedUnion("what", [
   object({
@@ -16820,6 +16908,7 @@ var makeInspectMobileOnRunnerContract = (ids) => {
   const output = discriminatedUnion("outcome", [
     inspectMobileAnswerSchema,
     makeRunnerFailureSchema([
+      "invalid-selector",
       "runner-is-not-mobile",
       "screen-needs-a-run",
       "screen-not-ready",
@@ -16827,7 +16916,12 @@ var makeInspectMobileOnRunnerContract = (ids) => {
     ])
   ]);
   return {
-    description: `Inspect one thing on a mobile interactive runner: the Appium session's status, the WebView contexts available, the current context's page source, or the elements at a point or carrying some text. Mobile only — a browser runner answers \`runner-is-not-mobile\`; call \`runner.inspect\` for a browser's equivalent surface instead. \`what: "session"\` always answers with the session's own status rather than \`screen-needs-a-run\`, since that is the question it exists to answer; the other three request kinds need a live session first and answer the same \`screen-needs-a-run\` or \`screen-not-ready\` outcomes \`runner.performAction\` and \`runner.takeScreenshot\` use, instead of reading anything when there is none. \`screen-needs-a-run\` means no Appium session has started on this runner yet — call \`runner.runFlow\` with a flow that opens one, then inspect again. \`screen-not-ready\` means the runner's Appium session exists but did not answer this instant, or more than one is somehow live — retry once; if it persists, relaunch the runner. \`runner-is-not-mobile\` means there is nothing here to inspect, and retrying will never help — launch an \`android\` or \`ios\` runner instead. ${retryableRunnerUnreachableDescription}`,
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: true
+    },
+    description: `Inspect one thing on a mobile interactive runner: the Appium session's status, the WebView contexts available, the current context's page source, or the elements at a point, carrying some text, or matching a selector. This does not refresh the runner's inactivity timer. Mobile only — a browser runner answers \`runner-is-not-mobile\`; call \`runner.inspect\` for a browser's equivalent surface instead. \`what: "session"\` always answers with the session's own status rather than \`screen-needs-a-run\`, since that is the question it exists to answer; the other three request kinds need a live session first and answer the same \`screen-needs-a-run\` or \`screen-not-ready\` outcomes \`runner.performAction\` and \`runner.takeScreenshot\` use, instead of reading anything when there is none. \`screen-needs-a-run\` means no Appium session has started on this runner yet — call \`runner.runFlow\` with a flow that opens one, then inspect again. \`screen-not-ready\` means the runner's Appium session exists but did not answer this instant, or more than one is somehow live — retry once; if it persists, relaunch the runner. \`runner-is-not-mobile\` means there is nothing here to inspect, and retrying will never help — launch an \`android\` or \`ios\` runner instead. \`invalid-selector\` (elements by selector only) means the selector itself could not be parsed under the given \`strategy\` — distinct from a selector that parsed fine but matched nothing, which answers \`matches: []\` instead. ${retryableRunnerUnreachableDescription}`,
     input,
     kind: "read",
     name: "runner.inspectMobile",
@@ -16935,6 +17029,11 @@ var makePerformActionOnRunnerContract = (ids) => {
     failure
   ]);
   return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: true,
+      readOnlyHint: false
+    },
     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",
@@ -16952,20 +17051,90 @@ var runSelectionSchema = object({
   error: "A selection's startLine must not be after its endLine.",
   path: ["startLine"]
 });
+// node_modules/@qawolf/api-contracts/dist/v1/trigger/configuration.js
+var isTimezone = (value) => {
+  try {
+    Intl.DateTimeFormat("en-US", { timeZone: value });
+    return true;
+  } catch {
+    return false;
+  }
+};
+var triggerCadenceSchema = _enum(["hourly", "daily"]).describe("How often the schedule fires.");
+var triggerActionKindSchema = _enum(["createSuite", "generativeSuite"]).describe("createSuite runs the flows named by flowIds and tagNames. generativeSuite lets QA Wolf choose the flows from the deployment's changes, and is not available to a schedule.");
+var makeTriggerActionSchema = (ids) => object({
+  flowIds: array(ids.flow).default([]).describe("Flows to run. Combined with tagNames."),
+  instructions: string2().min(1).optional().describe("Guidance for QA Wolf. Applies to generativeSuite only."),
+  investigateFailures: boolean2().optional().describe("Whether QA Wolf investigates failures in the resulting runs. Defaults to true."),
+  kind: triggerActionKindSchema.default("createSuite"),
+  tagNames: array(string2().min(1)).default([]).describe("Tags naming the flows to run. Combined with flowIds.")
+}).describe("What the trigger runs when it fires.");
+var makeTriggerScheduleFields = (ids) => ({
+  action: makeTriggerActionSchema(ids),
+  cadence: triggerCadenceSchema,
+  environmentId: ids.environmentId.describe("The environment the scheduled runs happen in."),
+  minuteOfHour: number2().int().min(0).max(59).optional().describe("Minutes past the hour an hourly schedule fires. Defaults to 0."),
+  timeOfDay: string2().regex(/^([01]\d|2[0-3]):[0-5]\d$/).optional().describe('The wall clock time a daily schedule fires, as "HH:mm". Required when cadence is daily.'),
+  timezoneId: string2().min(1).refine(isTimezone, "Expected an IANA timezone, such as America/New_York.").optional().describe("The IANA timezone that timeOfDay is read in, such as America/New_York. Required when cadence is daily.")
+});
+var makeTriggerDeploymentFields = (ids) => ({
+  action: makeTriggerActionSchema(ids),
+  branchPattern: string2().min(1).optional().describe("Only fire for deployments of a branch matching this pattern."),
+  deployTargetPattern: string2().min(1).optional().describe("Only fire for deployments of an app matching this pattern. A deploy target names one app within an environment."),
+  environmentIds: array(ids.environment).default([]).describe("Only fire for deployments to these environments. Mutually exclusive with environmentPattern."),
+  environmentPattern: string2().min(1).optional().describe("Only fire for deployments to environments matching this pattern. Mutually exclusive with environmentIds.")
+});
+
+// node_modules/@qawolf/api-contracts/dist/v1/trigger/resource.js
+var makeTriggerConfigurationSchema = (ids) => discriminatedUnion("kind", [
+  object({
+    ...makeTriggerScheduleFields({
+      environmentId: ids.environment,
+      flow: ids.flow
+    }),
+    kind: literal("schedule")
+  }),
+  object({
+    ...makeTriggerDeploymentFields(ids),
+    kind: literal("deployment")
+  }),
+  object({
+    actionCount: number2().int().describe("How many actions it runs."),
+    kind: literal("advanced"),
+    whenCount: number2().int().describe("How many separate match conditions it has.")
+  })
+]);
+var makeTriggerResourceSchema = (ids) => resource({
+  configuration: makeTriggerConfigurationSchema(ids),
+  createdAt: exports_iso.datetime(),
+  id: ids.trigger,
+  isPaused: boolean2().describe("A paused trigger never fires, on any path."),
+  name: string2(),
+  nextScheduledAt: exports_iso.datetime().optional().describe("When a schedule trigger next fires. Absent for a deployment trigger, and while a schedule trigger is paused."),
+  pausedAt: exports_iso.datetime().optional().describe("When it was paused."),
+  updatedAt: exports_iso.datetime()
+}, { urlFieldDescription: "Absolute URL of the team's triggers page." });
 // node_modules/@qawolf/api-contracts/dist/v1/agent/get.js
 var makeAgentGetContract = (ids) => {
   const input = object({
+    cursor: string2().min(1).optional().describe("Opaque cursor copied from this same session's previous nextCursor. Omit to read from its first reply."),
     sessionId: ids.chatSession.describe("The id agent.send answered with.")
   });
   const output = resource({
-    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."),
+    nextCursor: string2().min(1).describe("Send back as cursor on the next check to read only what follows. Always present, even with no replies. Belongs to this session alone."),
+    replies: array(agentReplySchema).describe("What the AI has said since the cursor, oldest first. A reply still being written returns again, longer. A reply carrying choices is a question the work is blocked on."),
     sessionId: ids.chatSession,
     status: agentSessionStatusSchema
   }, {
     urlFieldDescription: "Absolute URL of the live session in the QA Wolf app."
   });
   return {
-    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.',
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: true
+    },
+    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. Pass the nextCursor from one response as the cursor on the next check; it then reads only what is new, and only for the session that minted it. Continue monitoring silently when the status is unchanged and no replies come back; do not narrate waiting, announce the next check, or ask whether to keep monitoring. Report only substantive new progress, questions, blockers, or the final outcome. A status of "waiting-for-you" means the last reply is a question the work is blocked on, and answering it with agent.send is what unblocks it. Surface an explicit request for user input even if the status still says "working". Include the session URL when reporting a blocker or final outcome. On "completed", stop status checks and verify the requested result before claiming success. For new flows, validation, publication in the target environment, and readiness are separate checks; a Git push or final reply does not prove the flow is active. If every requested result is verified but status remains "working", report the mismatch and stop monitoring. Stop on "failed" or "cancelled" and report any confirmed partial result.',
     input,
     kind: "read",
     name: "agent.get",
@@ -16977,6 +17146,7 @@ var makeAgentGetContract = (ids) => {
 var makeAgentSendContract = (ids) => {
   const input = object({
     environmentId: ids.environmentRef.optional().describe("The environment to work in. Omit to use the team's default environment. Ignored when sessionId is given, because a session keeps the environment it opened in."),
+    filePaths: array(teamStoragePathSchema).max(20).optional().describe("Paths of files this request is about, from file.requestUpload. The AI reads them from storage rather than the message, so a plan of hundreds of journeys costs nothing to send."),
     message: string2().trim().min(1).max(1e4).describe("What you want QA Wolf to do, in plain language. Name the journey, the part of the app it covers, and anything the AI cannot discover for itself, such as a test account, a feature flag, or how to reach a staging environment. When answering a question from agent.get, send the answer here."),
     sessionId: ids.chatSession.optional().describe("Continue the session with this id instead of opening a new one. Omit to start fresh. Send this to answer a question or to add context to work already running."),
     workspaceId: ids.workspace.optional().describe("The workspace to work in. Required when authenticating with an organization or user API key.")
@@ -16988,6 +17158,11 @@ var makeAgentSendContract = (ids) => {
     urlFieldDescription: "Absolute URL of the live session in the QA Wolf app."
   });
   return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: true,
+      readOnlyHint: false
+    },
     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",
@@ -17006,6 +17181,11 @@ var makeAutomateContract = (ids) => {
   });
   const output = resource({ automationId: ids.automation }, { urlFieldDescription: "Absolute URL of the automation review page." });
   return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: true,
+      readOnlyHint: false
+    },
     description: "Request automation for draft flows. First create a named local .flow.ts draft for every requested journey that does not already have a matching draft; never reuse a generic starter or placeholder. Each new draft must start with a JSDoc Goal: description, import flow from @qawolf/flows/web, and use export default flow(...); a comment-only file or direct test(...) call is not a valid draft. Commit and push all changes with Git to publish them, then list remote drafts to resolve every selected ID. Do not use patch to create or rename a selected flow. Finally make one automation request containing all requested flow IDs.",
     input,
     kind: "write",
@@ -17037,6 +17217,11 @@ var makeFindEmailsContract = (ids) => {
     nextCursor: nextCursorSchema
   });
   return {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: true
+    },
     description: "List the workspace's inbox, or its sent mail, newest first. Read a message body with email.get.",
     input,
     kind: "read",
@@ -17053,6 +17238,11 @@ var makeGetEmailContract = (ids) => {
   });
   const output = makeEmailResourceSchema();
   return {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: true
+    },
     description: "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.",
     input,
     kind: "read",
@@ -17076,6 +17266,11 @@ var makeGetEmailAttachmentContract = (ids) => {
     type: string2().optional().describe("The MIME type.")
   }, { urlFieldDescription: emailUrlFieldDescription });
   return {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: true
+    },
     description: "Read one attachment of a workspace email as base64 content, by file name or by position. email.get lists both.",
     input,
     kind: "read",
@@ -17095,6 +17290,11 @@ var makeListEmailAddressesContract = (ids) => {
     nextCursor: nextCursorSchema
   });
   return {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: true
+    },
     description: "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.",
     input,
     kind: "read",
@@ -17117,6 +17317,11 @@ var makeRegisterEmailAddressContract = (ids) => {
   });
   const output = makeEmailAddressResourceSchema();
   return {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: false
+    },
     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",
@@ -17150,6 +17355,11 @@ var makeSendEmailContract = (ids) => {
     urlFieldDescription: emailUrlFieldDescription
   });
   return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: true,
+      readOnlyHint: false
+    },
     description: "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.",
     input,
     kind: "write",
@@ -17168,6 +17378,11 @@ var makeDeleteEnvironmentVariableContract = (ids) => {
     name: string2().describe("The canonicalized name that was removed. Returned even when the environment had no such variable.")
   });
   return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: false,
+      readOnlyHint: false
+    },
     description: "Remove one environment variable by name. Succeeds whether or not the variable existed.",
     input,
     kind: "write",
@@ -17213,6 +17428,11 @@ var makeFindEnvironmentsContract = (ids) => {
     nextCursor: nextCursorSchema
   });
   return {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: true
+    },
     description: "List the team's environments, newest first.",
     input,
     kind: "read",
@@ -17235,6 +17455,11 @@ var makeGetEnvironmentVariableContract = (ids) => {
     })).describe("The found variables, sorted by name.")
   });
   return {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: true
+    },
     description: "Read the values of named environment variables in one call. Values are secrets. Names that do not exist go to missingNames and do not fail the call.",
     input,
     kind: "read",
@@ -17250,6 +17475,11 @@ var makeGetEnvironmentContract = (ids) => {
   });
   const output = makeEnvironmentResourceSchema(ids);
   return {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: true
+    },
     description: "Read a single environment's name, kind, standing run health, flow-code branch and reconciliation state, run concurrency limit, and termination state. If flowCodeBranch exists, use its syncStatus for Git reconciliation and read lastSyncedCommitHash only when syncStatus is reconciled.",
     input,
     kind: "read",
@@ -17265,6 +17495,11 @@ var makeListEnvironmentVariableNamesContract = (ids) => {
     variableNames: array(string2()).describe("Names of the environment's variables, sorted alphabetically. Values are never returned.")
   });
   return {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: true
+    },
     description: "Use this to answer which QA Wolf environment variables are available to test code. Returns names only; values never leave the server.",
     input,
     kind: "read",
@@ -17282,6 +17517,11 @@ var makeSetEnvironmentVariableContract = (ids) => {
     name: string2().describe("The stored variable name after whitespace is replaced with underscores and letters are uppercased.")
   });
   return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: false,
+      readOnlyHint: false
+    },
     description: 'Create or replace an environment variable. If the user asks to create one for "my email" without naming it, use DEFAULT_EMAIL. The value is never returned.',
     input,
     kind: "write",
@@ -17296,7 +17536,12 @@ var makeCreateEnvironmentContract = (ids) => {
   });
   const output = makeEnvironmentResourceSchema(ids);
   return {
-    description: "Create an environment on the caller's team and return it in the environment.get shape.",
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: true,
+      readOnlyHint: false
+    },
+    description: "Create an environment on the caller's team and return it in the environment.get shape. This can also create a branch on the team's connected Git provider.",
     input,
     kind: "write",
     name: "environment.create",
@@ -17317,6 +17562,11 @@ var makeUpdateEnvironmentContract = (ids) => {
   });
   const output = makeEnvironmentResourceSchema(ids);
   return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: false,
+      readOnlyHint: false
+    },
     description: "Update an environment owned by the caller's team and return it in the environment.get shape. Omitted fields remain unchanged.",
     input,
     kind: "write",
@@ -17339,6 +17589,11 @@ var makeCreateTagContract = (ids) => {
   });
   const output = makeTagResourceSchema();
   return {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: false
+    },
     description: "Create a tag on the caller's team. Tags select flows in run.create.",
     input,
     kind: "write",
@@ -17367,6 +17622,11 @@ var makeAddTagToFlowsContract = (ids) => {
     })
   });
   return {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: false
+    },
     description: "Assign an existing tag to the selected flows. Create tags with tag.create. Flows that already carry the tag are reported in skippedFlows.",
     input,
     kind: "write",
@@ -17399,6 +17659,11 @@ var makeListFlowsContract = (ids) => {
     }))
   });
   return {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: true
+    },
     description: "List the flows of an environment at its latest reconciled commit, or, when an AI task is given, the flows on that task's branch.",
     input,
     kind: "read",
@@ -17420,6 +17685,11 @@ var makeRemoveTagFromFlowsContract = (ids) => {
     })
   });
   return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: false,
+      readOnlyHint: false
+    },
     description: "Remove a tag from the selected flows. Succeeds whether or not each flow carried the tag; the flows that did not are reported in skippedFlows.",
     input,
     kind: "write",
@@ -17444,6 +17714,11 @@ var makeUpdateFlowContract = (ids) => {
     })
   });
   return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: false,
+      readOnlyHint: false
+    },
     description: "Move a flow between draft and active readiness. The other statuses shown in the app are derived and cannot be set.",
     input,
     kind: "write",
@@ -17500,6 +17775,11 @@ var makeFindIssuesContract = (ids) => {
     nextCursor: nextCursorSchema
   });
   return {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: true
+    },
     description: "List the team's bug reports, maintenance reports, or coverage requests, newest first.",
     input,
     kind: "read",
@@ -17515,6 +17795,11 @@ var makeGetIssueContract = (ids) => {
     issue: makeIssueResourceSchema(ids)
   });
   return {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: true
+    },
     description: "Get an issue by id.",
     input,
     kind: "read",
@@ -17533,6 +17818,11 @@ var makeAddFlowsToIssueContract = (ids) => {
     issue: makeIssueResourceSchema(ids)
   });
   return {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: false
+    },
     description: "Add flows to a coverage request owned by the caller's team. " + "Flows already covered stay covered. " + "Bug and maintenance reports link to flows through the runs that reproduce them; use run.diagnose to record one.",
     input,
     kind: "write",
@@ -17564,6 +17854,11 @@ var makeCreateIssueContract = (ids) => {
     issue: makeIssueResourceSchema(ids)
   });
   return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: true,
+      readOnlyHint: false
+    },
     description: "Create a bug or coverage request issue for the caller's team. " + "Maintenance issues cannot be created through the public API.",
     input,
     kind: "write",
@@ -17582,6 +17877,11 @@ var makeRemoveFlowsFromIssueContract = (ids) => {
     issue: makeIssueResourceSchema(ids)
   });
   return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: false,
+      readOnlyHint: false
+    },
     description: "Remove flows from a coverage request owned by the caller's team. " + "Flows the request does not cover are left alone. " + "Bug and maintenance reports link to flows through the runs that reproduce them, so their flows cannot be set directly.",
     input,
     kind: "write",
@@ -17607,6 +17907,11 @@ var makeUpdateIssueContract = (ids) => {
     issue: makeIssueResourceSchema(ids)
   });
   return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: true,
+      readOnlyHint: false
+    },
     description: "Update an issue owned by the caller's team. Omitted fields remain unchanged.",
     input,
     kind: "write",
@@ -17626,6 +17931,11 @@ var makeDiagnoseRunContract = (ids) => {
     issue: makeIssueResourceSchema(ids)
   });
   return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: true,
+      readOnlyHint: false
+    },
     description: "Diagnose failed flows in a run as reproductions of a bug or maintenance report owned by the caller's team. " + "The issue's type selects the diagnosis. " + "Each flow must have failed in the run. " + "A flow that is already diagnosed moves to this issue. " + "The diagnosis appears on the run, and the reproduction appears under the issue's reproductions. " + "Coverage requests cannot be diagnosed; use issue.addFlows to cover flows instead.",
     input,
     kind: "write",
@@ -17662,6 +17972,11 @@ var makeFindRunsContract = (ids) => {
     })).describe("The environment's runs, newest first. Per-flow results are available via run.get.")
   });
   return {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: true
+    },
     description: "List an environment's recent runs, newest first.",
     input,
     kind: "read",
@@ -17738,6 +18053,11 @@ var makeGetRunContract = (ids) => {
     runId: ids.run.describe("The run this response describes. Treat it as canonical: it can differ from the id you asked for. A deploy notification returns a run id before the run exists, and if a second notification for the same commit is folded into an earlier run, that id resolves to the earlier run instead.")
   }, { urlFieldDescription: "Absolute URL of the run page." });
   return {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: true
+    },
     description: "Get a run's status, per-flow results, and links.",
     input,
     kind: "read",
@@ -17757,6 +18077,11 @@ var makeReattemptRunContract = (ids) => {
     runId: ids.run
   }, { urlFieldDescription: "Absolute URL of the run page." });
   return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: true,
+      readOnlyHint: false
+    },
     description: "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.",
     input,
     kind: "write",
@@ -17773,7 +18098,12 @@ var makeStopRunContract = (ids) => {
     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.",
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: true,
+      readOnlyHint: false
+    },
+    description: "Stop a run, including its queued flows and automatic retries. Stopping is asynchronous and can update run-status messages and commit statuses in connected integrations. 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",
@@ -17806,6 +18136,11 @@ var makeEvaluateSnippetOnRunnerContract = (ids) => {
     ])
   ]);
   return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: true,
+      readOnlyHint: false
+    },
     description: "Evaluate a snippet against whatever the runner's browser is showing right now. Answers whether the snippet ran, and its error if it threw — not the value it evaluated to, so read anything you want back out of the runner's journal (a snippet's `console.log` lands in the `console` stream). A snippet starts no run and leaves no run-scoped journal entries of its own. `runner-cannot-evaluate-snippets` on a runner with nothing attached to serve one — which will never clear, so check that the runner you launched is one that runs a browser or app before retrying. `runner-unreachable` if the runner could not be reached: it may still be starting, it may have terminated after inactivity, or it may be too busy to answer. Neither is proof the snippet did not run: a snippet that outlives the answer window is still executing when you read this, so do not blindly resubmit one that mutates what the page is looking at.",
     input,
     kind: "write",
@@ -17826,6 +18161,11 @@ var makeGetRunnerContract = (ids) => {
     running: boolean2().describe("False when no runner is running under this id: it was never launched, it was terminated, or it terminated on its own after inactivity. These are not distinguished, because the run system keeps no record of a runner once it is gone.")
   });
   return {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: true
+    },
     description: "Report whether a runner is running under this id on the caller's team. 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. An id that is not running is a success with `running: false` rather than an error, so this is how to check a runner is still there before addressing it.",
     input,
     kind: "read",
@@ -17864,6 +18204,11 @@ var makeHighlightSelectorOnRunnerContract = (ids) => {
     })
   ]);
   return {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: false
+    },
     description: "Highlight the elements a selector matches on an interactive runner's live page, and answer how many it matched. The highlight stays until it is replaced or cleared, so it is visible in the next `runner.takeScreenshot` — which is the point, since a caller cannot see the runner's screen otherwise. Send an empty selector to clear, which answers `cleared`. `status` tells a selector that matched nothing (`empty`) from one the page could not parse (`invalid`), so a caller can tell a bad locator from a locator pointing at nothing. `no-answer` if the page did not answer in time: the highlight runs inside the page, so a page that is gone or mid-navigation does not answer slowly, it does not answer at all. `runner-cannot-highlight-selectors` on a runner with no browser to draw on. `runner-unreachable` if the runner could not be reached: it may still be starting, or it may have terminated after inactivity.",
     input,
     kind: "write",
@@ -17892,6 +18237,11 @@ var makeImportPackageOnRunnerContract = (ids) => {
     })
   ]);
   return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: true,
+      readOnlyHint: false
+    },
     description: "Install a package into an interactive runner's live run and import it, so a snippet or a selection can use it without a full run to reinstall dependencies. An `install-failed` failure carries npm's reason in `errorMessage`. `runner-unreachable` if the runner could not be reached: it may still be starting, it may have terminated after inactivity, or it may be too busy to answer. The install may still have landed, but installing the same version again does nothing, so retrying is safe.",
     input,
     kind: "write",
@@ -17912,6 +18262,11 @@ var makeLaunchRunnerContract = (ids) => {
     outcome: literal("success")
   });
   return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: false,
+      readOnlyHint: false
+    },
     description: "Launch an interactive runner on the caller's team under an id the caller chooses. Launching the same id again returns the runner already running rather than starting a second one, and the same id with a different runnerName is refused. A runner is not permanent: it terminates on its own after a period of inactivity, and launching the same id after that starts and bills a new runner — so read `alreadyRunning` to tell which happened.",
     input,
     kind: "write",
@@ -17930,6 +18285,11 @@ var makeTerminateRunnerContract = (ids) => {
     wasRunning: boolean2().describe("False when no running runner had this id: it was already terminated, was never launched, or terminated on its own after inactivity. These are not distinguished, because the run system keeps no record of a runner once it is gone. Not an error, and a retry needs no special handling.")
   });
   return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: false,
+      readOnlyHint: false
+    },
     description: "End an interactive runner on the caller's team, and the pod it runs on with it. Terminating a runner that is not running succeeds and reports `wasRunning: false`. This ends the runner: use `runner.stopRun` to stop what a runner is currently executing while leaving the runner up.",
     input,
     kind: "write",
@@ -17948,6 +18308,11 @@ var makeListRunnersContract = (ids) => {
     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 {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: true
+    },
     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",
@@ -17977,6 +18342,11 @@ var makePromoteSnapshotOnRunnerContract = (ids) => {
     })
   ]);
   return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: false,
+      readOnlyHint: false
+    },
     description: "Accept a run's screenshot as the new baseline for an image diff, on the runner that produced it. The two paths are the ones the diff reported, which reach a caller as an `image-diff-artifact` entry on the runner's `run-events` journal stream. `snapshot-not-found` if the run wrote no screenshot at that path, which usually means the paths were not taken from a diff this run produced; nothing is changed, so correcting the path and repeating is safe. `runner-cannot-promote-snapshots` on a runner that stores no screenshots. `runner-unreachable` if the runner could not be reached: it may still be starting, or it may have terminated after inactivity. A promotion that lands is not undone by promoting again, so a retry after an unreachable answer is safe.",
     input,
     kind: "write",
@@ -17997,6 +18367,11 @@ var makeReadRunnerJournalContract = (ids) => {
     makeRunnerFailureSchema([runnerUnreachableFailureReason])
   ]);
   return {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: false
+    },
     description: `Read a window of one of an interactive runner's journal streams — the newest few, everything after a cursor, or everything belonging to one run. This is how a flow run's outcome and output are followed: \`run-status\` settles it, \`run-logs\` and \`run-events\` carry what it produced, and \`recorder\` carries the browser actions the runner recorded. A read counts as activity, so working through history does not get the runner reaped underneath you. ${retryableRunnerUnreachableDescription}`,
     input,
     kind: "read",
@@ -18069,6 +18444,11 @@ var makeRunFlowOnRunnerContract = (ids) => {
     failure
   ]);
   return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: true,
+      readOnlyHint: false
+    },
     description: "Run a flow on an interactive runner. When `selection` is given the lines run against the browser as it stands, so nothing is re-navigated and nothing is signed in again; without it the whole entry point runs from a fresh browser. A runner with no live browser starts one before a selection and says so with `bootstrappedRunner`, which means those lines ran against a fresh page rather than the one an earlier run left. A selection produces no `runStarted` event, so follow it by its run id on `run-status` like any other run. Send `unchangedFiles` to ship only what changed since an earlier run on this runner; a `needs-full-sync` failure names the paths it does not hold, and the way to recover is the same run again with every file in `files`. Answers as soon as the run is accepted, with the id to follow it by — nothing waits for the run to finish. Which browser or device the run needs is read from the flow file's own execution target, so it is not supplied here; when it does not match what the runner is, the call fails with `runner-target-mismatch` rather than failing partway through the run. `runner-unreachable` means the answer did not arrive, which is NOT the same as the run not having started: the runner may have accepted it and been too slow to say so, and resubmitting would start a second run that is billed and journalled alongside the first. Read the runner's `run-status` journal stream before resubmitting, and use the newest run id there if one appeared.",
     input,
     kind: "write",
@@ -18091,6 +18471,11 @@ var makeStopRunOnRunnerContract = (ids) => {
     makeRunnerFailureSchema([runnerUnreachableFailureReason])
   ]);
   return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: false,
+      readOnlyHint: false
+    },
     description: "Stop what a runner is currently executing, leaving the runner up and its browser on whatever page the run reached. Succeeds whether or not anything was running, and `wasRunning` says which. This is the counterpart of `runner.terminate`, which ends the runner itself. The run stops where it is, so the journal's `run-status` settles it as stopped rather than passed or failed. `runner-unreachable` if the runner could not be reached: it may still be starting, it may have terminated after inactivity, or it may be too busy to answer. The stop may still have landed, but stopping a runner that is already idle does nothing, so retrying is safe.",
     input,
     kind: "write",
@@ -18116,7 +18501,12 @@ var makeTakeScreenshotOnRunnerContract = (ids) => {
     ])
   ]);
   return {
-    description: `Take one screenshot of an interactive runner's screen. On a runner with a browser the image is the whole virtual desktop, browser window and all. On a mobile runner it is the device's own screen, re-encoded to JPEG on the pod so this contract reads one image format regardless of runner family. ${screenNeedsARunDescription} ${screenNotReadyDescription} ${runnerHasNoScreenDescription} ${retryableRunnerUnreachableDescription}`,
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: false
+    },
+    description: `Take one screenshot of an interactive runner's screen. On a runner with a browser the image is the whole virtual desktop, browser window and all; this refreshes the inactivity timer and can extend the runner's billed lifetime. On a mobile runner it is the device's own screen, re-encoded to JPEG on the pod so this contract reads one image format regardless of runner family. ${screenNeedsARunDescription} ${screenNotReadyDescription} ${runnerHasNoScreenDescription} ${retryableRunnerUnreachableDescription}`,
     input,
     kind: "read",
     name: "runner.takeScreenshot",
@@ -18139,6 +18529,11 @@ var makeListTagsContract = (ids) => {
     })).describe("The team's tags, alphabetical by name.")
   });
   return {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: true
+    },
     description: "List the team's tags, alphabetical by name. Tag names select flows in run.create.",
     input,
     kind: "read",
@@ -18147,6 +18542,250 @@ var makeListTagsContract = (ids) => {
   };
 };
 
+// node_modules/@qawolf/api-contracts/dist/v1/trigger/configurationRules.js
+var checkAction = (action, ctx) => {
+  const namesFlows = action.flowIds.length + action.tagNames.length > 0;
+  if (action.kind === "generativeSuite") {
+    if (namesFlows) {
+      ctx.addIssue({
+        code: "custom",
+        message: "flowIds and tagNames do not apply when the action is generativeSuite.",
+        path: ["action", "flowIds"]
+      });
+    }
+    return;
+  }
+  if (action.instructions !== undefined) {
+    ctx.addIssue({
+      code: "custom",
+      message: "instructions apply to a generativeSuite action only.",
+      path: ["action", "instructions"]
+    });
+  }
+  if (!namesFlows) {
+    ctx.addIssue({
+      code: "custom",
+      message: "At least one flow or tag is required.",
+      path: ["action", "flowIds"]
+    });
+  }
+};
+var checkSchedule = (value, ctx) => {
+  if (value.cadence === "daily") {
+    for (const field of ["timeOfDay", "timezoneId"]) {
+      if (value[field] === undefined) {
+        ctx.addIssue({
+          code: "custom",
+          message: `${field} is required when cadence is daily.`,
+          path: [field]
+        });
+      }
+    }
+    if (value.minuteOfHour !== undefined) {
+      ctx.addIssue({
+        code: "custom",
+        message: "minuteOfHour applies to an hourly cadence only.",
+        path: ["minuteOfHour"]
+      });
+    }
+  } else {
+    for (const field of ["timeOfDay", "timezoneId"]) {
+      if (value[field] !== undefined) {
+        ctx.addIssue({
+          code: "custom",
+          message: `${field} applies to a daily cadence only.`,
+          path: [field]
+        });
+      }
+    }
+  }
+  if (value.action.kind === "generativeSuite") {
+    ctx.addIssue({
+      code: "custom",
+      message: "A schedule trigger cannot use a generativeSuite action.",
+      path: ["action", "kind"]
+    });
+    return;
+  }
+  checkAction(value.action, ctx);
+};
+var checkDeployment = (value, ctx) => {
+  if (value.environmentPattern !== undefined && value.environmentIds.length > 0) {
+    ctx.addIssue({
+      code: "custom",
+      message: "Supply environmentIds or environmentPattern, not both.",
+      path: ["environmentPattern"]
+    });
+  }
+  checkAction(value.action, ctx);
+};
+var checkTriggerConfiguration = (value, ctx) => value.kind === "schedule" ? checkSchedule(value, ctx) : checkDeployment(value, ctx);
+
+// node_modules/@qawolf/api-contracts/dist/v1/trigger/create.js
+var makeCreateTriggerContract = (ids) => {
+  const commonFields = {
+    name: string2().trim().min(1).max(255),
+    workspaceId: ids.workspace.optional().describe("The workspace to create the trigger in. Required when authenticating with an organization or user API key.")
+  };
+  const input = discriminatedUnion("kind", [
+    object({
+      ...commonFields,
+      ...makeTriggerScheduleFields({
+        environmentId: ids.environmentRef,
+        flow: ids.flow
+      }),
+      kind: literal("schedule")
+    }),
+    object({
+      ...commonFields,
+      ...makeTriggerDeploymentFields(ids),
+      kind: literal("deployment")
+    })
+  ]).superRefine(checkTriggerConfiguration);
+  const output = object({ trigger: makeTriggerResourceSchema(ids) });
+  return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: true,
+      readOnlyHint: false
+    },
+    description: "Create a trigger. A schedule trigger runs a named set of flows on a cadence; " + "a deployment trigger runs when a matching deployment is reported.",
+    input,
+    kind: "write",
+    name: "trigger.create",
+    output
+  };
+};
+
+// node_modules/@qawolf/api-contracts/dist/v1/trigger/find.js
+var makeFindTriggersContract = (ids) => {
+  const input = object({
+    isPaused: boolean2().optional().describe("Only list paused, or only unpaused, triggers. Omit for both."),
+    workspaceId: ids.workspace.optional().describe("The workspace to list triggers from. Required when authenticating with an organization or user API key.")
+  });
+  const output = object({
+    triggers: array(makeTriggerResourceSchema(ids)).describe("The team's triggers, newest first.")
+  });
+  return {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: true
+    },
+    description: "List the team's triggers, newest first.",
+    input,
+    kind: "read",
+    name: "trigger.find",
+    output
+  };
+};
+
+// node_modules/@qawolf/api-contracts/dist/v1/trigger/get.js
+var makeGetTriggerContract = (ids) => {
+  const input = object({ triggerId: ids.trigger });
+  const output = object({ trigger: makeTriggerResourceSchema(ids) });
+  return {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: true
+    },
+    description: "Get one trigger by id.",
+    input,
+    kind: "read",
+    name: "trigger.get",
+    output
+  };
+};
+
+// node_modules/@qawolf/api-contracts/dist/v1/trigger/lifecycle.js
+var makePauseTriggerContract = (ids) => {
+  const input = object({ triggerId: ids.trigger });
+  const output = object({ trigger: makeTriggerResourceSchema(ids) });
+  return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: false,
+      readOnlyHint: false
+    },
+    description: "Pause a trigger so it stops firing. Pausing is idempotent. A team whose " + "triggers are all paused reports no trigger activity at all.",
+    input,
+    kind: "write",
+    name: "trigger.pause",
+    output
+  };
+};
+var makeResumeTriggerContract = (ids) => {
+  const input = object({ triggerId: ids.trigger });
+  const output = object({ trigger: makeTriggerResourceSchema(ids) });
+  return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: true,
+      readOnlyHint: false
+    },
+    description: "Resume a paused trigger. A schedule trigger restarts from the next " + "upcoming slot: the slots it missed while paused do not run.",
+    input,
+    kind: "write",
+    name: "trigger.resume",
+    output
+  };
+};
+var makeDeleteTriggerContract = (ids) => {
+  const input = object({ triggerId: ids.trigger });
+  const output = object({
+    triggerId: ids.trigger.describe("The id of the deleted trigger.")
+  });
+  return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: false,
+      readOnlyHint: false
+    },
+    description: "Delete a trigger permanently. The runs it already created are kept. " + "To stop a trigger without losing it, use trigger.pause.",
+    input,
+    kind: "write",
+    name: "trigger.delete",
+    output
+  };
+};
+
+// node_modules/@qawolf/api-contracts/dist/v1/trigger/update.js
+var makeUpdateTriggerContract = (ids) => {
+  const commonFields = {
+    name: string2().trim().min(1).max(255),
+    triggerId: ids.trigger
+  };
+  const input = discriminatedUnion("kind", [
+    object({
+      ...commonFields,
+      ...makeTriggerScheduleFields({
+        environmentId: ids.environmentRef,
+        flow: ids.flow
+      }),
+      kind: literal("schedule")
+    }),
+    object({
+      ...commonFields,
+      ...makeTriggerDeploymentFields(ids),
+      kind: literal("deployment")
+    })
+  ]).superRefine(checkTriggerConfiguration);
+  const output = object({ trigger: makeTriggerResourceSchema(ids) });
+  return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: true,
+      readOnlyHint: false
+    },
+    description: "Replace a trigger's configuration. Every field is written, so read the " + "trigger first and send its configuration back with your changes applied. " + "Pausing is separate: use trigger.pause and trigger.resume.",
+    input,
+    kind: "write",
+    name: "trigger.update",
+    output
+  };
+};
+
 // node_modules/@qawolf/api-contracts/dist/v1/index.js
 var makeContractsV1 = (ids) => {
   const resolvedIds = { ...defaultIdSchemas, ...ids };
@@ -18174,6 +18813,7 @@ var makeContractsV1 = (ids) => {
       setVariable: makeSetEnvironmentVariableContract(resolvedIds),
       update: makeUpdateEnvironmentContract(resolvedIds)
     },
+    file: makeFileContracts(resolvedIds),
     flow: {
       addTag: makeAddTagToFlowsContract(resolvedIds),
       list: makeListFlowsContract(resolvedIds),
@@ -18216,6 +18856,15 @@ var makeContractsV1 = (ids) => {
     tag: {
       create: makeCreateTagContract(resolvedIds),
       list: makeListTagsContract(resolvedIds)
+    },
+    trigger: {
+      create: makeCreateTriggerContract(resolvedIds),
+      delete: makeDeleteTriggerContract(resolvedIds),
+      find: makeFindTriggersContract(resolvedIds),
+      get: makeGetTriggerContract(resolvedIds),
+      pause: makePauseTriggerContract(resolvedIds),
+      resume: makeResumeTriggerContract(resolvedIds),
+      update: makeUpdateTriggerContract(resolvedIds)
     }
   };
 };
@@ -20564,7 +21213,7 @@ function startUpdateCheck(deps) {
 // package.json
 var package_default = {
   name: "@qawolf/cli",
-  version: "1.27.0",
+  version: "1.29.0",
   description: "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   keywords: [
     "automation",
@@ -20635,7 +21284,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.52.0",
+    "@qawolf/api-contracts": "0.53.0",
     "@qawolf/emails": "1.1.1",
     "@qawolf/flow-targets": "1.0.0",
     "@qawolf/flows": "0.1.4",
@@ -33264,27 +33913,50 @@ async function handleRunnerInspect(ctx, options, deps) {
 }
 
 // src/core/interactiveRunner/inspectMobileRequest.ts
+var blankInspectMobileFlags = {
+  context: undefined,
+  partial: undefined,
+  selector: undefined,
+  strategy: undefined,
+  text: undefined,
+  x: undefined,
+  y: undefined
+};
 function toNumber(value) {
   return value.trim() === "" ? Number.NaN : Number(value);
 }
-function buildInspectMobileRequest(what, flags) {
-  if (flags.by === "point" && (flags.text !== undefined || flags.partial !== undefined)) {
-    return {
-      error: "--by point matches by pixel, so --text/--partial would be ignored rather than searching by text. Pass --by text instead, or drop --text/--partial.",
-      ok: false
-    };
+var groupsOf = (flags) => ({
+  point: flags.x !== undefined || flags.y !== undefined,
+  selector: flags.selector !== undefined || flags.strategy !== undefined,
+  text: flags.text !== undefined || flags.partial !== undefined
+});
+function describeGroup(group) {
+  switch (group) {
+    case "point":
+      return "--x/--y";
+    case "selector":
+      return "--selector/--strategy";
+    case "text":
+      return "--text/--partial";
   }
-  if (flags.by === "text" && (flags.x !== undefined || flags.y !== undefined)) {
+}
+function buildInspectMobileRequest(what, flags) {
+  const groups = groupsOf(flags);
+  const present = ["point", "text", "selector"].filter((group) => groups[group]);
+  if (present.length > 1) {
     return {
-      error: "--by text matches by text, so --x/--y would be ignored rather than matching a point. Pass --by point instead, or drop --x/--y.",
+      error: `${describeGroup(present[0])} and ${describeGroup(present[1])} were both passed, but elements are found by a point, by text, or by a selector — never more than one at once. Drop all but one of them.`,
       ok: false
     };
   }
+  const by = present[0];
   const candidate = {
     what,
-    ...flags.by === undefined ? {} : { by: flags.by },
+    ...by === undefined ? {} : { by },
     ...flags.context === undefined ? {} : { context: flags.context },
     ...flags.partial === undefined ? {} : { partial: flags.partial },
+    ...flags.selector === undefined ? {} : { selector: flags.selector },
+    ...flags.strategy === undefined ? {} : { strategy: flags.strategy },
     ...flags.text === undefined ? {} : { text: flags.text },
     ...flags.x === undefined ? {} : { x: toNumber(flags.x) },
     ...flags.y === undefined ? {} : { y: toNumber(flags.y) }
@@ -33296,7 +33968,7 @@ function buildInspectMobileRequest(what, flags) {
   return { ok: true, request: parsed.data };
 }
 
-// src/domains/interactiveRunner/inspectMobile.ts
+// src/domains/interactiveRunner/inspectMobileAnswer.ts
 function describeSession(session) {
   switch (session.type) {
     case "ready":
@@ -33326,6 +33998,8 @@ function streamLine(value) {
       return JSON.stringify({ matches: value.matches });
   }
 }
+
+// src/domains/interactiveRunner/inspectMobile.ts
 async function handleRunnerInspectMobile(ctx, options, deps) {
   const built = buildInspectMobileRequest(options.what, options.flags);
   if (!built.ok)
@@ -33353,6 +34027,11 @@ async function handleRunnerInspectMobile(ctx, options, deps) {
   }
   const { failureReason } = result.value;
   switch (failureReason) {
+    case "invalid-selector":
+      return {
+        error: interactiveRunnerMessages.inspectMobileInvalidSelector,
+        exitCode: exitCodes.invalidArgs
+      };
     case "runner-is-not-mobile":
       return {
         error: interactiveRunnerMessages.runnerIsNotMobile,
@@ -33385,46 +34064,26 @@ async function handleRunnerInspectMobile(ctx, options, deps) {
 // src/commands/runner/inspectMobile.register.ts
 function registerRunnerInspectMobileCommands(inspect, signals) {
   declareCommandKind(inspect.command("session"), "read").description("Print the Appium session's status: ready, or why not").option("--runner <id>", runnerFlagDescription).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerInspectMobile(ctx, {
-    flags: {
-      by: undefined,
-      context: undefined,
-      partial: undefined,
-      text: undefined,
-      x: undefined,
-      y: undefined
-    },
+    flags: blankInspectMobileFlags,
     runner: opts.runner,
     what: "session"
   }, runnerDeps(ctx)))(opts, command));
   declareCommandKind(inspect.command("contexts"), "read").description("List the WebView contexts available, and which is current").option("--runner <id>", runnerFlagDescription).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerInspectMobile(ctx, {
-    flags: {
-      by: undefined,
-      context: undefined,
-      partial: undefined,
-      text: undefined,
-      x: undefined,
-      y: undefined
-    },
+    flags: blankInspectMobileFlags,
     runner: opts.runner,
     what: "contexts"
   }, runnerDeps(ctx)))(opts, command));
   declareCommandKind(inspect.command("page-source"), "read").description("Print the current context's page source, as a tree").option("--context <name>", "Read this context instead of the current one").option("--runner <id>", runnerFlagDescription).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerInspectMobile(ctx, {
-    flags: {
-      by: undefined,
-      context: opts.context,
-      partial: undefined,
-      text: undefined,
-      x: undefined,
-      y: undefined
-    },
+    flags: { ...blankInspectMobileFlags, context: opts.context },
     runner: opts.runner,
     what: "page"
   }, runnerDeps(ctx)))(opts, command));
-  declareCommandKind(inspect.command("elements"), "read").description("Find elements at a screen point, or elements carrying some text").requiredOption("--by <by>", "point or text").option("--context <name>", "Read this context instead of the current one").option("--partial", "text: match text containing this, rather than exactly this").option("--runner <id>", runnerFlagDescription).option("--text <text>", "text: the text to match").option("--x <pixels>", "point: whole pixels on the device's own screen").option("--y <pixels>", "point: whole pixels on the device's own screen").action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerInspectMobile(ctx, {
+  declareCommandKind(inspect.command("elements"), "read").description("Find elements at a screen point, carrying some text, or matching a selector").option("--context <name>", "Read this context instead of the current one").option("--partial", "text: match text containing this, rather than exactly this").option("--runner <id>", runnerFlagDescription).option("--selector <selector>", "Resolved the same way a screen object's own selector is").option("--strategy <strategy>", "selector: xpath, ios-predicate, or shadow (defaults to xpath)").option("--text <text>", "text: the text to match").option("--x <pixels>", "point: whole pixels on the device's own screen").option("--y <pixels>", "point: whole pixels on the device's own screen").action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerInspectMobile(ctx, {
     flags: {
-      by: opts.by,
       context: opts.context,
       partial: opts.partial,
+      selector: opts.selector,
+      strategy: opts.strategy,
       text: opts.text,
       x: opts.x,
       y: opts.y
@@ -33443,8 +34102,9 @@ Examples:
   $ qawolf runner inspect session
   $ qawolf runner inspect contexts
   $ qawolf runner inspect page-source --context WEBVIEW_1
-  $ qawolf runner inspect elements --by point --x 200 --y 400
-  $ qawolf runner inspect elements --by text --text "Sign in" --partial`;
+  $ qawolf runner inspect elements --x 200 --y 400
+  $ qawolf runner inspect elements --text "Sign in" --partial
+  $ qawolf runner inspect elements --selector "//android.widget.Button[@text='Sign in']"`;
 function registerRunnerInspectCommands(runner, signals) {
   const inspect = runner.command("inspect").description("Read one thing off a runner's live page (browser) or Appium session (mobile)").addHelpText("after", inspectExamples);
   declareCommandKind(inspect.command("element-html"), "read").description("Print the HTML of the first element a selector matches").requiredOption("--selector <selector>", "Playwright selector to inspect").option("--runner <id>", runnerFlagDescription).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerInspect(ctx, {
@@ -34782,4 +35442,4 @@ createProgram({ signals }).parseAsync().catch(() => {
     process.exitCode = 1;
 }).finally(() => exitWhenIdle(typeof process.exitCode === "number" ? process.exitCode : 0));
 
-//# debugId=90417CF807BBB8C264756E2164756E21
+//# debugId=424C032AEE2722C964756E2164756E21