@qawolf/api-contracts 0.32.0 → 0.34.0

package/dist/v1/index.d.ts

@@ -797,6 +797,32 @@ export declare const makeContractsV1: <EnvironmentId extends PublicIdSchema, Flo
                 outcome: z.ZodLiteral<"failure">;
             }, z.core.$strip>], "outcome">;
         };
+        highlightSelector: {
+            readonly description: "Highlight the elements a selector matches on an interactive runner's live page, and answer how many it matched. The highlight stays until it is replaced or cleared, so it is visible in the next `runner.takeScreenshot` — which is the point, since a caller cannot see the runner's screen otherwise. Send an empty selector to clear, which answers `cleared`. `status` tells a selector that matched nothing (`empty`) from one the page could not parse (`invalid`), so a caller can tell a bad locator from a locator pointing at nothing. `no-answer` if the page did not answer in time: the highlight runs inside the page, so a page that is gone or mid-navigation does not answer slowly, it does not answer at all. `runner-cannot-highlight-selectors` on a runner with no browser to draw on. `runner-unreachable` if the runner could not be reached: it may still be starting, or it may have terminated after inactivity.";
+            readonly input: z.ZodObject<{
+                id: z.ZodString;
+                selector: z.ZodString;
+            }, z.core.$strip>;
+            readonly kind: "write";
+            readonly name: "runner.highlightSelector";
+            readonly output: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                matchCount: z.ZodNumber;
+                outcome: z.ZodLiteral<"success">;
+                selector: z.ZodString;
+                status: z.ZodLiteral<"valid" | "invalid" | "empty">;
+                targetPage: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>, z.ZodObject<{
+                outcome: z.ZodLiteral<"cleared">;
+            }, z.core.$strip>, z.ZodObject<{
+                errorMessage: z.ZodOptional<z.ZodString>;
+                failureReason: z.ZodEnum<{
+                    "runner-unreachable": "runner-unreachable";
+                    "no-answer": "no-answer";
+                    "runner-cannot-highlight-selectors": "runner-cannot-highlight-selectors";
+                }>;
+                outcome: z.ZodLiteral<"failure">;
+            }, z.core.$strip>], "outcome">;
+        };
         importPackage: {
             readonly description: "Install a package into an interactive runner's live run and import it, so a snippet or a selection can use it without a full run to reinstall dependencies. An `install-failed` failure carries npm's reason in `errorMessage`. `runner-unreachable` if the runner could not be reached: it may still be starting, it may have terminated after inactivity, or it may be too busy to answer. The install may still have landed, but installing the same version again does nothing, so retrying is safe.";
             readonly input: z.ZodObject<{
@@ -848,6 +874,209 @@ export declare const makeContractsV1: <EnvironmentId extends PublicIdSchema, Flo
                 outcome: z.ZodLiteral<"failure">;
             }, z.core.$strip>], "outcome">;
         };
+        inspectMobile: {
+            readonly description: "Inspect one thing on a mobile interactive runner: the Appium session's status, the WebView contexts available, the current context's page source, or the elements at a point or carrying some text. Mobile only — a browser runner answers `runner-is-not-mobile`; call `runner.inspect` for a browser's equivalent surface instead. `what: \"session\"` always answers with the session's own status rather than `screen-needs-a-run`, since that is the question it exists to answer; the other three request kinds need a live session first and answer the same `screen-needs-a-run` or `screen-not-ready` outcomes `runner.performAction` and `runner.takeScreenshot` use, instead of reading anything when there is none. `screen-needs-a-run` means no Appium session has started on this runner yet — call `runner.runFlow` with a flow that opens one, then inspect again. `screen-not-ready` means the runner's Appium session exists but did not answer this instant, or more than one is somehow live — retry once; if it persists, relaunch the runner. `runner-is-not-mobile` means there is nothing here to inspect, and retrying will never help — launch an `android` or `ios` runner instead. `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;
+                request: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    what: z.ZodLiteral<"session">;
+                }, z.core.$strip>, z.ZodObject<{
+                    what: z.ZodLiteral<"contexts">;
+                }, z.core.$strip>, z.ZodObject<{
+                    context: z.ZodOptional<z.ZodString>;
+                    what: z.ZodLiteral<"page">;
+                }, z.core.$strip>, z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    by: z.ZodLiteral<"point">;
+                    context: z.ZodOptional<z.ZodString>;
+                    what: z.ZodLiteral<"elements">;
+                    x: z.ZodInt;
+                    y: z.ZodInt;
+                }, z.core.$strip>, z.ZodObject<{
+                    by: z.ZodLiteral<"text">;
+                    context: z.ZodOptional<z.ZodString>;
+                    partial: z.ZodOptional<z.ZodBoolean>;
+                    text: z.ZodString;
+                    what: z.ZodLiteral<"elements">;
+                }, z.core.$strip>], "by">], "what">;
+            }, z.core.$strip>;
+            readonly kind: "read";
+            readonly name: "runner.inspectMobile";
+            readonly output: z.ZodDiscriminatedUnion<[z.ZodDiscriminatedUnion<[z.ZodObject<{
+                outcome: z.ZodLiteral<"success">;
+                session: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    deviceName: z.ZodOptional<z.ZodString>;
+                    platformName: z.ZodString;
+                    sessionId: z.ZodString;
+                    type: z.ZodLiteral<"ready">;
+                }, z.core.$strip>, z.ZodObject<{
+                    error: z.ZodString;
+                    type: z.ZodLiteral<"unreachable">;
+                }, z.core.$strip>, z.ZodObject<{
+                    sessionCount: z.ZodNumber;
+                    type: z.ZodLiteral<"ambiguous">;
+                }, z.core.$strip>, z.ZodObject<{
+                    type: z.ZodLiteral<"no-session">;
+                }, z.core.$strip>], "type">;
+                what: z.ZodLiteral<"session">;
+            }, z.core.$strip>, z.ZodObject<{
+                contexts: z.ZodArray<z.ZodString>;
+                current: z.ZodString;
+                outcome: z.ZodLiteral<"success">;
+                what: z.ZodLiteral<"contexts">;
+            }, z.core.$strip>, z.ZodObject<{
+                context: z.ZodString;
+                orientation: z.ZodEnum<{
+                    PORTRAIT: "PORTRAIT";
+                    LANDSCAPE: "LANDSCAPE";
+                }>;
+                outcome: z.ZodLiteral<"success">;
+                pageSource: z.ZodType<{
+                    selectors: {
+                        strategy: {
+                            name: "xpath";
+                            type: "unique" | "full-path" | "sibling-of" | "parent-of";
+                        } | {
+                            name: "ios-predicate";
+                        } | {
+                            hostSelector: string;
+                            innerSelector: string;
+                            name: "shadow";
+                        };
+                        value: string;
+                    }[];
+                    tag: string;
+                    attributes?: {
+                        bounds?: {
+                            bottom: number;
+                            left: number;
+                            right: number;
+                            top: number;
+                        } | undefined;
+                        rest?: Record<string, string> | undefined;
+                    } | undefined;
+                } & {
+                    children?: (({
+                        selectors: {
+                            strategy: {
+                                name: "xpath";
+                                type: "unique" | "full-path" | "sibling-of" | "parent-of";
+                            } | {
+                                name: "ios-predicate";
+                            } | {
+                                hostSelector: string;
+                                innerSelector: string;
+                                name: "shadow";
+                            };
+                            value: string;
+                        }[];
+                        tag: string;
+                        attributes?: {
+                            bounds?: {
+                                bottom: number;
+                                left: number;
+                                right: number;
+                                top: number;
+                            } | undefined;
+                            rest?: Record<string, string> | undefined;
+                        } | undefined;
+                    } & /*elided*/ any) | string)[];
+                }, unknown, z.core.$ZodTypeInternals<{
+                    selectors: {
+                        strategy: {
+                            name: "xpath";
+                            type: "unique" | "full-path" | "sibling-of" | "parent-of";
+                        } | {
+                            name: "ios-predicate";
+                        } | {
+                            hostSelector: string;
+                            innerSelector: string;
+                            name: "shadow";
+                        };
+                        value: string;
+                    }[];
+                    tag: string;
+                    attributes?: {
+                        bounds?: {
+                            bottom: number;
+                            left: number;
+                            right: number;
+                            top: number;
+                        } | undefined;
+                        rest?: Record<string, string> | undefined;
+                    } | undefined;
+                } & {
+                    children?: (({
+                        selectors: {
+                            strategy: {
+                                name: "xpath";
+                                type: "unique" | "full-path" | "sibling-of" | "parent-of";
+                            } | {
+                                name: "ios-predicate";
+                            } | {
+                                hostSelector: string;
+                                innerSelector: string;
+                                name: "shadow";
+                            };
+                            value: string;
+                        }[];
+                        tag: string;
+                        attributes?: {
+                            bounds?: {
+                                bottom: number;
+                                left: number;
+                                right: number;
+                                top: number;
+                            } | undefined;
+                            rest?: Record<string, string> | undefined;
+                        } | undefined;
+                    } & /*elided*/ any) | string)[];
+                }, unknown>>;
+                what: z.ZodLiteral<"page">;
+            }, z.core.$strip>, z.ZodObject<{
+                matches: z.ZodArray<z.ZodObject<{
+                    attributes: z.ZodRecord<z.ZodString, z.ZodString>;
+                    bounds: z.ZodOptional<z.ZodObject<{
+                        bottom: z.ZodNumber;
+                        left: z.ZodNumber;
+                        right: z.ZodNumber;
+                        top: z.ZodNumber;
+                    }, z.core.$strip>>;
+                    center: z.ZodOptional<z.ZodObject<{
+                        x: z.ZodNumber;
+                        y: z.ZodNumber;
+                    }, z.core.$strip>>;
+                    selectors: z.ZodArray<z.ZodObject<{
+                        strategy: z.ZodUnion<readonly [z.ZodObject<{
+                            name: z.ZodLiteral<"xpath">;
+                            type: z.ZodEnum<{
+                                unique: "unique";
+                                "full-path": "full-path";
+                                "sibling-of": "sibling-of";
+                                "parent-of": "parent-of";
+                            }>;
+                        }, z.core.$strip>, z.ZodObject<{
+                            name: z.ZodLiteral<"ios-predicate">;
+                        }, z.core.$strip>, z.ZodObject<{
+                            hostSelector: z.ZodString;
+                            innerSelector: z.ZodString;
+                            name: z.ZodLiteral<"shadow">;
+                        }, z.core.$strip>]>;
+                        value: z.ZodString;
+                    }, z.core.$strip>>;
+                    tag: z.ZodString;
+                }, z.core.$strip>>;
+                outcome: z.ZodLiteral<"success">;
+                what: z.ZodLiteral<"elements">;
+            }, z.core.$strip>], "what">, z.ZodObject<{
+                failureReason: z.ZodEnum<{
+                    "runner-unreachable": "runner-unreachable";
+                    "runner-is-not-mobile": "runner-is-not-mobile";
+                    "screen-needs-a-run": "screen-needs-a-run";
+                    "screen-not-ready": "screen-not-ready";
+                }>;
+                outcome: z.ZodLiteral<"failure">;
+            }, z.core.$strip>], "outcome">;
+        };
         launch: {
             readonly 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.";
             readonly input: z.ZodObject<{
@@ -933,6 +1162,26 @@ export declare const makeContractsV1: <EnvironmentId extends PublicIdSchema, Flo
                 outcome: z.ZodLiteral<"failure">;
             }, z.core.$strip>], "failureReason">], "outcome">;
         };
