@qawolf/api-contracts 0.20.0 → 0.24.0

package/dist/v1/index.d.ts

@@ -3,6 +3,13 @@ export type { AnyPublicApiContract, PublicApiContract, PublicApiContractKind, }
 export { type IdentityResponse, identityResponse } from "./identity/index.js";
 export { type PublicIdSchema, type PublicIdSchemas, defaultIdSchemas, } from "./ids.js";
 export { makeFlowSelectionSchema } from "./run/index.js";
+export { type BrowserAction, browserActionSchema, } from "./runner/browserAction.js";
+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 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";
 import type { AnyPublicApiContract } from "./definition.js";
 import { type PublicIdSchema, type PublicIdSchemasOf } from "./ids.js";
 export type PublicApiInput<Api extends AnyPublicApiContract> = z.input<Api["input"]>;
@@ -14,9 +21,9 @@ export type PublicApiOutput<Api extends AnyPublicApiContract> = z.infer<Api["out
  * the same factory with its own strict id schemas, so the contract shape can
  * never drift between the two while validation strictness stays server-owned.
  */
-export declare const makeContractsV1: <EnvironmentId extends PublicIdSchema, FlowId extends PublicIdSchema, RunId extends PublicIdSchema, AutomationId extends PublicIdSchema = PublicIdSchema, IssueId extends PublicIdSchema = PublicIdSchema, WorkspaceId extends PublicIdSchema = PublicIdSchema>(ids: PublicIdSchemasOf<EnvironmentId, FlowId, RunId, AutomationId, IssueId, WorkspaceId>) => {
+export declare const makeContractsV1: <EnvironmentId extends PublicIdSchema, FlowId extends PublicIdSchema, RunId extends PublicIdSchema, AutomationId extends PublicIdSchema = PublicIdSchema, IssueId extends PublicIdSchema = PublicIdSchema, WorkspaceId extends PublicIdSchema = PublicIdSchema, AiTaskId extends PublicIdSchema = PublicIdSchema>(ids: PublicIdSchemasOf<EnvironmentId, FlowId, RunId, AutomationId, IssueId, WorkspaceId, AiTaskId>) => {
     automate: {
-        readonly description: "Request an automation that builds the selected draft flows in an environment.";
+        readonly description: "Request automation for draft flows. First create a named local .flow.ts draft for every requested journey that does not already have a matching draft; never reuse a generic starter or placeholder. Each new draft must start with a JSDoc Goal: description, import flow from @qawolf/flows/web, and use export default flow(...); a comment-only file or direct test(...) call is not a valid draft. Commit and push all changes with Git to publish them, then list remote drafts to resolve every selected ID. Do not use patch to create or rename a selected flow. Finally make one automation request containing all requested flow IDs.";
         readonly input: z.ZodObject<{
             environmentId: PublicIdSchema;
             flowIds: z.ZodArray<FlowId>;
@@ -54,6 +61,7 @@ export declare const makeContractsV1: <EnvironmentId extends PublicIdSchema, Flo
                     preview: "preview";
                 }>;
                 name: z.ZodString;
+                runConcurrencyLimit: z.ZodString;
                 status: z.ZodEnum<{
                     blocked: "blocked";
                     "needs-investigation": "needs-investigation";
@@ -106,6 +114,7 @@ export declare const makeContractsV1: <EnvironmentId extends PublicIdSchema, Flo
                         preview: "preview";
                     }>;
                     name: z.ZodString;
+                    runConcurrencyLimit: z.ZodString;
                     status: z.ZodEnum<{
                         blocked: "blocked";
                         "needs-investigation": "needs-investigation";
@@ -119,7 +128,7 @@ export declare const makeContractsV1: <EnvironmentId extends PublicIdSchema, Flo
             }, z.core.$strip>;
         };
         get: {
-            readonly description: "Read a single environment's name, kind, health status, and termination state.";
+            readonly description: "Read a single environment's name, kind, health status, run concurrency limit, and termination state.";
             readonly input: z.ZodObject<{
                 environmentId: PublicIdSchema;
             }, z.core.$strip>;
@@ -141,6 +150,7 @@ export declare const makeContractsV1: <EnvironmentId extends PublicIdSchema, Flo
                     preview: "preview";
                 }>;
                 name: z.ZodString;
+                runConcurrencyLimit: z.ZodString;
                 status: z.ZodEnum<{
                     blocked: "blocked";
                     "needs-investigation": "needs-investigation";
@@ -151,6 +161,22 @@ export declare const makeContractsV1: <EnvironmentId extends PublicIdSchema, Flo
                 url: z.ZodURL;
             }, z.core.$strip>;
         };
+        getVariable: {
+            readonly description: "Read the values of named environment variables in one call. Values are secrets. Names that do not exist go to missingNames and do not fail the call.";
+            readonly input: z.ZodObject<{
+                environmentId: PublicIdSchema;
+                variableNames: z.ZodArray<z.ZodString>;
+            }, z.core.$strip>;
+            readonly kind: "read";
+            readonly name: "environment.getVariable";
+            readonly output: z.ZodObject<{
+                missingNames: z.ZodArray<z.ZodString>;
+                variables: z.ZodArray<z.ZodObject<{
+                    name: z.ZodString;
+                    value: z.ZodString;
+                }, z.core.$strip>>;
+            }, z.core.$strip>;
+        };
         listVariableNames: {
             readonly description: "Use this to answer which QA Wolf environment variables are available to test code. Returns names only; values never leave the server.";
             readonly input: z.ZodObject<{
@@ -175,6 +201,42 @@ export declare const makeContractsV1: <EnvironmentId extends PublicIdSchema, Flo
                 name: z.ZodString;
             }, z.core.$strip>;
         };
+        update: {
+            readonly description: "Update an environment owned by the caller's team and return it in the environment.get shape. Omitted fields remain unchanged.";
+            readonly input: z.ZodObject<{
+                environmentId: PublicIdSchema;
+                name: z.ZodOptional<z.ZodString>;
+                runConcurrencyLimit: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>;
+            readonly kind: "write";
+            readonly name: "environment.update";
+            readonly output: z.ZodObject<{
+                alias: z.ZodOptional<z.ZodString>;
+                flowCodeBranch: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    lastSyncedCommitHash: z.ZodString;
+                    name: z.ZodString;
+                    syncStatus: z.ZodLiteral<"reconciled">;
+                }, z.core.$strip>, z.ZodObject<{
+                    name: z.ZodString;
+                    syncStatus: z.ZodLiteral<"not-reconciled">;
+                }, z.core.$strip>], "syncStatus">>;
+                id: EnvironmentId;
+                kind: z.ZodEnum<{
+                    static: "static";
+                    preview: "preview";
+                }>;
+                name: z.ZodString;
+                runConcurrencyLimit: z.ZodString;
+                status: z.ZodEnum<{
+                    blocked: "blocked";
+                    "needs-investigation": "needs-investigation";
+                    ready: "ready";
+                    running: "running";
+                }>;
+                terminatedAt: z.ZodOptional<z.ZodISODateTime>;
+                url: z.ZodURL;
+            }, z.core.$strip>;
+        };
     };
     flow: {
         addTag: {
@@ -205,11 +267,38 @@ export declare const makeContractsV1: <EnvironmentId extends PublicIdSchema, Flo
                     flowId: FlowId;
                     name: z.ZodString;
                     path: z.ZodString;
+                    readiness: z.ZodEnum<{
+                        draft: "draft";
+                        active: "active";
+                    }>;
                     tags: z.ZodArray<z.ZodString>;
                     url: z.ZodURL;
                 }, z.core.$strip>>;
             }, z.core.$strip>;
         };
