@qawolf/api-contracts 0.26.0 → 0.27.0

package/dist/v1/index.d.ts

@@ -7,9 +7,11 @@ export { type BrowserAction, browserActionSchema, } from "./runner/browserAction
 export { runEnvironmentSchema } from "./runner/environment.js";
 export { isShippableRunFilePath, runFilePathSchema, runPackageJsonPath, shippableRunFileExtensions, } from "./runner/files.js";
 export { type RunnerNameForPublicApi, makeRunnerSchema, runnerIdSchema, runnerNameSchema, } from "./runner/identity.js";
+export { type InspectOnRunnerRequest, inspectRequestSchema, } from "./runner/inspect.js";
 export { type JournalEntry, type JournalStream, type KnownJournalStream, type ReadJournalRequest, type ReadJournalResponse, journalEntrySchema, journalStreamSchema, knownJournalStreams, maxJournalStreamNameLength, readJournalRequestSchema, readJournalResponseSchema, } from "./runner/journal.js";
 export { type RunFiles, maxRunFilesByteLength, maxRunnerRequestEncodedByteLength, runFilesByteLength, runFilesSchema, } from "./runner/payloadSize.js";
 export { maxActionErrorMessageLength } from "./runner/performAction.js";
+export { type RunSelection, runSelectionSchema, } from "./runner/runSelection.js";
 import type { AnyPublicApiContract } from "./definition.js";
 import { type PublicIdSchema, type PublicIdSchemasOf } from "./ids.js";
 export type PublicApiInput<Api extends AnyPublicApiContract> = z.input<Api["input"]>;
@@ -767,25 +769,78 @@ export declare const makeContractsV1: <EnvironmentId extends PublicIdSchema, Flo
             readonly name: "runner.evaluateSnippet";
             readonly output: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 errorMessage: z.ZodOptional<z.ZodString>;
-                outcome: z.ZodLiteral<"evaluated">;
+                outcome: z.ZodLiteral<"success">;
                 result: z.ZodEnum<{
                     success: "success";
                     error: "error";
                     stopped: "stopped";
                 }>;
             }, 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">;
+        };
+        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<{
+                id: z.ZodString;
+                npmDependencies: z.ZodRecord<z.ZodString, z.ZodString>;
+                packageName: z.ZodString;
+                packageVersion: z.ZodString;
+            }, z.core.$strip>;
+            readonly kind: "write";
+            readonly name: "runner.importPackage";
+            readonly output: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                outcome: z.ZodLiteral<"success">;
+            }, z.core.$strip>, z.ZodObject<{
+                errorMessage: z.ZodOptional<z.ZodString>;
+                failureReason: z.ZodEnum<{
+                    "runner-unreachable": "runner-unreachable";
+                    "install-failed": "install-failed";
+                }>;
+                outcome: z.ZodLiteral<"failure">;
+            }, z.core.$strip>], "outcome">;
+        };
+        inspect: {
+            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">;
         };
         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 `outcome` to tell which happened.";
+            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<{
                 id: z.ZodString;
                 runnerName: z.ZodOptional<z.ZodEnum<{
-                    node20Basic: "node20Basic";
-                    node20WithAndroid: "node20WithAndroid";
-                    node20WithIos: "node20WithIos";
-                    node20WithPlaywright: "node20WithPlaywright";
+                    basic: "basic";
+                    playwright: "playwright";
+                    android: "android";
+                    ios: "ios";
                 }>>;
             }, z.core.$strip>;
             readonly kind: "write";
@@ -794,19 +849,17 @@ export declare const makeContractsV1: <EnvironmentId extends PublicIdSchema, Flo
                 gpuAccelerated: z.ZodBoolean;
                 id: z.ZodString;
                 runnerName: z.ZodEnum<{
-                    node20Basic: "node20Basic";
-                    node20WithAndroid: "node20WithAndroid";
-                    node20WithIos: "node20WithIos";
-                    node20WithPlaywright: "node20WithPlaywright";
-                }>;
-                outcome: z.ZodEnum<{
-                    launched: "launched";
-                    "already-running": "already-running";
+                    basic: "basic";
+                    playwright: "playwright";
+                    android: "android";
+                    ios: "ios";
                 }>;
