feat: record start [path], screenshot [path], --record-json (#18)

Author: thymikee

README.md

@@ -99,7 +99,6 @@ Flags:
 - `--udid <udid>` (iOS)
 - `--serial <serial>` (Android)
 - `--activity <component>` (Android; package/Activity or package/.Activity)
-- `--out <path>` (screenshot)
 - `--session <name>`
 - `--verbose` for daemon and runner logs
 - `--json` for structured output
@@ -115,6 +114,7 @@ Sessions:
 - `close` stops the session and releases device resources. Pass an app to close it explicitly, or omit to just close the session.
 - Use `--session <name>` to manage multiple sessions.
 - Session logs are written to `~/.agent-device/sessions/<session>-<timestamp>.ad`.
+- With `--record-json`, JSON logs are written to `~/.agent-device/sessions/<session>-<timestamp>.json` by default.
 
 Find (semantic):
 - `find <text> <action> [value]` finds by any text (label/value/identifier) using a scoped snapshot.

skills/agent-device/SKILL.md

@@ -117,7 +117,7 @@ agent-device alert get
 ```bash
 agent-device get text @e1
 agent-device get attrs @e1
-agent-device screenshot --out out.png
+agent-device screenshot out.png
 ```
 
 ### Trace logs (AX/XCTest)

src/core/dispatch.ts

@@ -244,7 +244,8 @@ export async function dispatchCommand(
       return { scale, x, y };
     }
     case 'screenshot': {
-      const path = outPath ?? `./screenshot-${Date.now()}.png`;
+      const positionalPath = positionals[0];
+      const path = positionalPath ?? outPath ?? `./screenshot-${Date.now()}.png`;
       await interactor.screenshot(path);
       return { path };
     }

src/daemon.ts

@@ -1413,7 +1413,7 @@ function writeSessionLog(session: SessionState): void {
     const safeName = session.name.replace(/[^a-zA-Z0-9._-]/g, '_');
     const timestamp = new Date(session.createdAt).toISOString().replace(/[:.]/g, '-');
     const scriptPath = path.join(sessionsDir, `${safeName}-${timestamp}.ad`);
-    const filePath = path.join(sessionsDir, `${safeName}-${timestamp}.json`);
+    const filePath = resolveSessionJsonPath(session, safeName, timestamp);
     const payload = {
       name: session.name,
       device: session.device,
@@ -1425,13 +1425,41 @@ function writeSessionLog(session: SessionState): void {
     const script = formatScript(session, payload.optimizedActions);
     fs.writeFileSync(scriptPath, script);
     if (session.actions.some((action) => action.flags?.recordJson)) {
+      fs.mkdirSync(path.dirname(filePath), { recursive: true });
       fs.writeFileSync(filePath, JSON.stringify(payload, null, 2));
     }
   } catch {
     // ignore
   }
 }
 
+function resolveSessionJsonPath(session: SessionState, safeName: string, timestamp: string): string {
+  const defaultFile = path.join(sessionsDir, `${safeName}-${timestamp}.json`);
+  const actionWithOut = [...session.actions]
+    .reverse()
+    .find((action) => action.flags?.recordJson && typeof action.flags?.out === 'string' && action.flags.out.trim().length > 0);
+  if (!actionWithOut || !actionWithOut.flags?.out) {
+    return defaultFile;
+  }
+
+  const rawOut = actionWithOut.flags.out.trim();
+  const resolvedOut = expandHome(rawOut);
+  const wantsDirectory = rawOut.endsWith('/') || rawOut.endsWith('\\');
+  if (wantsDirectory) {
+    return path.join(resolvedOut, `${safeName}-${timestamp}.json`);
+  }
+
+  try {
+    if (fs.existsSync(resolvedOut) && fs.statSync(resolvedOut).isDirectory()) {
+      return path.join(resolvedOut, `${safeName}-${timestamp}.json`);
+    }
+  } catch {
+    return defaultFile;
+  }
+
+  return resolvedOut;
+}
+
 function defaultTracePath(session: SessionState): string {
   const safeName = session.name.replace(/[^a-zA-Z0-9._-]/g, '_');
   const timestamp = new Date().toISOString().replace(/[:.]/g, '-');

src/utils/args.ts

@@ -193,7 +193,7 @@ Commands:
   fill <x> <y> <text> | fill <@ref> <text>   Tap then type
   scroll <direction> [amount]                Scroll in direction (0-1 amount)
   scrollintoview <text>                      Scroll until text appears (Android only)
-  screenshot [--out path]                    Capture screenshot
+  screenshot [path]                          Capture screenshot
   record start [path]                        Start screen recording
   record stop                                Stop screen recording
   trace start [path]                         Start trace log capture
@@ -213,7 +213,6 @@ Flags:
   --udid <udid>                              iOS device UDID
   --serial <serial>                          Android device serial
   --activity <component>                     Android activity to launch (package/Activity)
-  --out <path>                               Output path for screenshots
   --session <name>                           Named session
   --verbose                                  Stream daemon/runner logs
   --json                                     JSON output

website/docs/docs/commands.md

@@ -59,3 +59,13 @@ agent-device settings airplane off
 agent-device settings location on
 agent-device settings location off
 ```
+
+## Media and logs
+
+```bash
+agent-device screenshot                 # Auto filename
+agent-device screenshot page.png        # Explicit screenshot path
+agent-device record start               # Start screen recording to auto filename
+agent-device record start session.mp4   # Start recording to explicit path
+agent-device record stop                # Stop active recording
+```

website/docs/docs/quick-start.md

@@ -31,7 +31,7 @@ agent-device snapshot -i                 # Get interactive elements with refs
 agent-device click @e2                   # Click by ref
 agent-device fill @e3 "test@example.com" # Clear then type (Android verifies and retries once if needed)
 agent-device get text @e1                # Get text content
-agent-device screenshot --out page.png   # Save to specific path
+agent-device screenshot page.png         # Save to specific path
 agent-device close
 ```