@qawolf/api-contracts 0.20.0 → 0.24.0

package/dist/v1/runner/runFlow.js

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import { runEnvironmentSchema } from "./environment.js";
+import { runFilePathSchema, runPackageJsonPath } from "./files.js";
+import { runnerIdSchema, runnerNameSchema } from "./identity.js";
+import { runFilesSchema } from "./payloadSize.js";
+import { runnerUnreachableSchema } from "./unreachable.js";
+export const makeRunFlowOnRunnerContract = () => {
+    const input = z
+        .object({
+        entryPointPath: runFilePathSchema.describe("Path of the flow file to run, as it appears in `files`."),
+        env: runEnvironmentSchema
+            .optional()
+            .describe("Environment variables to make available to the run."),
+        files: runFilesSchema.describe("Every file the run needs keyed by its path — the flow file, everything it imports, package.json and tsconfig.json. A runner holds no copy of your project, so what runs is exactly what is sent here."),
+        id: runnerIdSchema.describe("Id of the runner to run the flow on."),
+    })
+        // Stated here rather than discovered when the runner cannot find a module.
+        .refine((request) => Object.hasOwn(request.files, request.entryPointPath), {
+        error: "The entry point must be one of the files.",
+        path: ["files"],
+    })
+        .refine((request) => Object.hasOwn(request.files, runPackageJsonPath), {
+        error: `The files must include ${runPackageJsonPath}; the run's npm dependencies are read from it.`,
+        path: ["files"],
+    });
+    const output = z.discriminatedUnion("outcome", [
+        z.object({
+            outcome: z.literal("submitted"),
+            runId: z
+                .string()
+                .describe("Id of the run, to follow it by. Read the `run-status` stream of the runner's journal for its outcome, and `run-logs` and `run-events` for its output."),
+        }),
+        runnerUnreachableSchema,
+        z.object({
+            outcome: z.literal("runner-target-mismatch"),
+            requiredRunnerName: runnerNameSchema.describe("The image this flow's execution target needs."),
+            runnerName: runnerNameSchema.describe("The image the runner is actually running."),
+        }),
+    ]);
+    return {
+        description: "Run a flow on an interactive runner. 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 answers `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",
+        name: "runner.runFlow",
+        output,
+    };
+};
+//# sourceMappingURL=runFlow.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runFlow.js","sourceRoot":"","sources":["../../../src/v1/runner/runFlow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAE3D,MAAM,CAAC,MAAM,2BAA2B,GAAG,GAAG,EAAE;IAC9C,MAAM,KAAK,GAAG,CAAC;SACZ,MAAM,CAAC;QACN,cAAc,EAAE,iBAAiB,CAAC,QAAQ,CACxC,yDAAyD,CAC1D;QACD,GAAG,EAAE,oBAAoB;aACtB,QAAQ,EAAE;aACV,QAAQ,CAAC,qDAAqD,CAAC;QAClE,KAAK,EAAE,cAAc,CAAC,QAAQ,CAC5B,uMAAuM,CACxM;QACD,EAAE,EAAE,cAAc,CAAC,QAAQ,CAAC,sCAAsC,CAAC;KACpE,CAAC;QACF,2EAA2E;SAC1E,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,cAAc,CAAC,EAAE;QACzE,KAAK,EAAE,2CAA2C;QAClD,IAAI,EAAE,CAAC,OAAO,CAAC;KAChB,CAAC;SACD,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,kBAAkB,CAAC,EAAE;QACrE,KAAK,EAAE,0BAA0B,kBAAkB,gDAAgD;QACnG,IAAI,EAAE,CAAC,OAAO,CAAC;KAChB,CAAC,CAAC;IAEL,MAAM,MAAM,GAAG,CAAC,CAAC,kBAAkB,CAAC,SAAS,EAAE;QAC7C,CAAC,CAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC;YAC/B,KAAK,EAAE,CAAC;iBACL,MAAM,EAAE;iBACR,QAAQ,CACP,uJAAuJ,CACxJ;SACJ,CAAC;QACF,uBAAuB;QACvB,CAAC,CAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,wBAAwB,CAAC;YAC5C,kBAAkB,EAAE,gBAAgB,CAAC,QAAQ,CAC3C,+CAA+C,CAChD;YACD,UAAU,EAAE,gBAAgB,CAAC,QAAQ,CACnC,2CAA2C,CAC5C;SACF,CAAC;KACH,CAAC,CAAC;IAEH,OAAO;QACL,WAAW,EACT,iwBAAiwB;QACnwB,KAAK;QACL,IAAI,EAAE,OAAO;QACb,IAAI,EAAE,gBAAgB;QACtB,MAAM;KAMP,CAAC;AACJ,CAAC,CAAC"}

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

