From 73135a7c7e64817719ecd3c43e152f2eda685fd4 Mon Sep 17 00:00:00 2001 From: Samanyu Das Date: Sun, 22 Nov 2026 21:57:08 +1030 Subject: [PATCH 1/5] refactor(contracts): share one systemSurfaceBundleId projection --- packages/capture-kit/src/snapshot-baseline.ts | 13 +------------ packages/contracts/src/facades/snapshot.ts | 1 + packages/contracts/src/snapshot-model.test.ts | 12 ++++++++++++ packages/contracts/src/snapshot-model.ts | 17 +++++++++++++++++ .../src/core/deferred-interaction-outcome.ts | 15 ++------------- 5 files changed, 33 insertions(+), 25 deletions(-) diff --git a/packages/capture-kit/src/snapshot-baseline.ts b/packages/capture-kit/src/snapshot-baseline.ts index 5b5b2141a1..220b026172 100644 --- a/packages/capture-kit/src/snapshot-baseline.ts +++ b/packages/capture-kit/src/snapshot-baseline.ts @@ -1,18 +1,7 @@ -import type { SnapshotState, SnapshotSystemSurface } from '@agent-device/contracts/snapshot-model'; +import { systemSurfaceBundleId, type SnapshotState } from '@agent-device/contracts/snapshot-model'; import type { SurfaceScopedNodes } from '@agent-device/contracts/interaction'; import type { SnapshotPresentation } from '@agent-device/kernel/snapshot'; -function systemSurfaceBundleId(surface: SnapshotSystemSurface | undefined): string | undefined { - if (surface === undefined) return undefined; - switch (surface.kind) { - case 'android-system-overlay': - return undefined; - case 'web-auth': - case 'payment': - return surface.bundleId; - } -} - /** Reproduce a populated baseline's view; without one, capture the interactive view. */ export function postActionPresentation( baseline: SurfaceScopedNodes | undefined, diff --git a/packages/contracts/src/facades/snapshot.ts b/packages/contracts/src/facades/snapshot.ts index 66ed7b5e70..30fa7ceeb4 100644 --- a/packages/contracts/src/facades/snapshot.ts +++ b/packages/contracts/src/facades/snapshot.ts @@ -12,6 +12,7 @@ export { } from '../snapshot-scope.ts'; export { snapshotStateProvenance, + systemSurfaceBundleId, isSnapshotBackend, usesMobileSnapshotPresentation, inheritPostGestureOutcome, diff --git a/packages/contracts/src/snapshot-model.test.ts b/packages/contracts/src/snapshot-model.test.ts index b439308ec6..76ad64300e 100644 --- a/packages/contracts/src/snapshot-model.test.ts +++ b/packages/contracts/src/snapshot-model.test.ts @@ -2,6 +2,7 @@ import { expect, test } from 'vitest'; import { readPostGestureOutcome, snapshotStateProvenance, + systemSurfaceBundleId, type SnapshotProvenance, type SnapshotStateProvenance, } from './snapshot-model.ts'; @@ -45,3 +46,14 @@ test('readPostGestureOutcome reads every outcome kind off the wire and drops mal ).toBeUndefined(); expect(readPostGestureOutcome('loading')).toBeUndefined(); }); + +test('systemSurfaceBundleId projects the host identity only for host-bearing surfaces', () => { + expect(systemSurfaceBundleId(undefined)).toBeUndefined(); + expect(systemSurfaceBundleId({ kind: 'android-system-overlay' })).toBeUndefined(); + expect(systemSurfaceBundleId({ kind: 'web-auth', bundleId: 'com.apple.SafariViewService' })).toBe( + 'com.apple.SafariViewService', + ); + expect(systemSurfaceBundleId({ kind: 'payment', bundleId: 'com.apple.PassbookUIService' })).toBe( + 'com.apple.PassbookUIService', + ); +}); diff --git a/packages/contracts/src/snapshot-model.ts b/packages/contracts/src/snapshot-model.ts index 6a4f5c6f48..607a66a0c7 100644 --- a/packages/contracts/src/snapshot-model.ts +++ b/packages/contracts/src/snapshot-model.ts @@ -98,6 +98,23 @@ export type SnapshotSystemSurface = | Readonly<{ kind: 'android-system-overlay' }> | IosSystemSurfaceProvenance; +/** + * The surface host bundle id a capture scopes comparisons by, or undefined when the surface carries + * no host identity (ordinary app content or an Android system overlay). + */ +export function systemSurfaceBundleId( + surface: SnapshotSystemSurface | undefined, +): string | undefined { + if (surface === undefined) return undefined; + switch (surface.kind) { + case 'android-system-overlay': + return undefined; + case 'web-auth': + case 'payment': + return surface.bundleId; + } +} + export type SnapshotState = { nodes: SnapshotNode[]; createdAt: number; diff --git a/packages/daemon/src/core/deferred-interaction-outcome.ts b/packages/daemon/src/core/deferred-interaction-outcome.ts index c690e661ef..c1d297520f 100644 --- a/packages/daemon/src/core/deferred-interaction-outcome.ts +++ b/packages/daemon/src/core/deferred-interaction-outcome.ts @@ -4,7 +4,7 @@ import type { PostOpenObservation } from '@agent-device/contracts/application-li import type { SnapshotCaptureAnnotations } from '@agent-device/contracts/capture'; import { isApplePlatform, isMobilePlatform } from '@agent-device/kernel/device'; import { formatRole, type SnapshotNode } from '@agent-device/kernel/snapshot'; -import type { SnapshotState, SnapshotSystemSurface } from '@agent-device/contracts/snapshot-model'; +import type { SnapshotState } from '@agent-device/contracts/snapshot-model'; import type { MovingTargetBaseline } from '@agent-device/contracts/runtime-contract'; import { captureAndroidFreshnessRecoveredAttempt, @@ -28,7 +28,7 @@ import { runPostGestureStabilityLoop, type PostGestureStabilityOutcome, } from '@agent-device/capture-kit/post-gesture-stability'; -import { isViewportRootNode } from '@agent-device/contracts/snapshot'; +import { isViewportRootNode, systemSurfaceBundleId } from '@agent-device/contracts/snapshot'; import type { DeferredSurface, SessionState } from './session-state.ts'; /** @@ -127,17 +127,6 @@ function restTree(snapshot: SnapshotState | undefined): SurfaceScopedNodes | und }; } -function systemSurfaceBundleId(surface: SnapshotSystemSurface | undefined): string | undefined { - if (surface === undefined) return undefined; - switch (surface.kind) { - case 'android-system-overlay': - return undefined; - case 'web-auth': - case 'payment': - return surface.bundleId; - } -} - /** Whether this mutation left an unsettled surface for the capture side to steady. */ function markSurfaceStabilization( session: SessionState, From bba9e37e54261047cb85a1d1b4a3ea944215997c Mon Sep 17 00:00:00 2001 From: Samanyu Das Date: Sun, 22 Nov 2026 21:58:14 +1030 Subject: [PATCH 2/5] refactor(snapshot): map Android system-surface metadata through one helper --- .../src/commands/capture/runtime/snapshot.ts | 18 +++++++++--------- packages/contracts/src/facades/snapshot.ts | 1 + packages/contracts/src/snapshot-model.test.ts | 10 ++++++++++ packages/contracts/src/snapshot-model.ts | 7 +++++++ packages/daemon/src/core/snapshot-capture.ts | 6 +++--- 5 files changed, 30 insertions(+), 12 deletions(-) diff --git a/packages/command-runtime/src/commands/capture/runtime/snapshot.ts b/packages/command-runtime/src/commands/capture/runtime/snapshot.ts index 0cb9d20c1c..382ce93065 100644 --- a/packages/command-runtime/src/commands/capture/runtime/snapshot.ts +++ b/packages/command-runtime/src/commands/capture/runtime/snapshot.ts @@ -10,7 +10,7 @@ import { } from '@agent-device/contracts/capture'; import { AppError } from '@agent-device/kernel/errors'; import { isSameSnapshotPresentation } from '@agent-device/kernel/snapshot'; -import { normalizeType } from '@agent-device/contracts/snapshot'; +import { androidSnapshotSystemSurface, normalizeType } from '@agent-device/contracts/snapshot'; import { snapshotProducerFacts } from '@agent-device/contracts/snapshot-producers'; import type { PresentedSurface, @@ -250,11 +250,16 @@ async function captureRuntimeSnapshot( ...(options.observeOnly === undefined ? {} : { observeOnly: options.observeOnly }), }, ); + const annotations = snapshotCaptureAnnotationsFrom(result); + const systemSurface = + result.snapshot.systemSurface ?? androidSnapshotSystemSurface(annotations.androidSnapshot); + const presented = ensureSnapshotPresentationKey(result.snapshot, options); const snapshot = copySnapshotClickabilityEvidence( result.snapshot, - ensureSnapshotPresentationKey(result.snapshot, options), + systemSurface && presented.systemSurface === undefined + ? { ...presented, systemSurface } + : presented, ); - const annotations = snapshotCaptureAnnotationsFrom(result); const warningTime = now(runtime); return { snapshot, @@ -350,12 +355,7 @@ function buildSnapshotWarnings(params: { ); if (reactNativeOverlayWarning) warnings.push(reactNativeOverlayWarning); - const systemSurfaceWarning = systemSurfaceDisclosure( - params.snapshot.systemSurface ?? - (params.annotations.androidSnapshot?.systemSurfaceOnly === true - ? { kind: 'android-system-overlay' } - : undefined), - ); + const systemSurfaceWarning = systemSurfaceDisclosure(params.snapshot.systemSurface); if (systemSurfaceWarning) warnings.push(systemSurfaceWarning); const recentDropWarning = formatRecentSnapshotDropWarning(params); diff --git a/packages/contracts/src/facades/snapshot.ts b/packages/contracts/src/facades/snapshot.ts index 30fa7ceeb4..ab256d8721 100644 --- a/packages/contracts/src/facades/snapshot.ts +++ b/packages/contracts/src/facades/snapshot.ts @@ -13,6 +13,7 @@ export { export { snapshotStateProvenance, systemSurfaceBundleId, + androidSnapshotSystemSurface, isSnapshotBackend, usesMobileSnapshotPresentation, inheritPostGestureOutcome, diff --git a/packages/contracts/src/snapshot-model.test.ts b/packages/contracts/src/snapshot-model.test.ts index 76ad64300e..ffd3c31c4f 100644 --- a/packages/contracts/src/snapshot-model.test.ts +++ b/packages/contracts/src/snapshot-model.test.ts @@ -1,5 +1,6 @@ import { expect, test } from 'vitest'; import { + androidSnapshotSystemSurface, readPostGestureOutcome, snapshotStateProvenance, systemSurfaceBundleId, @@ -57,3 +58,12 @@ test('systemSurfaceBundleId projects the host identity only for host-bearing sur 'com.apple.PassbookUIService', ); }); + +test('androidSnapshotSystemSurface maps systemSurfaceOnly to the shared Android overlay arm', () => { + expect(androidSnapshotSystemSurface(undefined)).toBeUndefined(); + expect(androidSnapshotSystemSurface({})).toBeUndefined(); + expect(androidSnapshotSystemSurface({ systemSurfaceOnly: false })).toBeUndefined(); + expect(androidSnapshotSystemSurface({ systemSurfaceOnly: true })).toEqual({ + kind: 'android-system-overlay', + }); +}); diff --git a/packages/contracts/src/snapshot-model.ts b/packages/contracts/src/snapshot-model.ts index 607a66a0c7..ccf24fac47 100644 --- a/packages/contracts/src/snapshot-model.ts +++ b/packages/contracts/src/snapshot-model.ts @@ -115,6 +115,13 @@ export function systemSurfaceBundleId( } } +/** Maps Android capture metadata to the shared occluding-surface model when it reports one. */ +export function androidSnapshotSystemSurface( + metadata: Readonly<{ systemSurfaceOnly?: boolean }> | undefined, +): SnapshotSystemSurface | undefined { + return metadata?.systemSurfaceOnly === true ? { kind: 'android-system-overlay' } : undefined; +} + export type SnapshotState = { nodes: SnapshotNode[]; createdAt: number; diff --git a/packages/daemon/src/core/snapshot-capture.ts b/packages/daemon/src/core/snapshot-capture.ts index eefb0c3ef4..86c6a474f4 100644 --- a/packages/daemon/src/core/snapshot-capture.ts +++ b/packages/daemon/src/core/snapshot-capture.ts @@ -18,6 +18,7 @@ import { type SnapshotViewportSize, } from '@agent-device/kernel/snapshot'; import { + androidSnapshotSystemSurface, type SnapshotCaptureProvenance, type SnapshotState, } from '@agent-device/contracts/snapshot-model'; @@ -152,9 +153,8 @@ async function captureSnapshotAttempt(params: CaptureSnapshotParams): Promise Date: Sun, 22 Nov 2026 21:58:59 +1030 Subject: [PATCH 3/5] refactor(platform-apple): drop duplicate iOS system-surface warning from runner --- .../__tests__/interactor-runner-provider.test.ts | 16 ++++++++++++++++ packages/platform-apple/src/interactor.ts | 9 +++------ 2 files changed, 19 insertions(+), 6 deletions(-) diff --git a/packages/platform-apple/src/__tests__/interactor-runner-provider.test.ts b/packages/platform-apple/src/__tests__/interactor-runner-provider.test.ts index 56610c69f1..c1aa877ff9 100644 --- a/packages/platform-apple/src/__tests__/interactor-runner-provider.test.ts +++ b/packages/platform-apple/src/__tests__/interactor-runner-provider.test.ts @@ -337,6 +337,22 @@ test('a message-less runner capture leaves its disclosures to the verdict', asyn assert.deepEqual(result.quality?.collapsedLeafIndexes, [1]); }); +test('a runner system-surface capture carries provenance without duplicating the disclosure warning', async () => { + const systemSurface = { bundleId: 'com.apple.SafariViewService', kind: 'web-auth' } as const; + const interactor = createAppleInteractor(IOS_SIMULATOR, {}, createLiveTestHostEnvironment(), { + hasLiveSession: () => true, + runCommand: async () => ({ + ...runnerResultFor({ command: 'snapshot' }), + systemSurface, + }), + }); + + const result = presentedSnapshot(await interactor.snapshot()); + + assert.deepEqual(result.systemSurface, systemSurface); + assert.equal('warnings' in result, false); +}); + test('macOS app snapshots preserve runner nodes outside the iOS presentation engine', async () => { const nodes = [{ index: 0, type: 'Other', value: 'checkbox, unchecked' }]; const interactor = createAppleInteractor(MACOS_DEVICE, {}, createLiveTestHostEnvironment(), { diff --git a/packages/platform-apple/src/interactor.ts b/packages/platform-apple/src/interactor.ts index 310e45a2b9..c89fdcf9d7 100644 --- a/packages/platform-apple/src/interactor.ts +++ b/packages/platform-apple/src/interactor.ts @@ -52,7 +52,6 @@ import { readAppleSnapshotResult, type AppleRunnerSnapshotResult, } from './snapshot-presentation.ts'; -import { iosSystemSurfaceDisclosure } from '@agent-device/contracts/ios-system-surface'; import { iosTargetActivationDisclosure } from '@agent-device/contracts/ios-target-activation'; const SNAPSHOT_RESPONSE_REASONS = { @@ -409,9 +408,9 @@ function assertReportedRunnerSnapshotNodes( /** * Agent-facing warnings for a runner capture: a legacy runner's message text when it carried no - * quality verdict, the shared disclosure when the capture describes an in-place system surface - * (e.g. the web sign-in or Apple Pay sheet) rather than the app itself (#2438), and the disclosure - * when this capture's own command had to bring the session app back to the foreground (#2682). + * quality verdict, and the disclosure when this capture's own command had to bring the session app + * back to the foreground (#2682). In-place system-surface disclosures (#2438) are derived once from + * `SnapshotState.systemSurface` at the shared consumer seams (`systemSurfaceDisclosure`). */ function runnerSnapshotWarnings(result: AppleRunnerSnapshotResult): string[] { const warnings: string[] = []; @@ -421,8 +420,6 @@ function runnerSnapshotWarnings(result: AppleRunnerSnapshotResult): string[] { ); } if (!result.quality && result.message) warnings.push(result.message); - if (result.systemSurface) - warnings.push(iosSystemSurfaceDisclosure(result.systemSurface.bundleId)); if (result.targetActivation) warnings.push(iosTargetActivationDisclosure(result.targetActivation)); return warnings; From 2b8ab943e71c603801ffb90455f1946567b27cd0 Mon Sep 17 00:00:00 2001 From: Samanyu Das Date: Sun, 22 Nov 2026 23:44:28 +1030 Subject: [PATCH 4/5] fix(snapshot): preserve snapshot-baseline eager closure and drop runtime stamp --- packages/capture-kit/src/snapshot-baseline.ts | 13 ++++++++++++- .../src/commands/capture/runtime/snapshot.ts | 14 ++++++-------- packages/platform-apple/src/interactor.ts | 3 +-- 3 files changed, 19 insertions(+), 11 deletions(-) diff --git a/packages/capture-kit/src/snapshot-baseline.ts b/packages/capture-kit/src/snapshot-baseline.ts index 220b026172..5b5b2141a1 100644 --- a/packages/capture-kit/src/snapshot-baseline.ts +++ b/packages/capture-kit/src/snapshot-baseline.ts @@ -1,7 +1,18 @@ -import { systemSurfaceBundleId, type SnapshotState } from '@agent-device/contracts/snapshot-model'; +import type { SnapshotState, SnapshotSystemSurface } from '@agent-device/contracts/snapshot-model'; import type { SurfaceScopedNodes } from '@agent-device/contracts/interaction'; import type { SnapshotPresentation } from '@agent-device/kernel/snapshot'; +function systemSurfaceBundleId(surface: SnapshotSystemSurface | undefined): string | undefined { + if (surface === undefined) return undefined; + switch (surface.kind) { + case 'android-system-overlay': + return undefined; + case 'web-auth': + case 'payment': + return surface.bundleId; + } +} + /** Reproduce a populated baseline's view; without one, capture the interactive view. */ export function postActionPresentation( baseline: SurfaceScopedNodes | undefined, diff --git a/packages/command-runtime/src/commands/capture/runtime/snapshot.ts b/packages/command-runtime/src/commands/capture/runtime/snapshot.ts index 382ce93065..dcb5440d40 100644 --- a/packages/command-runtime/src/commands/capture/runtime/snapshot.ts +++ b/packages/command-runtime/src/commands/capture/runtime/snapshot.ts @@ -250,16 +250,11 @@ async function captureRuntimeSnapshot( ...(options.observeOnly === undefined ? {} : { observeOnly: options.observeOnly }), }, ); - const annotations = snapshotCaptureAnnotationsFrom(result); - const systemSurface = - result.snapshot.systemSurface ?? androidSnapshotSystemSurface(annotations.androidSnapshot); - const presented = ensureSnapshotPresentationKey(result.snapshot, options); const snapshot = copySnapshotClickabilityEvidence( result.snapshot, - systemSurface && presented.systemSurface === undefined - ? { ...presented, systemSurface } - : presented, + ensureSnapshotPresentationKey(result.snapshot, options), ); + const annotations = snapshotCaptureAnnotationsFrom(result); const warningTime = now(runtime); return { snapshot, @@ -355,7 +350,10 @@ function buildSnapshotWarnings(params: { ); if (reactNativeOverlayWarning) warnings.push(reactNativeOverlayWarning); - const systemSurfaceWarning = systemSurfaceDisclosure(params.snapshot.systemSurface); + const systemSurfaceWarning = systemSurfaceDisclosure( + params.snapshot.systemSurface ?? + androidSnapshotSystemSurface(params.annotations.androidSnapshot), + ); if (systemSurfaceWarning) warnings.push(systemSurfaceWarning); const recentDropWarning = formatRecentSnapshotDropWarning(params); diff --git a/packages/platform-apple/src/interactor.ts b/packages/platform-apple/src/interactor.ts index c89fdcf9d7..49c66201f7 100644 --- a/packages/platform-apple/src/interactor.ts +++ b/packages/platform-apple/src/interactor.ts @@ -409,8 +409,7 @@ function assertReportedRunnerSnapshotNodes( /** * Agent-facing warnings for a runner capture: a legacy runner's message text when it carried no * quality verdict, and the disclosure when this capture's own command had to bring the session app - * back to the foreground (#2682). In-place system-surface disclosures (#2438) are derived once from - * `SnapshotState.systemSurface` at the shared consumer seams (`systemSurfaceDisclosure`). + * back to the foreground (#2682). */ function runnerSnapshotWarnings(result: AppleRunnerSnapshotResult): string[] { const warnings: string[] = []; From 983ebbc7ea275848f7f8585bd55e12c63cbada73 Mon Sep 17 00:00:00 2001 From: Samanyu Das Date: Mon, 23 Nov 2026 00:34:38 +1030 Subject: [PATCH 5/5] docs(capture-kit): note intentional ADR 0027 duplicate in snapshot-baseline --- packages/capture-kit/src/snapshot-baseline.ts | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/capture-kit/src/snapshot-baseline.ts b/packages/capture-kit/src/snapshot-baseline.ts index 5b5b2141a1..d7e10d9e3f 100644 --- a/packages/capture-kit/src/snapshot-baseline.ts +++ b/packages/capture-kit/src/snapshot-baseline.ts @@ -2,6 +2,8 @@ import type { SnapshotState, SnapshotSystemSurface } from '@agent-device/contrac import type { SurfaceScopedNodes } from '@agent-device/contracts/interaction'; import type { SnapshotPresentation } from '@agent-device/kernel/snapshot'; +// Intentionally duplicates `@agent-device/contracts/snapshot-model`'s `systemSurfaceBundleId` +// so this module keeps a type-only import and stays within ADR 0027's eager-closure budget. function systemSurfaceBundleId(surface: SnapshotSystemSurface | undefined): string | undefined { if (surface === undefined) return undefined; switch (surface.kind) {