+                alreadyRunning: z.ZodBoolean;
+                outcome: z.ZodLiteral<"success">;
             }, z.core.$strip>;
         };
         performAction: {
-            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. 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 `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">;
@@ -848,19 +901,20 @@ export declare const makeContractsV1: <EnvironmentId extends PublicIdSchema, Flo
             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">;
         };
         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.";
@@ -886,59 +940,77 @@ export declare const makeContractsV1: <EnvironmentId extends PublicIdSchema, Flo
                 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">;
         };
         runFlow: {
-            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">;
         };
-        stop: {
-            readonly 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.";
+        stopRun: {
+            readonly description: "Stop what a runner is currently executing, leaving the runner up and its browser on whatever page the run reached. Succeeds whether or not anything was running, and `wasRunning` says which. This is the counterpart of `runner.terminate`, which ends the runner itself. The run stops where it is, so the journal's `run-status` settles it as stopped rather than passed or failed. `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 stop may still have landed, but stopping a runner that is already idle does nothing, so retrying is safe.";
             readonly input: z.ZodObject<{
                 id: z.ZodString;
             }, z.core.$strip>;
             readonly kind: "write";
-            readonly name: "runner.stop";
-            readonly output: z.ZodObject<{
-                id: z.ZodString;
-                outcome: z.ZodEnum<{
-                    stopped: "stopped";
-                    "not-running": "not-running";
+            readonly name: "runner.stopRun";
+            readonly output: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                outcome: z.ZodLiteral<"success">;
+                wasRunning: z.ZodBoolean;
+            }, z.core.$strip>, z.ZodObject<{
+                failureReason: z.ZodEnum<{
+                    "runner-unreachable": "runner-unreachable";
                 }>;
-            }, z.core.$strip>;
+                outcome: z.ZodLiteral<"failure">;
+            }, z.core.$strip>], "outcome">;
         };
         takeScreenshot: {
-            readonly description: "Take one screenshot of an interactive runner's screen. The image is the runner's whole virtual desktop, browser window and all. `screen-needs-a-run` if the runner's virtual desktop has never started. Waiting will not change this and retrying is pointless — call `runner.runFlow` with a flow that opens a browser, then ask for the screen again. On a runner image with a browser that has never run anything, any `runner.performAction` also starts the browser itself. Evaluating a snippet does not start the desktop. `screen-not-ready` if the runner has a screen that cannot serve this instant. Retry in a second or two: the desktop restarts when a run changes the display size, and it serves one see-or-act request at a time, so a screenshot or action already in flight is the usual reason. Do not submit a run to clear this — a run may restart the display and discard what is on it. `runner-has-no-screen` if this runner is not one that runs a browser on a virtual desktop. Nothing about it can be seen or driven, and retrying will never help — launch a `node20WithPlaywright` runner instead. `runner-unreachable` if the runner could not be reached: it may still be starting, it may have terminated after inactivity, or it may be too busy to answer. Nothing was changed, so retrying is safe; if it persists, launch the runner again.";
+            readonly description: "Take one screenshot of an interactive runner's screen. The image is the runner's whole virtual desktop, browser window and all. `screen-needs-a-run` if the runner's virtual desktop has never started. Waiting will not change this and retrying is pointless — call `runner.runFlow` with a flow that opens a browser, then ask for the screen again. On a runner image with a browser that has never run anything, any `runner.performAction` also starts the browser itself. Evaluating a snippet does not start the desktop. `screen-not-ready` if the runner has a screen that cannot serve this instant. Retry in a second or two: the desktop restarts when a run changes the display size, and it serves one see-or-act request at a time, so a screenshot or action already in flight is the usual reason. Do not submit a run to clear this — a run may restart the display and discard what is on it. `runner-has-no-screen` if this runner is not one that runs a browser on a virtual desktop. Nothing about it can be seen or driven, and retrying will never help — launch a `playwright` runner instead. `runner-unreachable` if the runner could not be reached: it may still be starting, it may have terminated after inactivity, or it may be too busy to answer. Nothing was changed, so retrying is safe; if it persists, launch the runner again.";
             readonly input: z.ZodObject<{
                 id: z.ZodString;
             }, z.core.$strip>;
@@ -946,17 +1018,30 @@ export declare const makeContractsV1: <EnvironmentId extends PublicIdSchema, Flo
             readonly name: "runner.takeScreenshot";
             readonly output: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 imageJpegBase64: z.ZodString;
-                outcome: z.ZodLiteral<"captured">;
-            }, z.core.$strip>, z.ZodObject<{
-                outcome: z.ZodLiteral<"screen-needs-a-run">;
-            }, z.core.$strip>, z.ZodObject<{
-                outcome: z.ZodLiteral<"screen-not-ready">;
+                outcome: z.ZodLiteral<"success">;
             }, z.core.$strip>, z.ZodObject<{
-                outcome: z.ZodLiteral<"runner-has-no-screen">;
-            }, z.core.$strip>, z.ZodObject<{
-                outcome: z.ZodLiteral<"runner-unreachable">;
+                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>], "outcome">;
         };
