Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 0 additions & 5 deletions .fallowrc.json
Original file line number Diff line number Diff line change
Expand Up @@ -253,11 +253,6 @@
"file": "packages/daemon/src/execution/interaction/index.ts",
"exports": ["refMutationAdmissionResponse", "handleFindCommands", "handleInteractionCommands"]
},
{
// The macOS façade members are read off the memoized loadMacOs() loader in src/platform-runtime-apple-application-tools.ts. Fallow cannot connect that dynamic member read to the re-exports.
"file": "packages/platform-apple/src/macos-facade.ts",
"exports": ["resolveFrontmostMacOsApp", "runMacOsAlertAction"]
},
{
// answerSimulatorLaunchConfirmation is called from packages/platform-apple/src/lifecycle.ts through the lazy loadLaunchConfirmation() import; Fallow cannot connect the dynamic member read.
"file": "packages/platform-apple/src/launch-confirmation.ts",
Expand Down
24 changes: 24 additions & 0 deletions .github/actions/smoke-macos/action.yml
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,30 @@ runs:
uses: ./.github/actions/run-gate
with:
gate: macos-helper
# macOS desktop automation is a managed plugin, so the replay lane serves it from the plugin
# store built here. The plugin is installed once and then answers the visible reply below and
# the macOS gate, which is the evidence that a user's `plugins add` install drives this Mac. The
# store is the one the gate action stages the replay pair into: that step merges its selections
# into the same config, so the daemon the gate starts carries all three packages.
- name: Install the macOS platform plugin
shell: bash
run: |
set -euo pipefail
# The steps below drive the packed entry point, which refuses to run without the build it
# ships beside it, and `plugins add` is a CLI command.
pnpm build
pnpm --filter @agent-device/macos pack --out "$RUNNER_TEMP/macos-plugin.tgz"
mkdir -p "$RUNNER_TEMP/agent-device-replay-plugins"
export AGENT_DEVICE_HOME="$RUNNER_TEMP/agent-device-replay-plugins"
echo "AGENT_DEVICE_HOME=$AGENT_DEVICE_HOME" >> "$GITHUB_ENV"
node bin/agent-device.mjs plugins add "$RUNNER_TEMP/macos-plugin.tgz" --json
node bin/agent-device.mjs plugins list --json
# The store is read when a daemon starts, so the first macOS command below must not reach a
# daemon that was already running without this entry.
pnpm clean:daemon
printf '\n$ agent-device devices --platform macos\n'
node bin/agent-device.mjs devices --platform macos --json
pnpm clean:daemon
- name: Run macOS integration test
uses: ./.github/actions/run-gate
with:
Expand Down
8 changes: 7 additions & 1 deletion .jscpd-native.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
{
"path": ["apple", "android", "packages/platform-linux/linux", "packages/host-swift/swift"],
"path": [
"apple",
"android",
"packages/platform-linux/linux",
"packages/platform-macos/macos-helper",
"packages/host-swift/swift"
],
"format": ["swift", "objectivec", "kotlin", "java", "python"],
"formatsExts": { "objectivec": ["m", "h"] },
"mode": "weak",
Expand Down
4 changes: 3 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,9 @@ project's `.tmp/`. The scripts refuse other override paths. They clean build out
directory for every platform and keep other entries. Without an override, they clean the default
directory under `~/.agent-device/apple-runner/derived`.

Android and macOS helper builds remain separate because they require their native toolchains:
Android and macOS helper builds remain separate because they require their native toolchains.
The macOS helper is part of the `@agent-device/macos` plugin and lives in
`packages/platform-macos/macos-helper`:

```bash
pnpm build:android
Expand Down
8 changes: 4 additions & 4 deletions contracts/fixtures/runner-requests.json
Original file line number Diff line number Diff line change
Expand Up @@ -74,12 +74,12 @@
{"name": "ios-simulator.runner-snapshot-bridge.describe", "producer": "packages/platform-apple/src/__tests__/index-runner-requests.test.ts", "request": {"command": "snapshotBridge", "appBundleId": "com.example.app", "snapshotBridge": {"verb": "describe", "requestId": "<requestId>", "generation": "41:1700000000.000001", "expectedPid": 41, "expectedProcessStartTime": "1700000000.000001", "maxDepth": 128, "maxNodes": 5000, "maxDurationMs": 4000, "maxResponseBytes": 4194304}, "commandId": "<commandId>"}},
{"name": "ios-simulator.runner-snapshot-bridge.describe-surface-hosts", "producer": "packages/platform-apple/src/__tests__/index-runner-requests.test.ts", "request": {"command": "snapshotBridge", "appBundleId": "com.example.app", "snapshotBridge": {"verb": "describe", "requestId": "<requestId>", "generation": "41:1700000000.000001", "expectedPid": 41, "expectedProcessStartTime": "1700000000.000001", "maxDepth": 128, "maxNodes": 5000, "maxDurationMs": 4000, "maxResponseBytes": 4194304, "surfaceHostExecutables": ["SafariViewService.app/SafariViewService", "PassbookUIService.app/PassbookUIService"]}, "commandId": "<commandId>"}},
{"name": "ios-simulator.runner-snapshot-bridge.target", "producer": "packages/platform-apple/src/__tests__/index-runner-requests.test.ts", "request": {"command": "snapshotBridge", "appBundleId": "com.example.app", "snapshotBridge": {"verb": "target", "requestId": "<requestId>", "maxDurationMs": 4000}, "commandId": "<commandId>"}},
{"name": "macos.desktop-scroll.amount", "producer": "packages/platform-apple/src/__tests__/index-runner-requests.test.ts", "request": {"command": "desktopScroll", "direction": "down", "amount": 0.5, "durationMs": 300, "appBundleId": "com.example.app", "commandId": "<commandId>"}},
{"name": "macos.desktop-scroll.pixels", "producer": "packages/platform-apple/src/__tests__/index-runner-requests.test.ts", "request": {"command": "desktopScroll", "direction": "up", "pixels": 200, "durationMs": 300, "appBundleId": "com.example.app", "commandId": "<commandId>"}},
{"name": "macos.desktop-scroll.amount", "producer": "packages/platform-macos/src/runner-commands-runner-requests.test.ts", "request": {"command": "desktopScroll", "direction": "down", "amount": 0.5, "durationMs": 300, "appBundleId": "com.example.app"}},
{"name": "macos.desktop-scroll.pixels", "producer": "packages/platform-macos/src/runner-commands-runner-requests.test.ts", "request": {"command": "desktopScroll", "direction": "up", "pixels": 200, "durationMs": 300, "appBundleId": "com.example.app"}},
{"name": "macos.interactions-drag.single", "producer": "packages/platform-apple/src/__tests__/index-runner-requests.test.ts", "request": {"command": "drag", "x": 100, "y": 400, "x2": 100, "y2": 200, "durationMs": 120, "appBundleId": "com.example.app", "commandId": "<commandId>"}},
{"name": "macos.interactions-focus.coordinate", "producer": "packages/platform-apple/src/__tests__/index-runner-requests.test.ts", "request": {"command": "tap", "x": 10, "y": 20, "appBundleId": "com.example.app", "commandId": "<commandId>"}},
{"name": "macos.interactions-mouse-click.middle", "producer": "packages/platform-apple/src/__tests__/index-runner-requests.test.ts", "request": {"command": "mouseClick", "x": 10, "y": 20, "button": "middle", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
{"name": "macos.interactions-mouse-click.secondary", "producer": "packages/platform-apple/src/__tests__/index-runner-requests.test.ts", "request": {"command": "mouseClick", "x": 10, "y": 20, "button": "secondary", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
{"name": "macos.interactions-mouse-click.middle", "producer": "packages/platform-macos/src/runner-commands-runner-requests.test.ts", "request": {"command": "mouseClick", "x": 10, "y": 20, "button": "middle", "appBundleId": "com.example.app"}},
{"name": "macos.interactions-mouse-click.secondary", "producer": "packages/platform-macos/src/runner-commands-runner-requests.test.ts", "request": {"command": "mouseClick", "x": 10, "y": 20, "button": "secondary", "appBundleId": "com.example.app"}},
{"name": "macos.interactions-single-press-tap.coordinate", "producer": "packages/platform-apple/src/__tests__/index-runner-requests.test.ts", "request": {"command": "tap", "x": 10, "y": 20, "appBundleId": "com.example.app", "commandId": "<commandId>"}},
{"name": "macos.interactions-tap.coordinate", "producer": "packages/platform-apple/src/__tests__/index-runner-requests.test.ts", "request": {"command": "tap", "x": 10, "y": 20, "appBundleId": "com.example.app", "commandId": "<commandId>"}},
{"name": "macos.recording-start.output-path", "producer": "src/__tests__/screen-recording-runner-requests.test.ts", "request": {"command": "recordStart", "outPath": "/tmp/capture.mp4", "appBundleId": "com.example.app"}},
Expand Down
11 changes: 10 additions & 1 deletion docs/adr/0034-provider-plugin-registry.md
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,16 @@ Required families retain completeness checks.
Optional families may be absent.
The current composition is in `src/platform-runtime.ts` and the family contract is in `packages/contracts/src/platform-module.ts`.
macOS desktop remains a leaf under the single `apple` identity.
How the desktop runtime plugs into that identity is decided in [#4675](https://github.com/callstack/agent-device/issues/4675).
The managed `@agent-device/macos` package holds that leaf with the claim `{ kind: 'platform', family: 'apple', appleOs: 'macos' }` ([#4675](https://github.com/callstack/agent-device/issues/4675)).
A `platform` claim key has an optional `appleOs` part for this claim, and no other family uses it.
The bundled Apple owner keeps the `apple` claim for iOS and tvOS.
At each macOS branch, the owner calls the operations the installed leaf binds.
The leaf owns the two macOS app backends, the desktop surfaces, and the Swift helper.
The owner keeps the one Apple XCTest runner with its macOS wire cases, and gives the leaf a runner capability that is bound to one device.
The owner also gives the leaf the Apple tool routes of the calling request, so the leaf starts no command of its own.
When the package is absent, a macOS request returns `plugin-not-installed` with the install command, and discovery that names no platform omits the Mac.
A leaf of its own family was rejected because device identity would move out of the kernel and split the runner.
A plugin-owned runner was rejected because it needs a second Swift dispatch, build, and signing pipeline.
ADR 0019 defines the platform runtime boundary.

Version 2 plugins receive a typed incompatibility outcome without a compatibility shim.
Expand Down
1 change: 1 addition & 0 deletions docs/agents/device-verification.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,7 @@ The first run needs XCUITest automation permission.

When you change Apple targets, synchronize the kernel model, runtime-fact admission, dispatch,
discovery, and xctestrun preparation. Simulator-set scoping must not hide the host macOS target.
Before a macOS device check, install `@agent-device/macos`.
HarmonyOS has no provisioned CI device or HDC. Mocked tests do not replace local hardware evidence.
Before you run a live smoke harness, read its entry file under `test/integration/` for environment requirements.

Expand Down
49 changes: 49 additions & 0 deletions docs/evidence/macos-platform-plugin-extraction-2026-11-21.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
# macOS platform plugin extraction — measurements (2026-11-21)

Issue #4675 moves macOS desktop automation and the `macos-helper` Swift package out of the published
core into the managed platform plugin `@agent-device/macos`. This note records the measurements for
that change. The decision is in ADR 0034.

## Packed core size

Both trees were built from a clean worktree with `pnpm install --frozen-lockfile && pnpm build`, then
packed with `npm pack --ignore-scripts --json`. Neither build ran `pnpm build:package`, so neither
pack holds the packaged runner source or the Android helper artifacts. The comparison is valid for
the difference, not for the published total.

| Tree | Commit | Packed | Unpacked | Files |
| --- | --- | --- | --- | --- |
| `0.22` base | `80c44fe45e` | 1 638 382 B | 5 275 885 B | 645 |
| This change | `4dc93c9ff8` | 1 616 982 B | 5 188 827 B | 629 |
| Difference | | −21 400 B | −87 058 B | −16 |

The base pack holds 11 `apple/macos-helper` files (116 181 B). The changed pack holds none.
The `@agent-device/macos` tarball is 70 157 B packed, 26 files, about 308 KB unpacked.

The core keeps the shared Apple XCTest runner with its macOS wire cases and Swift desktop branches,
by the decision in #4675. That is why the JavaScript in `dist/src` changes by only −14 620 B: the
Apple owner still holds the runner routes, and the leaf port replaces the moved modules.

## Live check on a Mac

Host: macOS on Apple silicon, Xcode 27.1. The packed core was installed into an empty directory under
the repository `.tmp/`, with `AGENT_DEVICE_HOME` and `AGENT_DEVICE_STATE_DIR` inside it.

| Step | Result |
| --- | --- |
| `devices --platform macos`, no plugin | `UNSUPPORTED_PLATFORM`, `plugin-not-installed`, install hint |
| `plugins add ./macos.tgz` | installed and listed |
| `devices --platform macos` | the host Mac, `target=desktop` |
| `open TextEdit --platform macos` | opened |
| `snapshot -i`, default XCTest backend | blocked: see below |
| `open`, `snapshot -i`, `screenshot`, `press @e33`, `close`, native backend | all succeeded |

The default XCTest backend did not start on this host. `prepare ios-runner --platform macos` answered
`COMMAND_FAILED: Runner did not accept connection (xcodebuild exited early)`, and the runner log
holds `Failed to initialize for UI testing: ... "Timed out while enabling automation mode."`. The
host has not authorized XCUITest Automation Mode. The runner is the shared core runner and this
change does not alter it. The permission was not granted and the check did not work around it.

With `AGENT_DEVICE_MACOS_APP_BACKEND=native`, the plugin built its helper from the packed
`macos-helper` source and served the whole flow: a 45-node interactive snapshot of TextEdit, a
1172x976 window screenshot, and a press on a snapshot ref. The daemon was stopped afterwards.
1 change: 1 addition & 0 deletions examples/sdk/tsconfig.json
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,7 @@
{ "path": "../../packages/platform-apple" },
{ "path": "../../packages/platform-harmonyos" },
{ "path": "../../packages/platform-linux" },
{ "path": "../../packages/platform-macos" },
{ "path": "../../packages/platform-vega" },
{ "path": "../../packages/platform-web" },
{ "path": "../../packages/plugins" },
Expand Down
15 changes: 5 additions & 10 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -115,12 +115,12 @@
"build:android-ime-helper": "AGENT_DEVICE_ANDROID_HELPER=ime sh ./scripts/build-android-helper.sh $(node -p \"require('./package.json').version\") .tmp/android-ime-helper",
"package:android-ime-helper": "AGENT_DEVICE_ANDROID_HELPER=ime sh ./scripts/package-android-helper.sh $(node -p \"require('./package.json').version\") .tmp/android-ime-helper",
"package:android-ime-helper:npm": "rm -rf android/ime-helper/dist && AGENT_DEVICE_ANDROID_HELPER=ime sh ./scripts/package-android-helper.sh $(node -p \"require('./package.json').version\") android/ime-helper/dist",
"build:macos-helper": "node --experimental-strip-types scripts/swift-toolchain-tmpdir.ts swift build -c release --package-path apple/macos-helper",
"build:macos-helper:clean": "node --experimental-strip-types scripts/swift-toolchain-tmpdir.ts swift package --package-path apple/macos-helper clean && pnpm build:macos-helper",
"test:macos-helper": "node --experimental-strip-types scripts/swift-toolchain-tmpdir.ts swift test --package-path apple/macos-helper",
"build:macos-helper": "node --experimental-strip-types scripts/swift-toolchain-tmpdir.ts swift build -c release --package-path packages/platform-macos/macos-helper",
"build:macos-helper:clean": "node --experimental-strip-types scripts/swift-toolchain-tmpdir.ts swift package --package-path packages/platform-macos/macos-helper clean && pnpm build:macos-helper",
"test:macos-helper": "node --experimental-strip-types scripts/swift-toolchain-tmpdir.ts swift test --package-path packages/platform-macos/macos-helper",
"check:macos-helper": "pnpm build:macos-helper && pnpm test:macos-helper",
"prepare:publish-assets": "node scripts/prepare-publish-assets.mjs",
"build:package": "pnpm build && pnpm package:xcuitest && pnpm build:macos-helper:clean && pnpm prepare:publish-assets",
"build:package": "pnpm build && pnpm package:xcuitest && pnpm prepare:publish-assets",
"package:npm": "pnpm build:package && pnpm check:package",
"release:prepare": "rm -rf .tmp/release && pnpm check:mcp-metadata && pnpm build:package && pnpm check:package -- --pack-destination .tmp/release && node scripts/release-workspace.mjs pack",
"ad": "node bin/agent-device.mjs",
Expand Down Expand Up @@ -166,7 +166,7 @@
"depgraph:test": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test scripts/depgraph/model.test.ts scripts/depgraph/entries.test.ts scripts/depgraph/import-graph.test.ts scripts/depgraph/affected.test.ts scripts/depgraph/structure-summary.test.ts tools/depgraph-view/*.test.mjs",
"check:production-exports": "fallow dead-code --config fallow-production-exports.json --production --unused-exports --fail-on-issues",
"check:bundle-owner-files": "node --experimental-strip-types scripts/check-bundle-owner-files.ts",
"check:package": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test packages/maestro/test/package-artifact.test.mjs packages/maestro/test/package-smoke.mjs packages/replay/test/package-smoke.mjs packages/platform-web/test/package-smoke.mjs packages/platform-vega/test/package-smoke.mjs packages/platform-harmonyos/test/package-smoke.mjs packages/platform-linux/test/package-smoke.mjs && node --experimental-strip-types scripts/check-package.ts",
"check:package": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test packages/maestro/test/package-artifact.test.mjs packages/maestro/test/package-smoke.mjs packages/replay/test/package-smoke.mjs packages/platform-web/test/package-smoke.mjs packages/platform-vega/test/package-smoke.mjs packages/platform-harmonyos/test/package-smoke.mjs packages/platform-linux/test/package-smoke.mjs packages/platform-macos/test/package-smoke.mjs && node --experimental-strip-types scripts/check-package.ts",
"check:provider-plugin": "node scripts/check-provider-plugin.mjs",
"check:command-docs": "vitest run --project unit-core test/repo-guards/command-doc-coverage.test.ts test/repo-guards/command-doc-generated-blocks.test.ts test/repo-guards/reason-tables.test.ts",
"generate:command-docs": "node --experimental-strip-types scripts/command-docs/generate.ts --write",
Expand Down Expand Up @@ -237,11 +237,6 @@
"files": [
"bin",
"dist",
"apple/macos-helper",
"!apple/macos-helper/**/.build",
"!apple/macos-helper/Tests/**",
"apple/macos-helper/Tests/AgentDeviceMacOSHelperTests/PackStub.swift",
"apple/macos-helper/Tests/AgentDeviceMacOSInputTests/PackStub.swift",
"apple/snapshot-bridge",
"apple/fold-helper",
"android/snapshot-helper/dist",
Expand Down
7 changes: 5 additions & 2 deletions packages/build-config/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -47,21 +47,24 @@ export function assertManagedPlatformPluginFactory(
packageJsonUrl: URL,
factory: () => {
apiVersion: unknown;
contributes: readonly { kind: unknown; family: unknown }[];
contributes: readonly { kind: unknown; family: unknown; appleOs?: unknown }[];
},
label: string,
): void {
const manifest = JSON.parse(readFileSync(packageJsonUrl, 'utf8'))['agent-device'] as {
apiVersion: unknown;
platform: unknown;
appleOs?: unknown;
};
const { apiVersion, contributes } = factory();
const [platform] = contributes;
if (
apiVersion !== manifest.apiVersion ||
contributes.length !== 1 ||
platform?.kind !== 'platform' ||
platform.family !== manifest.platform
platform.family !== manifest.platform ||
// A leaf claim is part of the pair: a package that narrows must contribute the same leaf.
platform.appleOs !== manifest.appleOs
) {
throw new Error(`The managed ${label} factory must match its package claim`);
}
Expand Down
4 changes: 4 additions & 0 deletions packages/contracts/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -312,6 +312,10 @@
"types": "./src/logs-runtime-plan.ts",
"default": "./src/logs-runtime-plan.ts"
},
"./macos-platform-leaf": {
"types": "./src/macos-platform-leaf.ts",
"default": "./src/macos-platform-leaf.ts"
},
"./linux-tool-provider": {
"types": "./src/linux-tool-provider.ts",
"default": "./src/linux-tool-provider.ts"
Expand Down
Loading
Loading