+        promoteSnapshot: {
+            readonly description: "Accept a run's screenshot as the new baseline for an image diff, on the runner that produced it. The two paths are the ones the diff reported, which reach a caller as an `image-diff-artifact` entry on the runner's `run-events` journal stream. `snapshot-not-found` if the run wrote no screenshot at that path, which usually means the paths were not taken from a diff this run produced; nothing is changed, so correcting the path and repeating is safe. `runner-cannot-promote-snapshots` on a runner that stores no screenshots. `runner-unreachable` if the runner could not be reached: it may still be starting, or it may have terminated after inactivity. A promotion that lands is not undone by promoting again, so a retry after an unreachable answer is safe.";
+            readonly input: z.ZodObject<{
+                baselinePath: z.ZodString;
+                id: z.ZodString;
+                screenshotPath: z.ZodString;
+            }, z.core.$strip>;
+            readonly kind: "write";
+            readonly name: "runner.promoteSnapshot";
+            readonly output: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                outcome: z.ZodLiteral<"success">;
+            }, z.core.$strip>, z.ZodObject<{
+                failureReason: z.ZodEnum<{
+                    "runner-unreachable": "runner-unreachable";
+                    "runner-cannot-promote-snapshots": "runner-cannot-promote-snapshots";
+                    "snapshot-not-found": "snapshot-not-found";
+                }>;
+                outcome: z.ZodLiteral<"failure">;
+            }, z.core.$strip>], "outcome">;
+        };
         readJournal: {
             readonly 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. `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<{
@@ -970,6 +1219,7 @@ export declare const makeContractsV1: <EnvironmentId extends PublicIdSchema, Flo
             readonly input: z.ZodObject<{
                 entryPointPath: z.ZodString;
                 env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                environmentId: z.ZodOptional<PublicIdSchema>;
                 files: z.ZodRecord<z.ZodString, z.ZodString>;
                 id: z.ZodString;
                 selection: z.ZodOptional<z.ZodObject<{
@@ -1880,6 +2130,32 @@ export declare const publicContractsV1: {
                 outcome: z.ZodLiteral<"failure">;
             }, z.core.$strip>], "outcome">;
         };
+        highlightSelector: {
+            readonly description: "Highlight the elements a selector matches on an interactive runner's live page, and answer how many it matched. The highlight stays until it is replaced or cleared, so it is visible in the next `runner.takeScreenshot` — which is the point, since a caller cannot see the runner's screen otherwise. Send an empty selector to clear, which answers `cleared`. `status` tells a selector that matched nothing (`empty`) from one the page could not parse (`invalid`), so a caller can tell a bad locator from a locator pointing at nothing. `no-answer` if the page did not answer in time: the highlight runs inside the page, so a page that is gone or mid-navigation does not answer slowly, it does not answer at all. `runner-cannot-highlight-selectors` on a runner with no browser to draw on. `runner-unreachable` if the runner could not be reached: it may still be starting, or it may have terminated after inactivity.";
+            readonly input: z.ZodObject<{
+                id: z.ZodString;
+                selector: z.ZodString;
+            }, z.core.$strip>;
+            readonly kind: "write";
+            readonly name: "runner.highlightSelector";
+            readonly output: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                matchCount: z.ZodNumber;
+                outcome: z.ZodLiteral<"success">;
+                selector: z.ZodString;
+                status: z.ZodLiteral<"valid" | "invalid" | "empty">;
+                targetPage: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>, z.ZodObject<{
+                outcome: z.ZodLiteral<"cleared">;
+            }, z.core.$strip>, z.ZodObject<{
+                errorMessage: z.ZodOptional<z.ZodString>;
+                failureReason: z.ZodEnum<{
+                    "runner-unreachable": "runner-unreachable";
+                    "no-answer": "no-answer";
+                    "runner-cannot-highlight-selectors": "runner-cannot-highlight-selectors";
+                }>;
+                outcome: z.ZodLiteral<"failure">;
+            }, z.core.$strip>], "outcome">;
+        };
         importPackage: {
             readonly description: "Install a package into an interactive runner's live run and import it, so a snippet or a selection can use it without a full run to reinstall dependencies. An `install-failed` failure carries npm's reason in `errorMessage`. `runner-unreachable` if the runner could not be reached: it may still be starting, it may have terminated after inactivity, or it may be too busy to answer. The install may still have landed, but installing the same version again does nothing, so retrying is safe.";
             readonly input: z.ZodObject<{
@@ -1931,6 +2207,209 @@ export declare const publicContractsV1: {
                 outcome: z.ZodLiteral<"failure">;
             }, z.core.$strip>], "outcome">;
         };
+        inspectMobile: {
+            readonly description: "Inspect one thing on a mobile interactive runner: the Appium session's status, the WebView contexts available, the current context's page source, or the elements at a point or carrying some text. Mobile only — a browser runner answers `runner-is-not-mobile`; call `runner.inspect` for a browser's equivalent surface instead. `what: \"session\"` always answers with the session's own status rather than `screen-needs-a-run`, since that is the question it exists to answer; the other three request kinds need a live session first and answer the same `screen-needs-a-run` or `screen-not-ready` outcomes `runner.performAction` and `runner.takeScreenshot` use, instead of reading anything when there is none. `screen-needs-a-run` means no Appium session has started on this runner yet — call `runner.runFlow` with a flow that opens one, then inspect again. `screen-not-ready` means the runner's Appium session exists but did not answer this instant, or more than one is somehow live — retry once; if it persists, relaunch the runner. `runner-is-not-mobile` means there is nothing here to inspect, and retrying will never help — launch an `android` or `ios` runner instead. `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;
+                request: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    what: z.ZodLiteral<"session">;
+                }, z.core.$strip>, z.ZodObject<{
+                    what: z.ZodLiteral<"contexts">;
+                }, z.core.$strip>, z.ZodObject<{
+                    context: z.ZodOptional<z.ZodString>;
+                    what: z.ZodLiteral<"page">;
+                }, z.core.$strip>, z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    by: z.ZodLiteral<"point">;
+                    context: z.ZodOptional<z.ZodString>;
+                    what: z.ZodLiteral<"elements">;
+                    x: z.ZodInt;
+                    y: z.ZodInt;
+                }, z.core.$strip>, z.ZodObject<{
+                    by: z.ZodLiteral<"text">;
+                    context: z.ZodOptional<z.ZodString>;
+                    partial: z.ZodOptional<z.ZodBoolean>;
+                    text: z.ZodString;
+                    what: z.ZodLiteral<"elements">;
+                }, z.core.$strip>], "by">], "what">;
+            }, z.core.$strip>;
+            readonly kind: "read";
+            readonly name: "runner.inspectMobile";
+            readonly output: z.ZodDiscriminatedUnion<[z.ZodDiscriminatedUnion<[z.ZodObject<{
+                outcome: z.ZodLiteral<"success">;
+                session: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    deviceName: z.ZodOptional<z.ZodString>;
+                    platformName: z.ZodString;
+                    sessionId: z.ZodString;
+                    type: z.ZodLiteral<"ready">;
+                }, z.core.$strip>, z.ZodObject<{
+                    error: z.ZodString;
+                    type: z.ZodLiteral<"unreachable">;
+                }, z.core.$strip>, z.ZodObject<{
+                    sessionCount: z.ZodNumber;
+                    type: z.ZodLiteral<"ambiguous">;
+                }, z.core.$strip>, z.ZodObject<{
+                    type: z.ZodLiteral<"no-session">;
+                }, z.core.$strip>], "type">;
+                what: z.ZodLiteral<"session">;
+            }, z.core.$strip>, z.ZodObject<{
+                contexts: z.ZodArray<z.ZodString>;
+                current: z.ZodString;
+                outcome: z.ZodLiteral<"success">;
+                what: z.ZodLiteral<"contexts">;
+            }, z.core.$strip>, z.ZodObject<{
+                context: z.ZodString;
+                orientation: z.ZodEnum<{
+                    PORTRAIT: "PORTRAIT";
+                    LANDSCAPE: "LANDSCAPE";
+                }>;
+                outcome: z.ZodLiteral<"success">;
+                pageSource: z.ZodType<{
+                    selectors: {
+                        strategy: {
+                            name: "xpath";
+                            type: "unique" | "full-path" | "sibling-of" | "parent-of";
+                        } | {
+                            name: "ios-predicate";
+                        } | {
+                            hostSelector: string;
+                            innerSelector: string;
+                            name: "shadow";
+                        };
+                        value: string;
+                    }[];
+                    tag: string;
+                    attributes?: {
+                        bounds?: {
+                            bottom: number;
+                            left: number;
+                            right: number;
+                            top: number;
+                        } | undefined;
+                        rest?: Record<string, string> | undefined;
+                    } | undefined;
+                } & {
+                    children?: (({
+                        selectors: {
+                            strategy: {
+                                name: "xpath";
+                                type: "unique" | "full-path" | "sibling-of" | "parent-of";
+                            } | {
+                                name: "ios-predicate";
+                            } | {
+                                hostSelector: string;
+                                innerSelector: string;
+                                name: "shadow";
+                            };
+                            value: string;
+                        }[];
+                        tag: string;
+                        attributes?: {
+                            bounds?: {
+                                bottom: number;
+                                left: number;
+                                right: number;
+                                top: number;
+                            } | undefined;
+                            rest?: Record<string, string> | undefined;
+                        } | undefined;
+                    } & /*elided*/ any) | string)[];
+                }, unknown, z.core.$ZodTypeInternals<{
+                    selectors: {
+                        strategy: {
+                            name: "xpath";
+                            type: "unique" | "full-path" | "sibling-of" | "parent-of";
+                        } | {
+                            name: "ios-predicate";
+                        } | {
+                            hostSelector: string;
+                            innerSelector: string;
+                            name: "shadow";
+                        };
+                        value: string;
+                    }[];
+                    tag: string;
+                    attributes?: {
+                        bounds?: {
+                            bottom: number;
+                            left: number;
+                            right: number;
+                            top: number;
+                        } | undefined;
+                        rest?: Record<string, string> | undefined;
+                    } | undefined;
+                } & {
+                    children?: (({
+                        selectors: {
+                            strategy: {
+                                name: "xpath";
+                                type: "unique" | "full-path" | "sibling-of" | "parent-of";
+                            } | {
+                                name: "ios-predicate";
+                            } | {
+                                hostSelector: string;
+                                innerSelector: string;
+                                name: "shadow";
+                            };
+                            value: string;
+                        }[];
+                        tag: string;
+                        attributes?: {
+                            bounds?: {
+                                bottom: number;
+                                left: number;
+                                right: number;
+                                top: number;
+                            } | undefined;
+                            rest?: Record<string, string> | undefined;
+                        } | undefined;
+                    } & /*elided*/ any) | string)[];
+                }, unknown>>;
+                what: z.ZodLiteral<"page">;
+            }, z.core.$strip>, z.ZodObject<{
+                matches: z.ZodArray<z.ZodObject<{
+                    attributes: z.ZodRecord<z.ZodString, z.ZodString>;
+                    bounds: z.ZodOptional<z.ZodObject<{
+                        bottom: z.ZodNumber;
+                        left: z.ZodNumber;
+                        right: z.ZodNumber;
+                        top: z.ZodNumber;
+                    }, z.core.$strip>>;
+                    center: z.ZodOptional<z.ZodObject<{
+                        x: z.ZodNumber;
+                        y: z.ZodNumber;
+                    }, z.core.$strip>>;
+                    selectors: z.ZodArray<z.ZodObject<{
+                        strategy: z.ZodUnion<readonly [z.ZodObject<{
+                            name: z.ZodLiteral<"xpath">;
+                            type: z.ZodEnum<{
+                                unique: "unique";
+                                "full-path": "full-path";
+                                "sibling-of": "sibling-of";
+                                "parent-of": "parent-of";
+                            }>;
+                        }, z.core.$strip>, z.ZodObject<{
+                            name: z.ZodLiteral<"ios-predicate">;
+                        }, z.core.$strip>, z.ZodObject<{
+                            hostSelector: z.ZodString;
+                            innerSelector: z.ZodString;
+                            name: z.ZodLiteral<"shadow">;
+                        }, z.core.$strip>]>;
+                        value: z.ZodString;
+                    }, z.core.$strip>>;
+                    tag: z.ZodString;
+                }, z.core.$strip>>;
+                outcome: z.ZodLiteral<"success">;
+                what: z.ZodLiteral<"elements">;
+            }, z.core.$strip>], "what">, z.ZodObject<{
+                failureReason: z.ZodEnum<{
+                    "runner-unreachable": "runner-unreachable";
+                    "runner-is-not-mobile": "runner-is-not-mobile";
+                    "screen-needs-a-run": "screen-needs-a-run";
+                    "screen-not-ready": "screen-not-ready";
+                }>;
+                outcome: z.ZodLiteral<"failure">;
+            }, z.core.$strip>], "outcome">;
+        };
         launch: {
             readonly 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.";
             readonly input: z.ZodObject<{
@@ -2016,6 +2495,26 @@ export declare const publicContractsV1: {
                 outcome: z.ZodLiteral<"failure">;
             }, z.core.$strip>], "failureReason">], "outcome">;
         };
