@qawolf/api-contracts 0.30.0 → 0.33.0

package/dist/v1/runner/inspectMobileShapes.js

@@ -0,0 +1,59 @@
+import { z } from "zod";
+/**
+ * Duplicated from `packages/domain-runner-types/src/lib/appium.ts`: that
+ * package is private and this one is published, so it can't be imported here.
+ * A shape refused there must stay refused here.
+ */
+const boundsSchema = z.object({
+    bottom: z.number(),
+    left: z.number(),
+    right: z.number(),
+    top: z.number(),
+});
+const pointSchema = z.object({ x: z.number(), y: z.number() });
+const selectorSchema = z.object({
+    strategy: z.union([
+        z.object({
+            name: z.literal("xpath"),
+            type: z.enum(["unique", "full-path", "sibling-of", "parent-of"]),
+        }),
+        z.object({ name: z.literal("ios-predicate") }),
+        z.object({
+            hostSelector: z.string(),
+            innerSelector: z.string(),
+            name: z.literal("shadow"),
+        }),
+    ]),
+    value: z.string(),
+});
+export const elementSchema = z.object({
+    attributes: z.record(z.string(), z.string()),
+    bounds: boundsSchema
+        .optional()
+        .describe("The element's on-screen rectangle, absent off-screen."),
+    center: pointSchema
+        .optional()
+        .describe("Derived from `bounds`; absent wherever `bounds` is."),
+    selectors: selectorSchema
+        .array()
+        .describe("Ways to address this element again, most reliable first."),
+    tag: z.string(),
+});
+const basePageSourceNodeSchema = z.object({
+    attributes: z
+        .object({
+        bounds: boundsSchema.optional(),
+        rest: z.record(z.string(), z.string()).optional(),
+    })
+        .optional(),
+    selectors: selectorSchema.array(),
+    tag: z.string(),
+});
+export const pageSourceNodeSchema = basePageSourceNodeSchema.extend({
+    children: z
+        .lazy(() => z.union([pageSourceNodeSchema, z.string()]).array())
+        .optional()
+        .describe("A string child is a text node; there is no element to select."),
+});
+export const orientationSchema = z.enum(["PORTRAIT", "LANDSCAPE"]);
+//# sourceMappingURL=inspectMobileShapes.js.map

package/dist/v1/runner/inspectMobileShapes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspectMobileShapes.js","sourceRoot":"","sources":["../../../src/v1/runner/inspectMobileShapes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;CAChB,CAAC,CAAC;AAEH,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAE/D,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC;QAChB,CAAC,CAAC,MAAM,CAAC;YACP,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;YACxB,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,CAAC,CAAC;SACjE,CAAC;QACF,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC,EAAE,CAAC;QAC9C,CAAC,CAAC,MAAM,CAAC;YACP,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE;YACxB,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE;YACzB,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;SAC1B,CAAC;KACH,CAAC;IACF,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;CAClB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,UAAU,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;IAC5C,MAAM,EAAE,YAAY;SACjB,QAAQ,EAAE;SACV,QAAQ,CAAC,uDAAuD,CAAC;IACpE,MAAM,EAAE,WAAW;SAChB,QAAQ,EAAE;SACV,QAAQ,CAAC,qDAAqD,CAAC;IAClE,SAAS,EAAE,cAAc;SACtB,KAAK,EAAE;SACP,QAAQ,CAAC,0DAA0D,CAAC;IACvE,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;CAChB,CAAC,CAAC;AAEH,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,UAAU,EAAE,CAAC;SACV,MAAM,CAAC;QACN,MAAM,EAAE,YAAY,CAAC,QAAQ,EAAE;QAC/B,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;KAClD,CAAC;SACD,QAAQ,EAAE;IACb,SAAS,EAAE,cAAc,CAAC,KAAK,EAAE;IACjC,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;CAChB,CAAC,CAAC;AAMH,MAAM,CAAC,MAAM,oBAAoB,GAC/B,wBAAwB,CAAC,MAAM,CAAC;IAC9B,QAAQ,EAAE,CAAC;SACR,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,oBAAoB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;SAC/D,QAAQ,EAAE;SACV,QAAQ,CACP,+DAA+D,CAChE;CACJ,CAAC,CAAC;AAEL,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC"}

package/dist/v1/runner/performAction.d.ts

