Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
8b8fa2c
test: a network phone under android.networkDevices is enrolled under …
V3RON Nov 16, 2026
9e4d445
feat(android): a network phone is enrolled under its address with its…
V3RON Nov 16, 2026
899b3c8
test: an emulator is refused unsupported-kind whatever its transport …
V3RON Nov 16, 2026
aa13b51
feat(android): a network transport whose qemu flags say emulator is r…
V3RON Nov 16, 2026
6e2aab9
test: an enrolled network phone reads present only with its recorded …
V3RON Nov 16, 2026
9737c79
feat(android): a network phone reads present only when its hardware s…
V3RON Nov 16, 2026
61918d6
test: the worker connects an enrolled host:port phone the adb server …
V3RON Nov 16, 2026
fa7257f
feat(android): the worker connects an enrolled host:port phone adb no…
V3RON Nov 16, 2026
3fb7501
test: with the key on the host-level list includes network phones and…
V3RON Nov 16, 2026
9d850e1
feat(android): the host-level list includes network phones under andr…
V3RON Nov 16, 2026
e001888
test: a reclaim of a network phone uninstalls nothing unless the phon…
V3RON Nov 16, 2026
4fdb1df
feat(android): a reclaim of a network phone checks its hardware seria…
V3RON Nov 16, 2026
92fa191
test: android.networkDevices takes true or false, defaults to false a…
V3RON Nov 16, 2026
0d5293c
feat(android): the worker config key android.networkDevices (#1605)
V3RON Nov 16, 2026
55ac553
test: a leased network phone gets its address as the serial, scoped p…
V3RON Nov 16, 2026
09c8beb
docs: network phones under android.networkDevices in the safety rules…
V3RON Nov 16, 2026
8d05a6b
refactor(android): one emulator refusal (#1605)
V3RON Nov 16, 2026
bc75164
test: a network phone's unreadable hardware serial at reclaim names i…
V3RON Nov 16, 2026
c3a3c2f
docs: trim the Android manual under its cap, safety rules 1 and 7 nam…
V3RON Nov 16, 2026
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
15 changes: 11 additions & 4 deletions docs/internal/agent-rules/safety.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,12 @@ never enforce them only inside an individual rule or driver.
erases, reboots, shuts down or unpairs a physical device, and never runs
a command on one that is not enrolled, except `device add`'s read-only
inspection, which a worker with `devices.autoEnroll` runs on a phone plugged in
by USB ([ADR 0073](../adr/0073-a-worker-may-enrol-the-phones-plugged-into-it.md) §5)
by USB ([ADR 0073](../adr/0073-a-worker-may-enrol-the-phones-plugged-into-it.md) §5), or under
`android.networkDevices` one reached over the network ([ADR 0080](../adr/0080-an-android-worker-may-enrol-phones-reached-over-the-network.md) §4),
and, under `android.networkDevices`, `adb connect` for an enrolled
address and the read-only inspection and hardware-serial read that may
reach a phone answering at an enrolled address that is not the enrolled
one ([ADR 0080](../adr/0080-an-android-worker-may-enrol-phones-reached-over-the-network.md) §5)
([ADR 0022](../adr/0022-a-physical-device-is-a-second-device-type-the-core-knows.md) §3).

A component (an iOS simulator runtime or an Android system image) is
Expand Down Expand Up @@ -99,8 +104,9 @@ never enforce them only inside an individual rule or driver.
scoped by `simctl --set` and `ANDROID_AVD_HOME` — never the machine's
default device locations. (Under iOS `deviceSet: "default"`, reality is Xcode's set read through
devices whose durable mark names this instance, ADR 0048 §2.) For a physical device, reality is the platform
tool's list of USB devices, read only for enrolled IDs. The one read made beyond
enrolled IDs is the host-level USB list, `listAttachedPhysical()` (ADR 0073 §5).
tool's list of USB devices (under `android.networkDevices`, network phones too), read only for enrolled IDs. The one read made beyond
enrolled IDs is the host-level USB list, `listAttachedPhysical()` (ADR 0073 §5); under
`android.networkDevices` it also lists network transports, never an emulator (ADR 0080 §5).
8. **Ownership is proven, never inferred.** A device is Simlock's because it
lives inside a validly-marked Simlock root, not because of what it is
called. `Driver.listManaged()` must answer from root membership; the
Expand All @@ -112,7 +118,8 @@ never enforce them only inside an individual rule or driver.
physical device is Simlock's because an admin enrolled it, or the worker did under
`devices.autoEnroll`;
`listPresentPhysical()` answers only for enrolled IDs; `listAttachedPhysical()`
is the exception, a host-level list that names no phone and sends nothing to one.
is the exception, a host-level list that names no phone and sends nothing to one;
under `android.networkDevices` it also lists network transports (ADR 0080 §5).
9. **Root validation fails closed.** If a device root is missing its marker,
carries another instance's marker, is a symlink, or has the wrong owner or
permissions, that platform's driver does not start and Simlock reports why. Under iOS
Expand Down
2 changes: 1 addition & 1 deletion docs/internal/agent-rules/toolchain.md
Original file line number Diff line number Diff line change
Expand Up @@ -212,7 +212,7 @@ The machine can run a line only if:
| Physical iOS | `uname -s` is `Darwin`; `SIMLOCK_PHYSICAL_IOS` is the UDID of an iPhone on USB (trusted, Developer Mode on, unlocked, Auto-Lock Never); `SIMLOCK_PHYSICAL_IOS_APP` is a `.app` signed for it. `/usr/libexec/PlistBuddy -c "Print :CFBundleShortVersionString" /Library/Developer/PrivateFrameworks/CoreDevice.framework/Resources/Info.plist` prints a version whose major is 642 or later (streaming a phone needs the CoreDevice of Xcode 27 or later; the framework is machine-wide and does not follow `xcode-select`). DeviceHub and Xcode are not running during the lane. The stream cases need the iPhone on iOS 27 or later; an older iPhone runs the refusal case instead. Run `scripts/slow-e2e.sh --physical e2e/slow-ios-physical.test.ts` |
| iOS foldable | the iOS check; `xcrun simctl list runtimes` lists iOS 27.1 or later and `xcrun simctl list devicetypes` lists `iPhone Duo`; `SIMLOCK_E2E_AGENT_DEVICE` names agent-device 0.21.35 or later; `command -v ffmpeg` finds it. Run `scripts/slow-e2e.sh e2e/slow-ios-foldable.test.ts` |
| agent-device through simlock | `node -v` is 22.12.0 or later (agent-device's own minimum); the iOS check and `uname -m` is `arm64` (the fixture app is arm64 only), or the Android check; `SIMLOCK_E2E_AGENT_DEVICE` (in `.slow-lane.env`) is the absolute path of `bin/agent-device.mjs` in an install of the agent-device version `package.json` pins for `@agent-device/proxy` (`npm install -g agent-device@<version>`, or a checkout at tag `v<version>` built with `pnpm install && pnpm build && pnpm build:android`, the last building the Android snapshot helper); room for two devices: `node -p "os.totalmem() / 2**30"` prints at least 7 for iOS or 12 for Android (simlock's 4 GiB OS reserve plus two of its default 1.5 GiB iOS or 4 GiB Android per-device budgets). Run `scripts/slow-e2e.sh e2e/slow-agent-device.test.ts` or `scripts/slow-e2e.sh e2e/slow-agent-device-gateway.test.ts` |
| Physical Android | `command -v adb` finds it; `adb devices -l` lists `$SIMLOCK_PHYSICAL_ANDROID` on a USB transport (a `usb:` field) in state `device`; `SIMLOCK_PHYSICAL_ANDROID_APK` names an APK. Run `scripts/slow-e2e.sh --physical e2e/slow-android-physical.test.ts` |
| Physical Android | `command -v adb` finds it; `adb devices -l` lists `$SIMLOCK_PHYSICAL_ANDROID` on a USB transport (a `usb:` field) in state `device`; `SIMLOCK_PHYSICAL_ANDROID_APK` names an APK; `SIMLOCK_PHYSICAL_ANDROID_NETWORK` beside it names an address `adb devices -l` lists in state `device` with no `usb:` field, for the network case. Run `scripts/slow-e2e.sh --physical e2e/slow-android-physical.test.ts` |
| agent-device with a physical phone | the agent-device through simlock checks above (the Android or iOS one), and the Physical Android checks with `SIMLOCK_PHYSICAL_ANDROID`, or the Physical iOS checks with `SIMLOCK_PHYSICAL_IOS`; for iOS also `SIMLOCK_E2E_IOS_TEAM_ID` and `SIMLOCK_E2E_IOS_BUNDLE_ID` (in `.slow-lane.env`); set `SIMLOCK_E2E_IOS_PROVISIONING_PROFILE` and `SIMLOCK_E2E_IOS_SIGNING_IDENTITY` only for manual signing, which an Xcode-managed profile fails. Run `scripts/slow-e2e.sh --physical e2e/slow-agent-device-physical.test.ts` |
| Physical Android, a person at the phone | the Physical Android checks above, and `SIMLOCK_PHYSICAL_PERSON` is `1`. Run `scripts/slow-e2e.sh --physical-manual e2e/slow-android-physical-manual.test.ts` |
| Physical iOS, a person at the phone | the Physical iOS checks above, a passcode set on the phone (locking it then needs the passcode), and `SIMLOCK_PHYSICAL_PERSON` is `1`. Run `scripts/slow-e2e.sh --physical-manual e2e/slow-ios-physical-manual.test.ts` |
Expand Down
94 changes: 92 additions & 2 deletions e2e/slow-android-physical.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import { describe, expect, it } from "vitest";

import {
deviceStreamUrl,
freeLoopbackPort,
type TestEnv,
waitFor,
waitForDeviceState,
Expand All @@ -14,6 +15,7 @@ const execFileAsync = promisify(execFile);

const SERIAL = process.env["SIMLOCK_PHYSICAL_ANDROID"];
const APK = process.env["SIMLOCK_PHYSICAL_ANDROID_APK"];
const NETWORK = process.env["SIMLOCK_PHYSICAL_ANDROID_NETWORK"];

const PROBE_INTERVAL_MS = 2_000;
const EXEC_TIMEOUT_MS = 5_000;
Expand All @@ -30,6 +32,14 @@ const missing =
? "SIMLOCK_PHYSICAL_ANDROID_APK"
: undefined;

// why: the network case has its own gate, so a lane with a USB phone only still runs the USB cases.
const missingNetwork =
NETWORK === undefined || NETWORK === ""
? "SIMLOCK_PHYSICAL_ANDROID_NETWORK"
: APK === undefined || APK === ""
? "SIMLOCK_PHYSICAL_ANDROID_APK"
: undefined;

interface Frame {
readonly tag: number;
readonly payload: Uint8Array;
Expand All @@ -45,6 +55,7 @@ interface Rig {
readonly env: TestEnv;
readonly base: string;
readonly auth: Record<string, string>;
readonly port: number;
}

async function adbOut(serial: string, args: readonly string[]): Promise<string> {
Expand Down Expand Up @@ -83,15 +94,19 @@ async function serverPid(): Promise<string> {
return stdout.trim().split("\n")[0] ?? "";
}

async function rig(options: { readonly execTimeoutMs?: number } = {}): Promise<Rig> {
async function rig(
options: { readonly execTimeoutMs?: number; readonly networkDevices?: boolean } = {},
): Promise<Rig> {
const { env, port } = await withHttpDaemon((port) => ({
configOverrides: {
...(options.execTimeoutMs === undefined
? {}
: { exec: { timeoutMs: options.execTimeoutMs } }),
...(options.networkDevices === true ? { android: { networkDevices: true } } : {}),
health: { probeIntervalMs: PROBE_INTERVAL_MS, stableObservations: 2 },
http: { enabled: true, host: "127.0.0.1", port },
capabilities: {
...(options.networkDevices === true ? { tunnel: { enabled: true } } : {}),
stream: { bitrateKbps: 1500, enabled: true, fps: 30, maxDimension: 720 },
},
},
Expand All @@ -114,7 +129,7 @@ async function rig(options: { readonly execTimeoutMs?: number } = {}): Promise<R
authorization: `Bearer ${(created.json as { secret: string }).secret}`,
"content-type": "application/json",
};
return { auth, base, env };
return { auth, base, env, port };
}

async function enroll(env: TestEnv, serial: string): Promise<Record<string, unknown>> {
Expand Down Expand Up @@ -441,3 +456,78 @@ describe.skipIf(missing !== undefined)(
);
},
);

// why: the case needs a phone adb lists with no usb: field, which only an operator can connect; it runs when both the address and an APK are named.
describe.skipIf(missingNetwork !== undefined)(
missingNetwork === undefined
? "Android physical phone over the network (real adb)"
: `Android physical phone over the network (skipped: ${missingNetwork} is not set)`,
{ tags: ["slow", "android", "physical"] },
() => {
const address = NETWORK as string;
const apk = APK as string;

it(
"under android.networkDevices a phone listed by adb over the network is enrolled under its address and leased with ANDROID_SERIAL set to it, device.exec, the screen and a reverse tunnel work on it, and releasing uninstalls an app installed during the lease",
{ timeout: 10 * MINUTE },
async () => {
const name = await installApk(address, apk);
await uninstall(address, name);
const enrolledApps = await userAppsOf(address);
try {
const daemon = await rig({ networkDevices: true });
const added = await enroll(daemon.env, address);
expect(added["driverDeviceId"]).toBe(address);
const grant = await leasePhysical(daemon.env);
expect(grant.environment["ANDROID_SERIAL"]).toBe(address);
expect(grant.environment["ANDROID_ADB_SERVER_PORT"]).toBe("5037");

const hardwareSerial = (
await adbOut(address, ["shell", "getprop", "ro.serialno"])
).trim();
expect(await exec(daemon, grant.lease.id, ["shell", "getprop", "ro.serialno"])).toContain(
hardwareSerial,
);

const response = await streamOf(daemon, grant.device.id);
if (response.body === null) throw new Error("the stream answered without a body");
const frames = await readFrames(response.body, (read) =>
read.some((frame) => frame.tag === TAG.keyframe),
);
expect(frames.map((frame) => frame.tag)).toContain(TAG.keyframe);

const created = await daemon.env.cli(["token", "create", "--role", "operator"]);
expect(created.code, created.stderr).toBe(0);
const callerPort = String(await freeLoopbackPort());
const tunnel = daemon.env.cliBackground([
"--token",
(created.json as { secret: string }).secret,
"tunnel",
"reverse",
callerPort,
"--url",
`http://127.0.0.1:${String(daemon.port)}`,
"--lease",
grant.lease.id,
]);
expect(await tunnel.firstStdoutLine(60_000)).toBe(
`reverse device:${callerPort} -> localhost:${callerPort} (lease ${grant.lease.id})`,
);
tunnel.kill("SIGINT");
expect((await tunnel.waitForExit(10_000)).code).toBe(0);

expect(await installApk(address, apk)).toBe(name);
const released = await daemon.env.cli(["release", grant.lease.id]);
expect(released.code, released.stderr).toBe(0);
await waitForDeviceState(daemon.env, address, "ready", { timeout: 3 * MINUTE });

const after = await userAppsOf(address);
expect(after).not.toContain(name);
for (const kept of enrolledApps) expect(after).toContain(kept);
} finally {
await uninstall(address, name).catch(() => undefined);
}
},
);
},
);
4 changes: 2 additions & 2 deletions src/drivers/android/AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Android driver

Does: emulators in an owned AVD home behind Simlock's own adb server, and USB phones on the default adb server.
Does: emulators in an owned AVD home behind Simlock's own adb server, and phones on the default adb server.
Flows: [device selection](../../../docs/internal/flows/device-selection.md), [drivers](../AGENTS.md), [screen](screen/AGENTS.md), [input](input/AGENTS.md).

## Rules
Expand Down Expand Up @@ -43,7 +43,7 @@ Boot:

Physical phones:

- The 5037 server is never started, stopped or adopted on purpose. A physical `adb` command, `listAttachedPhysical`'s `devices -l` included, may start it as a side effect when nothing listens. Phones are USB transports only.
- The 5037 server is never started, stopped or adopted on purpose. A physical `adb` command, `listAttachedPhysical`'s `devices -l` included, may start it as a side effect when nothing listens. Phones are USB transports; under `android.networkDevices` (ADR 0080) a phone is told by `ro.serialno`, not its address.
- Before every command `DefaultAdbServerGate.check`: the 5037 server's protocol must equal Simlock's `adb version`; nothing listening is open. A mismatch or an unreadable answer sends no command and shows as advisory `adb-protocol-mismatch`.

Profiles and components:
Expand Down
10 changes: 10 additions & 0 deletions src/drivers/android/definition.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -71,4 +71,14 @@ describe("the Android driver's keys of the android config section", () => {
expect(warn).toHaveBeenCalledWith('Unknown config key: "android.emulator.launchArgs"');
expect(section.emulator).toEqual(defaults);
});

it("take android.networkDevices true or false, default it to false, and refuse a string naming the key", async () => {
expect((await load({})).section.networkDevices).toBe(false);
expect((await load({ android: { networkDevices: true } })).section.networkDevices).toBe(true);
expect((await load({ android: { networkDevices: false } })).section.networkDevices).toBe(false);

await expect(load({ android: { networkDevices: "yes" } })).rejects.toThrow(
'Invalid config value for "android.networkDevices"',
);
});
});
4 changes: 4 additions & 0 deletions src/drivers/android/definition.ts
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,8 @@ export interface AndroidDriverConfig {
/** why: an emulator boot may take this long, counted from its spawn, before it is given up. */
readonly bootTimeoutMs: number;
readonly emulator: AndroidEmulatorLaunchOptions;
/** why: ADR 0080 §1: a worker's opt-in to enrol, list and reconnect phones its adb server reaches over the network. */
readonly networkDevices: boolean;
}

export const DEFAULT_ADB_SERVER_PORT = 5038;
Expand All @@ -43,6 +45,7 @@ export const androidDriverConfig: DriverConfigEntry<AndroidDriverConfig> = {
defaults: {
bootTimeoutMs: 300_000,
emulator: { headless: false, gpu: "auto", audio: true, bootAnimation: true },
networkDevices: false,
},
validators: {
bootTimeoutMs: positiveNumber,
Expand All @@ -52,5 +55,6 @@ export const androidDriverConfig: DriverConfigEntry<AndroidDriverConfig> = {
audio: booleanValue,
bootAnimation: booleanValue,
}),
networkDevices: booleanValue,
},
};
1 change: 1 addition & 0 deletions src/drivers/android/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -196,7 +196,7 @@
readonly input: DeviceInputFactory | undefined;
readonly deviceTcp: AndroidDeviceTcp | undefined;

private constructor(

Check failure on line 199 in src/drivers/android/index.ts

View workflow job for this annotation

GitHub Actions / Fallow

High CRAP score (moderate)

Function 'constructor' has a CRAP score of 31.6 (threshold: 30). • Severity: moderate • Cyclomatic: 10 • Cognitive: 6 • CRAP: 31.6 (threshold: 30) • Lines: 133 CRAP combines complexity with coverage: high CRAP means changes here carry high risk. Consider adding tests, simplifying the function, or both.
options: AndroidDriverOptions,
sdk: AndroidSdkPaths,
deviceRoot: string,
Expand Down Expand Up @@ -238,6 +238,7 @@
baseEnv: options.env,
filesystem: options.filesystem,
isBareShell: (args) => this.#passthroughRules.isBareShell(args),
networkDevices: options.config?.networkDevices ?? false,
processRunner: options.processRunner,
tcpProbe: options.tcpProbe,
});
Expand Down
Loading
Loading