@@ -0,0 +1,14 @@
+import { z } from "zod";
+export declare const runnerScreenNotReadySchema: z.ZodObject<{
+    outcome: z.ZodLiteral<"screen-not-ready">;
+}, z.core.$strip>;
+export declare const screenNotReadyDescription = "`screen-not-ready` if the runner has a screen that cannot serve this instant. Retry in a second or two: the desktop restarts when a run changes the display size, and it serves one see-or-act request at a time, so a screenshot or action already in flight is the usual reason. Do not submit a run to clear this \u2014 a run may restart the display and discard what is on it.";
+export declare const runnerScreenNeedsARunSchema: z.ZodObject<{
+    outcome: z.ZodLiteral<"screen-needs-a-run">;
+}, z.core.$strip>;
+export declare const screenNeedsARunDescription = "`screen-needs-a-run` if the runner has not run anything yet, so its virtual desktop has never started. Waiting will not change this and retrying is pointless \u2014 call `runner.runFlow` on the runner, then ask for the screen again. Evaluating a snippet does not start the desktop.";
+export declare const runnerHasNoScreenSchema: z.ZodObject<{
+    outcome: z.ZodLiteral<"runner-has-no-screen">;
+}, z.core.$strip>;
+export declare const runnerHasNoScreenDescription = "`runner-has-no-screen` if this runner is not one that runs a browser on a virtual desktop. Nothing about it can be seen or driven, and retrying will never help \u2014 launch a `node20WithPlaywright` runner instead.";
+//# sourceMappingURL=screen.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"screen.d.ts","sourceRoot":"","sources":["../../../src/v1/runner/screen.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,0BAA0B;;iBAErC,CAAC;AAEH,eAAO,MAAM,yBAAyB,yXAC6U,CAAC;AAIpX,eAAO,MAAM,2BAA2B;;iBAEtC,CAAC;AAEH,eAAO,MAAM,0BAA0B,8RACiP,CAAC;AAEzR,eAAO,MAAM,uBAAuB;;iBAElC,CAAC;AAEH,eAAO,MAAM,4BAA4B,2NAC4K,CAAC"}

package/dist/v1/runner/screen.js

@@ -0,0 +1,16 @@
+import { z } from "zod";
+export const runnerScreenNotReadySchema = z.object({
+    outcome: z.literal("screen-not-ready"),
+});
+export const screenNotReadyDescription = "`screen-not-ready` if the runner has a screen that cannot serve this instant. Retry in a second or two: the desktop restarts when a run changes the display size, and it serves one see-or-act request at a time, so a screenshot or action already in flight is the usual reason. Do not submit a run to clear this — a run may restart the display and discard what is on it.";
+// Its own outcome, not a sentence inside `screen-not-ready`: the callers here are
+// models, and an instruction that only exists in prose is one they may not follow.
+export const runnerScreenNeedsARunSchema = z.object({
+    outcome: z.literal("screen-needs-a-run"),
+});
+export const screenNeedsARunDescription = "`screen-needs-a-run` if the runner has not run anything yet, so its virtual desktop has never started. Waiting will not change this and retrying is pointless — call `runner.runFlow` on the runner, then ask for the screen again. Evaluating a snippet does not start the desktop.";
+export const runnerHasNoScreenSchema = z.object({
+    outcome: z.literal("runner-has-no-screen"),
+});
+export const runnerHasNoScreenDescription = "`runner-has-no-screen` if this runner is not one that runs a browser on a virtual desktop. Nothing about it can be seen or driven, and retrying will never help — launch a `node20WithPlaywright` runner instead.";
+//# sourceMappingURL=screen.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"screen.js","sourceRoot":"","sources":["../../../src/v1/runner/screen.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAAC;CACvC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,yBAAyB,GACpC,iXAAiX,CAAC;AAEpX,kFAAkF;AAClF,mFAAmF;AACnF,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,oBAAoB,CAAC;CACzC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,0BAA0B,GACrC,sRAAsR,CAAC;AAEzR,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,sBAAsB,CAAC;CAC3C,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,4BAA4B,GACvC,mNAAmN,CAAC"}

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