+        update: {
+            readonly description: "Move a flow between draft and active readiness. The other statuses shown in the app are derived and cannot be set.";
+            readonly input: z.ZodObject<{
+                flowId: FlowId;
+                readiness: z.ZodEnum<{
+                    draft: "draft";
+                    active: "active";
+                }>;
+            }, z.core.$strip>;
+            readonly kind: "write";
+            readonly name: "flow.update";
+            readonly output: z.ZodObject<{
+                flow: z.ZodObject<{
+                    flowId: FlowId;
+                    name: z.ZodString;
+                    readiness: z.ZodEnum<{
+                        draft: "draft";
+                        active: "active";
+                    }>;
+                    url: z.ZodURL;
+                }, z.core.$strip>;
+            }, z.core.$strip>;
+        };
     };
     issue: {
         create: {
@@ -453,6 +542,7 @@ export declare const makeContractsV1: <EnvironmentId extends PublicIdSchema, Flo
         create: {
             readonly description: "Create a run for the selected flows and/or tags in an environment.";
             readonly input: z.ZodIntersection<z.ZodObject<{
+                aiTaskId: z.ZodOptional<AiTaskId>;
                 environmentId: PublicIdSchema;
                 environmentVariables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 ignoreRules: z.ZodDefault<z.ZodBoolean>;
@@ -527,6 +617,7 @@ export declare const makeContractsV1: <EnvironmentId extends PublicIdSchema, Flo
                         passed: "passed";
                     }>;
                 }, z.core.$strip>], "status">>;
+                runId: RunId;
                 completedAt: z.ZodOptional<z.ZodISODateTime>;
                 createdAt: z.ZodISODateTime;
                 git: z.ZodObject<{
@@ -535,7 +626,6 @@ export declare const makeContractsV1: <EnvironmentId extends PublicIdSchema, Flo
                     commitSha: z.ZodOptional<z.ZodString>;
                     commitUrl: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>;
-                runId: RunId;
                 status: z.ZodEnum<{
                     running: "running";
                     canceled: "canceled";
@@ -547,6 +637,210 @@ export declare const makeContractsV1: <EnvironmentId extends PublicIdSchema, Flo
             }, z.core.$strip>;
         };
     };
