@qawolf/cli 1.33.0 → 1.34.0

package/README.md

@@ -113,7 +113,31 @@ const submitted = await runner.run({
 if (submitted.ok) console.log(submitted.value.runId, submitted.value.fileSync);
 ```
 
-`ok: false` is a transport or auth failure. A runner that refused the request comes back as `ok: true` with `value.outcome === "failure"` and a `failureReason` from the published contract, so a caller can switch on it exhaustively.
+`ok: false` reports a request failure, including transport, auth, or local validation. A runner that refused the request comes back as `ok: true` with an outcome and `failureReason` from the published contract, so a caller can switch on it exhaustively. Most verbs expose `value.outcome`; recording controls expose `value.result.outcome` and a history `value.url`.
+
+Control video recording on a Playwright runner after a flow has started its screen:
+
+```ts
+const recordingId = crypto.randomUUID();
+const recording = await runner.record({
+  runnerId: "agent-1",
+  command: { action: "start", recordingId },
+});
+if (recording.ok && recording.value.result.outcome === "success") {
+  // Drive the browser, then stop this specific capture.
+  await runner.record({
+    runnerId: "agent-1",
+    command: { action: "stop", recordingId },
+  });
+}
+
+// History remains readable after the runner terminates.
+const history = await runner.listRecordings({ runnerId: "agent-1" });
+if (history.ok)
+  console.log(history.value.recordings, history.value.nextPageToken);
+```
+
+`record` also accepts `{ action: "status" }` and `{ action: "auto", enabled: true }` (or `false`). Keep the UUID when retrying start or stop. `listRecordings` accepts optional `recordingId` and `pageToken` filters and returns one page, with stable platform URLs and expiring video URLs. The equivalent CLI commands are `qawolf runner record start|stop|status|auto` and `qawolf runner list-recordings`; see the [runner reference](skills/qawolf-cli/references/runner.md#video-recording).
 
 ## Reference
 

package/dist/cli.js

@@ -15210,9 +15210,10 @@ function createLoggingSystem(opts) {
 }
 
 // src/core/publicApi/notFoundSubject.ts
-var runnerRoutesThatNameNoRunner = new Set([
+var runnerRoutesWithoutLivePod = new Set([
   "runner.launch",
-  "runner.list"
+  "runner.list",
+  "runner.recordings"
 ]);
 var runRoutesThatResolveOneRun = new Set([
   "run.diagnose",
@@ -15234,7 +15235,7 @@ function field(input, name) {
   return typeof value === "string" ? value : undefined;
 }
 function notFoundSubject(contractName, input) {
-  if (contractName.startsWith("runner.") && !runnerRoutesThatNameNoRunner.has(contractName)) {
+  if (contractName.startsWith("runner.") && !runnerRoutesWithoutLivePod.has(contractName)) {
     return { kind: "runner", runnerId: field(input, "id") };
   }
   if (runRoutesThatResolveOneRun.has(contractName)) {
@@ -22389,7 +22390,7 @@ function startUpdateCheck(deps) {
 // package.json
 var package_default = {
   name: "@qawolf/cli",
-  version: "1.33.0",
+  version: "1.34.0",
   description: "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   keywords: [
     "automation",
@@ -36271,6 +36272,9 @@ async function handleRunnerActions(ctx, options, deps) {
   return framesNote === undefined ? failure : { ...failure, error: appendSentence(failure.error, framesNote) };
 }
 
+// src/domains/interactiveRunner/deps.ts
+import { randomUUID as randomUUID3 } from "node:crypto";
+
 // src/shell/interactiveRunner/collectRunFiles.ts
 import { join as join53 } from "node:path";
 
@@ -36538,6 +36542,7 @@ function makeInteractiveRunnerDeps(options) {
     cwd: options.cwd,
     env: options.env,
     makeRunnerId,
+    makeRecordingId: randomUUID3,
     readFile: (path) => options.fs.readFile(path),
     readStdin: readStdin2,
     runFilesManifest: makeRunFilesManifestStore({
@@ -38415,6 +38420,207 @@ function registerRunCommand(runner, signals) {
   }, runnerDeps(ctx)))(opts, command));
 }
 
+// src/core/messages/interactiveRunner/recording.ts
+var recordingMessages = {
+  noRunnerIdForHistory: "Name the runner whose recordings to read with --runner <id> or QAWOLF_RUNNER_ID. History stays readable after the runner terminates.",
+  unsupported: "Video recording requires a Playwright runner.",
+  inProgress: "A recording is already in progress. Use runner record status to check its mode and id. Stop a manual recording by id, or wait for the run to finish an automatic recording.",
+  notFound: "That recording was not found on the runner. Use runner record status for the active recording or runner list-recordings for published history.",
+  idUsed: "That recording id has already been used. Start a new recording with a new UUID.",
+  failed: "The recording operation failed. If this was a stop, retry it with the same recording id to finish stopping or publishing it. Check runner list-recordings for its published status.",
+  failedCapture: "The recording failed. Check runner list-recordings for its published status.",
+  recordingId: (id) => `Recording id: ${id}.`
+};
+
+// src/domains/interactiveRunner/recordingOutput.ts
+function recordingFailure(reason) {
+  switch (reason) {
+    case "unsupported":
+      return {
+        error: recordingMessages.unsupported,
+        exitCode: exitCodes.invalidArgs
+      };
+    case "screen-not-ready":
+      return {
+        error: interactiveRunnerMessages.screenNotReady,
+        exitCode: exitCodes.network
+      };
+    case "recording-in-progress":
+      return {
+        error: recordingMessages.inProgress,
+        exitCode: exitCodes.invalidArgs
+      };
+    case "recording-not-found":
+      return {
+        error: recordingMessages.notFound,
+        exitCode: exitCodes.notFound
+      };
+    case "recording-id-used":
+      return {
+        error: recordingMessages.idUsed,
+        exitCode: exitCodes.invalidArgs
+      };
+    case "runner-unreachable":
+      return {
+        error: interactiveRunnerMessages.runnerUnreachable,
+        exitCode: exitCodes.network
+      };
+    case "recording-failed":
+      return {
+        error: recordingMessages.failed,
+        exitCode: exitCodes.testFailure
+      };
+  }
+}
+function formatRecordingState(answer) {
+  const { result, url } = answer;
+  if (result.outcome === "failure")
+    return recordingFailure(result.failureReason).error;
+  const { active, auto } = result.state;
+  const lines = [
+    active ? `Recording ${active.id} (${active.mode}), started ${active.startedAt}.` : "No active recording.",
+    `Automatic recording: ${auto}.`
+  ];
+  if (result.recording) {
+    lines.push(`Recording ${result.recording.id}: ${result.recording.status}.`);
+  }
+  return [...lines, url].join(`
+`);
+}
+function formatRecordings(answer) {
+  const lines = answer.recordings.map((recording) => [
+    `${recording.id} (${recording.mode}, ${recording.status})`,
+    `  ${recording.startedAt} to ${recording.endedAt}`,
+    `  ${recording.url}`,
+    ...recording.videoUrl ? [`  Video: ${recording.videoUrl}`] : []
+  ].join(`
+`));
+  if (lines.length === 0)
+    lines.push("No published recordings found.");
+  if (answer.nextPageToken !== undefined) {
+    lines.push(`Next page token (pass with --page-token): ${answer.nextPageToken}`);
+  }
+  return lines.join(`
+`);
+}
+
+// src/domains/interactiveRunner/recordingRequests.ts
+async function recordOnRunner(ctx, runner, command) {
+  const contract = publicContractsV1.runner.record;
+  const parsed = contract.input.safeParse({ id: runner.runnerId, command });
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: "Invalid recording request. Runner ids must be valid and recording ids must be UUIDs.",
+      exitCode: exitCodes.invalidArgs
+    };
+  }
+  const result = await ctx.platformClient.callPublicApi(contract, parsed.data, runnerCallOptions);
+  return result.ok ? result : { ok: false, ...runnerRequestFailure(result, runner) };
+}
+async function readRunnerRecordings(ctx, runner, query) {
+  const contract = publicContractsV1.runner.recordings;
+  const parsed = contract.input.safeParse({ id: runner.runnerId, ...query });
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: "Invalid recordings request. Use a valid runner id, a UUID recording id, and a page token of at most 4096 characters.",
+      exitCode: exitCodes.invalidArgs
+    };
+  }
+  const result = await ctx.platformClient.callPublicApi(contract, parsed.data);
+  return result.ok ? result : { ok: false, ...runnerRequestFailure(result, runner) };
+}
+
+// src/domains/interactiveRunner/recording.ts
+async function handleRunnerRecord(ctx, options, deps) {
+  const resolved = await resolveRunner(ctx, { autoLaunch: false, runner: options.runner }, deps);
+  if (resolved.type === "failed")
+    return { ...failureFields(resolved), exitCode: resolved.exitCode };
+  const command = options.command.action === "start" ? {
+    action: "start",
+    recordingId: options.command.recordingId ?? deps.makeRecordingId()
+  } : options.command;
+  const response = await recordOnRunner(ctx, resolved, command);
+  const idNote = "recordingId" in command ? recordingMessages.recordingId(command.recordingId) : undefined;
+  if (!response.ok) {
+    const fields = failureFields(response);
+    return {
+      ...fields,
+      ...idNote ? { errorBody: [fields.errorBody, idNote].filter(Boolean).join(`
+`) } : {},
+      exitCode: response.exitCode
+    };
+  }
+  const answer = response.value;
+  if (answer.result.outcome === "failure") {
+    return {
+      ...recordingFailure(answer.result.failureReason),
+      errorBody: [idNote, answer.url].filter(Boolean).join(`
+`)
+    };
+  }
+  ctx.ui.output(answer, formatRecordingState(answer));
+  if (answer.result.recording?.status === "failed") {
+    return {
+      error: recordingMessages.failedCapture,
+      exitCode: exitCodes.testFailure,
+      errorBody: [
+        recordingMessages.recordingId(answer.result.recording.id),
+        answer.url
+      ].join(`
+`)
+    };
+  }
+  return;
+}
+async function handleRunnerRecordings(ctx, options, deps) {
+  const resolved = await resolveRunner(ctx, {
+    autoLaunch: false,
+    noRunnerIdMessage: recordingMessages.noRunnerIdForHistory,
+    runner: options.runner
+  }, deps);
+  if (resolved.type === "failed")
+    return { ...failureFields(resolved), exitCode: resolved.exitCode };
+  const response = await readRunnerRecordings(ctx, resolved, {
+    ...options.recordingId === undefined ? {} : { recordingId: options.recordingId },
+    ...options.pageToken === undefined ? {} : { pageToken: options.pageToken }
+  });
+  if (!response.ok)
+    return { ...failureFields(response), exitCode: response.exitCode };
+  ctx.ui.output(response.value, formatRecordings(response.value));
+  return;
+}
+
+// src/commands/runner/recording.register.ts
+function registerRunnerRecordingCommands(runner, signals) {
+  const record = runner.command("record").description("Control video recording on a Playwright runner");
+  declareCommandKind(record.command("start"), "write").description("Start manual video capture across runs. Requires a ready screen and suppresses automatic capture until stopped").option("--recording-id <uuid>", "Recording UUID. Generated when omitted; reuse it when retrying this start").option("--runner <id>", runnerFlagDescription).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerRecord(ctx, {
+    command: { action: "start", recordingId: opts.recordingId },
+    runner: opts.runner
+  }, runnerDeps(ctx)))(opts, command));
+  declareCommandKind(record.command("stop <recording-id>"), "write").description("Stop the recording with this UUID and publish it. Retrying cannot stop a later recording").option("--runner <id>", runnerFlagDescription).action((recordingId, opts, command) => withAuthContext(signals, (ctx) => handleRunnerRecord(ctx, {
+    command: { action: "stop", recordingId },
+    runner: opts.runner
+  }, runnerDeps(ctx)))(opts, command));
+  declareCommandKind(record.command("status"), "read").description("Show the active recording and automatic recording setting").option("--runner <id>", runnerFlagDescription).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerRecord(ctx, {
+    command: { action: "status" },
+    runner: opts.runner
+  }, runnerDeps(ctx)))(opts, command));
+  declareCommandKind(record.command("auto"), "write").addArgument(new Argument2("<setting>", "Automatic recording setting").choices([
+    "on",
+    "off"
+  ])).description("Enable or disable automatic recording for subsequent full runs").option("--runner <id>", runnerFlagDescription).action((setting, opts, command) => withAuthContext(signals, (ctx) => handleRunnerRecord(ctx, {
+    command: { action: "auto", enabled: setting === "on" },
+    runner: opts.runner
+  }, runnerDeps(ctx)))(opts, command));
+  declareCommandKind(runner.command("list-recordings"), "read").description("Read a page of published video recordings, including after the runner terminates. Platform URLs persist; video URLs expire").option("--runner <id>", runnerFlagDescription).option("--recording-id <uuid>", "Look up one recording; an empty result means it is not published or does not exist").option("--page-token <token>", "Continue from nextPageToken returned by the previous page").action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerRecordings(ctx, {
+    runner: opts.runner,
+    ...opts.recordingId === undefined ? {} : { recordingId: opts.recordingId },
+    ...opts.pageToken === undefined ? {} : { pageToken: opts.pageToken }
+  }, runnerDeps(ctx)))(opts, command));
+}
+
 // src/commands/runner/index.ts
 function registerRunnerCommand(program, signals) {
   const runner = program.command("runner").description("Drive an interactive runner on the QA Wolf platform");
@@ -38428,6 +38634,7 @@ function registerRunnerCommand(program, signals) {
   registerRunnerImportPackageCommand(runner, signals);
   registerRunnerHighlightSelectorCommand(runner, signals);
   registerRunnerPromoteSnapshotCommand(runner, signals);
+  registerRunnerRecordingCommands(runner, signals);
 }
 
 // src/commands/program.ts
@@ -38458,4 +38665,4 @@ createProgram({ signals }).parseAsync().catch(() => {
     process.exitCode = 1;
 }).finally(() => exitWhenIdle(typeof process.exitCode === "number" ? process.exitCode : 0));
 
-//# debugId=3E71BA5C9A67947964756E2164756E21
+//# debugId=5DFA383F9EE30BDB64756E2164756E21

package/dist/runner-sdk.js

@@ -10868,6 +10868,9 @@ async function listRunners(ctx, deps) {
   };
 }
 
+// src/domains/interactiveRunner/deps.ts
+import { randomUUID as randomUUID2 } from "node:crypto";
+
 // src/shell/interactiveRunner/collectRunFiles.ts
 import { join as join2 } from "node:path";
 
@@ -12122,6 +12125,7 @@ function makeInteractiveRunnerDeps(options) {
     cwd: options.cwd,
     env: options.env,
     makeRunnerId,
+    makeRecordingId: randomUUID2,
     readFile: (path) => options.fs.readFile(path),
     readStdin,
     runFilesManifest: makeRunFilesManifestStore({
@@ -12238,9 +12242,10 @@ function makeDefaultFs() {
 }
 
 // src/core/publicApi/notFoundSubject.ts
-var runnerRoutesThatNameNoRunner = new Set([
+var runnerRoutesWithoutLivePod = new Set([
   "runner.launch",
-  "runner.list"
+  "runner.list",
+  "runner.recordings"
 ]);
 var runRoutesThatResolveOneRun = new Set([
   "run.diagnose",
@@ -12262,7 +12267,7 @@ function field(input, name) {
   return typeof value === "string" ? value : undefined;
 }
 function notFoundSubject(contractName, input) {
-  if (contractName.startsWith("runner.") && !runnerRoutesThatNameNoRunner.has(contractName)) {
+  if (contractName.startsWith("runner.") && !runnerRoutesWithoutLivePod.has(contractName)) {
     return { kind: "runner", runnerId: field(input, "id") };
   }
   if (runRoutesThatResolveOneRun.has(contractName)) {
@@ -14802,12 +14807,63 @@ function createRunVerbs({ deps, platformClient }) {
   };
 }
 
+// src/domains/interactiveRunner/recordingRequests.ts
+async function recordOnRunner(ctx, runner, command) {
+  const contract = publicContractsV1.runner.record;
+  const parsed = contract.input.safeParse({ id: runner.runnerId, command });
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: "Invalid recording request. Runner ids must be valid and recording ids must be UUIDs.",
+      exitCode: exitCodes.invalidArgs
+    };
+  }
+  const result = await ctx.platformClient.callPublicApi(contract, parsed.data, runnerCallOptions);
+  return result.ok ? result : { ok: false, ...runnerRequestFailure(result, runner) };
+}
+async function readRunnerRecordings(ctx, runner, query) {
+  const contract = publicContractsV1.runner.recordings;
+  const parsed = contract.input.safeParse({ id: runner.runnerId, ...query });
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: "Invalid recordings request. Use a valid runner id, a UUID recording id, and a page token of at most 4096 characters.",
+      exitCode: exitCodes.invalidArgs
+    };
+  }
+  const result = await ctx.platformClient.callPublicApi(contract, parsed.data);
+  return result.ok ? result : { ok: false, ...runnerRequestFailure(result, runner) };
+}
+
+// src/runnerSdk/recordingVerbs.ts
+function createRecordingVerbs(context) {
+  return {
+    async record({
+      runnerId,
+      command
+    }) {
+      return toSdkResult(await recordOnRunner(context, givenRunner(runnerId), command));
+    },
+    async listRecordings({
+      runnerId,
+      recordingId,
+      pageToken
+    }) {
+      return toSdkResult(await readRunnerRecordings(context, givenRunner(runnerId), {
+        ...recordingId === undefined ? {} : { recordingId },
+        ...pageToken === undefined ? {} : { pageToken }
+      }));
+    }
+  };
+}
+
 // src/runnerSdk/index.ts
 function createRunnerSdk(options) {
   const context = createSdkContext(options);
   return {
     ...createLifecycleVerbs(context),
     ...createRunVerbs(context),
+    ...createRecordingVerbs(context),
     ...createPageVerbs(context),
     ...createProjectVerbs(context),
     async list() {
@@ -14820,4 +14876,4 @@ export {
   createRunnerSdk
 };
 
-//# debugId=F5992CBD2796CE7464756E2164756E21
+//# debugId=A7A37F8150999CFE64756E2164756E21

package/dist/types/runnerSdk/index.d.ts

@@ -1,5 +1,5 @@
 import type { ListedRunner, RunnerSdkOptions, SdkResult } from "./types.js";
-export type { ActRequest, EvaluateSnippetRequest, EvaluatedSnippet, EventsRequest, FileSync, HighlightRequest, HighlightSelectorRequest, HighlightedSelector, ImportPackageRequest, ImportedPackage, InspectRequest, Inspected, Journal, JournalWindow, KeptAlive, LaunchRequest, LaunchedRunner, LinesLocation, ListedRunner, PackageVersion, PerformedAction, PromoteSnapshotRequest, PromotedSnapshot, RunEnvironment, RunFilter, RunRequest, RunSelection, RunnerFamily, RunnerRequest, RunnerSdkOptions, Screenshot, SdkResult, SnippetScope, StoppedRun, SubmittedRun, TerminatedRunner, } from "./types.js";
+export type { ActRequest, EvaluateSnippetRequest, EvaluatedSnippet, EventsRequest, FileSync, HighlightRequest, HighlightSelectorRequest, HighlightedSelector, ImportPackageRequest, ImportedPackage, InspectRequest, Inspected, Journal, JournalWindow, KeptAlive, LaunchRequest, LaunchedRunner, LinesLocation, ListedRunner, PackageVersion, PerformedAction, PromoteSnapshotRequest, PromotedSnapshot, RecordRequest, RecordResponse, RecordingsRequest, Recordings, RunEnvironment, RunFilter, RunRequest, RunSelection, RunnerFamily, RunnerRequest, RunnerSdkOptions, Screenshot, SdkResult, SnippetScope, StoppedRun, SubmittedRun, TerminatedRunner, } from "./types.js";
 export type RunnerSdk = ReturnType<typeof createRunnerSdk>;
 /**
  * Drives interactive runners on the caller's team through the QA Wolf public
@@ -15,6 +15,8 @@ export declare function createRunnerSdk(options: RunnerSdkOptions): {
     inspect({ request, runnerId, }: import("./types.js").InspectRequest): Promise<SdkResult<import("./types.js").Inspected>>;
     promoteSnapshot({ baselinePath, runnerId, screenshotPath, }: import("./types.js").PromoteSnapshotRequest): Promise<SdkResult<import("./types.js").PromotedSnapshot>>;
     screenshot({ runnerId, }: import("./types.js").RunnerRequest): Promise<SdkResult<import("./types.js").Screenshot>>;
+    record({ runnerId, command, }: import("./types.js").RecordRequest): Promise<SdkResult<import("./types.js").RecordResponse>>;
+    listRecordings({ runnerId, recordingId, pageToken, }: import("./types.js").RecordingsRequest): Promise<SdkResult<import("./types.js").Recordings>>;
     events({ runFilter, runnerId, stream, window, }: import("./types.js").EventsRequest): Promise<SdkResult<import("./types.js").Journal>>;
     run({ entryPointPath, environment, runnerId, selection, }: import("./types.js").RunRequest): Promise<SdkResult<import("./types.js").SubmittedRun>>;
     keepalive({ runnerId, }: import("./types.js").RunnerRequest): Promise<SdkResult<import("./types.js").KeptAlive>>;

package/dist/types/runnerSdk/types.d.ts

@@ -1,4 +1,4 @@
-import type { BrowserAction, InspectOnRunnerRequest, JournalStream, PublicApiOutput, ReadJournalResponse, RunnerNameForPublicApi, publicContractsV1 } from "@qawolf/api-contracts/v1";
+import type { BrowserAction, InspectOnRunnerRequest, JournalStream, PublicApiInput, PublicApiOutput, ReadJournalResponse, RunnerNameForPublicApi, publicContractsV1 } from "@qawolf/api-contracts/v1";
 type Runner = typeof publicContractsV1.runner;
 export type RunnerSdkOptions = {
     /** A QA Wolf team API key. The SDK never reads the CLI's stored credentials. */
@@ -60,6 +60,12 @@ export type LaunchRequest = {
 export type RunnerRequest = {
     runnerId: string;
 };
+/** Start and stop name the same UUID, so a retry cannot target a later capture. */
+export type RecordRequest = RunnerRequest & Pick<PublicApiInput<Runner["record"]>, "command">;
+export type RecordingsRequest = RunnerRequest & Pick<PublicApiInput<Runner["recordings"]>, "recordingId" | "pageToken">;
+/** Runner refusal is carried on result.outcome, inside the platform answer. */
+export type RecordResponse = PublicApiOutput<Runner["record"]>;
+export type Recordings = PublicApiOutput<Runner["recordings"]>;
 export type RunRequest = RunnerRequest & {
     entryPointPath: string;
     environment: RunEnvironment;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qawolf/cli",
-  "version": "1.33.0",
+  "version": "1.34.0",
   "description": "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   "keywords": [
     "automation",

package/skills/qawolf-cli/SKILL.md

@@ -196,7 +196,12 @@ that `url`; never guess a route and never send a repository link in its place.
 | `qawolf runner keepalive` | read | Reset a runner's inactivity clock, for a caller that pauses between actions |
 | `qawolf runner launch` | write | Launch an interactive runner and make it this directory's default |
 | `qawolf runner list` | read | List the runners running on your team |
+| `qawolf runner list-recordings` | read | Read a page of published video recordings, including after the runner terminates. Platform URLs persist; video URLs expire |
 | `qawolf runner promote-snapshot` | write | Accept a run's screenshot as the new baseline for an image diff, on the runner that produced it |
+| `qawolf runner record auto` | write | Enable or disable automatic recording for subsequent full runs |
+| `qawolf runner record start` | write | Start manual video capture across runs. Requires a ready screen and suppresses automatic capture until stopped |
+| `qawolf runner record status` | read | Show the active recording and automatic recording setting |
+| `qawolf runner record stop` | write | Stop the recording with this UUID and publish it. Retrying cannot stop a later recording |
 | `qawolf runner run` | write | Run a flow on an interactive runner, shipping the flow and what it imports |
 | `qawolf runner screenshot` | read | Save a JPEG of an interactive runner's screen to a file, or write it to stdout with --out - |
 | `qawolf runner stop-run` | write | Stop what a runner is currently executing, leaving the runner up |
@@ -278,7 +283,8 @@ by default.
 
 The `runner` commands drive a live cloud browser: `launch` one, `screenshot` to
 see it, `act` to click and type, `run` a flow on it, `exec` a snippet against its
-page, `events` to read its journal (including the `recorder` stream, which turns
+page, `record` to control video capture, `list-recordings` to read published video
+history even after termination, `events` to read its journal (including the `recorder` stream, which turns
 your actions into Playwright locators), `keepalive` to hold it open, and
 `terminate`
 when done. Everything is a plain request to one host, so a shell with an API key

package/skills/qawolf-cli/references/runner.md

@@ -195,6 +195,44 @@ The answer holds one entry per action reached, and the field to read on each is
 
 The sequence stops at the first action that fails. `--continue-on-failure` carries on past one that reached the runner and did not take effect, which is only safe for actions that do not depend on each other: a `type` after a failed `click` goes to whatever has focus. A runner that cannot be reached, a screen that cannot serve, or running out of time ends the sequence either way, and the message names every action that did not succeed.
 
+## Video recording
+
+Use `record` to control video capture on a Playwright runner. Start a flow first
+so the runner has a screen, then start a manual capture:
+
+```sh
+qawolf runner record start --runner ci --json
+# Keep result.state.active.id from the response and use it to stop this capture:
+qawolf runner record stop <recording-id> --runner ci
+qawolf runner record status --runner ci
+qawolf runner record auto on --runner ci
+qawolf runner record auto off --runner ci
+```
+
+Start generates a UUID unless you pass `--recording-id <uuid>`. If a start
+response is lost, the error includes that UUID: check `record status` and reuse
+the UUID when retrying. Stop always names a specific recording, so retrying it
+cannot stop a later capture. Manual recordings span runs and suppress automatic
+capture until stopped. The auto setting affects subsequent full runs.
+An active automatic recording ends with its run; `record stop` cannot interrupt
+it. If a stop publishes a recording with `status: "failed"`, the CLI returns
+exit code 1 and still prints the manifest so callers can inspect it.
+
+Published recordings remain accessible after the runner terminates:
+
+```sh
+qawolf runner list-recordings --runner ci --json
+qawolf runner list-recordings --runner ci --recording-id <uuid> --json
+qawolf runner list-recordings --runner ci --page-token '<nextPageToken>' --json
+```
+
+Each response is one page with `recordings` and an optional `nextPageToken`.
+Follow that token for more; the order is storage-key order, not newest-first.
+Entries include status, run ids, a stable platform `url`, and an expiring
+`videoUrl` when video is available. An empty lookup means the recording has not
+been published or does not exist. Abrupt runner loss may leave video unavailable.
+Keep the runner id for history lookups after termination clears the local default.
+
 ## The recorder: what you cannot get from pixels
 
 `qawolf runner events recorder` is the capability that has no equivalent in a