+        terminate: {
+            readonly 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.";
+            readonly input: z.ZodObject<{
+                id: z.ZodString;
+            }, z.core.$strip>;
+            readonly kind: "write";
+            readonly name: "runner.terminate";
+            readonly output: z.ZodObject<{
+                id: z.ZodString;
+                outcome: z.ZodLiteral<"success">;
+                wasRunning: z.ZodBoolean;
+            }, z.core.$strip>;
+        };
     };
     tag: {
         create: {
@@ -1740,25 +1825,78 @@ export declare const publicContractsV1: {
             readonly name: "runner.evaluateSnippet";
             readonly output: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 errorMessage: z.ZodOptional<z.ZodString>;
-                outcome: z.ZodLiteral<"evaluated">;
+                outcome: z.ZodLiteral<"success">;
                 result: z.ZodEnum<{
                     success: "success";
                     error: "error";
                     stopped: "stopped";
                 }>;
             }, 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">;
+        };
+        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<{
+                id: z.ZodString;
+                npmDependencies: z.ZodRecord<z.ZodString, z.ZodString>;
+                packageName: z.ZodString;
+                packageVersion: z.ZodString;
+            }, z.core.$strip>;
+            readonly kind: "write";
+            readonly name: "runner.importPackage";
+            readonly output: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                outcome: z.ZodLiteral<"success">;
+            }, z.core.$strip>, z.ZodObject<{
+                errorMessage: z.ZodOptional<z.ZodString>;
+                failureReason: z.ZodEnum<{
+                    "runner-unreachable": "runner-unreachable";
+                    "install-failed": "install-failed";
+                }>;
+                outcome: z.ZodLiteral<"failure">;
+            }, z.core.$strip>], "outcome">;
+        };
+        inspect: {
+            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">;
         };
         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 `outcome` to tell which happened.";
+            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<{
                 id: z.ZodString;
                 runnerName: z.ZodOptional<z.ZodEnum<{
-                    node20Basic: "node20Basic";
-                    node20WithAndroid: "node20WithAndroid";
-                    node20WithIos: "node20WithIos";
-                    node20WithPlaywright: "node20WithPlaywright";
+                    basic: "basic";
+                    playwright: "playwright";
+                    android: "android";
+                    ios: "ios";
                 }>>;
             }, z.core.$strip>;
             readonly kind: "write";