+    runner: {
+        evaluateSnippet: {
+            readonly description: "Evaluate a snippet against whatever the runner's browser is showing right now. Answers whether the snippet ran, and its error if it threw — not the value it evaluated to, so read anything you want back out of the runner's journal (a snippet's `console.log` lands in the `console` stream). A snippet starts no run and leaves no run-scoped journal entries of its own. `runner-unreachable` if the runner could not be reached or could not evaluate: as well as a runner that is still starting, has terminated after inactivity, or is busy, this covers a runner with no live page to evaluate against — which will never clear, so check that the runner you launched is one that runs a browser before retrying. It is NOT proof the snippet did not run: a snippet that outlives the answer window is still executing when you read this, so do not blindly resubmit one that mutates what the page is looking at.";
+            readonly input: z.ZodObject<{
+                code: z.ZodString;
+                filePath: z.ZodOptional<z.ZodString>;
+                files: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                id: z.ZodString;
+            }, z.core.$strip>;
+            readonly kind: "write";
+            readonly name: "runner.evaluateSnippet";
+            readonly output: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                errorMessage: z.ZodOptional<z.ZodString>;
+                outcome: z.ZodLiteral<"evaluated">;
+                result: z.ZodEnum<{
+                    success: "success";
+                    error: "error";
+                    stopped: "stopped";
+                }>;
+            }, z.core.$strip>, z.ZodObject<{
+                outcome: z.ZodLiteral<"runner-unreachable">;
+            }, 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 input: z.ZodObject<{
+                id: z.ZodString;
+                runnerName: z.ZodOptional<z.ZodEnum<{
+                    node20Basic: "node20Basic";
+                    node20WithAndroid: "node20WithAndroid";
+                    node20WithIos: "node20WithIos";
+                    node20WithPlaywright: "node20WithPlaywright";
+                }>>;
+            }, z.core.$strip>;
+            readonly kind: "write";
+            readonly name: "runner.launch";
+            readonly output: z.ZodObject<{
+                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";
+                }>;
+            }, 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. `screen-needs-a-run` if the runner has not run anything yet, so its virtual desktop has never started. Waiting will not change this and retrying is pointless — call `runner.runFlow` on the runner, then ask for the screen again. Evaluating a snippet does not start the desktop. `screen-not-ready` if the runner has a screen that cannot serve this instant. Retry in a second or two: the desktop restarts when a run changes the display size, and it serves one see-or-act request at a time, so a screenshot or action already in flight is the usual reason. Do not submit a run to clear this — a run may restart the display and discard what is on it. A `navigate` does not go through the screen, so a screen that is not ready does not stop it — but it still needs the runner to have run something, and until then it answers `action-failed` rather than `screen-needs-a-run`. `runner-has-no-screen` if this runner is not one that runs a browser on a virtual desktop. Nothing about it can be seen or driven, and retrying will never help — launch a `node20WithPlaywright` runner instead. `runner-unreachable` if the runner could not be reached: it may still be starting, it may have terminated after inactivity, or it may have stopped answering mid-action. This does not mean the action was not performed — take a screenshot before repeating it.";
+            readonly input: z.ZodObject<{
+                action: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    button: z.ZodLiteral<"left" | "right" | "wheel" | "back" | "forward">;
+                    type: z.ZodLiteral<"click">;
+                    x: z.ZodInt;
+                    y: z.ZodInt;
+                }, z.core.$strict>, z.ZodObject<{
+                    type: z.ZodLiteral<"double_click">;
+                    x: z.ZodInt;
+                    y: z.ZodInt;
+                }, z.core.$strict>, z.ZodObject<{
+                    scroll_x: z.ZodInt;
+                    scroll_y: z.ZodInt;
+                    type: z.ZodLiteral<"scroll">;
+                    x: z.ZodInt;
+                    y: z.ZodInt;
+                }, z.core.$strict>, z.ZodObject<{
+                    type: z.ZodLiteral<"move">;
+                    x: z.ZodInt;
+                    y: z.ZodInt;
+                }, z.core.$strict>, z.ZodObject<{
+                    path: z.ZodArray<z.ZodObject<{
+                        x: z.ZodInt;
+                        y: z.ZodInt;
+                    }, z.core.$strict>>;
+                    type: z.ZodLiteral<"drag">;
+                }, z.core.$strict>, z.ZodObject<{
+                    keys: z.ZodArray<z.ZodString>;
+                    type: z.ZodLiteral<"keypress">;
+                }, z.core.$strict>, z.ZodObject<{
+                    type: z.ZodLiteral<"navigate">;
+                    url: z.ZodURL;
+                }, z.core.$strict>, z.ZodObject<{
+                    text: z.ZodString;
+                    type: z.ZodLiteral<"type">;
+                }, z.core.$strict>], "type">;
+                id: z.ZodString;
+            }, z.core.$strip>;
+            readonly kind: "write";
+            readonly name: "runner.performAction";
+            readonly output: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                outcome: z.ZodLiteral<"performed">;
+            }, z.core.$strip>, z.ZodObject<{
+                errorMessage: z.ZodString;
+                outcome: z.ZodLiteral<"action-failed">;
+            }, z.core.$strip>, z.ZodObject<{
+                outcome: z.ZodLiteral<"screen-needs-a-run">;
+            }, z.core.$strip>, z.ZodObject<{
+                outcome: z.ZodLiteral<"screen-not-ready">;
+            }, z.core.$strip>, z.ZodObject<{
+                outcome: z.ZodLiteral<"runner-has-no-screen">;
+            }, z.core.$strip>, z.ZodObject<{
+                outcome: z.ZodLiteral<"runner-unreachable">;
+            }, z.core.$strip>], "outcome">;
+        };
+        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<{
+                runId: z.ZodOptional<z.ZodString>;
+                sinceSequence: z.ZodOptional<z.ZodNumber>;
+                tail: z.ZodOptional<z.ZodNumber>;
+                id: z.ZodString;
+                stream: z.ZodString;
+            }, z.core.$strip>;
+            readonly kind: "read";
+            readonly name: "runner.readJournal";
+            readonly output: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                entries: z.ZodArray<z.ZodPipe<z.ZodObject<{
+                    payload: z.ZodUnknown;
+                    recordedAt: z.ZodISODateTime;
+                    sequence: z.ZodNumber;
+                }, z.core.$strip>, z.ZodTransform<import("./runner/journal.js").JournalEntry<unknown>, {
+                    payload: unknown;
+                    recordedAt: string;
+                    sequence: number;
+                }>>>;
+                hasUnsearchedHistory: z.ZodBoolean;
+                nextSequence: z.ZodNumber;
+                oldestAvailableSequence: z.ZodNumber;
+                outcome: z.ZodLiteral<"read">;
+            }, z.core.$strip>, z.ZodObject<{
+                outcome: z.ZodLiteral<"runner-unreachable">;
+            }, 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 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;
+            }, z.core.$strip>;
+            readonly kind: "write";
+            readonly name: "runner.runFlow";
+            readonly output: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                outcome: z.ZodLiteral<"submitted">;
+                runId: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                outcome: z.ZodLiteral<"runner-unreachable">;
+            }, z.core.$strip>, z.ZodObject<{
+                outcome: z.ZodLiteral<"runner-target-mismatch">;
+                requiredRunnerName: z.ZodEnum<{
+                    node20Basic: "node20Basic";
+                    node20WithAndroid: "node20WithAndroid";
+                    node20WithIos: "node20WithIos";
+                    node20WithPlaywright: "node20WithPlaywright";
+                }>;
+                runnerName: z.ZodEnum<{
+                    node20Basic: "node20Basic";
+                    node20WithAndroid: "node20WithAndroid";
+                    node20WithIos: "node20WithIos";
+                    node20WithPlaywright: "node20WithPlaywright";
+                }>;
+            }, z.core.$strip>], "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.";
+            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";
+                }>;
+            }, z.core.$strip>;
+        };
+        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 has not run anything yet, so its virtual desktop has never started. Waiting will not change this and retrying is pointless — call `runner.runFlow` on the runner, then ask for the screen again. Evaluating a snippet does not start the desktop. `screen-not-ready` if the runner has a screen that cannot serve this instant. Retry in a second or two: the desktop restarts when a run changes the display size, and it serves one see-or-act request at a time, so a screenshot or action already in flight is the usual reason. Do not submit a run to clear this — a run may restart the display and discard what is on it. `runner-has-no-screen` if this runner is not one that runs a browser on a virtual desktop. Nothing about it can be seen or driven, and retrying will never help — launch a `node20WithPlaywright` runner instead. `runner-unreachable` if the runner could not be reached: it may still be starting, it may have terminated after inactivity, or it may be too busy to answer. Nothing was changed, so retrying is safe; if it persists, launch the runner again.";
+            readonly input: z.ZodObject<{
+                id: z.ZodString;
+            }, z.core.$strip>;
+            readonly kind: "read";
+            readonly name: "runner.takeScreenshot";
+            readonly output: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                imageJpegBase64: z.ZodString;
+                outcome: z.ZodLiteral<"captured">;
+            }, z.core.$strip>, z.ZodObject<{
+                outcome: z.ZodLiteral<"screen-needs-a-run">;
+            }, z.core.$strip>, z.ZodObject<{
+                outcome: z.ZodLiteral<"screen-not-ready">;
+            }, z.core.$strip>, z.ZodObject<{
+                outcome: z.ZodLiteral<"runner-has-no-screen">;
+            }, z.core.$strip>, z.ZodObject<{
+                outcome: z.ZodLiteral<"runner-unreachable">;
+            }, z.core.$strip>], "outcome">;
+        };
+    };
     tag: {
         create: {
             readonly description: "Create a tag on the caller's team. Tags select flows in run.create.";
@@ -585,7 +879,7 @@ export declare const makeContractsV1: <EnvironmentId extends PublicIdSchema, Flo
 };
 export declare const publicContractsV1: {
     automate: {
-        readonly description: "Request an automation that builds the selected draft flows in an environment.";
+        readonly description: "Request automation for draft flows. First create a named local .flow.ts draft for every requested journey that does not already have a matching draft; never reuse a generic starter or placeholder. Each new draft must start with a JSDoc Goal: description, import flow from @qawolf/flows/web, and use export default flow(...); a comment-only file or direct test(...) call is not a valid draft. Commit and push all changes with Git to publish them, then list remote drafts to resolve every selected ID. Do not use patch to create or rename a selected flow. Finally make one automation request containing all requested flow IDs.";
         readonly input: z.ZodObject<{
             environmentId: PublicIdSchema;
             flowIds: z.ZodArray<PublicIdSchema>;
@@ -623,6 +917,7 @@ export declare const publicContractsV1: {
                     preview: "preview";
                 }>;
                 name: z.ZodString;
+                runConcurrencyLimit: z.ZodString;
                 status: z.ZodEnum<{
                     blocked: "blocked";
                     "needs-investigation": "needs-investigation";
@@ -675,6 +970,7 @@ export declare const publicContractsV1: {
                         preview: "preview";
                     }>;
                     name: z.ZodString;
+                    runConcurrencyLimit: z.ZodString;
                     status: z.ZodEnum<{
                         blocked: "blocked";
                         "needs-investigation": "needs-investigation";
@@ -688,7 +984,7 @@ export declare const publicContractsV1: {
             }, z.core.$strip>;
         };
         get: {
-            readonly description: "Read a single environment's name, kind, health status, and termination state.";
+            readonly description: "Read a single environment's name, kind, health status, run concurrency limit, and termination state.";
             readonly input: z.ZodObject<{
                 environmentId: PublicIdSchema;
             }, z.core.$strip>;
@@ -710,6 +1006,7 @@ export declare const publicContractsV1: {
                     preview: "preview";
                 }>;
                 name: z.ZodString;
+                runConcurrencyLimit: z.ZodString;
                 status: z.ZodEnum<{
                     blocked: "blocked";
                     "needs-investigation": "needs-investigation";
@@ -720,6 +1017,22 @@ export declare const publicContractsV1: {
                 url: z.ZodURL;
             }, z.core.$strip>;
         };
+        getVariable: {
+            readonly description: "Read the values of named environment variables in one call. Values are secrets. Names that do not exist go to missingNames and do not fail the call.";
+            readonly input: z.ZodObject<{
+                environmentId: PublicIdSchema;
+                variableNames: z.ZodArray<z.ZodString>;
+            }, z.core.$strip>;
+            readonly kind: "read";
+            readonly name: "environment.getVariable";
+            readonly output: z.ZodObject<{
+                missingNames: z.ZodArray<z.ZodString>;
+                variables: z.ZodArray<z.ZodObject<{
+                    name: z.ZodString;
+                    value: z.ZodString;
+                }, z.core.$strip>>;
+            }, z.core.$strip>;
+        };
         listVariableNames: {
             readonly description: "Use this to answer which QA Wolf environment variables are available to test code. Returns names only; values never leave the server.";
             readonly input: z.ZodObject<{
@@ -744,6 +1057,42 @@ export declare const publicContractsV1: {
                 name: z.ZodString;
             }, z.core.$strip>;
         };
+        update: {
+            readonly description: "Update an environment owned by the caller's team and return it in the environment.get shape. Omitted fields remain unchanged.";
+            readonly input: z.ZodObject<{
+                environmentId: PublicIdSchema;
+                name: z.ZodOptional<z.ZodString>;
+                runConcurrencyLimit: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>;
+            readonly kind: "write";
+            readonly name: "environment.update";
+            readonly output: z.ZodObject<{
+                alias: z.ZodOptional<z.ZodString>;
+                flowCodeBranch: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    lastSyncedCommitHash: z.ZodString;
+                    name: z.ZodString;
+                    syncStatus: z.ZodLiteral<"reconciled">;
+                }, z.core.$strip>, z.ZodObject<{
+                    name: z.ZodString;
+                    syncStatus: z.ZodLiteral<"not-reconciled">;
+                }, z.core.$strip>], "syncStatus">>;
+                id: PublicIdSchema;
+                kind: z.ZodEnum<{
+                    static: "static";
+                    preview: "preview";
+                }>;
+                name: z.ZodString;
+                runConcurrencyLimit: z.ZodString;
+                status: z.ZodEnum<{
+                    blocked: "blocked";
+                    "needs-investigation": "needs-investigation";
+                    ready: "ready";
+                    running: "running";
+                }>;
+                terminatedAt: z.ZodOptional<z.ZodISODateTime>;
+                url: z.ZodURL;
+            }, z.core.$strip>;
+        };
     };
     flow: {
         addTag: {
@@ -774,11 +1123,38 @@ export declare const publicContractsV1: {
                     flowId: PublicIdSchema;
                     name: z.ZodString;
                     path: z.ZodString;
+                    readiness: z.ZodEnum<{
+                        draft: "draft";
+                        active: "active";
+                    }>;
                     tags: z.ZodArray<z.ZodString>;
                     url: z.ZodURL;
                 }, z.core.$strip>>;
             }, z.core.$strip>;
         };
+        update: {
+            readonly description: "Move a flow between draft and active readiness. The other statuses shown in the app are derived and cannot be set.";
+            readonly input: z.ZodObject<{
+                flowId: PublicIdSchema;
+                readiness: z.ZodEnum<{
+                    draft: "draft";
+                    active: "active";
+                }>;
+            }, z.core.$strip>;
+            readonly kind: "write";
+            readonly name: "flow.update";
+            readonly output: z.ZodObject<{
+                flow: z.ZodObject<{
+                    flowId: PublicIdSchema;
+                    name: z.ZodString;
+                    readiness: z.ZodEnum<{
+                        draft: "draft";
+                        active: "active";
+                    }>;
+                    url: z.ZodURL;
+                }, z.core.$strip>;
+            }, z.core.$strip>;
+        };
     };
     issue: {
         create: {
@@ -1022,6 +1398,7 @@ export declare const publicContractsV1: {
         create: {
             readonly description: "Create a run for the selected flows and/or tags in an environment.";
             readonly input: z.ZodIntersection<z.ZodObject<{
+                aiTaskId: z.ZodOptional<PublicIdSchema>;
                 environmentId: PublicIdSchema;
                 environmentVariables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 ignoreRules: z.ZodDefault<z.ZodBoolean>;
@@ -1096,6 +1473,7 @@ export declare const publicContractsV1: {
                         passed: "passed";
                     }>;
                 }, z.core.$strip>], "status">>;
+                runId: PublicIdSchema;
                 completedAt: z.ZodOptional<z.ZodISODateTime>;
                 createdAt: z.ZodISODateTime;
                 git: z.ZodObject<{
@@ -1104,7 +1482,6 @@ export declare const publicContractsV1: {
                     commitSha: z.ZodOptional<z.ZodString>;
                     commitUrl: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>;
-                runId: PublicIdSchema;
                 status: z.ZodEnum<{
                     running: "running";
                     canceled: "canceled";
@@ -1116,6 +1493,210 @@ export declare const publicContractsV1: {
             }, z.core.$strip>;
         };
     };
+    runner: {
+        evaluateSnippet: {
+            readonly description: "Evaluate a snippet against whatever the runner's browser is showing right now. Answers whether the snippet ran, and its error if it threw — not the value it evaluated to, so read anything you want back out of the runner's journal (a snippet's `console.log` lands in the `console` stream). A snippet starts no run and leaves no run-scoped journal entries of its own. `runner-unreachable` if the runner could not be reached or could not evaluate: as well as a runner that is still starting, has terminated after inactivity, or is busy, this covers a runner with no live page to evaluate against — which will never clear, so check that the runner you launched is one that runs a browser before retrying. It is NOT proof the snippet did not run: a snippet that outlives the answer window is still executing when you read this, so do not blindly resubmit one that mutates what the page is looking at.";
+            readonly input: z.ZodObject<{
+                code: z.ZodString;
+                filePath: z.ZodOptional<z.ZodString>;
+                files: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                id: z.ZodString;
+            }, z.core.$strip>;
+            readonly kind: "write";
+            readonly name: "runner.evaluateSnippet";
+            readonly output: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                errorMessage: z.ZodOptional<z.ZodString>;
+                outcome: z.ZodLiteral<"evaluated">;
+                result: z.ZodEnum<{
+                    success: "success";
+                    error: "error";
+                    stopped: "stopped";
+                }>;
+            }, z.core.$strip>, z.ZodObject<{
+                outcome: z.ZodLiteral<"runner-unreachable">;
+            }, 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 input: z.ZodObject<{
+                id: z.ZodString;
+                runnerName: z.ZodOptional<z.ZodEnum<{
+                    node20Basic: "node20Basic";
+                    node20WithAndroid: "node20WithAndroid";
+                    node20WithIos: "node20WithIos";
+                    node20WithPlaywright: "node20WithPlaywright";
+                }>>;
+            }, z.core.$strip>;
+            readonly kind: "write";
+            readonly name: "runner.launch";
+            readonly output: z.ZodObject<{
+                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";
+                }>;
+            }, 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. `screen-needs-a-run` if the runner has not run anything yet, so its virtual desktop has never started. Waiting will not change this and retrying is pointless — call `runner.runFlow` on the runner, then ask for the screen again. Evaluating a snippet does not start the desktop. `screen-not-ready` if the runner has a screen that cannot serve this instant. Retry in a second or two: the desktop restarts when a run changes the display size, and it serves one see-or-act request at a time, so a screenshot or action already in flight is the usual reason. Do not submit a run to clear this — a run may restart the display and discard what is on it. A `navigate` does not go through the screen, so a screen that is not ready does not stop it — but it still needs the runner to have run something, and until then it answers `action-failed` rather than `screen-needs-a-run`. `runner-has-no-screen` if this runner is not one that runs a browser on a virtual desktop. Nothing about it can be seen or driven, and retrying will never help — launch a `node20WithPlaywright` runner instead. `runner-unreachable` if the runner could not be reached: it may still be starting, it may have terminated after inactivity, or it may have stopped answering mid-action. This does not mean the action was not performed — take a screenshot before repeating it.";
+            readonly input: z.ZodObject<{
+                action: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    button: z.ZodLiteral<"left" | "right" | "wheel" | "back" | "forward">;
+                    type: z.ZodLiteral<"click">;
+                    x: z.ZodInt;
+                    y: z.ZodInt;
+                }, z.core.$strict>, z.ZodObject<{
+                    type: z.ZodLiteral<"double_click">;
+                    x: z.ZodInt;
+                    y: z.ZodInt;
+                }, z.core.$strict>, z.ZodObject<{
+                    scroll_x: z.ZodInt;
+                    scroll_y: z.ZodInt;
+                    type: z.ZodLiteral<"scroll">;
+                    x: z.ZodInt;
+                    y: z.ZodInt;
+                }, z.core.$strict>, z.ZodObject<{
+                    type: z.ZodLiteral<"move">;
+                    x: z.ZodInt;
+                    y: z.ZodInt;
+                }, z.core.$strict>, z.ZodObject<{
+                    path: z.ZodArray<z.ZodObject<{
+                        x: z.ZodInt;
+                        y: z.ZodInt;
+                    }, z.core.$strict>>;
+                    type: z.ZodLiteral<"drag">;
+                }, z.core.$strict>, z.ZodObject<{
+                    keys: z.ZodArray<z.ZodString>;
+                    type: z.ZodLiteral<"keypress">;
+                }, z.core.$strict>, z.ZodObject<{
+                    type: z.ZodLiteral<"navigate">;
+                    url: z.ZodURL;
+                }, z.core.$strict>, z.ZodObject<{
+                    text: z.ZodString;
+                    type: z.ZodLiteral<"type">;
+                }, z.core.$strict>], "type">;
+                id: z.ZodString;
+            }, z.core.$strip>;
+            readonly kind: "write";
+            readonly name: "runner.performAction";
+            readonly output: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                outcome: z.ZodLiteral<"performed">;
+            }, z.core.$strip>, z.ZodObject<{
+                errorMessage: z.ZodString;
+                outcome: z.ZodLiteral<"action-failed">;
+            }, z.core.$strip>, z.ZodObject<{
+                outcome: z.ZodLiteral<"screen-needs-a-run">;
+            }, z.core.$strip>, z.ZodObject<{
+                outcome: z.ZodLiteral<"screen-not-ready">;
+            }, z.core.$strip>, z.ZodObject<{
+                outcome: z.ZodLiteral<"runner-has-no-screen">;
+            }, z.core.$strip>, z.ZodObject<{
+                outcome: z.ZodLiteral<"runner-unreachable">;
+            }, z.core.$strip>], "outcome">;
+        };
+        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<{
+                runId: z.ZodOptional<z.ZodString>;
+                sinceSequence: z.ZodOptional<z.ZodNumber>;
+                tail: z.ZodOptional<z.ZodNumber>;
+                id: z.ZodString;
+                stream: z.ZodString;
+            }, z.core.$strip>;
+            readonly kind: "read";
+            readonly name: "runner.readJournal";
+            readonly output: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                entries: z.ZodArray<z.ZodPipe<z.ZodObject<{
+                    payload: z.ZodUnknown;
+                    recordedAt: z.ZodISODateTime;
+                    sequence: z.ZodNumber;
+                }, z.core.$strip>, z.ZodTransform<import("./runner/journal.js").JournalEntry<unknown>, {
+                    payload: unknown;
+                    recordedAt: string;
+                    sequence: number;
+                }>>>;
+                hasUnsearchedHistory: z.ZodBoolean;
+                nextSequence: z.ZodNumber;
+                oldestAvailableSequence: z.ZodNumber;
+                outcome: z.ZodLiteral<"read">;
+            }, z.core.$strip>, z.ZodObject<{
+                outcome: z.ZodLiteral<"runner-unreachable">;
+            }, 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 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;
+            }, z.core.$strip>;
+            readonly kind: "write";
+            readonly name: "runner.runFlow";
+            readonly output: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                outcome: z.ZodLiteral<"submitted">;
+                runId: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                outcome: z.ZodLiteral<"runner-unreachable">;
+            }, z.core.$strip>, z.ZodObject<{
+                outcome: z.ZodLiteral<"runner-target-mismatch">;
+                requiredRunnerName: z.ZodEnum<{
+                    node20Basic: "node20Basic";
+                    node20WithAndroid: "node20WithAndroid";
+                    node20WithIos: "node20WithIos";
+                    node20WithPlaywright: "node20WithPlaywright";
+                }>;
+                runnerName: z.ZodEnum<{
+                    node20Basic: "node20Basic";
+                    node20WithAndroid: "node20WithAndroid";
+                    node20WithIos: "node20WithIos";
+                    node20WithPlaywright: "node20WithPlaywright";
+                }>;
+            }, z.core.$strip>], "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.";
+            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";
+                }>;
+            }, z.core.$strip>;
+        };
+        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 has not run anything yet, so its virtual desktop has never started. Waiting will not change this and retrying is pointless — call `runner.runFlow` on the runner, then ask for the screen again. Evaluating a snippet does not start the desktop. `screen-not-ready` if the runner has a screen that cannot serve this instant. Retry in a second or two: the desktop restarts when a run changes the display size, and it serves one see-or-act request at a time, so a screenshot or action already in flight is the usual reason. Do not submit a run to clear this — a run may restart the display and discard what is on it. `runner-has-no-screen` if this runner is not one that runs a browser on a virtual desktop. Nothing about it can be seen or driven, and retrying will never help — launch a `node20WithPlaywright` runner instead. `runner-unreachable` if the runner could not be reached: it may still be starting, it may have terminated after inactivity, or it may be too busy to answer. Nothing was changed, so retrying is safe; if it persists, launch the runner again.";
+            readonly input: z.ZodObject<{
+                id: z.ZodString;
+            }, z.core.$strip>;
+            readonly kind: "read";
+            readonly name: "runner.takeScreenshot";
+            readonly output: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                imageJpegBase64: z.ZodString;
+                outcome: z.ZodLiteral<"captured">;
+            }, z.core.$strip>, z.ZodObject<{
+                outcome: z.ZodLiteral<"screen-needs-a-run">;
+            }, z.core.$strip>, z.ZodObject<{
+                outcome: z.ZodLiteral<"screen-not-ready">;
+            }, z.core.$strip>, z.ZodObject<{
+                outcome: z.ZodLiteral<"runner-has-no-screen">;
+            }, z.core.$strip>, z.ZodObject<{
+                outcome: z.ZodLiteral<"runner-unreachable">;
+            }, z.core.$strip>], "outcome">;
+        };
+    };
     tag: {
         create: {
             readonly description: "Create a tag on the caller's team. Tags select flows in run.create.";