argent-screen-recording

1. Tools

• screen-recording-start — start capturing the screen of a booted device to a video file. Frames come from the same simulator-server backend that screenshot and the interaction tools already use, and are encoded live to h264 mp4 (constant 30 fps, device-native resolution).
• screen-recording-stop — stop the capture, finalize the container, and retrieve the video as a downloadable artifact (video.hostPath for co-located clients).

One recording per device at a time; different devices can record concurrently. Recording does not disturb anything else reading the device — a preview window can stay open on the same screen.

---

2. Critical: never leave a recording running

A recording does not stop itself before its timeLimitSeconds cap, so a forgotten one keeps capturing until the cap fires — holding the recording session, wasting disk, and delaying the video you are waiting on (and with trimStatic: false it comes back padded with dead air). Two safety nets exist — use both:

1. Set yourself a reminder the moment the recording starts. You know the expected capture length (the interaction you are about to drive). Immediately after screen-recording-start returns, schedule a wake-up for that expected end time using whatever your harness provides — a built-in reminder/wakeup or scheduled-task tool if you have one, otherwise a background shell running sleep <expected-seconds> whose completion notification pulls you back. When it fires, call screen-recording-stop. Do not rely on remembering.
2. Read the tool-result notes. While a recording is running, every argent tool result carries a NOTE: reminding you it is still going and how to stop it. If the note says the recording already ended (time limit hit), still call screen-recording-stop — that is what hands you the file.

---

3. Workflow

1. Ensure the target device is booted and the app is in the state you want the video to open on (list-devices, launch-app, argent-device-interact).
2. Call screen-recording-start with udid and a timeLimitSeconds slightly above the expected interaction length (default 180, max 600). Taps and swipes are drawn into the video by default (see the touch-visualizer note below); pass showTouches: false for a clean raw-screen capture.
3. Set the end-of-recording reminder described in §2 — this step is not optional.
4. Drive the interaction to capture: gestures, navigation, typing (argent-device-interact). Prefer run-sequence for tight multi-step interactions so tool-call latency does not pad the video.
5. Call screen-recording-stop with the same udid. It returns { video, durationMs, wallClockMs?, trimmedMs?, warning? }; video is an artifact whose resolved path points at the durably-saved file (see below). The video is already final when stop returns (the watermark is stamped during capture, not in a second pass), so stop takes well under a second.
6. Check warning: it reports cap-triggered stops, early encoder exits, a dropped frame stream, and possibly-truncated containers. Verify the file plays (or at least has a sane size) before presenting it to the user.