refactor: migrate wait to request-bound runtime

Author: thymikee

packages/contracts/src/facades/platform.ts

@@ -226,6 +226,8 @@ export type {
   SelectorCaptureRuntimePlan,
   SnapshotRuntimePlan,
 } from '../platform-runtime-operations.ts';
+export { waitObservesDevice } from '../wait-runtime-plan.ts';
+export type { WaitRuntimeTarget } from '../wait-runtime-plan.ts';
 export type {
   PlatformRuntimeHost,
   PlatformRuntimeModule,
@@ -258,8 +260,16 @@ export type {
 export {
   bindLocalSnapshotInteractor,
   bindProviderSnapshotInteractor,
+  captureSnapshotSignal,
   snapshotRuntimeOperationFacts,
 } from '../snapshot-runtime.ts';
+export { findTextRuntimeOperationFacts } from '../find-text-runtime.ts';
+export type {
+  FindTextInput,
+  FindTextResult,
+  FindTextRuntimeOperationFacts,
+  FindTextRuntimeOperations,
+} from '../find-text-runtime.ts';
 export type {
   CaptureSnapshotInput,
   LocalSnapshotInteractorResolver,

packages/contracts/src/find-text-runtime.ts

@@ -0,0 +1,44 @@
+import type { SessionSurface } from './session-surface.ts';
+import type { RuntimeOperationFact } from './platform-runtime.ts';
+import type { SnapshotRuntimeExecution } from './snapshot-runtime.ts';
+
+/**
+ * A native, tree-independent answer to "is this text on screen right now".
+ *
+ * `surface` and `appBundleId` are the session facts an owner may need to decide it cannot answer
+ * for this request — the daemon does not pre-filter by family, so an owner that has no reading
+ * for the current surface reports `found: false` and the caller consults the canonical tree.
+ */
+export type FindTextInput = Readonly<{
+  text: string;
+  options?: Readonly<{ appBundleId?: string; surface?: SessionSurface }>;
+  execution?: SnapshotRuntimeExecution;
+  /** Per-capture cancellation; see `CaptureSnapshotInput.signal`. */
+  signal?: AbortSignal;
+}>;
+
+/**
+ * Deliberately asymmetric, and the reason this is a `preferred` operation rather than a second
+ * execution path (ADR 0019 §2/§9):
+ *
+ * - `found: true` is **authoritative** — the owner observed the text and the wait is satisfied.
+ * - `found: false` is **not** authoritative. It means "not proven by this owner", and the caller
+ *   must still consult the canonical tree in the same poll. An owner that cannot answer at all
+ *   reports `false` rather than throwing.
+ *
+ * So the required tree path remains semantically complete on its own: removing this operation
+ * changes how fast a satisfied wait returns, never whether it can be satisfied.
+ */
+export type FindTextResult = Readonly<{ found: boolean }>;
+
+export type FindTextRuntimeOperations = Readonly<{
+  findText(input: FindTextInput): Promise<FindTextResult>;
+}>;
+
+export type FindTextRuntimeOperationFacts = Readonly<{ findText: RuntimeOperationFact }>;
+
+export function findTextRuntimeOperationFacts(
+  input: FindTextRuntimeOperationFacts,
+): FindTextRuntimeOperationFacts {
+  return Object.freeze({ findText: input.findText });
+}

packages/contracts/src/interactor-types.ts

@@ -232,6 +232,17 @@ export type Interactor = {
     point: Point,
     options?: { appBundleId?: string; surface?: SessionSurface; signal?: AbortSignal },
   ): Promise<string | undefined>;
+  /**
+   * Native text-presence reading, when the backend has one that does not require a tree capture.
+   * A `true` answer is authoritative; anything else means "not proven here" and the caller
+   * consults the canonical tree (see `FindTextResult`).
+   */
+  findText?(
+    text: string,
+    options?: { appBundleId?: string; signal?: AbortSignal },
+  ): Promise<{
+    found: boolean;
+  }>;
   gestureViewport?(): Promise<Rect>;
   back(mode?: BackMode): Promise<void>;
   home(): Promise<void>;

packages/contracts/src/platform-runtime-operations.ts

@@ -14,6 +14,7 @@ import type { ScreenRecordingRuntimeHost } from './screen-recording-runtime-host
 import type { ScreenRecordingRuntimeOperations } from './screen-recording-runtime.ts';
 import type { ScreenshotRuntimeOperations } from './screenshot-runtime.ts';
 import type { SnapshotRuntimeHost, SnapshotRuntimeOperations } from './snapshot-runtime.ts';
+import type { FindTextRuntimeOperations } from './find-text-runtime.ts';
 import type { ViewportRuntimeOperations } from './viewport-runtime.ts';
 import type { ElementTextRuntimeOperations } from './element-text-runtime.ts';
 import type {
@@ -47,6 +48,7 @@ export type PlatformRuntimeOperations = AppLogRuntimeOperations &
   ScreenRecordingRuntimeOperations &
   ScreenshotRuntimeOperations &
   SnapshotRuntimeOperations &
+  FindTextRuntimeOperations &
   ViewportRuntimeOperations &
   ElementTextRuntimeOperations &
   DeviceReadinessRuntimeOperations &
@@ -91,11 +93,11 @@ const captureSnapshotWithCustomActionsWithoutActiveAppUse = defineUse({
  */
 const selectorCaptureUse = defineUse({
   required: ['captureSnapshot'],
-  preferred: ['readTextAtPoint'],
+  preferred: ['readTextAtPoint', 'findText'],
 });
 const selectorCaptureWithoutActiveAppUse = defineUse({
   required: ['captureSnapshot', 'captureSnapshotWithoutActiveApp'],
-  preferred: ['readTextAtPoint'],
+  preferred: ['readTextAtPoint', 'findText'],
 });
 
 /**

packages/contracts/src/platform-runtime-unavailable.ts

@@ -12,6 +12,7 @@ import type {
 } from './platform-runtime.ts';
 import { screenshotRuntimeOperationFacts } from './screenshot-runtime.ts';
 import { snapshotRuntimeOperationFacts } from './snapshot-runtime.ts';
+import { findTextRuntimeOperationFacts } from './find-text-runtime.ts';
 import { viewportRuntimeOperationFacts } from './viewport-runtime.ts';
 import { elementTextRuntimeOperationFacts } from './element-text-runtime.ts';
 
@@ -105,6 +106,10 @@ export function createUnavailablePlatformRuntimeFacts(
         customActions: snapshot,
         withoutActiveApp: snapshot,
       }),
+      // The preferred text reading starts unavailable for every family, on the same sentinel as
+      // capture: an owner that has a native reading declares it explicitly, and one that does not
+      // sends every text wait to the canonical tree.
+      ...findTextRuntimeOperationFacts({ findText: snapshot }),
       ...viewportRuntimeOperationFacts({ setViewport: viewport }),
       ...elementTextRuntimeOperationFacts({ readTextAtPoint: elementText }),
       ensureReady: readiness,

packages/contracts/src/snapshot-runtime.test.ts

@@ -2,7 +2,11 @@ import assert from 'node:assert/strict';
 import { test } from 'vitest';
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import type { Interactor, RunnerContext } from './interactor-types.ts';
-import { bindLocalSnapshotInteractor, bindProviderSnapshotInteractor } from './snapshot-runtime.ts';
+import {
+  bindLocalSnapshotInteractor,
+  bindProviderSnapshotInteractor,
+  captureSnapshotSignal,
+} from './snapshot-runtime.ts';
 
 const device: DeviceInfo = {
   id: 'snapshot-device',
@@ -66,3 +70,69 @@ test('provider snapshot binding fails closed when its selected owner loses the i
       error.message === 'Provider-owned snapshot operation has no bound provider interactor.',
   );
 });
+
+// ---------------------------------------------------------------------------
+// Per-capture cancellation (`CaptureSnapshotInput.signal`). A `DeviceBinding`'s
+// signal is fixed at bind time, but `wait` binds once and polls many times, so
+// each poll must be able to cancel its own capture without cancelling the
+// binding. These are the contract-level halves of that claim; the poll-deadline
+// behaviour itself is proven end to end in `src/daemon/__tests__/wait-runtime.test.ts`.
+// ---------------------------------------------------------------------------
+
+test('a capture with no per-capture signal receives the binding signal itself, not a wrapper', () => {
+  const binding = new AbortController().signal;
+
+  // Identity, deliberately: a wrapper would satisfy a deep-equal while quietly changing
+  // cancellation semantics for every single-capture consumer (`snapshot`, `diff`), which pass
+  // no signal at all.
+  assert.equal(captureSnapshotSignal(binding, {}), binding);
+  assert.equal(captureSnapshotSignal(binding, { options: { appBundleId: 'x' } }), binding);
+});
+
+test('binding-level cancellation still aborts a capture that carries its own signal', () => {
+  const binding = new AbortController();
+  const perCapture = new AbortController();
+
+  const composed = captureSnapshotSignal(binding.signal, { signal: perCapture.signal });
+
+  assert.equal(composed.aborted, false);
+  binding.abort();
+  // The composition adds a second way to cancel; it must not have replaced the first.
+  assert.equal(composed.aborted, true);
+});
+
+test('a per-capture signal aborts its own capture without aborting the binding', () => {
+  const binding = new AbortController();
+  const perCapture = new AbortController();
+
+  const composed = captureSnapshotSignal(binding.signal, { signal: perCapture.signal });
+  perCapture.abort(new DOMException('Wait deadline exceeded', 'TimeoutError'));
+
+  assert.equal(composed.aborted, true);
+  // The binding outlives the poll: the next poll of the same wait still has a live binding.
+  assert.equal(binding.signal.aborted, false);
+});
+
+test('the shared interactor binding composes the per-capture signal it is handed', async () => {
+  const binding = new AbortController();
+  const perCapture = new AbortController();
+  let capturedSignal: AbortSignal | undefined;
+  const operations = bindLocalSnapshotInteractor({
+    device,
+    signal: binding.signal,
+    resolveInteractor: async () =>
+      ({
+        snapshot: async (options: Parameters<Interactor['snapshot']>[0]) => {
+          capturedSignal = options?.signal;
+          return { backend: 'android', nodes: [] };
+        },
+      }) as unknown as Interactor,
+  });
+
+  await operations.captureSnapshot({ signal: perCapture.signal });
+
+  assert.ok(capturedSignal, 'the interactor must receive a signal');
+  assert.equal(capturedSignal.aborted, false);
+  perCapture.abort(new DOMException('Wait deadline exceeded', 'TimeoutError'));
+  assert.equal(capturedSignal.aborted, true, 'the poll deadline must reach the platform');
+});

packages/contracts/src/snapshot-runtime.ts

@@ -13,12 +13,34 @@ export type { SnapshotResult } from './interactor-types.ts';
 /** Runner metadata needed by the selected snapshot implementation, without request-owned state. */
 export type SnapshotRuntimeExecution = Readonly<Omit<RunnerContext, 'appBundleId' | 'signal'>>;
 
-/** Neutral snapshot intent. The request binding supplies cancellation and exact-owner authority. */
+/** Neutral snapshot intent. The request binding supplies exact-owner authority. */
 export type CaptureSnapshotInput = Readonly<{
   options?: Readonly<Omit<SnapshotOptions, 'signal'>>;
   execution?: SnapshotRuntimeExecution;
+  /**
+   * Per-capture cancellation, composed with the binding's own signal. A command that captures
+   * once needs nothing here. A POLLING command does: `wait` enforces each poll's remaining
+   * budget by aborting that capture and then waiting for it to quiesce (it deliberately does
+   * not race-and-abandon, so a late capture cannot mutate session state or keep a helper).
+   * Without this a stalled capture consumes the whole request instead of producing the poll's
+   * stalled-capture verdict.
+   */
+  signal?: AbortSignal;
 }>;
 
+/**
+ * The one place a per-capture signal joins its binding's: the binding always cancels, the
+ * caller may cancel sooner — identically for app and desktop surface captures.
+ */
+export function captureSnapshotSignal(
+  bindingSignal: AbortSignal,
+  input: CaptureSnapshotInput,
+): AbortSignal {
+  return input.signal === undefined
+    ? bindingSignal
+    : AbortSignal.any([bindingSignal, input.signal]);
+}
+
 export type SnapshotRuntimeOperations = Readonly<{
   captureSnapshot(input: CaptureSnapshotInput): Promise<SnapshotResult>;
   captureSnapshotWithCustomActions(input: CaptureSnapshotInput): Promise<SnapshotResult>;
@@ -81,10 +103,11 @@ function bindSnapshotInteractor(
   params: SnapshotInteractorBindingParams,
 ): SnapshotRuntimeOperations {
   const captureSnapshot = async (input: CaptureSnapshotInput) => {
+    const signal = captureSnapshotSignal(params.signal, input);
     const runner: RunnerContext = {
       ...input.execution,
       appBundleId: input.options?.appBundleId,
-      signal: params.signal,
+      signal,
     };
     const interactor =
       params.ownership === 'local'
@@ -97,7 +120,7 @@ function bindSnapshotInteractor(
         { reason: 'provider-runtime-interactor-missing', deviceId: params.device.id },
       );
     }
-    return await interactor.snapshot({ ...input.options, signal: params.signal });
+    return await interactor.snapshot({ ...input.options, signal });
   };
   return Object.freeze({
     captureSnapshot,

packages/contracts/src/wait-runtime-plan.ts

@@ -0,0 +1,15 @@
+/** The normalized wait target, independent of the positional grammar that produced it. */
+export type WaitRuntimeTarget = 'sleep' | 'text' | 'ref' | 'selector' | 'stable';
+
+/**
+ * Which wait shapes reach a device at all. A duration wait observes nothing, so it never asks
+ * for a plan and therefore never admits or binds — the absence of platform execution for that
+ * shape is stated here rather than left as an incidental branch in the handler.
+ *
+ * Every other shape polls the selector family's ordinary capture plan
+ * (`resolveSelectorCaptureRuntimePlan`); `wait` contributes no plan of its own, and its preferred
+ * `findText` rides that plan's preferred set beside `get`'s `readTextAtPoint`.
+ */
+export function waitObservesDevice(target: WaitRuntimeTarget): boolean {
+  return target !== 'sleep';
+}

packages/platform-android/src/runtime.ts

@@ -15,6 +15,7 @@ import {
   elementTextRuntimeOperationFacts,
   localRuntimeOwner,
   screenshotRuntimeOperationFacts,
+  findTextRuntimeOperationFacts,
   snapshotRuntimeOperationFacts,
   viewportRuntimeOperationFacts,
 } from '@agent-device/contracts/platform';
@@ -153,6 +154,8 @@ export function createAndroidPlatformRuntime(host: PlatformRuntimeHost): Platfor
         ...screenshotRuntimeOperationFacts({
           capture: device.kind === 'simulator' ? screenshotKindUnavailable : available,
         }),
+        // No native text reading: every text wait on this owner polls the canonical tree.
+        ...findTextRuntimeOperationFacts({ findText: snapshotKindUnavailable }),
         ...viewportRuntimeOperationFacts({ setViewport: viewportUnavailable }),
         // uiautomator reads text at a point through the same adb path the snapshot uses, so the
         // synthetic `simulator` row is the only Android kind without a live read.

packages/platform-apple/src/runtime-snapshot.ts

@@ -1,9 +1,14 @@
 import type {
   CaptureSnapshotInput,
+  FindTextInput,
+  FindTextResult,
   PlatformRuntimeHost,
   PlatformRuntimeOperations,
 } from '@agent-device/contracts/platform';
-import { bindLocalSnapshotInteractor } from '@agent-device/contracts/platform';
+import {
+  bindLocalSnapshotInteractor,
+  captureSnapshotSignal,
+} from '@agent-device/contracts/platform';
 import { isMacOs, type DeviceInfo } from '@agent-device/kernel/device';
 
 /** Apple-owned selection between app snapshots and explicit macOS surface snapshots. */
@@ -22,7 +27,11 @@ export function bindAppleSnapshotRuntime(
       input.options?.surface !== undefined &&
       input.options.surface !== 'app'
     ) {
-      return await host.snapshot.captureSurface(request.device, input.options, request.signal);
+      return await host.snapshot.captureSurface(
+        request.device,
+        input.options,
+        captureSnapshotSignal(request.signal, input),
+      );
     }
     return await appSnapshot.captureSnapshot(input);
   };
@@ -37,3 +46,44 @@ type SnapshotRuntimeOperation = Pick<
   PlatformRuntimeOperations,
   'captureSnapshot' | 'captureSnapshotWithCustomActions' | 'captureSnapshotWithoutActiveApp'
 >;
+
+/**
+ * The runner's native text reading. Every condition under which Apple cannot answer lives here
+ * rather than in the daemon, which is the point of the migration: no caller inspects the family,
+ * the surface, or the session to decide whether to consult it.
+ *
+ * - No tracked app bundle id: the runner query is scoped to an application, so there is nothing
+ *   to ask about.
+ * - macOS on an explicit non-app surface: the runner reads the *application*, so a positive
+ *   answer would describe the wrong surface. Reporting `false` sends the poll to the desktop
+ *   surface capture, which is the reading that matches the request.
+ *
+ * Both report `found: false` — "not proven here" — never an error, so the caller's canonical tree
+ * remains the complete path (ADR 0019 section 2).
+ */
+export function bindAppleFindTextRuntime(
+  host: PlatformRuntimeHost,
+  request: Readonly<{ device: DeviceInfo; signal: AbortSignal }>,
+): Pick<PlatformRuntimeOperations, 'findText'> {
+  return Object.freeze({
+    findText: async (input: FindTextInput): Promise<FindTextResult> => {
+      const appBundleId = input.options?.appBundleId;
+      if (appBundleId === undefined) return { found: false };
+      if (isMacOs(request.device) && input.options?.surface !== undefined) {
+        if (input.options.surface !== 'app') return { found: false };
+      }
+      const signal =
+        input.signal === undefined
+          ? request.signal
+          : AbortSignal.any([request.signal, input.signal]);
+      signal.throwIfAborted();
+      const interactor = await host.localInteractors.resolve(request.device, {
+        ...input.execution,
+        appBundleId,
+        signal,
+      });
+      if (!interactor.findText) return { found: false };
+      return await interactor.findText(input.text, { appBundleId, signal });
+    },
+  });
+}