refactor(mcp): introduce honest public targetKind-discriminated interaction response contracts

Replace the public AgentDeviceClient return types for press/click/fill/longpress/find with serialized-payload-shaped response data (targetKind, flat ref/selector/x/y, per-command extras) instead of internal runtime result types. The internal PressCommandResult/FillCommandResult/LongPressCommandResult keep their kind/target shapes for the daemon runtime; the public CommandResultMap now points to the new response contracts.

- Add PressCommandResponseData/FillCommandResponseData/LongPressCommandResponseData/FindCommandResponseData in src/contracts/interaction.ts.
- Update CommandResultMap and command-result tests.
- Add client-facing shape tests asserting the public response data discriminates on targetKind and exposes flat identity fields.

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: thymikee

src/__tests__/client.test.ts

@@ -3,6 +3,13 @@ import assert from 'node:assert/strict';
 import { mkdtempSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import type {
+  ClickCommandResponseData,
+  FillCommandResponseData,
+  FindCommandResponseData,
+  LongPressCommandResponseData,
+  PressCommandResponseData,
+} from '../contracts/interaction.ts';
 import {
   createAgentDeviceClient,
   type AgentDeviceClient,
@@ -1140,3 +1147,114 @@ test('capture.snapshot passes a digest (non-default level) payload through unnor
   assert.equal(asRecord.nodeCount, 3);
   assert.ok(!('identifiers' in asRecord));
 });
+
+test('interactions expose targetKind-discriminated public response data', async () => {
+  const setup = createTransport(async (req) => {
+    if (req.command === 'press') {
+      return {
+        ok: true,
+        data: {
+          targetKind: 'ref',
+          ref: 'e5',
+          x: 88,
+          y: 99,
+          message: 'Tapped @e5 (88, 99)',
+        },
+      };
+    }
+    if (req.command === 'click') {
+      return {
+        ok: true,
+        data: {
+          targetKind: 'point',
+          x: 10,
+          y: 20,
+          button: 'secondary',
+          message: 'Tapped (10, 20)',
+        },
+      };
+    }
+    if (req.command === 'fill') {
+      return {
+        ok: true,
+        data: {
+          targetKind: 'ref',
+          ref: 'e5',
+          x: 88,
+          y: 99,
+          text: 'hello',
+          message: 'Filled 5 chars',
+        },
+      };
+    }
+    if (req.command === 'longpress') {
+      return {
+        ok: true,
+        data: {
+          targetKind: 'selector',
+          selector: 'label=Foo',
+          x: 30,
+          y: 40,
+          gesture: 'longpress',
+          durationMs: 500,
+          message: 'Long pressed label=Foo (30, 40)',
+        },
+      };
+    }
+    if (req.command === 'find') {
+      return {
+        ok: true,
+        data: { ref: '@e5', refsGeneration: 42, text: 'Hello' },
+      };
+    }
+    throw new Error(`unexpected command: ${req.command}`);
+  });
+  const client = createAgentDeviceClient(setup.config, { transport: setup.transport });
+
+  const press = await client.interactions.press({ ref: '@e5' });
+  const click = await client.interactions.click({ x: 10, y: 20, button: 'secondary' });
+  const fill = await client.interactions.fill({ ref: '@e5', text: 'hello' });
+  const longPress = await client.interactions.longPress({
+    selector: 'label=Foo',
+    durationMs: 500,
+  });
+  const find = await client.interactions.find({
+    locator: 'label',
+    query: 'Foo',
+    action: 'getText',
+  });
+
+  const pressType: Equal<typeof press, PressCommandResponseData> = true;
+  const clickType: Equal<typeof click, ClickCommandResponseData> = true;
+  const fillType: Equal<typeof fill, FillCommandResponseData> = true;
+  const longPressType: Equal<typeof longPress, LongPressCommandResponseData> = true;
+  const findType: Equal<typeof find, FindCommandResponseData> = true;
+
+  assert.equal(press.targetKind, 'ref');
+  assert.equal(press.ref, 'e5');
+  assert.equal(press.x, 88);
+  assert.equal(press.y, 99);
+
+  assert.equal(click.targetKind, 'point');
+  assert.equal(click.x, 10);
+  assert.equal(click.y, 20);
+  assert.equal(click.button, 'secondary');
+
+  assert.equal(fill.targetKind, 'ref');
+  assert.equal(fill.ref, 'e5');
+  assert.equal(fill.text, 'hello');
+
+  assert.equal(longPress.targetKind, 'selector');
+  assert.equal(longPress.selector, 'label=Foo');
+  assert.equal(longPress.gesture, 'longpress');
+  assert.equal(longPress.durationMs, 500);
+
+  assert.equal(find.ref, '@e5');
+  assert.equal(find.refsGeneration, 42);
+  assert.equal(find.text, 'Hello');
+
+  assert.deepEqual(
+    [pressType, clickType, fillType, longPressType, findType],
+    [true, true, true, true, true],
+  );
+});

src/contracts/interaction.ts

@@ -1,4 +1,6 @@
 import type { Point, SnapshotNode } from '../kernel/snapshot.ts';
+import type { ResponseCost } from '../kernel/contracts.ts';
+import type { ClickButton } from '../core/click-button.ts';
 
 export type SelectorTarget = {
   kind: 'selector';
@@ -228,46 +230,120 @@ export type SettleObservation = {
   hint?: string;
 };
 
-export type PressCommandResult = ResolvedInteractionTarget & {
-  backendResult?: Record<string, unknown>;
+/**
+ * Public daemon response data shared by press/click/fill/longpress.
+ * `buildInteractionResponseData` emits this shape (ADR 0011 Layer 2):
+ * `targetKind` discriminates the resolved target, identity fields are FLAT
+ * (`ref`, `selector`, `x`, `y`), and per-command extras ride alongside.
+ */
+type TouchResponseDataBase = {
   message?: string;
   warning?: string;
-  evidence?: InteractionEvidence;
-  settle?: SettleObservation;
-  // Public response fields added by the daemon response layer.
   x?: number;
   y?: number;
-  button?: string;
+  referenceWidth?: number;
+  referenceHeight?: number;
+  evidence?: InteractionEvidence;
+  settle?: SettleObservation;
+  resolution?: ResolutionDisclosure;
+  cost?: ResponseCost;
+};
+
+type TouchResponsePoint = TouchResponseDataBase & {
+  targetKind: 'point';
+  x: number;
+  y: number;
+};
+
+type TouchResponseRef = TouchResponseDataBase & {
+  targetKind: 'ref';
+  ref: string;
+  refLabel?: string;
+  selectorChain?: string[];
+  targetHittable?: boolean;
+  hint?: string;
+};
+
+type TouchResponseSelector = TouchResponseDataBase & {
+  targetKind: 'selector';
+  selector: string;
+  selectorChain?: string[];
+  refLabel?: string;
+  targetHittable?: boolean;
+  hint?: string;
+};
+
+type TouchPressExtras = {
+  button?: ClickButton;
   count?: number;
   intervalMs?: number;
   holdMs?: number;
   jitterPx?: number;
   doubleTap?: boolean;
 };
 
+export type PressCommandResponseData =
+  | (TouchResponsePoint & TouchPressExtras)
+  | (TouchResponseRef & TouchPressExtras)
+  | (TouchResponseSelector & TouchPressExtras);
+
+export type ClickCommandResponseData = PressCommandResponseData;
+
+type TouchFillExtras = {
+  text: string;
+  delayMs?: number;
+};
+
+export type FillCommandResponseData =
+  | (TouchResponsePoint & TouchFillExtras)
+  | (TouchResponseRef & TouchFillExtras)
+  | (TouchResponseSelector & TouchFillExtras);
+
+type TouchLongPressExtras = {
+  durationMs?: number;
+  gesture: 'longpress';
+};
+
+export type LongPressCommandResponseData =
+  | (TouchResponsePoint & TouchLongPressExtras)
+  | (TouchResponseRef & TouchLongPressExtras)
+  | (TouchResponseSelector & TouchLongPressExtras);
+
+/**
+ * Internal runtime result for press/click. The daemon response layer turns
+ * this into `PressCommandResponseData` via `buildInteractionResponseData`.
+ */
+export type PressCommandResult = ResolvedInteractionTarget & {
+  backendResult?: Record<string, unknown>;
+  message?: string;
+  warning?: string;
+  evidence?: InteractionEvidence;
+  settle?: SettleObservation;
+};
+
+/**
+ * Internal runtime result for fill. The daemon response layer turns this into
+ * `FillCommandResponseData` via `buildInteractionResponseData`.
+ */
 export type FillCommandResult = ResolvedInteractionTarget & {
   text: string;
   warning?: string;
   backendResult?: Record<string, unknown>;
   message?: string;
   evidence?: InteractionEvidence;
   settle?: SettleObservation;
-  // Public response fields added by the daemon response layer.
-  x?: number;
-  y?: number;
-  delayMs?: number;
 };
 
+/**
+ * Internal runtime result for longpress. The daemon response layer turns this
+ * into `LongPressCommandResponseData` via `buildInteractionResponseData`.
+ */
 export type LongPressCommandResult = ResolvedInteractionTarget & {
   durationMs?: number;
   backendResult?: Record<string, unknown>;
   message?: string;
   warning?: string;
   settle?: SettleObservation;
-  // Public response fields added by the daemon response layer.
-  x?: number;
-  y?: number;
-  gesture?: 'longpress';
 };
 
 /**
@@ -278,7 +354,7 @@ export type LongPressCommandResult = ResolvedInteractionTarget & {
  * (ADR 0014). The shape is intentionally a flat, optional-field record because
  * the action positional changes which fields are present.
  */
-export type FindCommandResult = {
+export type FindCommandResponseData = {
   ref?: string;
   refsGeneration?: number;
   found?: true;

src/core/command-descriptor/__tests__/command-result.test.ts

@@ -1,8 +1,9 @@
 import { expect, test } from 'vitest';
 import type {
-  FillCommandResult,
-  LongPressCommandResult,
-  PressCommandResult,
+  FillCommandResponseData,
+  LongPressCommandResponseData,
+  PressCommandResponseData,
+  FindCommandResponseData,
 } from '../../../contracts/interaction.ts';
 import type { BootCommandResult, ShutdownCommandResult } from '../../../contracts/device.ts';
 import type { ViewportCommandResult } from '../../../contracts/viewport.ts';
@@ -36,10 +37,11 @@ type Equal<A, B> =
   (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
 
 test('seeded CommandResult entries resolve to their existing contract result types', () => {
-  const press: Equal<CommandResult<'press'>, PressCommandResult> = true;
-  const click: Equal<CommandResult<'click'>, PressCommandResult> = true;
-  const fill: Equal<CommandResult<'fill'>, FillCommandResult> = true;
-  const longPress: Equal<CommandResult<'longpress'>, LongPressCommandResult> = true;
+  const press: Equal<CommandResult<'press'>, PressCommandResponseData> = true;
+  const click: Equal<CommandResult<'click'>, PressCommandResponseData> = true;
+  const fill: Equal<CommandResult<'fill'>, FillCommandResponseData> = true;
+  const longPress: Equal<CommandResult<'longpress'>, LongPressCommandResponseData> = true;
+  const find: Equal<CommandResult<'find'>, FindCommandResponseData> = true;
   const boot: Equal<CommandResult<'boot'>, BootCommandResult> = true;
   const shutdown: Equal<CommandResult<'shutdown'>, ShutdownCommandResult> = true;
   const viewport: Equal<CommandResult<'viewport'>, ViewportCommandResult> = true;
@@ -69,6 +71,7 @@ test('seeded CommandResult entries resolve to their existing contract result typ
     click,
     fill,
     longPress,
+    find,
     boot,
     shutdown,
     viewport,
@@ -116,6 +119,7 @@ test('seeded CommandResult entries resolve to their existing contract result typ
     true,
     true,
     true,
+    true,
   ]);
 });
 

src/core/command-descriptor/command-result.ts

@@ -1,8 +1,9 @@
 import type {
-  FillCommandResult,
-  FindCommandResult,
-  LongPressCommandResult,
-  PressCommandResult,
+  ClickCommandResponseData,
+  FillCommandResponseData,
+  FindCommandResponseData,
+  LongPressCommandResponseData,
+  PressCommandResponseData,
 } from '../../contracts/interaction.ts';
 import type { BootCommandResult, ShutdownCommandResult } from '../../contracts/device.ts';
 import type { ViewportCommandResult } from '../../contracts/viewport.ts';
@@ -45,11 +46,11 @@ import type { ReplayCommandResult, ReplaySuiteResult } from '../../contracts/rep
  * re-read of the handler's literal return; see the per-type docstrings.
  */
 export interface CommandResultMap {
-  press: PressCommandResult;
-  click: PressCommandResult;
-  fill: FillCommandResult;
-  longpress: LongPressCommandResult;
-  find: FindCommandResult;
+  press: PressCommandResponseData;
+  click: ClickCommandResponseData;
+  fill: FillCommandResponseData;
+  longpress: LongPressCommandResponseData;
+  find: FindCommandResponseData;
   boot: BootCommandResult;
   shutdown: ShutdownCommandResult;
   viewport: ViewportCommandResult;