@@ -0,0 +1,22 @@
+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 has not run anything yet, so its virtual desktop has never started. Waiting will not change this and retrying is pointless — call `runner.runFlow` on the runner, then ask for the screen again. 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 `node20WithPlaywright` 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>;
+    readonly kind: "read";
+    readonly name: "runner.takeScreenshot";
+    readonly output: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        imageJpegBase64: z.ZodString;
+        outcome: z.ZodLiteral<"captured">;
+    }, z.core.$strip>, z.ZodObject<{
+        outcome: z.ZodLiteral<"screen-needs-a-run">;
+    }, z.core.$strip>, z.ZodObject<{
+        outcome: z.ZodLiteral<"screen-not-ready">;
+    }, z.core.$strip>, z.ZodObject<{
+        outcome: z.ZodLiteral<"runner-has-no-screen">;
+    }, z.core.$strip>, z.ZodObject<{
+        outcome: z.ZodLiteral<"runner-unreachable">;
+    }, z.core.$strip>], "outcome">;
+};
+//# sourceMappingURL=takeScreenshot.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"takeScreenshot.d.ts","sourceRoot":"","sources":["../../../src/v1/runner/takeScreenshot.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAkBxB,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;;;;CAqC9C,CAAC"}

package/dist/v1/runner/takeScreenshot.js

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import { runnerIdSchema } from "./identity.js";
+import { runnerHasNoScreenDescription, runnerHasNoScreenSchema, runnerScreenNeedsARunSchema, runnerScreenNotReadySchema, screenNeedsARunDescription, screenNotReadyDescription, } from "./screen.js";
+import { retryableRunnerUnreachableDescription, runnerUnreachableSchema, } from "./unreachable.js";
+export const makeTakeScreenshotOnRunnerContract = () => {
+    const input = z.object({
+        id: runnerIdSchema.describe("Id of the runner to take a screenshot of."),
+    });
+    const output = z.discriminatedUnion("outcome", [
+        z.object({
+            // Not `z.base64()`: its regex runs against every multi-megabyte frame,
+            // on the server and in every client that parses with this schema
+            // (https://github.com/colinhacks/zod/issues/4283), and the value comes
+            // from our own encoder.
+            imageJpegBase64: z
+                .string()
+                .min(1)
+                .describe("The screenshot, as a base64-encoded JPEG. Decode it and write the bytes to a `.jpg` file — writing this string to the file leaves you with base64 text rather than an image."),
+            outcome: z.literal("captured"),
+        }),
+        runnerScreenNeedsARunSchema,
+        runnerScreenNotReadySchema,
+        runnerHasNoScreenSchema,
+        runnerUnreachableSchema,
+    ]);
+    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}`,
+        input,
+        kind: "read",
+        name: "runner.takeScreenshot",
+        output,
+    };
+};
+//# sourceMappingURL=takeScreenshot.js.map

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

@@ -0,0 +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,EACL,4BAA4B,EAC5B,uBAAuB,EACvB,2BAA2B,EAC3B,0BAA0B,EAC1B,0BAA0B,EAC1B,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,qCAAqC,EACrC,uBAAuB,GACxB,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,UAAU,CAAC;SAC/B,CAAC;QACF,2BAA2B;QAC3B,0BAA0B;QAC1B,uBAAuB;QACvB,uBAAuB;KACxB,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"}

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

@@ -0,0 +1,16 @@
+import { z } from "zod";
+/**
+ * The one answer every verb that talks to a live runner can give instead of
+ * doing the work. One condition, because telling pod states apart would commit
+ * a published contract to a taxonomy of transient ones. Carries no advice —
+ * whether a retry is safe differs per verb, and each verb says so itself.
+ */
+export declare const runnerUnreachableSchema: z.ZodObject<{
+    outcome: z.ZodLiteral<"runner-unreachable">;
+}, z.core.$strip>;
+/**
+ * For verbs that change nothing when they fail. A verb that may already have
+ * taken effect must not use this — see `runner.runFlow`.
+ */
+export declare const retryableRunnerUnreachableDescription = "`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.";
+//# sourceMappingURL=unreachable.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"unreachable.d.ts","sourceRoot":"","sources":["../../../src/v1/runner/unreachable.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB;;iBAElC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,qCAAqC,oPACiM,CAAC"}