@@ -2,7 +2,7 @@ import { z } from "zod";
 /** How much of a failure reason this API passes on. */
 export declare const maxActionErrorMessageLength = 1000;
 export declare const makePerformActionOnRunnerContract: () => {
-    readonly 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. `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. `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. A `navigate` does not go through the screen, so a screen that is not ready does not stop it. `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. `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.";
+    readonly 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. `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. A `navigate` does not go through the screen, so a screen that is not ready does not stop it. `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. `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. `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.";
     readonly input: z.ZodObject<{
         action: z.ZodDiscriminatedUnion<[z.ZodObject<{
             button: z.ZodLiteral<"left" | "right" | "wheel" | "back" | "forward">;
@@ -52,9 +52,10 @@ export declare const makePerformActionOnRunnerContract: () => {
     }, z.core.$strip>, z.ZodObject<{
         failureReason: z.ZodEnum<{
             "runner-unreachable": "runner-unreachable";
-            "runner-has-no-screen": "runner-has-no-screen";
             "screen-needs-a-run": "screen-needs-a-run";
             "screen-not-ready": "screen-not-ready";
+            "runner-has-no-screen": "runner-has-no-screen";
+            "action-not-supported-on-mobile": "action-not-supported-on-mobile";
         }>;
         outcome: z.ZodLiteral<"failure">;
     }, z.core.$strip>], "failureReason">], "outcome">;

package/dist/v1/runner/performAction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"performAction.d.ts","sourceRoot":"","sources":["../../../src/v1/runner/performAction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAmBxB,uDAAuD;AACvD,eAAO,MAAM,2BAA2B,OAAQ,CAAC;AAEjD,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0C7C,CAAC"}
+{"version":3,"file":"performAction.d.ts","sourceRoot":"","sources":["../../../src/v1/runner/performAction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAsBxB,uDAAuD;AACvD,eAAO,MAAM,2BAA2B,OAAQ,CAAC;AAEjD,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2C7C,CAAC"}

package/dist/v1/runner/performAction.js

@@ -7,6 +7,7 @@ import { runnerUnreachableFailureReason } from "./unreachable.js";
 // Not the shared retryable wording: the action may have taken effect before its
 // answer was lost.
 const 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.";
+const 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.";
 /** How much of a failure reason this API passes on. */
 export const maxActionErrorMessageLength = 1_000;
 export const makePerformActionOnRunnerContract = () => {
@@ -27,6 +28,7 @@ export const makePerformActionOnRunnerContract = () => {
         }),
         makeRunnerFailureSchema([
             ...screenFailureReasons,
+            "action-not-supported-on-mobile",
             runnerUnreachableFailureReason,
         ]),
     ]);
@@ -35,7 +37,7 @@ export const makePerformActionOnRunnerContract = () => {
         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. \`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} ${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} ${unreachableDescription}`,
         input,
         kind: "write",
         name: "runner.performAction",

package/dist/v1/runner/performAction.js.map

@@ -1 +1 @@
-{"version":3,"file":"performAction.js","sourceRoot":"","sources":["../../../src/v1/runner/performAction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EACL,4BAA4B,EAC5B,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,8BAA8B,EAAE,MAAM,kBAAkB,CAAC;AAElE,gFAAgF;AAChF,mBAAmB;AACnB,MAAM,sBAAsB,GAC1B,mQAAmQ,CAAC;AAEtQ,uDAAuD;AACvD,MAAM,CAAC,MAAM,2BAA2B,GAAG,KAAK,CAAC;AAEjD,MAAM,CAAC,MAAM,iCAAiC,GAAG,GAAG,EAAE;IACpD,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC;QACrB,MAAM,EAAE,mBAAmB,CAAC,QAAQ,CAClC,yFAAyF,CAC1F;QACD,EAAE,EAAE,cAAc,CAAC,QAAQ,CAAC,6BAA6B,CAAC;KAC3D,CAAC,CAAC;IAEH,+EAA+E;IAC/E,8CAA8C;IAC9C,MAAM,OAAO,GAAG,CAAC,CAAC,kBAAkB,CAAC,eAAe,EAAE;QACpD,CAAC,CAAC,MAAM,CAAC;YACP,YAAY,EAAE,CAAC;iBACZ,MAAM,EAAE;iBACR,GAAG,CAAC,2BAA2B,CAAC;iBAChC,QAAQ,CAAC,6CAA6C,CAAC;YAC1D,aAAa,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC;YACzC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;SAC9B,CAAC;QACF,uBAAuB,CAAC;YACtB,GAAG,oBAAoB;YACvB,8BAA8B;SAC/B,CAAC;KACH,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,CAAC,CAAC,kBAAkB,CAAC,SAAS,EAAE;QAC7C,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QAC3C,OAAO;KACR,CAAC,CAAC;IAEH,OAAO;QACL,WAAW,EAAE,mlCAAmlC,yBAAyB,mGAAmG,4BAA4B,IAAI,sBAAsB,EAAE;QACpxC,KAAK;QACL,IAAI,EAAE,OAAO;QACb,IAAI,EAAE,sBAAsB;QAC5B,MAAM;KAMP,CAAC;AACJ,CAAC,CAAC"}
+{"version":3,"file":"performAction.js","sourceRoot":"","sources":["../../../src/v1/runner/performAction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EACL,4BAA4B,EAC5B,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,8BAA8B,EAAE,MAAM,kBAAkB,CAAC;AAElE,gFAAgF;AAChF,mBAAmB;AACnB,MAAM,sBAAsB,GAC1B,mQAAmQ,CAAC;AAEtQ,MAAM,+BAA+B,GACnC,6ZAA6Z,CAAC;AAEha,uDAAuD;AACvD,MAAM,CAAC,MAAM,2BAA2B,GAAG,KAAK,CAAC;AAEjD,MAAM,CAAC,MAAM,iCAAiC,GAAG,GAAG,EAAE;IACpD,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC;QACrB,MAAM,EAAE,mBAAmB,CAAC,QAAQ,CAClC,yFAAyF,CAC1F;QACD,EAAE,EAAE,cAAc,CAAC,QAAQ,CAAC,6BAA6B,CAAC;KAC3D,CAAC,CAAC;IAEH,+EAA+E;IAC/E,8CAA8C;IAC9C,MAAM,OAAO,GAAG,CAAC,CAAC,kBAAkB,CAAC,eAAe,EAAE;QACpD,CAAC,CAAC,MAAM,CAAC;YACP,YAAY,EAAE,CAAC;iBACZ,MAAM,EAAE;iBACR,GAAG,CAAC,2BAA2B,CAAC;iBAChC,QAAQ,CAAC,6CAA6C,CAAC;YAC1D,aAAa,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC;YACzC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;SAC9B,CAAC;QACF,uBAAuB,CAAC;YACtB,GAAG,oBAAoB;YACvB,gCAAgC;YAChC,8BAA8B;SAC/B,CAAC;KACH,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,CAAC,CAAC,kBAAkB,CAAC,SAAS,EAAE;QAC7C,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QAC3C,OAAO;KACR,CAAC,CAAC;IAEH,OAAO;QACL,WAAW,EAAE,8yCAA8yC,yBAAyB,mGAAmG,4BAA4B,IAAI,+BAA+B,IAAI,sBAAsB,EAAE;QAClhD,KAAK;QACL,IAAI,EAAE,OAAO;QACb,IAAI,EAAE,sBAAsB;QAC5B,MAAM;KAMP,CAAC;AACJ,CAAC,CAAC"}

package/dist/v1/runner/takeScreenshot.d.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 export declare const makeTakeScreenshotOnRunnerContract: () => {
-    readonly description: "Take one screenshot of an interactive runner's screen. The image is the runner's whole virtual desktop, browser window and all. `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. `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. `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. `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. Nothing was changed, so retrying is safe; if it persists, launch the runner again.";
+    readonly 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. `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. `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. `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. `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. Nothing was changed, so retrying is safe; if it persists, launch the runner again.";
     readonly input: z.ZodObject<{
         id: z.ZodString;
     }, z.core.$strip>;
@@ -12,9 +12,9 @@ export declare const makeTakeScreenshotOnRunnerContract: () => {
     }, z.core.$strip>, z.ZodObject<{
         failureReason: z.ZodEnum<{
             "runner-unreachable": "runner-unreachable";
-            "runner-has-no-screen": "runner-has-no-screen";
             "screen-needs-a-run": "screen-needs-a-run";
             "screen-not-ready": "screen-not-ready";
+            "runner-has-no-screen": "runner-has-no-screen";
         }>;
         outcome: z.ZodLiteral<"failure">;
     }, z.core.$strip>], "outcome">;

package/dist/v1/runner/takeScreenshot.js

@@ -25,7 +25,7 @@ export const makeTakeScreenshotOnRunnerContract = () => {
         ]),
     ]);
     return {
-        description: `Take one screenshot of an interactive runner's screen. The image is the runner's whole virtual desktop, browser window and all. ${screenNeedsARunDescription} ${screenNotReadyDescription} ${runnerHasNoScreenDescription} ${retryableRunnerUnreachableDescription}`,
+        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}`,
         input,
         kind: "read",
         name: "runner.takeScreenshot",

package/dist/v1/runner/takeScreenshot.js.map

@@ -1 +1 @@
-{"version":3,"file":"takeScreenshot.js","sourceRoot":"","sources":["../../../src/v1/runner/takeScreenshot.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EACL,4BAA4B,EAC5B,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,qCAAqC,EACrC,8BAA8B,GAC/B,MAAM,kBAAkB,CAAC;AAE1B,MAAM,CAAC,MAAM,kCAAkC,GAAG,GAAG,EAAE;IACrD,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC;QACrB,EAAE,EAAE,cAAc,CAAC,QAAQ,CAAC,2CAA2C,CAAC;KACzE,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,CAAC,CAAC,kBAAkB,CAAC,SAAS,EAAE;QAC7C,CAAC,CAAC,MAAM,CAAC;YACP,uEAAuE;YACvE,iEAAiE;YACjE,uEAAuE;YACvE,wBAAwB;YACxB,eAAe,EAAE,CAAC;iBACf,MAAM,EAAE;iBACR,GAAG,CAAC,CAAC,CAAC;iBACN,QAAQ,CACP,8KAA8K,CAC/K;YACH,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;SAC9B,CAAC;QACF,uBAAuB,CAAC;YACtB,GAAG,oBAAoB;YACvB,8BAA8B;SAC/B,CAAC;KACH,CAAC,CAAC;IAEH,OAAO;QACL,WAAW,EAAE,mIAAmI,0BAA0B,IAAI,yBAAyB,IAAI,4BAA4B,IAAI,qCAAqC,EAAE;QAClR,KAAK;QACL,IAAI,EAAE,MAAM;QACZ,IAAI,EAAE,uBAAuB;QAC7B,MAAM;KAMP,CAAC;AACJ,CAAC,CAAC"}
+{"version":3,"file":"takeScreenshot.js","sourceRoot":"","sources":["../../../src/v1/runner/takeScreenshot.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EACL,4BAA4B,EAC5B,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,qCAAqC,EACrC,8BAA8B,GAC/B,MAAM,kBAAkB,CAAC;AAE1B,MAAM,CAAC,MAAM,kCAAkC,GAAG,GAAG,EAAE;IACrD,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC;QACrB,EAAE,EAAE,cAAc,CAAC,QAAQ,CAAC,2CAA2C,CAAC;KACzE,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,CAAC,CAAC,kBAAkB,CAAC,SAAS,EAAE;QAC7C,CAAC,CAAC,MAAM,CAAC;YACP,uEAAuE;YACvE,iEAAiE;YACjE,uEAAuE;YACvE,wBAAwB;YACxB,eAAe,EAAE,CAAC;iBACf,MAAM,EAAE;iBACR,GAAG,CAAC,CAAC,CAAC;iBACN,QAAQ,CACP,8KAA8K,CAC/K;YACH,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;SAC9B,CAAC;QACF,uBAAuB,CAAC;YACtB,GAAG,oBAAoB;YACvB,8BAA8B;SAC/B,CAAC;KACH,CAAC,CAAC;IAEH,OAAO;QACL,WAAW,EAAE,0SAA0S,0BAA0B,IAAI,yBAAyB,IAAI,4BAA4B,IAAI,qCAAqC,EAAE;QACzb,KAAK;QACL,IAAI,EAAE,MAAM;QACZ,IAAI,EAAE,uBAAuB;QAC7B,MAAM;KAMP,CAAC;AACJ,CAAC,CAAC"}

package/dist/v1/runnerReexports.d.ts

@@ -0,0 +1,11 @@
+export { type BrowserAction, browserActionSchema, } from "./runner/browserAction.js";
+export { runEnvironmentSchema } from "./runner/environment.js";
+export { isShippableRunFilePath, runFilePathSchema, runPackageJsonPath, shippableRunFileExtensions, } from "./runner/files.js";
+export { type RunnerNameForPublicApi, makeRunnerSchema, runnerIdSchema, runnerNameSchema, } from "./runner/identity.js";
+export { type InspectOnRunnerRequest, inspectRequestSchema, } from "./runner/inspect.js";
+export { type InspectMobileRequest, inspectMobileRequestSchema, } from "./runner/inspectMobile.js";
+export { type JournalEntry, type JournalStream, type KnownJournalStream, type ReadJournalRequest, type ReadJournalResponse, journalEntrySchema, journalStreamSchema, knownJournalStreams, maxJournalStreamNameLength, readJournalRequestSchema, readJournalResponseSchema, } from "./runner/journal.js";
+export { type RunFiles, maxRunFilesByteLength, maxRunnerRequestEncodedByteLength, runFilesByteLength, runFilesSchema, } from "./runner/payloadSize.js";
+export { maxActionErrorMessageLength } from "./runner/performAction.js";
+export { type RunSelection, runSelectionSchema, } from "./runner/runSelection.js";
+//# sourceMappingURL=runnerReexports.d.ts.map

package/dist/v1/runnerReexports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runnerReexports.d.ts","sourceRoot":"","sources":["../../src/v1/runnerReexports.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,aAAa,EAClB,mBAAmB,GACpB,MAAM,2BAA2B,CAAC;AAInC,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAK/D,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,kBAAkB,EAClB,0BAA0B,GAC3B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,KAAK,sBAAsB,EAC3B,gBAAgB,EAChB,cAAc,EACd,gBAAgB,GACjB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,sBAAsB,EAC3B,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,KAAK,oBAAoB,EACzB,0BAA0B,GAC3B,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACnB,0BAA0B,EAC1B,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,KAAK,QAAQ,EACb,qBAAqB,EACrB,iCAAiC,EACjC,kBAAkB,EAClB,cAAc,GACf,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AACxE,OAAO,EACL,KAAK,YAAY,EACjB,kBAAkB,GACnB,MAAM,0BAA0B,CAAC"}

package/dist/v1/runnerReexports.js

@@ -0,0 +1,23 @@
+// The `runner` resource's shared types and schemas, re-exported here rather
+// than restated by every server and client that needs them. Split out of
+// `index.ts` to keep that file under the line limit.
+export { browserActionSchema, } from "./runner/browserAction.js";
+// Carries the reservation of QA Wolf's own variable names, which the server
+// validates with rather than restating — a second copy of that rule is how the
+// reservation comes to differ from what is actually stamped.
+export { runEnvironmentSchema } from "./runner/environment.js";
+// The travel rule for files bound for a runner: which files travel, how much may
+// travel, and what environment a run may carry. A client needs the predicate and
+// the size bounds to collect and pre-check with; the schemas are also what the
+// server and the runner validate with, so they are shared rather than restated.
+export { isShippableRunFilePath, runFilePathSchema, runPackageJsonPath, shippableRunFileExtensions, } from "./runner/files.js";
+export { makeRunnerSchema, runnerIdSchema, runnerNameSchema, } from "./runner/identity.js";
+export { inspectRequestSchema, } from "./runner/inspect.js";
+export { inspectMobileRequestSchema, } from "./runner/inspectMobile.js";
+// A journal read is answered verbatim by the public API, so its wire shapes are
+// published here and the private journal package imports them from here.
+export { journalEntrySchema, journalStreamSchema, knownJournalStreams, maxJournalStreamNameLength, readJournalRequestSchema, readJournalResponseSchema, } from "./runner/journal.js";
+export { maxRunFilesByteLength, maxRunnerRequestEncodedByteLength, runFilesByteLength, runFilesSchema, } from "./runner/payloadSize.js";
+export { maxActionErrorMessageLength } from "./runner/performAction.js";
+export { runSelectionSchema, } from "./runner/runSelection.js";
+//# sourceMappingURL=runnerReexports.js.map

package/dist/v1/runnerReexports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runnerReexports.js","sourceRoot":"","sources":["../../src/v1/runnerReexports.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,yEAAyE;AACzE,qDAAqD;AACrD,OAAO,EAEL,mBAAmB,GACpB,MAAM,2BAA2B,CAAC;AACnC,4EAA4E;AAC5E,+EAA+E;AAC/E,6DAA6D;AAC7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC/D,iFAAiF;AACjF,iFAAiF;AACjF,+EAA+E;AAC/E,gFAAgF;AAChF,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,kBAAkB,EAClB,0BAA0B,GAC3B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAEL,gBAAgB,EAChB,cAAc,EACd,gBAAgB,GACjB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAEL,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAEL,0BAA0B,GAC3B,MAAM,2BAA2B,CAAC;AACnC,gFAAgF;AAChF,yEAAyE;AACzE,OAAO,EAML,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACnB,0BAA0B,EAC1B,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAEL,qBAAqB,EACrB,iCAAiC,EACjC,kBAAkB,EAClB,cAAc,GACf,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AACxE,OAAO,EAEL,kBAAkB,GACnB,MAAM,0BAA0B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qawolf/api-contracts",
-  "version": "0.30.0",
+  "version": "0.33.0",
   "private": false,
   "description": "Versioned contracts for the QA Wolf public API",
   "repository": {