+        promoteSnapshot: {
+            readonly description: "Accept a run's screenshot as the new baseline for an image diff, on the runner that produced it. The two paths are the ones the diff reported, which reach a caller as an `image-diff-artifact` entry on the runner's `run-events` journal stream. `snapshot-not-found` if the run wrote no screenshot at that path, which usually means the paths were not taken from a diff this run produced; nothing is changed, so correcting the path and repeating is safe. `runner-cannot-promote-snapshots` on a runner that stores no screenshots. `runner-unreachable` if the runner could not be reached: it may still be starting, or it may have terminated after inactivity. A promotion that lands is not undone by promoting again, so a retry after an unreachable answer is safe.";
+            readonly input: z.ZodObject<{
+                baselinePath: z.ZodString;
+                id: z.ZodString;
+                screenshotPath: z.ZodString;
+            }, z.core.$strip>;
+            readonly kind: "write";
+            readonly name: "runner.promoteSnapshot";
+            readonly output: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                outcome: z.ZodLiteral<"success">;
+            }, z.core.$strip>, z.ZodObject<{
+                failureReason: z.ZodEnum<{
+                    "runner-unreachable": "runner-unreachable";
+                    "runner-cannot-promote-snapshots": "runner-cannot-promote-snapshots";
+                    "snapshot-not-found": "snapshot-not-found";
+                }>;
+                outcome: z.ZodLiteral<"failure">;
+            }, z.core.$strip>], "outcome">;
+        };
         readJournal: {
             readonly 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. `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<{
@@ -2053,6 +2552,7 @@ export declare const publicContractsV1: {
             readonly input: z.ZodObject<{
                 entryPointPath: z.ZodString;
                 env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                environmentId: z.ZodOptional<PublicIdSchema>;
                 files: z.ZodRecord<z.ZodString, z.ZodString>;
                 id: z.ZodString;
                 selection: z.ZodOptional<z.ZodObject<{

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/v1/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,YAAY,EACV,oBAAoB,EACpB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,KAAK,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,gBAAgB,GACjB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AACzD,cAAc,sBAAsB,CAAC;AAGrC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAc5D,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,iBAAiB,EAEvB,MAAM,UAAU,CAAC;AAwBlB,MAAM,MAAM,cAAc,CAAC,GAAG,SAAS,oBAAoB,IAAI,CAAC,CAAC,KAAK,CACpE,GAAG,CAAC,OAAO,CAAC,CACb,CAAC;AAEF,MAAM,MAAM,eAAe,CAAC,GAAG,SAAS,oBAAoB,IAAI,CAAC,CAAC,KAAK,CACrE,GAAG,CAAC,QAAQ,CAAC,CACd,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAC1B,aAAa,SAAS,cAAc,EACpC,MAAM,SAAS,cAAc,EAC7B,KAAK,SAAS,cAAc,EAC5B,YAAY,SAAS,cAAc,GAAG,cAAc,EACpD,OAAO,SAAS,cAAc,GAAG,cAAc,EAC/C,WAAW,SAAS,cAAc,GAAG,cAAc,EACnD,QAAQ,SAAS,cAAc,GAAG,cAAc,EAEhD,KAAK,iBAAiB,CACpB,aAAa,EACb,MAAM,EACN,KAAK,EACL,YAAY,EACZ,OAAO,EACP,WAAW,EACX,QAAQ,CACT;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuDF,CAAC;AAEF,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAAoC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/v1/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,YAAY,EACV,oBAAoB,EACpB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,KAAK,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,gBAAgB,GACjB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AACzD,cAAc,sBAAsB,CAAC;AAGrC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAc5D,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,iBAAiB,EAEvB,MAAM,UAAU,CAAC;AA2BlB,MAAM,MAAM,cAAc,CAAC,GAAG,SAAS,oBAAoB,IAAI,CAAC,CAAC,KAAK,CACpE,GAAG,CAAC,OAAO,CAAC,CACb,CAAC;AAEF,MAAM,MAAM,eAAe,CAAC,GAAG,SAAS,oBAAoB,IAAI,CAAC,CAAC,KAAK,CACrE,GAAG,CAAC,QAAQ,CAAC,CACd,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAC1B,aAAa,SAAS,cAAc,EACpC,MAAM,SAAS,cAAc,EAC7B,KAAK,SAAS,cAAc,EAC5B,YAAY,SAAS,cAAc,GAAG,cAAc,EACpD,OAAO,SAAS,cAAc,GAAG,cAAc,EAC/C,WAAW,SAAS,cAAc,GAAG,cAAc,EACnD,QAAQ,SAAS,cAAc,GAAG,cAAc,EAEhD,KAAK,iBAAiB,CACpB,aAAa,EACb,MAAM,EACN,KAAK,EACL,YAAY,EACZ,OAAO,EACP,WAAW,EACX,QAAQ,CACT;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuDF,CAAC;AAEF,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAAoC,CAAC"}

package/dist/v1/index.js

@@ -21,10 +21,13 @@ import { makeGetRunContract } from "./run/get.js";
 import { makeCreateRunContract } from "./run/index.js";
 import { makeReattemptRunContract } from "./run/reattempt.js";
 import { makeEvaluateSnippetOnRunnerContract } from "./runner/evaluateSnippet.js";
+import { makeHighlightSelectorOnRunnerContract } from "./runner/highlightSelector.js";
 import { makeImportPackageOnRunnerContract } from "./runner/importPackage.js";
 import { makeLaunchRunnerContract, makeTerminateRunnerContract, } from "./runner/index.js";
 import { makeInspectOnRunnerContract } from "./runner/inspect.js";
+import { makeInspectMobileOnRunnerContract } from "./runner/inspectMobile.js";
 import { makePerformActionOnRunnerContract } from "./runner/performAction.js";
+import { makePromoteSnapshotOnRunnerContract } from "./runner/promoteSnapshot.js";
 import { makeReadRunnerJournalContract } from "./runner/readJournal.js";
 import { makeRunFlowOnRunnerContract } from "./runner/runFlow.js";
 import { makeStopRunOnRunnerContract } from "./runner/stopRun.js";
@@ -74,15 +77,15 @@ export const makeContractsV1 = (ids) => {
         },
         runner: {
             evaluateSnippet: makeEvaluateSnippetOnRunnerContract(),
+            highlightSelector: makeHighlightSelectorOnRunnerContract(),
             importPackage: makeImportPackageOnRunnerContract(),
             inspect: makeInspectOnRunnerContract(),
-            // `runner.inspectMobile` (./runner/inspectMobile.js) stays out of this
-            // catalog until ARC-556 adds its router endpoint, to avoid tripping
-            // apex-backend's contract/router drift check.
+            inspectMobile: makeInspectMobileOnRunnerContract(),
             launch: makeLaunchRunnerContract(),
             performAction: makePerformActionOnRunnerContract(),
+            promoteSnapshot: makePromoteSnapshotOnRunnerContract(),
             readJournal: makeReadRunnerJournalContract(),
-            runFlow: makeRunFlowOnRunnerContract(),
+            runFlow: makeRunFlowOnRunnerContract(resolvedIds),
             stopRun: makeStopRunOnRunnerContract(),
             takeScreenshot: makeTakeScreenshotOnRunnerContract(),
             terminate: makeTerminateRunnerContract(),

package/dist/v1/index.js.map

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

package/dist/v1/runner/environment.js

@@ -27,7 +27,7 @@ function refusalForRunEnvironmentVariableName(name) {
     return undefined;
 }
 const maxRunEnvironmentVariables = 200;
-const maxRunEnvironmentValueLength = 8 * 1024;
+const maxRunEnvironmentValueLength = 16 * 1024;
 /** Bounded on its own, so a large project is never refused for its environment. */
 export const runEnvironmentSchema = z
     .record(z.string(), z.string().max(maxRunEnvironmentValueLength))

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

@@ -1 +1 @@
-{"version":3,"file":"environment.js","sourceRoot":"","sources":["../../../src/v1/runner/environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AAEH;;;;;;;GAOG;AACH,MAAM,kCAAkC,GAAG,gBAAgB,CAAC;AAE5D;;;;GAIG;AACH,SAAS,oCAAoC,CAC3C,IAAY;IAEZ,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,GAAG;QACtC,OAAO,oEAAoE,CAAC;IAC9E,IAAI,CAAC,0BAA0B,CAAC,IAAI,CAAC,IAAI,CAAC;QACxC,OAAO,iHAAiH,CAAC;IAC3H,0EAA0E;IAC1E,IAAI,IAAI,CAAC,WAAW,EAAE,KAAK,kCAAkC;QAC3D,OAAO,GAAG,kCAAkC,0CAA0C,CAAC;IACzF,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,0BAA0B,GAAG,GAAG,CAAC;AACvC,MAAM,4BAA4B,GAAG,CAAC,GAAG,IAAI,CAAC;AAE9C,mFAAmF;AACnF,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC;KAClC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC;KAChE,WAAW,CAAC,CAAC,WAAW,EAAE,iBAAiB,EAAE,EAAE;IAC9C,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;QAC5C,MAAM,OAAO,GAAG,oCAAoC,CAAC,IAAI,CAAC,CAAC;QAC3D,IAAI,OAAO,KAAK,SAAS;YAAE,SAAS;QACpC,iBAAiB,CAAC,QAAQ,CAAC;YACzB,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,OAAO;YAChB,IAAI,EAAE,CAAC,IAAI,CAAC;SACb,CAAC,CAAC;IACL,CAAC;AACH,CAAC,CAAC;KACD,MAAM,CACL,CAAC,WAAW,EAAE,EAAE,CACd,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,MAAM,IAAI,0BAA0B,EAC/D;IACE,KAAK,EAAE,WAAW,0BAA0B,yCAAyC;CACtF,CACF,CAAC"}
+{"version":3,"file":"environment.js","sourceRoot":"","sources":["../../../src/v1/runner/environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AAEH;;;;;;;GAOG;AACH,MAAM,kCAAkC,GAAG,gBAAgB,CAAC;AAE5D;;;;GAIG;AACH,SAAS,oCAAoC,CAC3C,IAAY;IAEZ,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,GAAG;QACtC,OAAO,oEAAoE,CAAC;IAC9E,IAAI,CAAC,0BAA0B,CAAC,IAAI,CAAC,IAAI,CAAC;QACxC,OAAO,iHAAiH,CAAC;IAC3H,0EAA0E;IAC1E,IAAI,IAAI,CAAC,WAAW,EAAE,KAAK,kCAAkC;QAC3D,OAAO,GAAG,kCAAkC,0CAA0C,CAAC;IACzF,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,0BAA0B,GAAG,GAAG,CAAC;AACvC,MAAM,4BAA4B,GAAG,EAAE,GAAG,IAAI,CAAC;AAE/C,mFAAmF;AACnF,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC;KAClC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC;KAChE,WAAW,CAAC,CAAC,WAAW,EAAE,iBAAiB,EAAE,EAAE;IAC9C,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;QAC5C,MAAM,OAAO,GAAG,oCAAoC,CAAC,IAAI,CAAC,CAAC;QAC3D,IAAI,OAAO,KAAK,SAAS;YAAE,SAAS;QACpC,iBAAiB,CAAC,QAAQ,CAAC;YACzB,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,OAAO;YAChB,IAAI,EAAE,CAAC,IAAI,CAAC;SACb,CAAC,CAAC;IACL,CAAC;AACH,CAAC,CAAC;KACD,MAAM,CACL,CAAC,WAAW,EAAE,EAAE,CACd,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,MAAM,IAAI,0BAA0B,EAC/D;IACE,KAAK,EAAE,WAAW,0BAA0B,yCAAyC;CACtF,CACF,CAAC"}

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

@@ -0,0 +1,30 @@
+import { z } from "zod";
+/** Long enough for a generated Playwright locator, short enough to bound the page work. */
+export declare const maxHighlightSelectorLength = 2000;
+export declare const makeHighlightSelectorOnRunnerContract: () => {
+    readonly description: "Highlight the elements a selector matches on an interactive runner's live page, and answer how many it matched. The highlight stays until it is replaced or cleared, so it is visible in the next `runner.takeScreenshot` — which is the point, since a caller cannot see the runner's screen otherwise. Send an empty selector to clear, which answers `cleared`. `status` tells a selector that matched nothing (`empty`) from one the page could not parse (`invalid`), so a caller can tell a bad locator from a locator pointing at nothing. `no-answer` if the page did not answer in time: the highlight runs inside the page, so a page that is gone or mid-navigation does not answer slowly, it does not answer at all. `runner-cannot-highlight-selectors` on a runner with no browser to draw on. `runner-unreachable` if the runner could not be reached: it may still be starting, or it may have terminated after inactivity.";
+    readonly input: z.ZodObject<{
+        id: z.ZodString;
+        selector: z.ZodString;
+    }, z.core.$strip>;
+    readonly kind: "write";
+    readonly name: "runner.highlightSelector";
+    readonly output: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        matchCount: z.ZodNumber;
+        outcome: z.ZodLiteral<"success">;
+        selector: z.ZodString;
+        status: z.ZodLiteral<"valid" | "invalid" | "empty">;
+        targetPage: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        outcome: z.ZodLiteral<"cleared">;
+    }, z.core.$strip>, z.ZodObject<{
+        errorMessage: z.ZodOptional<z.ZodString>;
+        failureReason: z.ZodEnum<{
+            "runner-unreachable": "runner-unreachable";
+            "no-answer": "no-answer";
+            "runner-cannot-highlight-selectors": "runner-cannot-highlight-selectors";
+        }>;
+        outcome: z.ZodLiteral<"failure">;
+    }, z.core.$strip>], "outcome">;
+};
+//# sourceMappingURL=highlightSelector.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"highlightSelector.d.ts","sourceRoot":"","sources":["../../../src/v1/runner/highlightSelector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,2FAA2F;AAC3F,eAAO,MAAM,0BAA0B,OAAQ,CAAC;AAEhD,eAAO,MAAM,qCAAqC;;;;;;;;;;;;;;;;;;;;;;;;;CA2DjD,CAAC"}

package/dist/v1/runner/highlightSelector.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { runnerIdSchema } from "./identity.js";
+/** Long enough for a generated Playwright locator, short enough to bound the page work. */
+export const maxHighlightSelectorLength = 2_000;
+export const makeHighlightSelectorOnRunnerContract = () => {
+    const input = z.object({
+        id: runnerIdSchema.describe("Id of the runner to highlight on."),
+        selector: z
+            .string()
+            .max(maxHighlightSelectorLength)
+            .describe("The selector to highlight. An empty string clears whatever is highlighted."),
+    });
+    const output = z.discriminatedUnion("outcome", [
+        z.object({
+            matchCount: z
+                .number()
+                .int()
+                .gte(0)
+                .describe("How many elements the selector matched."),
+            outcome: z.literal("success"),
+            selector: z.string().describe("The selector the page matched on."),
+            status: z
+                .literal(["valid", "invalid", "empty"])
+                .describe("`valid` when the selector parsed and matched, `empty` when it parsed and matched nothing, `invalid` when the page could not read it as a selector."),
+            targetPage: z
+                .string()
+                .optional()
+                .describe("Present when the match was on a page other than the default one."),
+        }),
+        z.object({
+            outcome: z.literal("cleared"),
+        }),
+        z.object({
+            errorMessage: z.string().optional(),
+            failureReason: z.enum([
+                "no-answer",
+                "runner-cannot-highlight-selectors",
+                "runner-unreachable",
+            ]),
+            outcome: z.literal("failure"),
+        }),
+    ]);
+    return {
+        description: "Highlight the elements a selector matches on an interactive runner's live page, and answer how many it matched. The highlight stays until it is replaced or cleared, so it is visible in the next `runner.takeScreenshot` — which is the point, since a caller cannot see the runner's screen otherwise. Send an empty selector to clear, which answers `cleared`. `status` tells a selector that matched nothing (`empty`) from one the page could not parse (`invalid`), so a caller can tell a bad locator from a locator pointing at nothing. `no-answer` if the page did not answer in time: the highlight runs inside the page, so a page that is gone or mid-navigation does not answer slowly, it does not answer at all. `runner-cannot-highlight-selectors` on a runner with no browser to draw on. `runner-unreachable` if the runner could not be reached: it may still be starting, or it may have terminated after inactivity.",
+        input,
+        kind: "write",
+        name: "runner.highlightSelector",
+        output,
+    };
+};
+//# sourceMappingURL=highlightSelector.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"highlightSelector.js","sourceRoot":"","sources":["../../../src/v1/runner/highlightSelector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,2FAA2F;AAC3F,MAAM,CAAC,MAAM,0BAA0B,GAAG,KAAK,CAAC;AAEhD,MAAM,CAAC,MAAM,qCAAqC,GAAG,GAAG,EAAE;IACxD,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC;QACrB,EAAE,EAAE,cAAc,CAAC,QAAQ,CAAC,mCAAmC,CAAC;QAChE,QAAQ,EAAE,CAAC;aACR,MAAM,EAAE;aACR,GAAG,CAAC,0BAA0B,CAAC;aAC/B,QAAQ,CACP,4EAA4E,CAC7E;KACJ,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,CAAC,CAAC,kBAAkB,CAAC,SAAS,EAAE;QAC7C,CAAC,CAAC,MAAM,CAAC;YACP,UAAU,EAAE,CAAC;iBACV,MAAM,EAAE;iBACR,GAAG,EAAE;iBACL,GAAG,CAAC,CAAC,CAAC;iBACN,QAAQ,CAAC,yCAAyC,CAAC;YACtD,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;YAC7B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,mCAAmC,CAAC;YAClE,MAAM,EAAE,CAAC;iBACN,OAAO,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;iBACtC,QAAQ,CACP,oJAAoJ,CACrJ;YACH,UAAU,EAAE,CAAC;iBACV,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CACP,kEAAkE,CACnE;SACJ,CAAC;QACF,CAAC,CAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;SAC9B,CAAC;QACF,CAAC,CAAC,MAAM,CAAC;YACP,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;YACnC,aAAa,EAAE,CAAC,CAAC,IAAI,CAAC;gBACpB,WAAW;gBACX,mCAAmC;gBACnC,oBAAoB;aACrB,CAAC;YACF,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;SAC9B,CAAC;KACH,CAAC,CAAC;IAEH,OAAO;QACL,WAAW,EACT,84BAA84B;QACh5B,KAAK;QACL,IAAI,EAAE,OAAO;QACb,IAAI,EAAE,0BAA0B;QAChC,MAAM;KAMP,CAAC;AACJ,CAAC,CAAC"}

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

@@ -21,7 +21,7 @@ export declare const inspectMobileRequestSchema: z.ZodDiscriminatedUnion<[z.ZodO
 }, z.core.$strip>], "by">], "what">;
 export type InspectMobileRequest = z.infer<typeof inspectMobileRequestSchema>;
 export declare const makeInspectMobileOnRunnerContract: () => {
-    readonly description: "Inspect one thing on a mobile interactive runner: the Appium session's status, the WebView contexts available, the current context's page source, or the elements at a point or carrying some text. Mobile only — a browser runner answers `runner-is-not-mobile`; call `runner.inspect` for a browser's equivalent surface instead. `what: \"session\"` always answers with the session's own status rather than `screen-needs-a-run`, since that is the question it exists to answer; the other three request kinds need a live session first and answer the same `screen-needs-a-run` or `screen-not-ready` outcomes `runner.performAction` and `runner.takeScreenshot` use, instead of reading anything when there is none. `screen-needs-a-run` means no Appium session has started on this runner yet — call `runner.runFlow` with a flow that opens one, then inspect again. `screen-not-ready` means the runner's Appium session exists but did not answer this instant, or more than one is somehow live — retry once; if it persists, relaunch the runner. `runner-is-not-mobile` means there is nothing here to inspect, and retrying will never help — launch a `node20WithAndroid` or `node20WithIos` runner instead. `runner-unreachable` if the runner could not be reached: it may still be starting, it may have terminated after inactivity, or it may be too busy to answer. Nothing was changed, so retrying is safe; if it persists, launch the runner again.";
+    readonly description: "Inspect one thing on a mobile interactive runner: the Appium session's status, the WebView contexts available, the current context's page source, or the elements at a point or carrying some text. Mobile only — a browser runner answers `runner-is-not-mobile`; call `runner.inspect` for a browser's equivalent surface instead. `what: \"session\"` always answers with the session's own status rather than `screen-needs-a-run`, since that is the question it exists to answer; the other three request kinds need a live session first and answer the same `screen-needs-a-run` or `screen-not-ready` outcomes `runner.performAction` and `runner.takeScreenshot` use, instead of reading anything when there is none. `screen-needs-a-run` means no Appium session has started on this runner yet — call `runner.runFlow` with a flow that opens one, then inspect again. `screen-not-ready` means the runner's Appium session exists but did not answer this instant, or more than one is somehow live — retry once; if it persists, relaunch the runner. `runner-is-not-mobile` means there is nothing here to inspect, and retrying will never help — launch an `android` or `ios` runner instead. `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;
         request: z.ZodDiscriminatedUnion<[z.ZodObject<{

package/dist/v1/runner/inspectMobile.js

@@ -108,7 +108,7 @@ export const makeInspectMobileOnRunnerContract = () => {
         ]),
     ]);
     return {
-        description: `Inspect one thing on a mobile interactive runner: the Appium session's status, the WebView contexts available, the current context's page source, or the elements at a point or carrying some text. Mobile only — a browser runner answers \`runner-is-not-mobile\`; call \`runner.inspect\` for a browser's equivalent surface instead. \`what: "session"\` always answers with the session's own status rather than \`screen-needs-a-run\`, since that is the question it exists to answer; the other three request kinds need a live session first and answer the same \`screen-needs-a-run\` or \`screen-not-ready\` outcomes \`runner.performAction\` and \`runner.takeScreenshot\` use, instead of reading anything when there is none. \`screen-needs-a-run\` means no Appium session has started on this runner yet — call \`runner.runFlow\` with a flow that opens one, then inspect again. \`screen-not-ready\` means the runner's Appium session exists but did not answer this instant, or more than one is somehow live — retry once; if it persists, relaunch the runner. \`runner-is-not-mobile\` means there is nothing here to inspect, and retrying will never help — launch a \`node20WithAndroid\` or \`node20WithIos\` runner instead. ${retryableRunnerUnreachableDescription}`,
+        description: `Inspect one thing on a mobile interactive runner: the Appium session's status, the WebView contexts available, the current context's page source, or the elements at a point or carrying some text. Mobile only — a browser runner answers \`runner-is-not-mobile\`; call \`runner.inspect\` for a browser's equivalent surface instead. \`what: "session"\` always answers with the session's own status rather than \`screen-needs-a-run\`, since that is the question it exists to answer; the other three request kinds need a live session first and answer the same \`screen-needs-a-run\` or \`screen-not-ready\` outcomes \`runner.performAction\` and \`runner.takeScreenshot\` use, instead of reading anything when there is none. \`screen-needs-a-run\` means no Appium session has started on this runner yet — call \`runner.runFlow\` with a flow that opens one, then inspect again. \`screen-not-ready\` means the runner's Appium session exists but did not answer this instant, or more than one is somehow live — retry once; if it persists, relaunch the runner. \`runner-is-not-mobile\` means there is nothing here to inspect, and retrying will never help — launch an \`android\` or \`ios\` runner instead. ${retryableRunnerUnreachableDescription}`,
         input,
         kind: "read",
         name: "runner.inspectMobile",

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

@@ -1 +1 @@
-{"version":3,"file":"inspectMobile.js","sourceRoot":"","sources":["../../../src/v1/runner/inspectMobile.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"inspectMobile.js","sourceRoot":"","sources":["../../../src/v1/runner/inspectMobile.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EACL,qCAAqC,EACrC,8BAA8B,GAC/B,MAAM,kBAAkB,CAAC;AAE1B;;;;GAIG;AAEH,MAAM,oBAAoB,GAAG,GAAG,CAAC;AAEjC,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE;IACrE,CAAC,CAAC,MAAM,CAAC;QACP,IAAI,EAAE,CAAC;aACJ,OAAO,CAAC,SAAS,CAAC;aAClB,QAAQ,CACP,wFAAwF,CACzF;KACJ,CAAC;IACF,CAAC,CAAC,MAAM,CAAC;QACP,IAAI,EAAE,CAAC;aACJ,OAAO,CAAC,UAAU,CAAC;aACnB,QAAQ,CACP,yEAAyE,CAC1E;KACJ,CAAC;IACF,CAAC,CAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;aACP,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,EAAE;aACV,QAAQ,CAAC,oDAAoD,CAAC;QACjE,IAAI,EAAE,CAAC;aACJ,OAAO,CAAC,MAAM,CAAC;aACf,QAAQ,CAAC,6DAA6D,CAAC;KAC3E,CAAC;IACF,CAAC;SACE,kBAAkB,CAAC,IAAI,EAAE;QACxB,CAAC,CAAC,MAAM,CAAC;YACP,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;YACtB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;YACrC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;YAC3B,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,0CAA0C,CAAC;YACtE,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,0CAA0C,CAAC;SACvE,CAAC;QACF,CAAC,CAAC,MAAM,CAAC;YACP,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;YACrB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;YACrC,OAAO,EAAE,CAAC;iBACP,OAAO,EAAE;iBACT,QAAQ,EAAE;iBACV,QAAQ,CAAC,uDAAuD,CAAC;YACpE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,oBAAoB,CAAC;YACjD,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;SAC5B,CAAC;KACH,CAAC;SACD,QAAQ,CACP,kFAAkF,CACnF;CACJ,CAAC,CAAC;AAEH,MAAM,yBAAyB,GAAG,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE;IAC7D,CAAC,CAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;QAC7B,OAAO,EAAE,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE;YACpC,CAAC,CAAC,MAAM,CAAC;gBACP,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;gBACjC,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE;gBACxB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;gBACrB,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;aACzB,CAAC;YACF,CAAC,CAAC,MAAM,CAAC;gBACP,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;gBACjB,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC;aAC/B,CAAC;YACF,CAAC,CAAC,MAAM,CAAC;gBACP,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE;gBACxB,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC;aAC7B,CAAC;YACF,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;SAC5C,CAAC;QACF,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;KAC3B,CAAC;IACF,CAAC,CAAC,MAAM,CAAC;QACP,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE;QAC5B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;QACnB,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;QAC7B,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;KAC5B,CAAC;IACF,CAAC,CAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;QACnB,WAAW,EAAE,iBAAiB;QAC9B,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;QAC7B,UAAU,EAAE,oBAAoB;QAChC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;KACxB,CAAC;IACF,CAAC,CAAC,MAAM,CAAC;QACP,OAAO,EAAE,aAAa,CAAC,KAAK,EAAE;QAC9B,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;QAC7B,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;KAC5B,CAAC;CACH,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,iCAAiC,GAAG,GAAG,EAAE;IACpD,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC;QACrB,EAAE,EAAE,cAAc,CAAC,QAAQ,CAAC,8BAA8B,CAAC;QAC3D,OAAO,EAAE,0BAA0B;KACpC,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,CAAC,CAAC,kBAAkB,CAAC,SAAS,EAAE;QAC7C,yBAAyB;QACzB,uBAAuB,CAAC;YACtB,sBAAsB;YACtB,oBAAoB;YACpB,kBAAkB;YAClB,8BAA8B;SAC/B,CAAC;KACH,CAAC,CAAC;IAEH,OAAO;QACL,WAAW,EAAE,6qCAA6qC,qCAAqC,EAAE;QACjuC,KAAK;QACL,IAAI,EAAE,MAAM;QACZ,IAAI,EAAE,sBAAsB;QAC5B,MAAM;KAMP,CAAC;AACJ,CAAC,CAAC"}

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

@@ -1 +1 @@
-{"version":3,"file":"journal.d.ts","sourceRoot":"","sources":["../../../src/v1/runner/journal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AAEH,qDAAqD;AACrD,MAAM,MAAM,YAAY,CAAC,OAAO,IAAI;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;GAgB5B,CAAC;AAEJ,eAAO,MAAM,mBAAmB,0EAMtB,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,kBAAkB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAE/D;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAE7C,eAAO,MAAM,mBAAmB,aAGE,CAAC;AAEnC;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,iFAAiF;IACjF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,aAAa,CAAC;IACtB,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,wBAAwB;;;;;iBAKK,CAAC;AAE3C,MAAM,MAAM,mBAAmB,GAAG;IAChC,iFAAiF;IACjF,OAAO,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,CAAC;IACjC;;;;;OAKG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAC9B;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,uBAAuB,EAAE,MAAM,CAAC;CACjC,CAAC;AAEF,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;iBAKK,CAAC"}
+{"version":3,"file":"journal.d.ts","sourceRoot":"","sources":["../../../src/v1/runner/journal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AAEH,qDAAqD;AACrD,MAAM,MAAM,YAAY,CAAC,OAAO,IAAI;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;GAc1B,CAAC;AAEN,eAAO,MAAM,mBAAmB,0EAMtB,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,kBAAkB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAE/D;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAE7C,eAAO,MAAM,mBAAmB,aAGE,CAAC;AAEnC;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,iFAAiF;IACjF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,aAAa,CAAC;IACtB,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,wBAAwB;;;;;iBAKK,CAAC;AAE3C,MAAM,MAAM,mBAAmB,GAAG;IAChC,iFAAiF;IACjF,OAAO,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,CAAC;IACjC;;;;;OAKG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAC9B;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,uBAAuB,EAAE,MAAM,CAAC;CACjC,CAAC;AAEF,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;iBAKK,CAAC"}

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

@@ -1 +1 @@
-{"version":3,"file":"journal.js","sourceRoot":"","sources":["../../../src/v1/runner/journal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAiBxB;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC;KAChC,MAAM,CAAC;IACN,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;IACpB,UAAU,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE;IAC5B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;CACtC,CAAC;KACD,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,SAAS,IAAI,KAAK,EAAE;IACrC,KAAK,EAAE,2CAA2C;IAClD,IAAI,EAAE,CAAC,SAAS,CAAC;CAClB,CAAC;KACD,SAAS,CACR,CAAC,KAAK,EAAyB,EAAE,CAAC,CAAC;IACjC,OAAO,EAAE,KAAK,CAAC,OAAO;IACtB,UAAU,EAAE,KAAK,CAAC,UAAU;IAC5B,QAAQ,EAAE,KAAK,CAAC,QAAQ;CACzB,CAAC,CACH,CAAC;AAEJ,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,SAAS;IACT,UAAU;IACV,YAAY;IACZ,UAAU;IACV,YAAY;CACJ,CAAC;AAWX;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,EAAE,CAAC;AAE7C,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC;KACjC,MAAM,EAAE;KACR,GAAG,CAAC,0BAA0B,CAAC;KAC/B,KAAK,CAAC,wBAAwB,CAAC,CAAC;AAqBnC,yEAAyE;AACzE,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IAC5C,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE;IACxD,MAAM,EAAE,mBAAmB;IAC3B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CAC7C,CAAyC,CAAC;AAwB3C,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,kBAAkB,CAAC;IACpC,oBAAoB,EAAE,CAAC,CAAC,OAAO,EAAE;IACjC,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC5C,uBAAuB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;CACxD,CAA0C,CAAC"}
+{"version":3,"file":"journal.js","sourceRoot":"","sources":["../../../src/v1/runner/journal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAiBxB;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC;KAChC,MAAM,CAAC;IACN,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;IACpB,UAAU,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE;IAC5B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;CACtC,CAAC;KACD,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,SAAS,IAAI,KAAK,EAAE;IACrC,KAAK,EAAE,2CAA2C;IAClD,IAAI,EAAE,CAAC,SAAS,CAAC;CAClB,CAAC;KACD,SAAS,CAAC,CAAC,KAAK,EAAyB,EAAE,CAAC,CAAC;IAC5C,OAAO,EAAE,KAAK,CAAC,OAAO;IACtB,UAAU,EAAE,KAAK,CAAC,UAAU;IAC5B,QAAQ,EAAE,KAAK,CAAC,QAAQ;CACzB,CAAC,CAAC,CAAC;AAEN,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,SAAS;IACT,UAAU;IACV,YAAY;IACZ,UAAU;IACV,YAAY;CACJ,CAAC;AAWX;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,EAAE,CAAC;AAE7C,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC;KACjC,MAAM,EAAE;KACR,GAAG,CAAC,0BAA0B,CAAC;KAC/B,KAAK,CAAC,wBAAwB,CAAC,CAAC;AAqBnC,yEAAyE;AACzE,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IAC5C,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE;IACxD,MAAM,EAAE,mBAAmB;IAC3B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CAC7C,CAAyC,CAAC;AAwB3C,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,kBAAkB,CAAC;IACpC,oBAAoB,EAAE,CAAC,CAAC,OAAO,EAAE;IACjC,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC5C,uBAAuB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;CACxD,CAA0C,CAAC"}

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

@@ -0,0 +1,24 @@
+import { z } from "zod";
+/** A path within the run's own screenshot storage, not a filesystem path. */
+export declare const maxSnapshotPathLength = 1024;
+export declare const makePromoteSnapshotOnRunnerContract: () => {
+    readonly description: "Accept a run's screenshot as the new baseline for an image diff, on the runner that produced it. The two paths are the ones the diff reported, which reach a caller as an `image-diff-artifact` entry on the runner's `run-events` journal stream. `snapshot-not-found` if the run wrote no screenshot at that path, which usually means the paths were not taken from a diff this run produced; nothing is changed, so correcting the path and repeating is safe. `runner-cannot-promote-snapshots` on a runner that stores no screenshots. `runner-unreachable` if the runner could not be reached: it may still be starting, or it may have terminated after inactivity. A promotion that lands is not undone by promoting again, so a retry after an unreachable answer is safe.";
+    readonly input: z.ZodObject<{
+        baselinePath: z.ZodString;
+        id: z.ZodString;
+        screenshotPath: z.ZodString;
+    }, z.core.$strip>;
+    readonly kind: "write";
+    readonly name: "runner.promoteSnapshot";
+    readonly output: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        outcome: z.ZodLiteral<"success">;
+    }, z.core.$strip>, z.ZodObject<{
+        failureReason: z.ZodEnum<{
+            "runner-unreachable": "runner-unreachable";
+            "runner-cannot-promote-snapshots": "runner-cannot-promote-snapshots";
+            "snapshot-not-found": "snapshot-not-found";
+        }>;
+        outcome: z.ZodLiteral<"failure">;
+    }, z.core.$strip>], "outcome">;
+};
+//# sourceMappingURL=promoteSnapshot.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"promoteSnapshot.d.ts","sourceRoot":"","sources":["../../../src/v1/runner/promoteSnapshot.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,6EAA6E;AAC7E,eAAO,MAAM,qBAAqB,OAAQ,CAAC;AAE3C,eAAO,MAAM,mCAAmC;;;;;;;;;;;;;;;;;;;CAwC/C,CAAC"}

package/dist/v1/runner/promoteSnapshot.js

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import { runnerIdSchema } from "./identity.js";
+/** A path within the run's own screenshot storage, not a filesystem path. */
+export const maxSnapshotPathLength = 1_024;
+export const makePromoteSnapshotOnRunnerContract = () => {
+    const input = z.object({
+        baselinePath: z
+            .string()
+            .min(1)
+            .max(maxSnapshotPathLength)
+            .describe("The baseline to replace, as named in the image diff."),
+        id: runnerIdSchema.describe("Id of the runner holding the screenshot."),
+        screenshotPath: z
+            .string()
+            .min(1)
+            .max(maxSnapshotPathLength)
+            .describe("The screenshot to promote, as named in the image diff."),
+    });
+    const output = z.discriminatedUnion("outcome", [
+        z.object({ outcome: z.literal("success") }),
+        z.object({
+            failureReason: z.enum([
+                "runner-cannot-promote-snapshots",
+                "runner-unreachable",
+                "snapshot-not-found",
+            ]),
+            outcome: z.literal("failure"),
+        }),
+    ]);
+    return {
+        description: "Accept a run's screenshot as the new baseline for an image diff, on the runner that produced it. The two paths are the ones the diff reported, which reach a caller as an `image-diff-artifact` entry on the runner's `run-events` journal stream. `snapshot-not-found` if the run wrote no screenshot at that path, which usually means the paths were not taken from a diff this run produced; nothing is changed, so correcting the path and repeating is safe. `runner-cannot-promote-snapshots` on a runner that stores no screenshots. `runner-unreachable` if the runner could not be reached: it may still be starting, or it may have terminated after inactivity. A promotion that lands is not undone by promoting again, so a retry after an unreachable answer is safe.",
+        input,
+        kind: "write",
+        name: "runner.promoteSnapshot",
+        output,
+    };
+};
+//# sourceMappingURL=promoteSnapshot.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"promoteSnapshot.js","sourceRoot":"","sources":["../../../src/v1/runner/promoteSnapshot.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,6EAA6E;AAC7E,MAAM,CAAC,MAAM,qBAAqB,GAAG,KAAK,CAAC;AAE3C,MAAM,CAAC,MAAM,mCAAmC,GAAG,GAAG,EAAE;IACtD,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC;QACrB,YAAY,EAAE,CAAC;aACZ,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,GAAG,CAAC,qBAAqB,CAAC;aAC1B,QAAQ,CAAC,sDAAsD,CAAC;QACnE,EAAE,EAAE,cAAc,CAAC,QAAQ,CAAC,0CAA0C,CAAC;QACvE,cAAc,EAAE,CAAC;aACd,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,GAAG,CAAC,qBAAqB,CAAC;aAC1B,QAAQ,CAAC,wDAAwD,CAAC;KACtE,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,CAAC,CAAC,MAAM,CAAC;YACP,aAAa,EAAE,CAAC,CAAC,IAAI,CAAC;gBACpB,iCAAiC;gBACjC,oBAAoB;gBACpB,oBAAoB;aACrB,CAAC;YACF,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;SAC9B,CAAC;KACH,CAAC,CAAC;IAEH,OAAO;QACL,WAAW,EACT,svBAAsvB;QACxvB,KAAK;QACL,IAAI,EAAE,OAAO;QACb,IAAI,EAAE,wBAAwB;QAC9B,MAAM;KAMP,CAAC;AACJ,CAAC,CAAC"}

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

@@ -1,9 +1,13 @@
 import { z } from "zod";
-export declare const makeRunFlowOnRunnerContract: () => {
+import type { PublicIdSchema } from "../ids.js";
+export declare const makeRunFlowOnRunnerContract: (ids: {
+    environmentRef: PublicIdSchema;
+}) => {
     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>>;
+        environmentId: z.ZodOptional<PublicIdSchema>;
         files: z.ZodRecord<z.ZodString, z.ZodString>;
         id: z.ZodString;
         selection: z.ZodOptional<z.ZodObject<{

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;AA4BxB,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+GvC,CAAC"}
+{"version":3,"file":"runFlow.d.ts","sourceRoot":"","sources":["../../../src/v1/runner/runFlow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AA0BhD,eAAO,MAAM,2BAA2B,GAAI,KAAK;IAC/C,cAAc,EAAE,cAAc,CAAC;CAChC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+HA,CAAC"}

package/dist/v1/runner/runFlow.js

@@ -17,13 +17,16 @@ const unchangedFilesSchema = z
         });
     }
 });
-export const makeRunFlowOnRunnerContract = () => {
+export const makeRunFlowOnRunnerContract = (ids) => {
     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."),
+        environmentId: ids.environmentRef
+            .optional()
+            .describe("A QA Wolf environment whose variables the run is given, by id or alias. QA Wolf reads and decrypts them itself, so they never travel in the request and the count and length limits on `env` do not apply to them. Send this or `env`, not both."),
         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
@@ -32,6 +35,12 @@ export const makeRunFlowOnRunnerContract = () => {
         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."),
+    })
+        // Both would need a merge order, and the two surfaces that carry an
+        // environment and caller variables today do not agree on one.
+        .refine((request) => request.env === undefined || request.environmentId === undefined, {
+        error: "Send env or environmentId, not both. An environment's variables are taken as they are stored, so there is no order in which the two would combine.",
+        path: ["environmentId"],
     })
         // Stated here rather than discovered when the runner cannot find a module.
         .refine((request) => Object.hasOwn(request.files, request.entryPointPath), {

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

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

package/package.json

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