@qawolf/api-contracts 0.22.0 → 0.25.0

package/dist/v1/run/get.js

@@ -5,6 +5,89 @@ export const makeGetRunContract = (ids) => {
     const input = z.object({
         runId: ids.run,
     });
+    // Artifact URLs are signed without checking storage, so a fetch can return
+    // 404 when the attempt never produced that artifact. For example, only
+    // Playwright flows produce traces, and manual Wolf Browser attempts store
+    // no artifacts at all.
+    const artifactUrls = {
+        logsUrl: z
+            .url()
+            .optional()
+            .describe("Signed URL for the attempt's execution logs."),
+        traceUrl: z
+            .url()
+            .optional()
+            .describe("Signed URL for the attempt's Playwright trace (a trace.zip; open it with `npx playwright show-trace`)."),
+        videoUrl: z
+            .url()
+            .optional()
+            .describe("Signed URL for the attempt's screen recording."),
+    };
+    const automatedKind = z
+        .literal("automated")
+        .describe("The attempt ran on a QA Wolf runner.");
+    // A discriminated union like the flow entry itself. An attempt with a
+    // verdict always carries its completion time. A terminated attempt never
+    // carries artifact links. Manual Wolf Browser attempts always pass and
+    // never carry artifact links. The contract therefore cannot emit a record
+    // that contradicts its own status or kind.
+    const automatedAttempt = z.discriminatedUnion("status", [
+        z.object({
+            ...artifactUrls,
+            completedAt: z.iso.datetime(),
+            kind: automatedKind,
+            startedAt: z.iso.datetime(),
+            status: z.literal("passed"),
+        }),
+        z.object({
+            ...artifactUrls,
+            completedAt: z.iso.datetime(),
+            kind: automatedKind,
+            startedAt: z.iso
+                .datetime()
+                .optional()
+                .describe("Absent when the attempt failed before it could start."),
+            status: z.literal("failed"),
+        }),
+        z.object({
+            completedAt: z.iso.datetime().optional(),
+            kind: automatedKind,
+            startedAt: z.iso.datetime().optional(),
+            status: z
+                .literal("canceled")
+                .describe("The attempt was terminated without reaching a verdict."),
+        }),
+    ]);
+    const manualAttempt = z.object({
+        completedAt: z.iso.datetime(),
+        kind: z
+            .literal("manual")
+            .describe("The attempt ran by hand in the Wolf Browser."),
+        startedAt: z.iso.datetime(),
+        status: z.literal("passed"),
+    });
+    const attempt = z.union([automatedAttempt, manualAttempt]);
+    const attempts = z
+        .array(attempt)
+        .optional()
+        .describe("The flow's finished execution attempts, oldest first, including " +
+        "manual Wolf Browser attempts. Present once at least one attempt has " +
+        "finished, so a flow that passed after retries also lists its failed " +
+        "attempts. Artifact URLs appear only on automated attempts that " +
+        "reached a verdict, stay valid for at least a day (call run.get " +
+        "again for fresh ones), and can return 404 when the attempt did not " +
+        "produce that artifact.");
+    const diagnosis = z
+        .object({
+        issueId: ids.issue,
+        type: z.enum(["bug", "maintenance"]),
+    })
+        .optional()
+        .describe("QA Wolf's investigation verdict for the failure: `bug` means the " +
+        "application is broken, `maintenance` means the test needed an " +
+        "update and the failure does not indicate an application problem. " +
+        "Absent until the investigation reaches a verdict. Pass issueId to " +
+        "issue.get for details.");
     // We return one flat entry per flow, each carrying its own status, rather
     // than status-keyed buckets (`{ passed: [...], failed: [...] }`). A flat list
     // is a superset — the caller can group by status — and gives each flow a
@@ -19,7 +102,9 @@ export const makeGetRunContract = (ids) => {
     // "failed ⇔ failure present" instead of defensively checking, and we can't
     // accidentally emit a contradictory record.
     const failedFlow = z.object({
+        attempts,
         failure: z.object({
+            diagnosis,
             // The raw error from the run itself, available the moment the flow fails.
             // Chosen over QA Wolf's analyzed error (`RunAnalysisDto`): the analysis is
             // produced only after investigation and is usually absent while an agent
@@ -33,6 +118,7 @@ export const makeGetRunContract = (ids) => {
         status: z.literal("failed"),
     });
     const nonFailedFlow = z.object({
+        attempts,
         flowId: ids.flow,
         name: z.string(),
         status: z.enum(["queued", "running", "passed", "canceled"]),

package/dist/v1/run/get.js.map

@@ -1 +1 @@
-{"version":3,"file":"get.js","sourceRoot":"","sources":["../../../src/v1/run/get.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEpD,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAGhC,GAID,EAAE,EAAE;IACH,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC;QACrB,KAAK,EAAE,GAAG,CAAC,GAAG;KACf,CAAC,CAAC;IAEH,0EAA0E;IAC1E,8EAA8E;IAC9E,yEAAyE;IACzE,0EAA0E;IAC1E,4EAA4E;IAC5E,sEAAsE;IACtE,4BAA4B;IAC5B,0EAA0E;IAC1E,8EAA8E;IAC9E,4EAA4E;IAC5E,iEAAiE;IACjE,2EAA2E;IAC3E,4CAA4C;IAC5C,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC;QAC1B,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC;YAChB,0EAA0E;YAC1E,2EAA2E;YAC3E,yEAAyE;YACzE,+DAA+D;YAC/D,oEAAoE;YACpE,oDAAoD;YACpD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;SAClB,CAAC;QACF,MAAM,EAAE,GAAG,CAAC,IAAI;QAChB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;QAChB,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;KAC5B,CAAC,CAAC;IACH,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;QAC7B,MAAM,EAAE,GAAG,CAAC,IAAI;QAChB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;QAChB,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;KAC5D,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,CAAC;SACZ,KAAK,CAAC,CAAC,CAAC,kBAAkB,CAAC,QAAQ,EAAE,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC,CAAC;SAClE,QAAQ,CAAC,kDAAkD,CAAC,CAAC;IAEhE,MAAM,MAAM,GAAG,QAAQ,CACrB;QACE,GAAG,oBAAoB,CAAC,GAAG,CAAC;QAC5B,KAAK;QACL,yEAAyE;QACzE,uEAAuE;QACvE,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,QAAQ,CACrB,6RAA6R,CAC9R;KACF,EACD,EAAE,mBAAmB,EAAE,+BAA+B,EAAE,CACzD,CAAC;IAEF,OAAO;QACL,WAAW,EAAE,kDAAkD;QAC/D,KAAK;QACL,IAAI,EAAE,MAAM;QACZ,IAAI,EAAE,SAAS;QACf,MAAM;KAMP,CAAC;AACJ,CAAC,CAAC"}
+{"version":3,"file":"get.js","sourceRoot":"","sources":["../../../src/v1/run/get.ts"],"names":[],"mappings":"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"}

package/dist/v1/run/index.d.ts

@@ -2,13 +2,15 @@ import { z } from "zod";
 import type { PublicIdSchema } from "../ids.js";
 import { makeFlowSelectionSchema } from "./flowSelection.js";
 export { makeFlowSelectionSchema };
-export declare const makeCreateRunContract: <FlowId extends PublicIdSchema, RunId extends PublicIdSchema>(ids: {
+export declare const makeCreateRunContract: <AiTaskId extends PublicIdSchema, FlowId extends PublicIdSchema, RunId extends PublicIdSchema>(ids: {
+    aiTask: AiTaskId;
     environmentRef: PublicIdSchema;
     flow: FlowId;
     run: RunId;
 }) => {
     readonly description: "Create a run for the selected flows and/or tags in an environment.";
     readonly input: z.ZodIntersection<z.ZodObject<{
+        aiTaskId: z.ZodOptional<AiTaskId>;
         environmentId: PublicIdSchema;
         environmentVariables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         ignoreRules: z.ZodDefault<z.ZodBoolean>;

package/dist/v1/run/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/v1/run/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAGhD,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAE7D,OAAO,EAAE,uBAAuB,EAAE,CAAC;AAEnC,eAAO,MAAM,qBAAqB,GAChC,MAAM,SAAS,cAAc,EAC7B,KAAK,SAAS,cAAc,EAC5B,KAAK;IACL,cAAc,EAAE,cAAc,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,KAAK,CAAC;CACZ;;;;;;;;;;;;;;;;;;CAyCA,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/v1/run/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAGhD,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAE7D,OAAO,EAAE,uBAAuB,EAAE,CAAC;AAEnC,eAAO,MAAM,qBAAqB,GAChC,QAAQ,SAAS,cAAc,EAC/B,MAAM,SAAS,cAAc,EAC7B,KAAK,SAAS,cAAc,EAC5B,KAAK;IACL,MAAM,EAAE,QAAQ,CAAC;IACjB,cAAc,EAAE,cAAc,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,KAAK,CAAC;CACZ;;;;;;;;;;;;;;;;;;;CA8CA,CAAC"}

package/dist/v1/run/index.js

@@ -5,6 +5,9 @@ export { makeFlowSelectionSchema };
 export const makeCreateRunContract = (ids) => {
     const input = z
         .object({
+        aiTaskId: ids.aiTask
+            .describe("The AI task whose conversation should receive run status updates.")
+            .optional(),
         environmentId: ids.environmentRef,
         environmentVariables: z.record(z.string(), z.string()).optional(),
         ignoreRules: z.boolean().default(false),

package/dist/v1/run/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/v1/run/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAE7D,OAAO,EAAE,uBAAuB,EAAE,CAAC;AAEnC,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAGnC,GAID,EAAE,EAAE;IACH,MAAM,KAAK,GAAG,CAAC;SACZ,MAAM,CAAC;QACN,aAAa,EAAE,GAAG,CAAC,cAAc;QACjC,oBAAoB,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;QACjE,WAAW,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;QACvC,+DAA+D;QAC/D,wEAAwE;QACxE,gEAAgE;QAChE,+BAA+B;QAC/B,iBAAiB,EAAE,CAAC;aACjB,MAAM,EAAE;aACR,GAAG,EAAE;aACL,QAAQ,EAAE;aACV,QAAQ,CAAC,2DAA2D,CAAC;aACrE,QAAQ,EAAE;QACb,UAAU,EAAE,CAAC;aACV,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,CAAC,oDAAoD,CAAC;aAC9D,QAAQ,EAAE;KACd,CAAC;SACD,GAAG,CAAC,uBAAuB,CAAC,GAAG,CAAC,CAAC,CAAC;IACrC,MAAM,MAAM,GAAG,QAAQ,CACrB,EAAE,KAAK,EAAE,GAAG,CAAC,GAAG,EAAE,EAClB,EAAE,mBAAmB,EAAE,+BAA+B,EAAE,CACzD,CAAC;IAEF,OAAO;QACL,WAAW,EACT,oEAAoE;QACtE,KAAK;QACL,IAAI,EAAE,OAAO;QACb,IAAI,EAAE,YAAY;QAClB,MAAM;KAMP,CAAC;AACJ,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/v1/run/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAE7D,OAAO,EAAE,uBAAuB,EAAE,CAAC;AAEnC,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAInC,GAKD,EAAE,EAAE;IACH,MAAM,KAAK,GAAG,CAAC;SACZ,MAAM,CAAC;QACN,QAAQ,EAAE,GAAG,CAAC,MAAM;aACjB,QAAQ,CACP,mEAAmE,CACpE;aACA,QAAQ,EAAE;QACb,aAAa,EAAE,GAAG,CAAC,cAAc;QACjC,oBAAoB,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;QACjE,WAAW,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;QACvC,+DAA+D;QAC/D,wEAAwE;QACxE,gEAAgE;QAChE,+BAA+B;QAC/B,iBAAiB,EAAE,CAAC;aACjB,MAAM,EAAE;aACR,GAAG,EAAE;aACL,QAAQ,EAAE;aACV,QAAQ,CAAC,2DAA2D,CAAC;aACrE,QAAQ,EAAE;QACb,UAAU,EAAE,CAAC;aACV,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,CAAC,oDAAoD,CAAC;aAC9D,QAAQ,EAAE;KACd,CAAC;SACD,GAAG,CAAC,uBAAuB,CAAC,GAAG,CAAC,CAAC,CAAC;IACrC,MAAM,MAAM,GAAG,QAAQ,CACrB,EAAE,KAAK,EAAE,GAAG,CAAC,GAAG,EAAE,EAClB,EAAE,mBAAmB,EAAE,+BAA+B,EAAE,CACzD,CAAC;IAEF,OAAO;QACL,WAAW,EACT,oEAAoE;QACtE,KAAK;QACL,IAAI,EAAE,OAAO;QACb,IAAI,EAAE,YAAY;QAClB,MAAM;KAMP,CAAC;AACJ,CAAC,CAAC"}

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

@@ -0,0 +1,39 @@
+import { z } from "zod";
+/** The action shapes, bounded. Strict: a bound rejects rather than truncates. */
+export declare const browserActionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    button: z.ZodLiteral<"left" | "right" | "wheel" | "back" | "forward">;
+    type: z.ZodLiteral<"click">;
+    x: z.ZodInt;
+    y: z.ZodInt;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"double_click">;
+    x: z.ZodInt;
+    y: z.ZodInt;
+}, z.core.$strict>, z.ZodObject<{
+    scroll_x: z.ZodInt;
+    scroll_y: z.ZodInt;
+    type: z.ZodLiteral<"scroll">;
+    x: z.ZodInt;
+    y: z.ZodInt;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"move">;
+    x: z.ZodInt;
+    y: z.ZodInt;
+}, z.core.$strict>, z.ZodObject<{
+    path: z.ZodArray<z.ZodObject<{
+        x: z.ZodInt;
+        y: z.ZodInt;
+    }, z.core.$strict>>;
+    type: z.ZodLiteral<"drag">;
+}, z.core.$strict>, z.ZodObject<{
+    keys: z.ZodArray<z.ZodString>;
+    type: z.ZodLiteral<"keypress">;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"navigate">;
+    url: z.ZodURL;
+}, z.core.$strict>, z.ZodObject<{
+    text: z.ZodString;
+    type: z.ZodLiteral<"type">;
+}, z.core.$strict>], "type">;
+export type BrowserAction = z.infer<typeof browserActionSchema>;
+//# sourceMappingURL=browserAction.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"browserAction.d.ts","sourceRoot":"","sources":["../../../src/v1/runner/browserAction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA4CxB,iFAAiF;AACjF,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BA+C9B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/v1/runner/browserAction.js

@@ -0,0 +1,82 @@
+import { z } from "zod";
+/**
+ * The input of `runner.performAction`, validated with the same schema by apex and
+ * the runner. Only ever tighten a bound: pods deploy separately, so a widened
+ * bound forwards actions an older pod rejects.
+ *
+ * `snake_case` on purpose: these are the computer-use tool names.
+ */
+/** A whole pixel on the runner's virtual desktop. */
+const maxScreenCoordinate = 20_000;
+const screenCoordinateSchema = z.int().min(0).max(maxScreenCoordinate);
+const screenPointSchema = z.strictObject({
+    x: screenCoordinateSchema,
+    y: screenCoordinateSchema,
+});
+/** A signed wheel delta in whole pixels. A full page is a few hundred. */
+const maxScrollDelta = 5_000;
+const scrollDeltaSchema = z.int().min(-maxScrollDelta).max(maxScrollDelta);
+/** The keyboard is held for 50 ms per character, so 200 of them is ten seconds. */
+const maxTypedTextLength = 200;
+/** A chord is modifiers plus a key, and names are like `ArrowDown` or `a`. */
+const maxKeypressKeys = 10;
+const maxKeyNameLength = 32;
+/** A sampled path, each point a pointer event. Fewer than two is not a drag. */
+const minDragPathPoints = 2;
+const maxDragPathPoints = 100;
+/** The de-facto ceiling browsers honour. */
+const maxNavigateUrlLength = 2048;
+/** Only the two schemes a browser navigation means, matched on the parsed scheme. */
+const navigableUrlSchema = z
+    .url({ protocol: /^https?$/ })
+    .max(maxNavigateUrlLength);
+/** The action shapes, bounded. Strict: a bound rejects rather than truncates. */
+export const browserActionSchema = z.discriminatedUnion("type", [
+    z.strictObject({
+        button: z.literal(["left", "right", "wheel", "back", "forward"]),
+        type: z.literal("click"),
+        x: screenCoordinateSchema,
+        y: screenCoordinateSchema,
+    }),
+    z.strictObject({
+        type: z.literal("double_click"),
+        x: screenCoordinateSchema,
+        y: screenCoordinateSchema,
+    }),
+    z.strictObject({
+        scroll_x: scrollDeltaSchema,
+        scroll_y: scrollDeltaSchema,
+        type: z.literal("scroll"),
+        x: screenCoordinateSchema,
+        y: screenCoordinateSchema,
+    }),
+    z.strictObject({
+        type: z.literal("move"),
+        x: screenCoordinateSchema,
+        y: screenCoordinateSchema,
+    }),
+    z.strictObject({
+        path: z
+            .array(screenPointSchema)
+            .min(minDragPathPoints)
+            .max(maxDragPathPoints),
+        type: z.literal("drag"),
+    }),
+    z.strictObject({
+        keys: z
+            .array(z.string().min(1).max(maxKeyNameLength))
+            .min(1)
+            .max(maxKeypressKeys),
+        type: z.literal("keypress"),
+    }),
+    /** The one action not performed on the screen: it goes to the last active page. */
+    z.strictObject({
+        type: z.literal("navigate"),
+        url: navigableUrlSchema,
+    }),
+    z.strictObject({
+        text: z.string().min(1).max(maxTypedTextLength),
+        type: z.literal("type"),
+    }),
+]);
+//# sourceMappingURL=browserAction.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"browserAction.js","sourceRoot":"","sources":["../../../src/v1/runner/browserAction.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,61 @@
+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). `performed` if the action took effect. `action-failed`, with a reason, if it reached the runner and did not take effect. `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. A `navigate` does not go through the screen, so a screen that is not ready does not stop it — but it still needs the runner to have run something, and until then it answers `action-failed` rather than `screen-needs-a-run`. `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 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">;
+            type: z.ZodLiteral<"click">;
+            x: z.ZodInt;
+            y: z.ZodInt;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"double_click">;
+            x: z.ZodInt;
+            y: z.ZodInt;
+        }, z.core.$strict>, z.ZodObject<{
+            scroll_x: z.ZodInt;
+            scroll_y: z.ZodInt;
+            type: z.ZodLiteral<"scroll">;
+            x: z.ZodInt;
+            y: z.ZodInt;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"move">;
+            x: z.ZodInt;
+            y: z.ZodInt;
+        }, z.core.$strict>, z.ZodObject<{
+            path: z.ZodArray<z.ZodObject<{
+                x: z.ZodInt;
+                y: z.ZodInt;
+            }, z.core.$strict>>;
+            type: z.ZodLiteral<"drag">;
+        }, z.core.$strict>, z.ZodObject<{
+            keys: z.ZodArray<z.ZodString>;
+            type: z.ZodLiteral<"keypress">;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"navigate">;
+            url: z.ZodURL;
+        }, z.core.$strict>, z.ZodObject<{
+            text: z.ZodString;
+            type: z.ZodLiteral<"type">;
+        }, z.core.$strict>], "type">;
+        id: z.ZodString;
+    }, z.core.$strip>;
+    readonly kind: "write";
+    readonly name: "runner.performAction";
+    readonly output: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        outcome: z.ZodLiteral<"performed">;
+    }, z.core.$strip>, z.ZodObject<{
+        errorMessage: z.ZodString;
+        outcome: z.ZodLiteral<"action-failed">;
+    }, 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=performAction.d.ts.map

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

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

package/dist/v1/runner/performAction.js

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import { browserActionSchema } from "./browserAction.js";
+import { runnerIdSchema } from "./identity.js";
+import { runnerHasNoScreenDescription, runnerHasNoScreenSchema, runnerScreenNeedsARunSchema, runnerScreenNotReadySchema, screenNeedsARunDescription, screenNotReadyDescription, } from "./screen.js";
+import { runnerUnreachableSchema } 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.";
+/** How much of a failure reason this API passes on. */
+export const maxActionErrorMessageLength = 1_000;
+export const makePerformActionOnRunnerContract = () => {
+    const input = z.object({
+        action: browserActionSchema.describe("The action to perform. Coordinates are pixels on the screenshot's own coordinate space."),
+        id: runnerIdSchema.describe("Id of the runner to act on."),
+    });
+    const output = z.discriminatedUnion("outcome", [
+        z.object({ outcome: z.literal("performed") }),
+        z.object({
+            errorMessage: z
+                .string()
+                .max(maxActionErrorMessageLength)
+                .describe("What stopped the action from taking effect."),
+            outcome: z.literal("action-failed"),
+        }),
+        runnerScreenNeedsARunSchema,
+        runnerScreenNotReadySchema,
+        runnerHasNoScreenSchema,
+        runnerUnreachableSchema,
+    ]);
+    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). \`performed\` if the action took effect. \`action-failed\`, with a reason, if it reached the runner and did not take effect. ${screenNeedsARunDescription} ${screenNotReadyDescription} A \`navigate\` does not go through the screen, so a screen that is not ready does not stop it — but it still needs the runner to have run something, and until then it answers \`action-failed\` rather than \`screen-needs-a-run\`. ${runnerHasNoScreenDescription} ${unreachableDescription}`,
+        input,
+        kind: "write",
+        name: "runner.performAction",
+        output,
+    };
+};
+//# sourceMappingURL=performAction.js.map

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

@@ -0,0 +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,EACL,4BAA4B,EAC5B,uBAAuB,EACvB,2BAA2B,EAC3B,0BAA0B,EAC1B,0BAA0B,EAC1B,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAE3D,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,MAAM,MAAM,GAAG,CAAC,CAAC,kBAAkB,CAAC,SAAS,EAAE;QAC7C,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC;QAC7C,CAAC,CAAC,MAAM,CAAC;YACP,YAAY,EAAE,CAAC;iBACZ,MAAM,EAAE;iBACR,GAAG,CAAC,2BAA2B,CAAC;iBAChC,QAAQ,CAAC,6CAA6C,CAAC;YAC1D,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC;SACpC,CAAC;QACF,2BAA2B;QAC3B,0BAA0B;QAC1B,uBAAuB;QACvB,uBAAuB;KACxB,CAAC,CAAC;IAEH,OAAO;QACL,WAAW,EAAE,gkBAAgkB,0BAA0B,IAAI,yBAAyB,yOAAyO,4BAA4B,IAAI,sBAAsB,EAAE;QACr6B,KAAK;QACL,IAAI,EAAE,OAAO;QACb,IAAI,EAAE,sBAAsB;QAC5B,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/package.json

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