package/dist/v1/runner/unreachable.js

@@ -0,0 +1,16 @@
+import { z } from "zod";
+/**
+ * The one answer every verb that talks to a live runner can give instead of
+ * doing the work. One condition, because telling pod states apart would commit
+ * a published contract to a taxonomy of transient ones. Carries no advice —
+ * whether a retry is safe differs per verb, and each verb says so itself.
+ */
+export const runnerUnreachableSchema = z.object({
+    outcome: z.literal("runner-unreachable"),
+});
+/**
+ * For verbs that change nothing when they fail. A verb that may already have
+ * taken effect must not use this — see `runner.runFlow`.
+ */
+export const retryableRunnerUnreachableDescription = "`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.";
+//# sourceMappingURL=unreachable.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"unreachable.js","sourceRoot":"","sources":["../../../src/v1/runner/unreachable.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,oBAAoB,CAAC;CACzC,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,qCAAqC,GAChD,iPAAiP,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qawolf/api-contracts",
-  "version": "0.20.0",
+  "version": "0.24.0",
   "private": false,
   "description": "Versioned contracts for the QA Wolf public API",
   "repository": {
@@ -27,10 +27,10 @@
   },
   "scripts": {
     "build": "rm -rf ./dist && tsc -p tsconfig.build.json",
-    "lint:ci": "npm run lint:non-fixable; NON_FIXABLE_EXIT=$?; npm run lint:fixable && exit $NON_FIXABLE_EXIT",
-    "lint:dev": "npm run lint:fixable",
-    "lint:fixable": "eslint . --fix --quiet && oxfmt --write .",
-    "lint:non-fixable": "dpdm --exit-code circular:1 --no-tree --no-warning --transform --include='.*' --exclude='/(dist|node_modules)/' '**/*'",
+    "lint:ci": "npm run lint:first-half; FIRST_HALF_EXIT=$?; npm run lint:second-half && exit $FIRST_HALF_EXIT",
+    "lint:dev": "npm run lint:first-half",
+    "lint:first-half": "eslint . --fix --quiet && oxfmt --write .",
+    "lint:second-half": "dpdm --exit-code circular:1 --no-tree --no-warning --transform --include='.*' --exclude='/(dist|node_modules)/' '**/*'",
     "prepublishOnly": "npm run build",
     "test": "NODE_OPTIONS=\"--experimental-vm-modules\" NODE_NO_WARNINGS=1 jest",
     "tsc:check": "tsgo --noEmit -p tsconfig.typecheck.json"
@@ -47,6 +47,6 @@
     "zod": "^4.1.11"
   },
   "engines": {
-    "node": ">=22.22.0 <25"
+    "node": ">=20.19.0 <25"
   }
 }