fix: derive interaction response data transforms

src/commands/__tests__/command-surface-metadata.test.ts

@@ -1,6 +1,9 @@
 import assert from 'node:assert/strict';
 import { test } from 'vitest';
-import { listMcpExposedCommandNames } from '../../core/command-descriptor/registry.ts';
+import {
+  listCommandResponseDataTransforms,
+  listMcpExposedCommandNames,
+} from '../../core/command-descriptor/registry.ts';
 import {
   listCommandMetadata,
   listCommandMetadataNames,
@@ -49,6 +52,25 @@ test('common command input accepts web platform selector', () => {
   assert.equal(input.platform, 'web');
 });
 
+test('command response data transforms reference command input fields', () => {
+  const metadataByName = new Map<string, ReturnType<typeof listCommandMetadata>[number]>(
+    listCommandMetadata().map((metadata) => [metadata.name, metadata] as const),
+  );
+
+  for (const { command, transform } of listCommandResponseDataTransforms()) {
+    const metadata = metadataByName.get(command);
+    assert.ok(metadata, `${command} response data transform must have command metadata`);
+
+    const inputFields = new Set(Object.keys(metadata.inputSchema.properties ?? {}));
+    for (const field of Object.keys(transform.fields)) {
+      assert.ok(
+        inputFields.has(field),
+        `${command} response data transform field ${field} must be declared by command input metadata`,
+      );
+    }
+  }
+});
+
 test('command family facets expose one complete metadata and executable surface', () => {
   const familyNames = commandFamilies.map((family) => family.name);
   assert.deepEqual(familyNames, [...new Set(familyNames)], 'command family names must be unique');

src/core/__tests__/interaction-response-data-transform.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, test } from 'vitest';
+import { resolveCommandResponseDataTransform } from '../command-descriptor/registry.ts';
+import { transformInteractionResponseData } from '../interaction-response-data-transform.ts';
+
+describe('interaction response data transform', () => {
+  test('reads command-owned response data transform from descriptors', () => {
+    expect(resolveCommandResponseDataTransform('press')?.fields).toEqual({
+      count: { defaultValue: 1, omitDefault: true },
+      intervalMs: { defaultValue: 0, omitDefault: true },
+      holdMs: { defaultValue: 0, omitDefault: true },
+      jitterPx: { defaultValue: 0, omitDefault: true },
+      doubleTap: { defaultValue: false, omitDefault: true },
+    });
+    expect(resolveCommandResponseDataTransform('fill')?.fields.delayMs).toEqual({
+      defaultValue: 0,
+    });
+    expect(resolveCommandResponseDataTransform('longpress')).toBeUndefined();
+  });
+
+  test('omits default press repeat values', () => {
+    expect(
+      transformInteractionResponseData({
+        command: 'press',
+        input: {
+          count: 1,
+          intervalMs: 0,
+          holdMs: 0,
+          jitterPx: 0,
+          doubleTap: false,
+        },
+        data: undefined,
+      }),
+    ).toEqual({});
+  });
+
+  test('keeps non-default press repeat values', () => {
+    expect(
+      transformInteractionResponseData({
+        command: 'press',
+        input: {
+          count: 2,
+          intervalMs: 25,
+          holdMs: 10,
+          jitterPx: 1,
+          doubleTap: true,
+        },
+        data: undefined,
+      }),
+    ).toEqual({
+      count: 2,
+      intervalMs: 25,
+      holdMs: 10,
+      jitterPx: 1,
+      doubleTap: true,
+    });
+  });
+
+  test('keeps the normalized fill delay default', () => {
+    expect(
+      transformInteractionResponseData({ command: 'fill', input: {}, data: undefined }),
+    ).toEqual({
+      delayMs: 0,
+    });
+  });
+
+  test('preserves backend fields while applying command defaults', () => {
+    expect(
+      transformInteractionResponseData({
+        command: 'press',
+        input: {},
+        data: {
+          count: 1,
+          videoPath: '/tmp/demo.mp4',
+        },
+      }),
+    ).toEqual({ videoPath: '/tmp/demo.mp4' });
+  });
+
+  test('removes default touch repeat fields from fill backend data', () => {
+    expect(
+      transformInteractionResponseData({
+        command: 'fill',
+        input: {},
+        data: {
+          count: 1,
+          delayMs: 0,
+          doubleTap: false,
+          holdMs: 0,
+          intervalMs: 0,
+          jitterPx: 0,
+          text: 'Hello',
+        },
+      }),
+    ).toEqual({ delayMs: 0, text: 'Hello' });
+  });
+});

src/core/command-descriptor/registry.ts

@@ -14,7 +14,11 @@ import {
 } from './timeout-policy.ts';
 import { resolvePostActionObservationSupport } from './post-action-observation.ts';
 import type { PostActionObservationSupport } from './post-action-observation.ts';
-import type { CommandDescriptor, CommandTimeoutPolicy } from './types.ts';
+import type {
+  CommandDescriptor,
+  CommandResponseDataTransform,
+  CommandTimeoutPolicy,
+} from './types.ts';
 
 type RawCommandDescriptor = Omit<CommandDescriptor, 'mcpExposed'> & {
   mcpExposed?: boolean;
@@ -125,6 +129,22 @@ const SETTLE_FLAG_PRESERVE_DAEMON_TIMEOUT_POLICY: CommandTimeoutPolicy = {
   onTimeout: 'preserve-daemon',
 };
 
+const TOUCH_INTERACTION_RESPONSE_DATA_TRANSFORM = {
+  fields: {
+    count: { defaultValue: 1, omitDefault: true },
+    intervalMs: { defaultValue: 0, omitDefault: true },
+    holdMs: { defaultValue: 0, omitDefault: true },
+    jitterPx: { defaultValue: 0, omitDefault: true },
+    doubleTap: { defaultValue: false, omitDefault: true },
+  },
+} as const satisfies CommandResponseDataTransform;
+
+const FILL_INTERACTION_RESPONSE_DATA_TRANSFORM = {
+  fields: {
+    delayMs: { defaultValue: 0 },
+  },
+} as const satisfies CommandResponseDataTransform;
+
 function interactionTimeoutPolicy(command: string): CommandTimeoutPolicy {
   return resolvePostActionObservationSupport(command) !== undefined
     ? SETTLE_FLAG_PRESERVE_DAEMON_TIMEOUT_POLICY
@@ -516,6 +536,7 @@ const RAW_COMMAND_DESCRIPTORS = [
     capability: { apple: APPLE_SIM_AND_DEVICE, android: ANDROID_ALL, linux: LINUX_DEVICE },
     timeoutPolicy: interactionTimeoutPolicy(PUBLIC_COMMANDS.click),
     postActionObservation: postActionObservation(PUBLIC_COMMANDS.click),
+    responseDataTransform: TOUCH_INTERACTION_RESPONSE_DATA_TRANSFORM,
     batchable: true,
   },
   {
@@ -524,6 +545,7 @@ const RAW_COMMAND_DESCRIPTORS = [
     capability: { apple: APPLE_SIM_AND_DEVICE, android: ANDROID_ALL, linux: LINUX_DEVICE },
     timeoutPolicy: interactionTimeoutPolicy(PUBLIC_COMMANDS.fill),
     postActionObservation: postActionObservation(PUBLIC_COMMANDS.fill),
+    responseDataTransform: FILL_INTERACTION_RESPONSE_DATA_TRANSFORM,
     batchable: true,
   },
   {
@@ -540,6 +562,7 @@ const RAW_COMMAND_DESCRIPTORS = [
     capability: { apple: APPLE_SIM_AND_DEVICE, android: ANDROID_ALL, linux: LINUX_DEVICE },
     timeoutPolicy: interactionTimeoutPolicy(PUBLIC_COMMANDS.press),
     postActionObservation: postActionObservation(PUBLIC_COMMANDS.press),
+    responseDataTransform: TOUCH_INTERACTION_RESPONSE_DATA_TRANSFORM,
     batchable: true,
   },
   {
@@ -775,6 +798,15 @@ const TIMEOUT_POLICY_BY_COMMAND: ReadonlyMap<string, CommandTimeoutPolicy> = new
   commandDescriptors.map((descriptor) => [descriptor.name, descriptor.timeoutPolicy]),
 );
 
+const RESPONSE_DATA_TRANSFORM_BY_COMMAND: ReadonlyMap<string, CommandResponseDataTransform> =
+  new Map(
+    Array.from(COMMAND_DESCRIPTOR_BY_NAME.values()).flatMap((descriptor) =>
+      descriptor.responseDataTransform
+        ? [[descriptor.name, descriptor.responseDataTransform] as const]
+        : [],
+    ),
+  );
+
 export function resolveCommandPostActionObservationSupport(
   command: string | undefined,
 ): PostActionObservationSupport | undefined {
@@ -800,3 +832,30 @@ export function resolveCommandTimeoutPolicy(command: string | undefined): Comman
   if (command === undefined) return DEFAULT_TIMEOUT_POLICY;
   return TIMEOUT_POLICY_BY_COMMAND.get(command) ?? DEFAULT_TIMEOUT_POLICY;
 }
+
+export function resolveCommandResponseDataTransform(
+  command: string | undefined,
+): CommandResponseDataTransform | undefined {
+  if (command === undefined) return undefined;
+  return RESPONSE_DATA_TRANSFORM_BY_COMMAND.get(command);
+}
+
+export function listCommandResponseDataTransforms(): Array<{
+  command: string;
+  transform: CommandResponseDataTransform;
+}> {
+  return Array.from(RESPONSE_DATA_TRANSFORM_BY_COMMAND, ([command, transform]) => ({
+    command,
+    transform,
+  }));
+}
+
+export function listCommandResponseDataTransformFieldNames(): string[] {
+  return [
+    ...new Set(
+      Array.from(RESPONSE_DATA_TRANSFORM_BY_COMMAND.values()).flatMap((transform) =>
+        Object.keys(transform.fields),
+      ),
+    ),
+  ].sort();
+}

src/core/command-descriptor/types.ts

@@ -2,6 +2,15 @@ import type { CommandCapability } from '../capabilities.ts';
 import type { DaemonCommandDescriptor } from '../../daemon/daemon-command-registry.ts';
 import type { PostActionObservationSupport } from './post-action-observation.ts';
 
+export type ResponseDataFieldTransform = {
+  defaultValue?: unknown;
+  omitDefault?: boolean;
+};
+
+export type CommandResponseDataTransform = {
+  fields: Record<string, ResponseDataFieldTransform>;
+};
+
 /**
  * The daemon route + request-policy traits for a command, minus the `command`
  * key (which is carried at the descriptor top level as `name`). This reuses the
@@ -81,6 +90,10 @@ export type CommandTimeoutPolicy = {
  *                   commands that support `--settle`/`--verify`; consumed by
  *                   command surfaces and timeout policy instead of repeated
  *                   command-name lists.
+ *  - `responseDataTransform` — optional public response data shaping rules for
+ *                   command-owned fields in daemon responses. This keeps
+ *                   response shaping on the same descriptor surface as other
+ *                   command traits.
  *
  * The registry started dormant (proven byte-equal to the hand tables by the
  * parity tests) and is now the live source: the daemon registry, capability
@@ -95,4 +108,5 @@ export type CommandDescriptor = {
   mcpExposed: boolean;
   timeoutPolicy: CommandTimeoutPolicy;
   postActionObservation?: PostActionObservationSupport;
+  responseDataTransform?: CommandResponseDataTransform;
 };

src/core/interaction-response-data-transform.ts

@@ -0,0 +1,52 @@
+import {
+  listCommandResponseDataTransformFieldNames,
+  resolveCommandResponseDataTransform,
+} from './command-descriptor/registry.ts';
+import type { ResponseDataFieldTransform } from './command-descriptor/types.ts';
+
+export type InteractionResponseDataTransformCommand = 'click' | 'press' | 'fill';
+
+const controlledResponseDataFieldNames = new Set(listCommandResponseDataTransformFieldNames());
+
+export function transformInteractionResponseData(params: {
+  command: InteractionResponseDataTransformCommand;
+  input: Record<string, unknown> | undefined;
+  data: Record<string, unknown> | undefined;
+}): Record<string, unknown> {
+  return applyResponseDataFieldTransforms({
+    fields: readCommandResponseDataTransformFields(params.command),
+    input: params.input ?? {},
+    data: params.data,
+    controlledFields: controlledResponseDataFieldNames,
+  });
+}
+
+function readCommandResponseDataTransformFields(
+  command: InteractionResponseDataTransformCommand,
+): Record<string, ResponseDataFieldTransform> {
+  const transform = resolveCommandResponseDataTransform(command);
+  if (!transform) {
+    throw new Error(`Missing response data transform descriptor for ${command}`);
+  }
+  return transform.fields;
+}
+
+function applyResponseDataFieldTransforms(params: {
+  fields: Record<string, ResponseDataFieldTransform>;
+  input: Record<string, unknown>;
+  data: Record<string, unknown> | undefined;
+  controlledFields: ReadonlySet<string>;
+}): Record<string, unknown> {
+  const transformed = Object.fromEntries(
+    Object.entries(params.data ?? {}).filter(([key]) => !params.controlledFields.has(key)),
+  );
+  for (const [key, field] of Object.entries(params.fields)) {
+    const value = params.input[key] === undefined ? field.defaultValue : params.input[key];
+    if (value === undefined || (field.omitDefault === true && value === field.defaultValue)) {
+      delete transformed[key];
+      continue;
+    }
+    transformed[key] = value;
+  }
+  return Object.fromEntries(Object.entries(transformed).filter(([, value]) => value !== undefined));
+}