@qawolf/api-contracts 0.25.0 → 0.27.0

package/dist/v1/runner/index.js

@@ -5,36 +5,38 @@ export const makeLaunchRunnerContract = () => {
         id: runnerIdSchema.describe("Id to launch the runner under, chosen by the caller. Launching the same id again returns the runner already running under it."),
         runnerName: runnerNameSchema
             .optional()
-            .describe("Image to run. Defaults to the standard web image, node20WithPlaywright."),
+            .describe("The runner family to launch. Defaults to the standard web family, playwright."),
     });
     const output = makeRunnerSchema().extend({
-        outcome: z
-            .enum(["launched", "already-running"])
-            .describe("`launched` if this call started the runner. `already-running` if a runner was already running under this id and was returned unchanged — no second runner was started."),
+        alreadyRunning: z
+            .boolean()
+            .describe("True when a runner was already running under this id and was returned unchanged, so no second runner was started and nothing new is billed. Not an error either way."),
+        outcome: z.literal("success"),
     });
     return {
-        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 `outcome` to tell which happened.",
+        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",
         name: "runner.launch",
         output,
     };
 };
-export const makeStopRunnerContract = () => {
+export const makeTerminateRunnerContract = () => {
     const input = z.object({
-        id: runnerIdSchema.describe("Id of the runner to stop."),
+        id: runnerIdSchema.describe("Id of the runner to terminate."),
     });
     const output = z.object({
         id: runnerIdSchema.describe("Id of the runner the call addressed."),
-        outcome: z
-            .enum(["stopped", "not-running"])
-            .describe("`stopped` if the runner was running and has been stopped. `not-running` if no running runner has this id — it was already stopped, 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."),
+        outcome: z.literal("success"),
+        wasRunning: z
+            .boolean()
+            .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 {
-        description: "Stop an interactive runner on the caller's team. Stopping a runner that is not running succeeds and reports `not-running`, so a retry needs no special handling.",
+        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",
-        name: "runner.stop",
+        name: "runner.terminate",
         output,
     };
 };

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/v1/runner/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAEvB,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAG,EAAE;IAC3C,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC;QACrB,EAAE,EAAE,cAAc,CAAC,QAAQ,CACzB,+HAA+H,CAChI;QACD,UAAU,EAAE,gBAAgB;aACzB,QAAQ,EAAE;aACV,QAAQ,CACP,yEAAyE,CAC1E;KACJ,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,gBAAgB,EAAE,CAAC,MAAM,CAAC;QACvC,OAAO,EAAE,CAAC;aACP,IAAI,CAAC,CAAC,UAAU,EAAE,iBAAiB,CAAC,CAAC;aACrC,QAAQ,CACP,wKAAwK,CACzK;KACJ,CAAC,CAAC;IAEH,OAAO;QACL,WAAW,EACT,8aAA8a;QAChb,KAAK;QACL,IAAI,EAAE,OAAO;QACb,IAAI,EAAE,eAAe;QACrB,MAAM;KAMP,CAAC;AACJ,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,EAAE;IACzC,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC;QACrB,EAAE,EAAE,cAAc,CAAC,QAAQ,CAAC,2BAA2B,CAAC;KACzD,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;QACtB,EAAE,EAAE,cAAc,CAAC,QAAQ,CAAC,sCAAsC,CAAC;QACnE,OAAO,EAAE,CAAC;aACP,IAAI,CAAC,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;aAChC,QAAQ,CACP,oSAAoS,CACrS;KACJ,CAAC,CAAC;IAEH,OAAO;QACL,WAAW,EACT,kKAAkK;QACpK,KAAK;QACL,IAAI,EAAE,OAAO;QACb,IAAI,EAAE,aAAa;QACnB,MAAM;KAMP,CAAC;AACJ,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/v1/runner/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAEvB,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAG,EAAE;IAC3C,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC;QACrB,EAAE,EAAE,cAAc,CAAC,QAAQ,CACzB,+HAA+H,CAChI;QACD,UAAU,EAAE,gBAAgB;aACzB,QAAQ,EAAE;aACV,QAAQ,CACP,+EAA+E,CAChF;KACJ,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,gBAAgB,EAAE,CAAC,MAAM,CAAC;QACvC,cAAc,EAAE,CAAC;aACd,OAAO,EAAE;aACT,QAAQ,CACP,sKAAsK,CACvK;QACH,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;KAC9B,CAAC,CAAC;IAEH,OAAO;QACL,WAAW,EACT,qbAAqb;QACvb,KAAK;QACL,IAAI,EAAE,OAAO;QACb,IAAI,EAAE,eAAe;QACrB,MAAM;KAMP,CAAC;AACJ,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,2BAA2B,GAAG,GAAG,EAAE;IAC9C,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC;QACrB,EAAE,EAAE,cAAc,CAAC,QAAQ,CAAC,gCAAgC,CAAC;KAC9D,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;QACtB,EAAE,EAAE,cAAc,CAAC,QAAQ,CAAC,sCAAsC,CAAC;QACnE,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;QAC7B,UAAU,EAAE,CAAC;aACV,OAAO,EAAE;aACT,QAAQ,CACP,2RAA2R,CAC5R;KACJ,CAAC,CAAC;IAEH,OAAO;QACL,WAAW,EACT,yRAAyR;QAC3R,KAAK;QACL,IAAI,EAAE,OAAO;QACb,IAAI,EAAE,kBAAkB;QACxB,MAAM;KAMP,CAAC;AACJ,CAAC,CAAC"}

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

@@ -0,0 +1,42 @@
+import { z } from "zod";
+export declare const inspectRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    selector: z.ZodString;
+    what: z.ZodLiteral<"element-html">;
+}, z.core.$strip>, z.ZodObject<{
+    selector: z.ZodOptional<z.ZodString>;
+    what: z.ZodLiteral<"page-html">;
+}, z.core.$strip>, z.ZodObject<{
+    variableName: z.ZodString;
+    what: z.ZodLiteral<"variable">;
+}, z.core.$strip>], "what">;
+export type InspectOnRunnerRequest = z.infer<typeof inspectRequestSchema>;
+export declare const makeInspectOnRunnerContract: () => {
+    readonly description: string;
+    readonly input: z.ZodObject<{
+        id: z.ZodString;
+        request: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            selector: z.ZodString;
+            what: z.ZodLiteral<"element-html">;
+        }, z.core.$strip>, z.ZodObject<{
+            selector: z.ZodOptional<z.ZodString>;
+            what: z.ZodLiteral<"page-html">;
+        }, z.core.$strip>, z.ZodObject<{
+            variableName: z.ZodString;
+            what: z.ZodLiteral<"variable">;
+        }, z.core.$strip>], "what">;
+    }, z.core.$strip>;
+    readonly kind: "read";
+    readonly name: "runner.inspect";
+    readonly output: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        outcome: z.ZodLiteral<"success">;
+        value: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        errorMessage: z.ZodOptional<z.ZodString>;
+        failureReason: z.ZodEnum<{
+            "runner-unreachable": "runner-unreachable";
+            "nothing-to-inspect": "nothing-to-inspect";
+        }>;
+        outcome: z.ZodLiteral<"failure">;
+    }, z.core.$strip>], "outcome">;
+};
+//# sourceMappingURL=inspect.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../../../src/v1/runner/inspect.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAUxB,eAAO,MAAM,oBAAoB;;;;;;;;;2BA0B/B,CAAC;AAEH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAE1E,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmCvC,CAAC"}

