refactor: share the replay request field vocabulary across the CLI and client views

The new replay script-source flags appear in both CliFlags and CommandExecutionOptions, which fallow flagged as a clone; ReplayRequestFields declares them once. The test-suite handler's missing-sources rejection now travels the typed-error path its sibling rejections already use, so the fix adds no branch to handleSessionReplayCommands.

Author: thymikee

packages/contracts/src/cli-flags.ts

@@ -20,11 +20,12 @@ import type {
 } from './remote-config-fields.ts';
 import type { ScreenshotRequestFlags } from './screenshot.ts';
 import type { RecordingScope } from './recording-scope.ts';
-import type { ReplayScriptSourceBundle } from './replay.ts';
+import type { ReplayRequestFields } from './replay-request-fields.ts';
 
 export type CliFlags = CloudProviderProfileFields &
   RemoteConfigMetroOptions &
-  ScreenshotRequestFlags & {
+  ScreenshotRequestFlags &
+  ReplayRequestFields & {
     json: boolean;
     config?: string;
     remoteConfig?: string;
@@ -140,30 +141,9 @@ export type CliFlags = CloudProviderProfileFields &
     record?: boolean;
     retainPaths?: boolean;
     retentionMs?: number;
-    replayUpdate?: boolean;
     replayMaestro?: boolean;
-    replayEnv?: string[];
-    replayShellEnv?: Record<string, string>;
-    /**
-     * #1802: the caller-read script text `replay` executes. The daemon never
-     * opens a caller path, so this is the ONLY source a replay run reads.
-     */
-    replayScriptSource?: ReplayScriptSourceBundle;
-    /** #1802: `test`'s caller-side discovery result — one bundle per discovered source, in run order. */
-    replayScriptSources?: ReplayScriptSourceBundle[];
-    replayFrom?: number;
-    replayPlanDigest?: string;
-    /** Replay: leave the session active by suppressing an authored terminal close in native .ad. */
-    replayKeepSession?: boolean;
-    failFast?: boolean;
-    timeoutMs?: number;
-    retries?: number;
-    recordVideo?: boolean;
-    artifactsDir?: string;
     reporter?: string[];
     reportJunit?: string;
-    shardAll?: number;
-    shardSplit?: number;
     steps?: string;
     stepsFile?: string;
     findFirst?: boolean;

packages/contracts/src/client-request.ts

@@ -15,67 +15,51 @@ import type {
   SessionRuntimeHints,
 } from '@agent-device/kernel/contracts';
 import type { DaemonBatchStep } from './batch-step.ts';
-import type { ReplayScriptSourceBundle } from './replay.ts';
+import type { ReplayRequestFields } from './replay-request-fields.ts';
 import type { AgentDeviceClientConfig, AgentDeviceSelectionOptions } from './client-connection.ts';
 
-export type CommandExecutionOptions = Partial<ScreenshotRequestFlags> & {
-  positionals?: string[];
-  kind?: string;
-  out?: string;
-  artifact?: string;
-  dsym?: string;
-  searchPath?: string;
-  interactiveOnly?: boolean;
-  depth?: number;
-  scope?: string;
-  raw?: boolean;
-  customActions?: boolean;
-  forceFull?: boolean;
-  count?: number;
-  fps?: number;
-  recordingScope?: RecordingScope;
-  quality?: RecordingExportQuality;
-  hideTouches?: boolean;
-  intervalMs?: number;
-  delayMs?: number;
-  durationMs?: number;
-  holdMs?: number;
-  jitterPx?: number;
-  pixels?: number;
-  doubleTap?: boolean;
-  verify?: boolean;
-  settle?: boolean;
-  settleQuietMs?: number;
-  clickButton?: ClickButton;
-  pauseMs?: number;
-  pattern?: SwipePattern;
-  headless?: boolean;
-  restart?: boolean;
-  replayUpdate?: boolean;
-  replayBackend?: string;
-  replayEnv?: string[];
-  replayShellEnv?: Record<string, string>;
-  /** #1802: caller-read script text for `replay`; the daemon never opens a caller path. */
-  replayScriptSource?: ReplayScriptSourceBundle;
-  /** #1802: caller-side `test` discovery result — one bundle per discovered source, in run order. */
-  replayScriptSources?: ReplayScriptSourceBundle[];
-  replayFrom?: number;
-  replayPlanDigest?: string;
-  replayKeepSession?: boolean;
-  failFast?: boolean;
-  timeoutMs?: number;
-  retries?: number;
-  recordVideo?: boolean;
-  artifactsDir?: string;
-  shardAll?: number;
-  shardSplit?: number;
-  findFirst?: boolean;
-  findLast?: boolean;
-  networkInclude?: NetworkIncludeMode;
-  batchOnError?: 'stop';
-  batchMaxSteps?: number;
-  batchSteps?: DaemonBatchStep[];
-};
+export type CommandExecutionOptions = Partial<ScreenshotRequestFlags> &
+  ReplayRequestFields & {
+    positionals?: string[];
+    kind?: string;
+    out?: string;
+    artifact?: string;
+    dsym?: string;
+    searchPath?: string;
+    interactiveOnly?: boolean;
+    depth?: number;
+    scope?: string;
+    raw?: boolean;
+    customActions?: boolean;
+    forceFull?: boolean;
+    count?: number;
+    fps?: number;
+    recordingScope?: RecordingScope;
+    quality?: RecordingExportQuality;
+    hideTouches?: boolean;
+    intervalMs?: number;
+    delayMs?: number;
+    durationMs?: number;
+    holdMs?: number;
+    jitterPx?: number;
+    pixels?: number;
+    doubleTap?: boolean;
+    verify?: boolean;
+    settle?: boolean;
+    settleQuietMs?: number;
+    clickButton?: ClickButton;
+    pauseMs?: number;
+    pattern?: SwipePattern;
+    headless?: boolean;
+    restart?: boolean;
+    replayBackend?: string;
+    findFirst?: boolean;
+    findLast?: boolean;
+    networkInclude?: NetworkIncludeMode;
+    batchOnError?: 'stop';
+    batchMaxSteps?: number;
+    batchSteps?: DaemonBatchStep[];
+  };
 
 export type InternalRequestOptions = AgentDeviceClientConfig &
   AgentDeviceSelectionOptions &

packages/contracts/src/replay-request-fields.ts

@@ -0,0 +1,34 @@
+import type { ReplayScriptSourceBundle } from './replay.ts';
+
+/**
+ * The replay/test request vocabulary, declared once.
+ *
+ * `CliFlags` and `CommandExecutionOptions` are two views of the same request — the flags a CLI
+ * invocation parses and the options a programmatic call passes — and every replay/suite field
+ * appears in both. Stating them here keeps the two views from drifting field by field; each view
+ * adds only what is genuinely its own (`replayMaestro` and the reporter flags are CLI-side,
+ * `replayBackend` is the resolved engine the client sends).
+ */
+export type ReplayRequestFields = {
+  replayUpdate?: boolean;
+  replayEnv?: string[];
+  replayShellEnv?: Record<string, string>;
+  /**
+   * #1802: the caller-read script text `replay` executes. The daemon never opens a caller path,
+   * so this is the ONLY source a replay run reads.
+   */
+  replayScriptSource?: ReplayScriptSourceBundle;
+  /** #1802: `test`'s caller-side discovery result — one bundle per discovered source, in run order. */
+  replayScriptSources?: ReplayScriptSourceBundle[];
+  replayFrom?: number;
+  replayPlanDigest?: string;
+  /** Replay: leave the session active by suppressing an authored terminal close in native .ad. */
+  replayKeepSession?: boolean;
+  failFast?: boolean;
+  timeoutMs?: number;
+  retries?: number;
+  recordVideo?: boolean;
+  artifactsDir?: string;
+  shardAll?: number;
+  shardSplit?: number;
+};

src/daemon/handlers/session-replay.ts

@@ -9,7 +9,7 @@ import { handleCloseCommand } from './session-close.ts';
 import { runReplayScriptSource } from './session-replay-runtime.ts';
 import { collectReplayActionArtifactPaths } from './session-replay-runtime-artifacts.ts';
 import { errorResponse } from './response.ts';
-import { asAppError } from '@agent-device/kernel/errors';
+import { AppError, asAppError } from '@agent-device/kernel/errors';
 import { emitRequestProgress } from '../../request/progress.ts';
 import {
   clearRequestCanceled,
@@ -184,19 +184,17 @@ export async function handleSessionReplayCommands(params: {
     // That rejection has always surfaced as an INVALID_ARGS response, so it is caught here
     // rather than escaping the handler now that translation happens before the suite runs.
     let suiteRequest: ReplayTestSuiteRequest;
+    // #1802: the caller expanded its own paths/globs and sent one script source bundle per
+    // discovered source. `sourceBundles` is that list, keyed below by entry path so each nested
+    // replay attempt executes exactly the text the caller read for that file.
+    let sourceBundles: readonly ReplayScriptSourceBundle[];
     try {
       suiteRequest = toReplayTestSuiteRequest(req, sessionName);
+      sourceBundles = requireReplayTestScriptSources(req);
     } catch (err) {
       const appErr = asAppError(err);
       return errorResponse(appErr.code, appErr.message);
     }
-    // #1802: the caller expanded its own paths/globs and sent one script source bundle per
-    // discovered source. `sourceBundles` is that list, keyed below by entry path so each nested
-    // replay attempt executes exactly the text the caller read for that file.
-    const sourceBundles = req.flags?.replayScriptSources;
-    if (!sourceBundles) {
-      return errorResponse('INVALID_ARGS', REPLAY_SCRIPT_SOURCE_REQUIRED_MESSAGE);
-    }
     const sourceBundlesByPath = new Map(sourceBundles.map((bundle) => [bundle.entry, bundle]));
     const outcome = await runReplayTestSuite({
       request: suiteRequest,
@@ -375,6 +373,18 @@ function resolveReplayVideoRuntime(params: {
  * `replayBackend` is deliberately not carried across: it selects an engine, and it has already
  * been applied here when building the source-discovery and shard-target capabilities.
  */
+/**
+ * #1802: a `test` request states the script sources its suite runs, because the daemon opens no
+ * caller path. Absent entirely means a client too old to send them; it is rejected as a typed
+ * `AppError` so it travels the same translation-failure path the shard/flag rejections already
+ * take, rather than adding a second refusal shape to the handler.
+ */
+function requireReplayTestScriptSources(req: DaemonRequest): readonly ReplayScriptSourceBundle[] {
+  const sources = req.flags?.replayScriptSources;
+  if (!sources) throw new AppError('INVALID_ARGS', REPLAY_SCRIPT_SOURCE_REQUIRED_MESSAGE);
+  return sources;
+}
+
 function toReplayTestSuiteRequest(req: DaemonRequest, sessionName: string): ReplayTestSuiteRequest {
   const flags = req.flags ?? {};
   const cwd = req.meta?.cwd;