@@ -1767,19 +1905,17 @@ export declare const publicContractsV1: {
                 gpuAccelerated: z.ZodBoolean;
                 id: z.ZodString;
                 runnerName: z.ZodEnum<{
-                    node20Basic: "node20Basic";
-                    node20WithAndroid: "node20WithAndroid";
-                    node20WithIos: "node20WithIos";
-                    node20WithPlaywright: "node20WithPlaywright";
-                }>;
-                outcome: z.ZodEnum<{
-                    launched: "launched";
-                    "already-running": "already-running";
+                    basic: "basic";
+                    playwright: "playwright";
+                    android: "android";
+                    ios: "ios";
                 }>;
+                alreadyRunning: z.ZodBoolean;
+                outcome: z.ZodLiteral<"success">;
             }, z.core.$strip>;
         };
         performAction: {
-            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. 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 `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">;
@@ -1821,19 +1957,20 @@ export declare const publicContractsV1: {
             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">;
         };
         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.";
@@ -1859,59 +1996,77 @@ export declare const publicContractsV1: {
                 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">;
         };
         runFlow: {
-            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">;
         };
-        stop: {
-            readonly 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.";
+        stopRun: {
+            readonly description: "Stop what a runner is currently executing, leaving the runner up and its browser on whatever page the run reached. Succeeds whether or not anything was running, and `wasRunning` says which. This is the counterpart of `runner.terminate`, which ends the runner itself. The run stops where it is, so the journal's `run-status` settles it as stopped rather than passed or failed. `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 stop may still have landed, but stopping a runner that is already idle does nothing, so retrying is safe.";
             readonly input: z.ZodObject<{
                 id: z.ZodString;
             }, z.core.$strip>;
             readonly kind: "write";
-            readonly name: "runner.stop";
-            readonly output: z.ZodObject<{
-                id: z.ZodString;
-                outcome: z.ZodEnum<{
-                    stopped: "stopped";
-                    "not-running": "not-running";
+            readonly name: "runner.stopRun";
+            readonly output: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                outcome: z.ZodLiteral<"success">;
+                wasRunning: z.ZodBoolean;
+            }, z.core.$strip>, z.ZodObject<{
+                failureReason: z.ZodEnum<{
+                    "runner-unreachable": "runner-unreachable";
                 }>;
-            }, z.core.$strip>;
+                outcome: z.ZodLiteral<"failure">;
+            }, z.core.$strip>], "outcome">;
         };
         takeScreenshot: {
-            readonly description: "Take one screenshot of an interactive runner's screen. The image is the runner's whole virtual desktop, browser window and all. `screen-needs-a-run` if the runner's virtual desktop has never started. Waiting will not change this and retrying is pointless — call `runner.runFlow` with a flow that opens a browser, then ask for the screen again. On a runner image with a browser that has never run anything, any `runner.performAction` also starts the browser itself. Evaluating a snippet does not start the desktop. `screen-not-ready` if the runner has a screen that cannot serve this instant. Retry in a second or two: the desktop restarts when a run changes the display size, and it serves one see-or-act request at a time, so a screenshot or action already in flight is the usual reason. Do not submit a run to clear this — a run may restart the display and discard what is on it. `runner-has-no-screen` if this runner is not one that runs a browser on a virtual desktop. Nothing about it can be seen or driven, and retrying will never help — launch a `node20WithPlaywright` runner instead. `runner-unreachable` if the runner could not be reached: it may still be starting, it may have terminated after inactivity, or it may be too busy to answer. Nothing was changed, so retrying is safe; if it persists, launch the runner again.";
+            readonly description: "Take one screenshot of an interactive runner's screen. The image is the runner's whole virtual desktop, browser window and all. `screen-needs-a-run` if the runner's virtual desktop has never started. Waiting will not change this and retrying is pointless — call `runner.runFlow` with a flow that opens a browser, then ask for the screen again. On a runner image with a browser that has never run anything, any `runner.performAction` also starts the browser itself. Evaluating a snippet does not start the desktop. `screen-not-ready` if the runner has a screen that cannot serve this instant. Retry in a second or two: the desktop restarts when a run changes the display size, and it serves one see-or-act request at a time, so a screenshot or action already in flight is the usual reason. Do not submit a run to clear this — a run may restart the display and discard what is on it. `runner-has-no-screen` if this runner is not one that runs a browser on a virtual desktop. Nothing about it can be seen or driven, and retrying will never help — launch a `playwright` runner instead. `runner-unreachable` if the runner could not be reached: it may still be starting, it may have terminated after inactivity, or it may be too busy to answer. Nothing was changed, so retrying is safe; if it persists, launch the runner again.";
             readonly input: z.ZodObject<{
                 id: z.ZodString;
             }, z.core.$strip>;
@@ -1919,17 +2074,30 @@ export declare const publicContractsV1: {
             readonly name: "runner.takeScreenshot";
             readonly output: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 imageJpegBase64: z.ZodString;
-                outcome: z.ZodLiteral<"captured">;
-            }, z.core.$strip>, z.ZodObject<{
-                outcome: z.ZodLiteral<"screen-needs-a-run">;
-            }, z.core.$strip>, z.ZodObject<{
-                outcome: z.ZodLiteral<"screen-not-ready">;
+                outcome: z.ZodLiteral<"success">;
             }, z.core.$strip>, z.ZodObject<{
-                outcome: z.ZodLiteral<"runner-has-no-screen">;
-            }, z.core.$strip>, z.ZodObject<{
-                outcome: z.ZodLiteral<"runner-unreachable">;
+                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>], "outcome">;
         };
+        terminate: {
+            readonly 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.";
+            readonly input: z.ZodObject<{
+                id: z.ZodString;
+            }, z.core.$strip>;
+            readonly kind: "write";
+            readonly name: "runner.terminate";
+            readonly output: z.ZodObject<{
+                id: z.ZodString;
+                outcome: z.ZodLiteral<"success">;
+                wasRunning: z.ZodBoolean;
+            }, z.core.$strip>;
+        };
     };
     tag: {
         create: {