package/dist/v1/runner/inspect.js

@@ -0,0 +1,61 @@
+import { z } from "zod";
+import { runnerIdSchema } from "./identity.js";
+import { retryableRunnerUnreachableDescription } from "./unreachable.js";
+const maxSelectorLength = 2_000;
+const maxVariableNameLength = 256;
+export const inspectRequestSchema = z.discriminatedUnion("what", [
+    z.object({
+        selector: z
+            .string()
+            .min(1)
+            .max(maxSelectorLength)
+            .describe("Playwright selector for the element to inspect."),
+        what: z.literal("element-html"),
+    }),
+    z.object({
+        selector: z
+            .string()
+            .min(1)
+            .max(maxSelectorLength)
+            .optional()
+            .describe("Inspect only this subtree. Omit to inspect the whole page."),
+        what: z.literal("page-html"),
+    }),
+    z.object({
+        variableName: z
+            .string()
+            .min(1)
+            .max(maxVariableNameLength)
+            .describe("Name of a top-level variable in the running workflow."),
+        what: z.literal("variable"),
+    }),
+]);
+export const makeInspectOnRunnerContract = () => {
+    const input = z.object({
+        id: runnerIdSchema.describe("Id of the runner to inspect."),
+        request: inspectRequestSchema,
+    });
+    const output = z.discriminatedUnion("outcome", [
+        z.object({
+            outcome: z.literal("success"),
+            value: z.string().describe("The HTML, or the variable's value as JSON."),
+        }),
+        z.object({
+            errorMessage: z
+                .string()
+                .optional()
+                .describe("What the runner said, when it said anything."),
+            failureReason: z.enum(["nothing-to-inspect", "runner-unreachable"]),
+            outcome: z.literal("failure"),
+        }),
+    ]);
+    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`. " +
+            retryableRunnerUnreachableDescription,
+        input,
+        kind: "read",
+        name: "runner.inspect",
+        output,
+    };
+};
+//# sourceMappingURL=inspect.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.js","sourceRoot":"","sources":["../../../src/v1/runner/inspect.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,qCAAqC,EAAE,MAAM,kBAAkB,CAAC;AAEzE,MAAM,iBAAiB,GAAG,KAAK,CAAC;AAChC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAElC,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE;IAC/D,CAAC,CAAC,MAAM,CAAC;QACP,QAAQ,EAAE,CAAC;aACR,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,GAAG,CAAC,iBAAiB,CAAC;aACtB,QAAQ,CAAC,iDAAiD,CAAC;QAC9D,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,cAAc,CAAC;KAChC,CAAC;IACF,CAAC,CAAC,MAAM,CAAC;QACP,QAAQ,EAAE,CAAC;aACR,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,GAAG,CAAC,iBAAiB,CAAC;aACtB,QAAQ,EAAE;aACV,QAAQ,CAAC,4DAA4D,CAAC;QACzE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC;KAC7B,CAAC;IACF,CAAC,CAAC,MAAM,CAAC;QACP,YAAY,EAAE,CAAC;aACZ,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,GAAG,CAAC,qBAAqB,CAAC;aAC1B,QAAQ,CAAC,uDAAuD,CAAC;QACpE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;KAC5B,CAAC;CACH,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,2BAA2B,GAAG,GAAG,EAAE;IAC9C,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC;QACrB,EAAE,EAAE,cAAc,CAAC,QAAQ,CAAC,8BAA8B,CAAC;QAC3D,OAAO,EAAE,oBAAoB;KAC9B,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,CAAC,CAAC,kBAAkB,CAAC,SAAS,EAAE;QAC7C,CAAC,CAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;YAC7B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,4CAA4C,CAAC;SACzE,CAAC;QACF,CAAC,CAAC,MAAM,CAAC;YACP,YAAY,EAAE,CAAC;iBACZ,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,8CAA8C,CAAC;YAC3D,aAAa,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,oBAAoB,EAAE,oBAAoB,CAAC,CAAC;YACnE,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;SAC9B,CAAC;KACH,CAAC,CAAC;IAEH,OAAO;QACL,WAAW,EACT,mZAAmZ;YACnZ,qCAAqC;QACvC,KAAK;QACL,IAAI,EAAE,MAAM;QACZ,IAAI,EAAE,gBAAgB;QACtB,MAAM;KAMP,CAAC;AACJ,CAAC,CAAC"}

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

@@ -0,0 +1,6 @@
+import { z } from "zod";
+export declare function makeRunnerFailureSchema<const Reasons extends readonly [string, ...string[]]>(reasons: Reasons): z.ZodObject<{
+    failureReason: z.ZodEnum<{ [k_1 in Reasons[number]]: k_1; } extends infer T ? { [k in keyof T]: T[k]; } : never>;
+    outcome: z.ZodLiteral<"failure">;
+}, z.core.$strip>;
+//# sourceMappingURL=outcome.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"outcome.d.ts","sourceRoot":"","sources":["../../../src/v1/runner/outcome.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,wBAAgB,uBAAuB,CACrC,KAAK,CAAC,OAAO,SAAS,SAAS,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,EACpD,OAAO,EAAE,OAAO;;;kBAKjB"}

package/dist/v1/runner/outcome.js

@@ -0,0 +1,8 @@
+import { z } from "zod";
+export function makeRunnerFailureSchema(reasons) {
+    return z.object({
+        failureReason: z.enum(reasons),
+        outcome: z.literal("failure"),
+    });
+}
+//# sourceMappingURL=outcome.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"outcome.js","sourceRoot":"","sources":["../../../src/v1/runner/outcome.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,UAAU,uBAAuB,CAErC,OAAgB;IAChB,OAAO,CAAC,CAAC,MAAM,CAAC;QACd,aAAa,EAAE,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC;QAC9B,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;KAC9B,CAAC,CAAC;AACL,CAAC"}

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

@@ -5,12 +5,18 @@ import { z } from "zod";
  * because it is the half a client can apply while collecting — escaping can
  * inflate the encoding severalfold, which
  * {@link maxRunnerRequestEncodedByteLength} bounds on the way out.
+ * The run payloads for Figma and other POM customers are currently still extremely large
+ * The QA Wolf CLI Runner sends the run payload via an API and needs to send the files
+ * We can drop these back to 10MB once the POM teams have been optimized - NOVA-1626
  */
 export declare const maxRunFilesByteLength: number;
 /**
  * The largest request, JSON-encoded, that may be sent to a runner. Checked
  * against the fully assembled request, so an oversized one is refused with a
  * reason rather than failing opaquely in transport.
+ * The run payloads for Figma and other POM customers are currently still extremely large
+ * The QA Wolf CLI Runner sends the run payload via an API and needs to send the files
+ * We can drop these back to 10MB once the POM teams have been optimized - NOVA-1626
  */
 export declare const maxRunnerRequestEncodedByteLength: number;
 /** UTF-8 bytes these files would carry. Compare against {@link maxRunFilesByteLength}. */

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

@@ -1 +1 @@
-{"version":3,"file":"payloadSize.d.ts","sourceRoot":"","sources":["../../../src/v1/runner/payloadSize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,QAAkB,CAAC;AAErD;;;;GAIG;AACH,eAAO,MAAM,iCAAiC,QAAkB,CAAC;AAEjE,0FAA0F;AAC1F,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAM1D;AAOD;;;;;GAKG;AACH,eAAO,MAAM,cAAc,uCAgBvB,CAAC;AAEL,oDAAoD;AACpD,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC"}
+{"version":3,"file":"payloadSize.d.ts","sourceRoot":"","sources":["../../../src/v1/runner/payloadSize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,QAAmB,CAAC;AAEtD;;;;;;;GAOG;AACH,eAAO,MAAM,iCAAiC,QAAmB,CAAC;AAElE,0FAA0F;AAC1F,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAM1D;AAOD;;;;;GAKG;AACH,eAAO,MAAM,cAAc,uCAgBvB,CAAC;AAEL,oDAAoD;AACpD,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC"}

package/dist/v1/runner/payloadSize.js

@@ -6,14 +6,20 @@ import { isShippableRunFilePath, runFilePathRefusal } from "./files.js";
  * because it is the half a client can apply while collecting — escaping can
  * inflate the encoding severalfold, which
  * {@link maxRunnerRequestEncodedByteLength} bounds on the way out.
+ * The run payloads for Figma and other POM customers are currently still extremely large
+ * The QA Wolf CLI Runner sends the run payload via an API and needs to send the files
+ * We can drop these back to 10MB once the POM teams have been optimized - NOVA-1626
  */
-export const maxRunFilesByteLength = 4 * 1024 * 1024;
+export const maxRunFilesByteLength = 30 * 1024 * 1024;
 /**
  * The largest request, JSON-encoded, that may be sent to a runner. Checked
  * against the fully assembled request, so an oversized one is refused with a
  * reason rather than failing opaquely in transport.
+ * The run payloads for Figma and other POM customers are currently still extremely large
+ * The QA Wolf CLI Runner sends the run payload via an API and needs to send the files
+ * We can drop these back to 10MB once the POM teams have been optimized - NOVA-1626
  */
-export const maxRunnerRequestEncodedByteLength = 9 * 1024 * 1024;
+export const maxRunnerRequestEncodedByteLength = 30 * 1024 * 1024;
 /** UTF-8 bytes these files would carry. Compare against {@link maxRunFilesByteLength}. */
 export function runFilesByteLength(files) {
     return Object.entries(files).reduce((total, [path, content]) => total + utf8ByteLength(content) + utf8ByteLength(path), 0);

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

@@ -1 +1 @@
-{"version":3,"file":"payloadSize.js","sourceRoot":"","sources":["../../../src/v1/runner/payloadSize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAExE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAErD;;;;GAIG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAEjE,0FAA0F;AAC1F,MAAM,UAAU,kBAAkB,CAAC,KAAe;IAChD,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,MAAM,CACjC,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,EAAE,CACzB,KAAK,GAAG,cAAc,CAAC,OAAO,CAAC,GAAG,cAAc,CAAC,IAAI,CAAC,EACxD,CAAC,CACF,CAAC;AACJ,CAAC;AAED,iFAAiF;AACjF,SAAS,cAAc,CAAC,IAAY;IAClC,OAAO,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AACzC,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC;KAC5B,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;IAC/B,wEAAwE;IACxE,4CAA4C;KAC3C,WAAW,CAAC,CAAC,KAAK,EAAE,iBAAiB,EAAE,EAAE;IACxC,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACtC,IAAI,sBAAsB,CAAC,IAAI,CAAC;YAAE,SAAS;QAC3C,iBAAiB,CAAC,QAAQ,CAAC;YACzB,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,kBAAkB;YAC3B,IAAI,EAAE,CAAC,IAAI,CAAC;SACb,CAAC,CAAC;IACL,CAAC;AACH,CAAC,CAAC;KACD,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,kBAAkB,CAAC,KAAK,CAAC,IAAI,qBAAqB,EAAE;IACrE,KAAK,EAAE,8CAA8C,qBAAqB,kBAAkB;CAC7F,CAAC,CAAC"}
+{"version":3,"file":"payloadSize.js","sourceRoot":"","sources":["../../../src/v1/runner/payloadSize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAExE;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAEtD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAElE,0FAA0F;AAC1F,MAAM,UAAU,kBAAkB,CAAC,KAAe;IAChD,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,MAAM,CACjC,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,EAAE,CACzB,KAAK,GAAG,cAAc,CAAC,OAAO,CAAC,GAAG,cAAc,CAAC,IAAI,CAAC,EACxD,CAAC,CACF,CAAC;AACJ,CAAC;AAED,iFAAiF;AACjF,SAAS,cAAc,CAAC,IAAY;IAClC,OAAO,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AACzC,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC;KAC5B,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;IAC/B,wEAAwE;IACxE,4CAA4C;KAC3C,WAAW,CAAC,CAAC,KAAK,EAAE,iBAAiB,EAAE,EAAE;IACxC,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACtC,IAAI,sBAAsB,CAAC,IAAI,CAAC;YAAE,SAAS;QAC3C,iBAAiB,CAAC,QAAQ,CAAC;YACzB,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,kBAAkB;YAC3B,IAAI,EAAE,CAAC,IAAI,CAAC;SACb,CAAC,CAAC;IACL,CAAC;AACH,CAAC,CAAC;KACD,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,kBAAkB,CAAC,KAAK,CAAC,IAAI,qBAAqB,EAAE;IACrE,KAAK,EAAE,8CAA8C,qBAAqB,kBAAkB;CAC7F,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). `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 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 input: z.ZodObject<{
         action: z.ZodDiscriminatedUnion<[z.ZodObject<{
             button: z.ZodLiteral<"left" | "right" | "wheel" | "back" | "forward">;
@@ -44,18 +44,19 @@ export declare const makePerformActionOnRunnerContract: () => {
     readonly kind: "write";
     readonly name: "runner.performAction";
     readonly output: z.ZodDiscriminatedUnion<[z.ZodObject<{
-        outcome: z.ZodLiteral<"performed">;
-    }, z.core.$strip>, z.ZodObject<{
+        outcome: z.ZodLiteral<"success">;
+    }, z.core.$strip>, z.ZodDiscriminatedUnion<[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">;
+        failureReason: z.ZodLiteral<"action-failed">;
+        outcome: z.ZodLiteral<"failure">;
     }, z.core.$strip>, z.ZodObject<{
-        outcome: z.ZodLiteral<"runner-unreachable">;
-    }, z.core.$strip>], "outcome">;
+        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";
+        }>;
+        outcome: z.ZodLiteral<"failure">;
+    }, z.core.$strip>], "failureReason">], "outcome">;
 };
 //# sourceMappingURL=performAction.d.ts.map

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;AAqBxB,uDAAuD;AACvD,eAAO,MAAM,2BAA2B,OAAQ,CAAC;AAEjD,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmC7C,CAAC"}
+{"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"}

