feat(runner): answer an action with a screenshot via act --screenshot

[Goran Gajic (gorangajic)]

Relates to WIZ-11973. Stacked on #1578 (WIZ-11974), which it reuses for writing image bytes.

Draft until the contract lands. The pinned @qawolf/api-contracts 0.39.0 has no option on runner.performAction for asking for a screenshot with the answer, and no platform branch I could find adds one yet. This PR is built against a placeholder in one file, performActionContract.ts: the published schemas extended with input screenshot: true and an optional imageJpegBase64 on the success. It is a schema rather than a type cast so the flag can be tried against a platform preview that has the change. Today, against a platform without it, the action is performed and the CLI answers "Performed click, but the runner answered without the screen it was asked for" with exit 4. Please point me at the real shape when part 1 is published and I will replace the placeholder, pin the release, handle any failure reasons it adds, and give the runner SDK's act verb the same option (its types may only import the published contracts, so it waits for the pin).

Overview of Changes

A Tester computer-use step is two CLI calls, act then screenshot, with a fixed 500 ms wait between them because nothing says when the screen has caught up. About 2.3 s per step against 1.4 s over WebRTC on the preview.

qawolf runner act ... --screenshot <path> asks the runner for its screen with the answer and writes it the way runner screenshot does: to the file, or to stdout with -. One call per step and the fixed wait goes away. When the action was performed but the image did not arrive or could not be written, the message says the action took effect and points at a plain screenshot, and every such case exits 4, the code the runner guide already reads as "screenshot before repeating", so nobody clicks twice to get a picture. A terminal on stdout is refused before a runner is resolved or anything is sent. The runner guide and the skill now tell agents to prefer the one call.

exec moved to its own registration file only to keep the interact file under the line limit.

Testing

bun run typecheck
bun run lint
bun run format:check
bun run knip
bun run test
bun run build

Added tests: the option is sent only when the flag is given; the image is written to the file or to stdout with the confirmation kept off stdout in json and agent mode; a forwarded stdin action works with --screenshot -; a terminal on stdout is refused with no runner resolved; an answer without an image, a non-JPEG, and an unwritable destination each exit 4, say the action happened and do not invite a repeat; refusals, lost answers and timed-out requests read as before.

Checklist

• Changes follow the code style of this project
• Self-review completed
• Tests added/updated (or not applicable)
• No breaking changes (or described below)

🤖 Generated with Claude Code

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

_{Comment @coderabbitai help to get the list of available commands.}