package/dist/v1/runner/performAction.js

@@ -1,8 +1,9 @@
 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";
+import { makeRunnerFailureSchema } from "./outcome.js";
+import { runnerHasNoScreenDescription, screenFailureReasons, screenNotReadyDescription, } from "./screen.js";
+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.";
@@ -13,22 +14,28 @@ export const makePerformActionOnRunnerContract = () => {
         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") }),
+    // `action-failed` is the one reason that carries a message, so it is an arm of
+    // its own and the other reasons share theirs.
+    const failure = z.discriminatedUnion("failureReason", [
         z.object({
             errorMessage: z
                 .string()
                 .max(maxActionErrorMessageLength)
                 .describe("What stopped the action from taking effect."),
-            outcome: z.literal("action-failed"),
+            failureReason: z.literal("action-failed"),
+            outcome: z.literal("failure"),
         }),
-        runnerScreenNeedsARunSchema,
-        runnerScreenNotReadySchema,
-        runnerHasNoScreenSchema,
-        runnerUnreachableSchema,
+        makeRunnerFailureSchema([
+            ...screenFailureReasons,
+            runnerUnreachableFailureReason,
+        ]),
+    ]);
+    const output = z.discriminatedUnion("outcome", [
+        z.object({ outcome: z.literal("success") }),
+        failure,
     ]);
     return {
-        description: `Perform one raw browser action on an interactive runner: click, double_click, move, drag, scroll, keypress, type, or navigate. Coordinates are whole pixels on the runner's virtual desktop, in the same space as \`runner.takeScreenshot\`. One action per request, and the runner serves one at a time. The action shapes follow the computer-use vocabulary, minus \`screenshot\` (use \`runner.takeScreenshot\`) and \`wait\` (delay on the caller's side). \`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}`,
+        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}`,
         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,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"}
+{"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"}

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

@@ -23,9 +23,12 @@ export declare const makeReadRunnerJournalContract: () => {
         hasUnsearchedHistory: z.ZodBoolean;
         nextSequence: z.ZodNumber;
         oldestAvailableSequence: z.ZodNumber;
-        outcome: z.ZodLiteral<"read">;
+        outcome: z.ZodLiteral<"success">;
     }, z.core.$strip>, z.ZodObject<{
-        outcome: z.ZodLiteral<"runner-unreachable">;
+        failureReason: z.ZodEnum<{
+            "runner-unreachable": "runner-unreachable";
+        }>;
+        outcome: z.ZodLiteral<"failure">;
     }, z.core.$strip>], "outcome">;
 };
 //# sourceMappingURL=readJournal.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"readJournal.d.ts","sourceRoot":"","sources":["../../../src/v1/runner/readJournal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgBxB,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyBzC,CAAC"}
+{"version":3,"file":"readJournal.d.ts","sourceRoot":"","sources":["../../../src/v1/runner/readJournal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAiBxB,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyBzC,CAAC"}

package/dist/v1/runner/readJournal.js

@@ -1,15 +1,16 @@
 import { z } from "zod";
 import { runnerIdSchema } from "./identity.js";
 import { journalStreamSchema, knownJournalStreams, readJournalRequestSchema, readJournalResponseSchema, } from "./journal.js";
-import { retryableRunnerUnreachableDescription, runnerUnreachableSchema, } from "./unreachable.js";
+import { makeRunnerFailureSchema } from "./outcome.js";
+import { retryableRunnerUnreachableDescription, runnerUnreachableFailureReason, } from "./unreachable.js";
 export const makeReadRunnerJournalContract = () => {
     const input = readJournalRequestSchema.extend({
         id: runnerIdSchema.describe("Id of the runner to read the journal of."),
         stream: journalStreamSchema.describe(`The stream to read. QA Wolf writes ${knownJournalStreams.join(", ")}; an unwritten stream reads as empty rather than as an error.`),
     });
     const output = z.discriminatedUnion("outcome", [
-        readJournalResponseSchema.extend({ outcome: z.literal("read") }),
-        runnerUnreachableSchema,
+        readJournalResponseSchema.extend({ outcome: z.literal("success") }),
+        makeRunnerFailureSchema([runnerUnreachableFailureReason]),
     ]);
     return {
         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}`,

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

@@ -1 +1 @@
-{"version":3,"file":"readJournal.js","sourceRoot":"","sources":["../../../src/v1/runner/readJournal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,qCAAqC,EACrC,uBAAuB,GACxB,MAAM,kBAAkB,CAAC;AAE1B,MAAM,CAAC,MAAM,6BAA6B,GAAG,GAAG,EAAE;IAChD,MAAM,KAAK,GAAG,wBAAwB,CAAC,MAAM,CAAC;QAC5C,EAAE,EAAE,cAAc,CAAC,QAAQ,CAAC,0CAA0C,CAAC;QACvE,MAAM,EAAE,mBAAmB,CAAC,QAAQ,CAClC,sCAAsC,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,+DAA+D,CACpI;KACF,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,CAAC,CAAC,kBAAkB,CAAC,SAAS,EAAE;QAC7C,yBAAyB,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAChE,uBAAuB;KACxB,CAAC,CAAC;IAEH,OAAO;QACL,WAAW,EAAE,wcAAwc,qCAAqC,EAAE;QAC5f,KAAK;QACL,IAAI,EAAE,MAAM;QACZ,IAAI,EAAE,oBAAoB;QAC1B,MAAM;KAMP,CAAC;AACJ,CAAC,CAAC"}
+{"version":3,"file":"readJournal.js","sourceRoot":"","sources":["../../../src/v1/runner/readJournal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EACL,qCAAqC,EACrC,8BAA8B,GAC/B,MAAM,kBAAkB,CAAC;AAE1B,MAAM,CAAC,MAAM,6BAA6B,GAAG,GAAG,EAAE;IAChD,MAAM,KAAK,GAAG,wBAAwB,CAAC,MAAM,CAAC;QAC5C,EAAE,EAAE,cAAc,CAAC,QAAQ,CAAC,0CAA0C,CAAC;QACvE,MAAM,EAAE,mBAAmB,CAAC,QAAQ,CAClC,sCAAsC,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,+DAA+D,CACpI;KACF,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,CAAC,CAAC,kBAAkB,CAAC,SAAS,EAAE;QAC7C,yBAAyB,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACnE,uBAAuB,CAAC,CAAC,8BAA8B,CAAC,CAAC;KAC1D,CAAC,CAAC;IAEH,OAAO;QACL,WAAW,EAAE,wcAAwc,qCAAqC,EAAE;QAC5f,KAAK;QACL,IAAI,EAAE,MAAM;QACZ,IAAI,EAAE,oBAAoB;QAC1B,MAAM;KAMP,CAAC;AACJ,CAAC,CAAC"}

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

@@ -1,33 +1,46 @@
 import { z } from "zod";
 export declare const makeRunFlowOnRunnerContract: () => {
-    readonly 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.";
+    readonly 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.";
     readonly input: z.ZodObject<{
         entryPointPath: z.ZodString;
         env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         files: z.ZodRecord<z.ZodString, z.ZodString>;
         id: z.ZodString;
+        selection: z.ZodOptional<z.ZodObject<{
+            endLine: z.ZodInt;
+            path: z.ZodString;
+            startLine: z.ZodInt;
+        }, z.core.$strip>>;
+        unchangedFiles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     }, z.core.$strip>;
     readonly kind: "write";
     readonly name: "runner.runFlow";
     readonly output: z.ZodDiscriminatedUnion<[z.ZodObject<{
-        outcome: z.ZodLiteral<"submitted">;
+        bootstrappedRunner: z.ZodOptional<z.ZodBoolean>;
+        outcome: z.ZodLiteral<"success">;
         runId: z.ZodString;
-    }, z.core.$strip>, z.ZodObject<{
-        outcome: z.ZodLiteral<"runner-unreachable">;
-    }, z.core.$strip>, z.ZodObject<{
-        outcome: z.ZodLiteral<"runner-target-mismatch">;
+    }, z.core.$strip>, z.ZodDiscriminatedUnion<[z.ZodObject<{
+        failureReason: z.ZodLiteral<"runner-target-mismatch">;
+        outcome: z.ZodLiteral<"failure">;
         requiredRunnerName: z.ZodEnum<{
-            node20Basic: "node20Basic";
-            node20WithAndroid: "node20WithAndroid";
-            node20WithIos: "node20WithIos";
-            node20WithPlaywright: "node20WithPlaywright";
+            basic: "basic";
+            playwright: "playwright";
+            android: "android";
+            ios: "ios";
         }>;
         runnerName: z.ZodEnum<{
-            node20Basic: "node20Basic";
-            node20WithAndroid: "node20WithAndroid";
-            node20WithIos: "node20WithIos";
-            node20WithPlaywright: "node20WithPlaywright";
+            basic: "basic";
+            playwright: "playwright";
+            android: "android";
+            ios: "ios";
         }>;
-    }, z.core.$strip>], "outcome">;
+    }, z.core.$strip>, z.ZodObject<{
+        failureReason: z.ZodLiteral<"needs-full-sync">;
+        missingPaths: z.ZodArray<z.ZodString>;
+        outcome: z.ZodLiteral<"failure">;
+    }, z.core.$strip>, z.ZodObject<{
+        failureReason: z.ZodLiteral<"runner-unreachable">;
+        outcome: z.ZodLiteral<"failure">;
+    }, z.core.$strip>], "failureReason">], "outcome">;
 };
 //# sourceMappingURL=runFlow.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"runFlow.d.ts","sourceRoot":"","sources":["../../../src/v1/runner/runFlow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAUxB,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0DvC,CAAC"}
+{"version":3,"file":"runFlow.d.ts","sourceRoot":"","sources":["../../../src/v1/runner/runFlow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA4BxB,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+GvC,CAAC"}

package/dist/v1/runner/runFlow.js

@@ -1,9 +1,22 @@
 import { z } from "zod";
 import { runEnvironmentSchema } from "./environment.js";
-import { runFilePathSchema, runPackageJsonPath } from "./files.js";
+import { isShippableRunFilePath, runFilePathRefusal, runFilePathSchema, runPackageJsonPath, } from "./files.js";
 import { runnerIdSchema, runnerNameSchema } from "./identity.js";
 import { runFilesSchema } from "./payloadSize.js";
-import { runnerUnreachableSchema } from "./unreachable.js";
+import { runSelectionSchema } from "./runSelection.js";
+const unchangedFilesSchema = z
+    .record(z.string(), z.string().min(1))
+    .superRefine((hashes, refinementContext) => {
+    for (const path of Object.keys(hashes)) {
+        if (isShippableRunFilePath(path))
+            continue;
+        refinementContext.addIssue({
+            code: "custom",
+            message: runFilePathRefusal,
+            path: [path],
+        });
+    }
+});
 export const makeRunFlowOnRunnerContract = () => {
     const input = z
         .object({
@@ -13,6 +26,12 @@ export const makeRunFlowOnRunnerContract = () => {
             .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."),
+        selection: runSelectionSchema
+            .optional()
+            .describe("Run only these lines, inside the page the runner is already on, instead of running the whole flow from a fresh browser. Omit to run the whole entry point."),
+        unchangedFiles: unchangedFilesSchema
+            .optional()
+            .describe("Files this runner already holds from an earlier run, keyed by path with a hex SHA-256 of the content it should hold. Send this to make `files` only what changed. The runner refuses with `needs-full-sync` if it holds none of a referenced path, so it never runs something other than what was asked for. Omit it to send every file."),
     })
         // Stated here rather than discovered when the runner cannot find a module.
         .refine((request) => Object.hasOwn(request.files, request.entryPointPath), {
@@ -22,23 +41,50 @@ export const makeRunFlowOnRunnerContract = () => {
         .refine((request) => Object.hasOwn(request.files, runPackageJsonPath), {
         error: `The files must include ${runPackageJsonPath}; the run's npm dependencies are read from it.`,
         path: ["files"],
+    })
+        .refine((request) => request.selection === undefined ||
+        Object.hasOwn(request.files, request.selection.path), {
+        error: "A selection must name a file carried in files.",
+        path: ["selection", "path"],
+    })
+        .refine((request) => Object.keys(request.unchangedFiles ?? {}).every((path) => !Object.hasOwn(request.files, path)), {
+        error: "A path may be sent in files or referenced in unchangedFiles, not both.",
+        path: ["unchangedFiles"],
     });
+    const failure = z.discriminatedUnion("failureReason", [
+        z.object({
+            failureReason: z.literal("runner-target-mismatch"),
+            outcome: z.literal("failure"),
+            requiredRunnerName: runnerNameSchema.describe("The runner family this flow's execution target needs."),
+            runnerName: runnerNameSchema.describe("The runner family the runner is actually running."),
+        }),
+        z.object({
+            failureReason: z.literal("needs-full-sync"),
+            missingPaths: z
+                .array(runFilePathSchema)
+                .describe("Paths referenced in `unchangedFiles` that this runner does not hold. Send the run again with every file it needs in `files`."),
+            outcome: z.literal("failure"),
+        }),
+        z.object({
+            failureReason: z.literal("runner-unreachable"),
+            outcome: z.literal("failure"),
+        }),
+    ]);
     const output = z.discriminatedUnion("outcome", [
         z.object({
-            outcome: z.literal("submitted"),
+            bootstrappedRunner: z
+                .boolean()
+                .optional()
+                .describe("True when the runner had no live browser and one was started before the run, so a `selection` ran against a fresh page rather than the one an earlier run left. Absent means the runner was already warm. Only a request carrying `selection` can bootstrap, because a whole run starts its own browser either way."),
+            outcome: z.literal("success"),
             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."),
-        }),
+        failure,
     ]);
     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.",
+        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",
         name: "runner.runFlow",