Skip to content

Commit b7a1ca3

Browse files
Rutvij97thymikee
andauthored
feat(config): pin workspace devices with explicit selectors (#4384)
* feat(cli): opt-in workspace device pin via devicePin (#2161) Add a `devicePin` boolean to project config (also `--device-pin` and `AGENT_DEVICE_DEVICE_PIN`) that turns the configured platform/device/udid/ serial defaults into a pin. A typed selector or MCP input that contradicts the pin fails with INVALID_ARGS before any daemon is contacted; the error names the file that set the pin and lists each conflict under `details.reason: "device_pin_conflict"`. A pin with nothing to pin fails with `device_pin_without_selector`. Config merging now records where each default came from (user config, project config, or env), and the CLI result exposes the pin plus a pin/default/flag origin per selector key. Closes #2161 * refactor(command-surface): export only the device-pin surface the CLI and MCP consume The dead-code check flagged re-exports with no consumers; resolveCliOptions now has an explicit return type so the pin types stay portable. * refactor(command-surface): keep the device pin inside cli-config The eager-closure budget rejects a new module on the command-surface entry, so the pin helpers live next to the config merge they read. * test(command-surface): colocate the device-pin tests with cli-config * fix(device-pin): enforce the pin at client request finalization Check the device pin once in the client's execute, against the request flags and every batch step's flags, so CLI batch, nested MCP batch and remote-config defaults all go through the same check. - Add assertRequestHonorsDevicePin and drop selectorOrigins, DevicePinSurface and pickExplicitSelector. - Make the hidden --device-pin flag turn the pin on. - Remove resolveConfigBackedFlagDefaults and the env policy-source fallback; document the precedence rule. - Add batch-step regression tests for the client, CLI and MCP paths and cover udid/serial pins and the exact hint. * fix(device-pin): correct --config precedence and name the right remedy per pin source An explicit --config or AGENT_DEVICE_CONFIG file replaces the user and project config files, so the docs and the cli-config comment no longer list it as a layer on top of them. The conflict message and hint now say to drop --device-pin or unset AGENT_DEVICE_DEVICE_PIN when that is what turned the pin on. Tests: a devicePin key in MCP tool input is rejected before a client is created, and the passing batch case checks the selectors in the sent request. * fix(device-pin): tell the user to turn the pin off at the layer that set it A config file or AGENT_DEVICE_DEVICE_PIN is now told to set the pin to false ("devicePin": false, or the variable to 0), which also overrides a lower layer that pins. When --device-pin sits on top of a config or variable that pins as well, the remedy names that layer too, since dropping the flag alone leaves the pin in force. The variable name comes from the recorded provenance instead of being hardcoded. * refactor(config): make workspace device pins explicit selector objects * fix(device-pin): validate refinements against the resolved device * refactor(config): parse device policy at the file boundary * refactor(device-pin): load selection policy only for pinned requests * refactor(daemon): remove obsolete claim-only admission commentary * build(client): declare the device-selection project reference * fix(device-pin): retain typed diagnostics for incompatible selectors * fix(device-pin): preserve narrower platforms during resolution * fix(device-pin): enforce selectors during proxy allocation * chore(gates): track optional device pin allocation metadata * fix(device-pin): validate pins at daemon transport boundaries * chore(gates): cover device pin boundary validation * refactor(contracts): keep pin parsing in the inventory contract owner * chore(gates): track pin parsers in inventory contracts * fix(device-pin): admit proxy keys and validate selector combinations * chore(gates): track pin request metadata and prove removal detection --------- Co-authored-by: Rutvij97 <[email protected]> Co-authored-by: Michał Pierzchała <[email protected]>
1 parent 799e9c0 commit b7a1ca3

40 files changed

Lines changed: 1767 additions & 112 deletions

‎packages/client/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
"@agent-device/contracts": "workspace:*",
1111
"@agent-device/daemon-client": "workspace:*",
1212
"@agent-device/daemon-contracts": "workspace:*",
13+
"@agent-device/device-selection": "workspace:*",
1314
"@agent-device/host-kit": "workspace:*",
1415
"@agent-device/kernel": "workspace:*",
1516
"@agent-device/platform-apple": "workspace:*",
Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
import assert from 'node:assert/strict';
2+
import { test } from 'vitest';
3+
import type { AgentDeviceDaemonTransport } from '@agent-device/contracts/client';
4+
import type { CommandFlags } from '@agent-device/contracts/command';
5+
import { runCommand, type DevicePin } from '@agent-device/command-surface';
6+
import { createAgentDeviceClient } from '../index.ts';
7+
8+
const PIN: DevicePin = {
9+
selector: { platform: 'ios', device: 'iPad Pro' },
10+
source: { kind: 'project', path: '/repo/agent-device.json' },
11+
};
12+
13+
function recordingClient(devicePin: DevicePin | undefined) {
14+
const requests: Array<Parameters<AgentDeviceDaemonTransport>[0]> = [];
15+
const transport: AgentDeviceDaemonTransport = async (request) => {
16+
requests.push(request);
17+
return { ok: true, data: { results: [], executed: 0, total: 0 } };
18+
};
19+
return { requests, client: createAgentDeviceClient({}, { transport, devicePin }) };
20+
}
21+
22+
function failsWithPinConflict(expected: { message: RegExp; conflicts: unknown[] }) {
23+
return (error: unknown): boolean => {
24+
assert.ok(error instanceof Error && 'code' in error && 'details' in error);
25+
assert.equal(error.code, 'INVALID_ARGS');
26+
assert.match(error.message, expected.message);
27+
const details = error.details as Record<string, unknown>;
28+
assert.equal(details.reason, 'device_pin_conflict');
29+
assert.equal(details.pinSource, 'project config file /repo/agent-device.json');
30+
assert.deepEqual(details.conflicts, expected.conflicts);
31+
return true;
32+
};
33+
}
34+
35+
test('a batch step naming another device fails before the request leaves the client', async () => {
36+
const { client, requests } = recordingClient(PIN);
37+
38+
await assert.rejects(
39+
runCommand(client, 'batch', {
40+
steps: [
41+
{ command: 'snapshot', input: {} },
42+
{ command: 'open', input: { app: 'com.example.app', device: 'iPhone 16' } },
43+
],
44+
}),
45+
failsWithPinConflict({
46+
message:
47+
/^Batch step 2: device "iPhone 16" conflicts with the device pin from project config file/,
48+
conflicts: [{ key: 'device', pinned: 'iPad Pro', requested: 'iPhone 16', step: 2 }],
49+
}),
50+
);
51+
assert.equal(requests.length, 0);
52+
});
53+
54+
test('a top-level selector from any layer that contradicts the pin fails', async () => {
55+
const { client, requests } = recordingClient(PIN);
56+
57+
await assert.rejects(
58+
runCommand(client, 'snapshot', { platform: 'android' }),
59+
failsWithPinConflict({
60+
message: /^platform "android" conflicts with the device pin/,
61+
conflicts: [{ key: 'platform', pinned: 'ios', requested: 'android' }],
62+
}),
63+
);
64+
assert.equal(requests.length, 0);
65+
});
66+
67+
test('a batch whose steps repeat, refine, or omit the pin is sent', async () => {
68+
const { client, requests } = recordingClient(PIN);
69+
70+
await runCommand(client, 'batch', {
71+
platform: 'ios',
72+
device: 'iPad Pro',
73+
steps: [
74+
{ command: 'snapshot', input: {} },
75+
{ command: 'open', input: { app: 'com.example.app', device: 'iPad Pro' } },
76+
// The daemon checks that this identity still matches the pinned name.
77+
{ command: 'snapshot', input: { udid: 'ABCDEF' } },
78+
],
79+
});
80+
81+
assert.equal(requests.length, 1);
82+
const flags = requests[0]?.flags as CommandFlags | undefined;
83+
assert.ok(requests[0]?.meta && 'devicePin' in requests[0].meta);
84+
assert.deepEqual(requests[0].meta.devicePin, PIN);
85+
assert.equal(flags?.platform, 'ios');
86+
assert.equal(flags?.device, 'iPad Pro');
87+
const steps = flags?.batchSteps;
88+
assert.equal(steps?.length, 3);
89+
assert.equal(steps?.[0]?.flags?.device, undefined);
90+
assert.equal(steps?.[1]?.flags?.device, 'iPad Pro');
91+
assert.equal(steps?.[2]?.flags?.udid, 'ABCDEF');
92+
});
93+
94+
test('without a pin the client sends a batch step that names another device', async () => {
95+
const { client, requests } = recordingClient(undefined);
96+
97+
await runCommand(client, 'batch', {
98+
steps: [{ command: 'open', input: { app: 'com.example.app', device: 'iPhone 16' } }],
99+
});
100+
101+
const steps = (requests[0]?.flags as CommandFlags | undefined)?.batchSteps;
102+
assert.equal(steps?.[0]?.flags?.device, 'iPhone 16');
103+
});
104+
105+
test('the client supplies pin selectors even when request options contain undefined defaults', async () => {
106+
const { client, requests } = recordingClient(PIN);
107+
await runCommand(client, 'snapshot', { platform: undefined, device: undefined });
108+
assert.equal(requests[0]?.flags?.platform, 'ios');
109+
assert.equal(requests[0]?.flags?.device, 'iPad Pro');
110+
assert.ok(requests[0]?.meta && 'devicePin' in requests[0].meta);
111+
assert.deepEqual(requests[0].meta.devicePin, PIN);
112+
});
113+
114+
test('a name alias and overlapping Apple platform selectors are accepted', async () => {
115+
const { client, requests } = recordingClient(PIN);
116+
await runCommand(client, 'snapshot', { device: 'ipad_pro', platform: 'apple' });
117+
assert.equal(requests.length, 1);
118+
assert.equal(requests[0]?.flags?.platform, 'ios');
119+
});
120+
121+
test('an Apple-family pin forwards a requested leaf platform', async () => {
122+
const { client, requests } = recordingClient({ ...PIN, selector: { platform: 'apple' } });
123+
await runCommand(client, 'snapshot', { platform: 'macos' });
124+
assert.equal(requests[0]?.flags?.platform, 'macos');
125+
});
126+
127+
for (const [selector, input, conflict] of [
128+
[
129+
{ platform: 'ios' },
130+
{ serial: 'emulator-5554' },
131+
{ key: 'serial', pinnedKey: 'platform', pinned: 'ios', requested: 'emulator-5554' },
132+
],
133+
[
134+
{ platform: 'android' },
135+
{ udid: 'IPAD-001' },
136+
{ key: 'udid', pinnedKey: 'platform', pinned: 'android', requested: 'IPAD-001' },
137+
],
138+
[
139+
{ udid: 'IPAD-001' },
140+
{ serial: 'emulator-5554' },
141+
{ key: 'serial', pinnedKey: 'udid', pinned: 'IPAD-001', requested: 'emulator-5554' },
142+
],
143+
[
144+
{ serial: 'emulator-5554' },
145+
{ udid: 'IPAD-001' },
146+
{ key: 'udid', pinnedKey: 'serial', pinned: 'emulator-5554', requested: 'IPAD-001' },
147+
],
148+
[
149+
{ udid: 'IPAD-001' },
150+
{ platform: 'android' },
151+
{ key: 'platform', pinnedKey: 'udid', pinned: 'IPAD-001', requested: 'android' },
152+
],
153+
[
154+
{ serial: 'emulator-5554' },
155+
{ platform: 'ios' },
156+
{ key: 'platform', pinnedKey: 'serial', pinned: 'emulator-5554', requested: 'ios' },
157+
],
158+
[
159+
{ platform: 'linux' },
160+
{ udid: 'IPAD-001' },
161+
{ key: 'udid', pinnedKey: 'platform', pinned: 'linux', requested: 'IPAD-001' },
162+
],
163+
[
164+
{ platform: 'web' },
165+
{ serial: 'emulator-5554' },
166+
{ key: 'serial', pinnedKey: 'platform', pinned: 'web', requested: 'emulator-5554' },
167+
],
168+
] as const) {
169+
test(`a pin ${JSON.stringify(selector)} rejects incompatible selector ${JSON.stringify(input)} before transport`, async () => {
170+
const { client, requests } = recordingClient({ ...PIN, selector });
171+
await assert.rejects(
172+
runCommand(client, 'snapshot', input),
173+
failsWithPinConflict({ message: /conflicts with the device pin/, conflicts: [conflict] }),
174+
);
175+
assert.equal(requests.length, 0);
176+
});
177+
}
178+
179+
test('an incompatible selector in a batch step is rejected before any request is sent', async () => {
180+
const { client, requests } = recordingClient(PIN);
181+
await assert.rejects(
182+
runCommand(client, 'batch', {
183+
steps: [{ command: 'snapshot', input: { serial: 'emulator-5554' } }],
184+
}),
185+
failsWithPinConflict({
186+
message: /^Batch step 1: serial/,
187+
conflicts: [
188+
{
189+
key: 'serial',
190+
pinnedKey: 'platform',
191+
pinned: 'ios',
192+
requested: 'emulator-5554',
193+
step: 1,
194+
},
195+
],
196+
}),
197+
);
198+
assert.equal(requests.length, 0);
199+
});
200+
201+
for (const [platform, identity] of [
202+
['ios', { udid: 'IPAD-001' }],
203+
['macos', { udid: 'MAC-001' }],
204+
['android', { serial: 'emulator-5554' }],
205+
['harmonyos', { serial: 'HARMONY-001' }],
206+
['vega', { serial: 'VEGA-001' }],
207+
] as const) {
208+
test(`a ${platform} pin accepts a compatible identity selector`, async () => {
209+
const { client, requests } = recordingClient({ ...PIN, selector: { platform } });
210+
await runCommand(client, 'snapshot', identity);
211+
assert.equal(requests.length, 1);
212+
if ('udid' in identity) {
213+
assert.equal(requests[0]?.flags?.udid, identity.udid);
214+
} else {
215+
assert.equal(requests[0]?.flags?.serial, identity.serial);
216+
}
217+
});
218+
}

‎packages/client/src/index.ts‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,7 @@ import { INTERNAL_COMMANDS } from '@agent-device/command-registry/catalog';
5555
import {
5656
buildRequestFlags,
5757
type AgentDeviceClient,
58+
type DevicePin,
5859
prepareDaemonCommandRequest,
5960
type DaemonCommandName,
6061
} from '@agent-device/command-surface';
@@ -78,7 +79,12 @@ export { pickScreenshotResultData } from './screenshot-result.ts';
7879

7980
export function createAgentDeviceClient(
8081
config: AgentDeviceClientConfig = {},
81-
deps: { transport?: AgentDeviceDaemonTransport; host?: HostEnvironment } = {},
82+
deps: {
83+
transport?: AgentDeviceDaemonTransport;
84+
host?: HostEnvironment;
85+
/** The operator-configured device selector enforced on every request. */
86+
devicePin?: DevicePin;
87+
} = {},
8288
): AgentDeviceClient {
8389
const host = deps.host ?? captureHostEnvironment(process);
8490
const transport = deps.transport ?? createDaemonTransport(host);
@@ -135,8 +141,18 @@ export function createAgentDeviceClient(
135141
...(input ? { input } : {}),
136142
flags: buildRequestFlags(merged, metadataFlags),
137143
runtime: merged.runtime,
138-
meta: { ...buildMeta(merged), requestId },
144+
meta: {
145+
...buildMeta(merged),
146+
requestId,
147+
...(deps.devicePin ? { devicePin: deps.devicePin } : {}),
148+
},
139149
};
150+
if (deps.devicePin) {
151+
const { assertRequestHonorsDevicePin, effectiveDevicePinSelector } =
152+
await import('@agent-device/device-selection/device-selection-resolver');
153+
assertRequestHonorsDevicePin(deps.devicePin, request);
154+
Object.assign(request.flags, effectiveDevicePinSelector(deps.devicePin, request.flags));
155+
}
140156
// `signal` rides the transport context (it is a live object, never wire data), and the guard
141157
// answers for a custom transport that ignores it: the caller's promise settles on abort either
142158
// way. The built-in transport closes the request's connection, which is what makes the daemon

‎packages/client/tsconfig.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
{ "path": "../contracts" },
1717
{ "path": "../daemon-client" },
1818
{ "path": "../daemon-contracts" },
19+
{ "path": "../device-selection" },
1920
{ "path": "../host-kit" },
2021
{ "path": "../kernel" },
2122
{ "path": "../platform-apple" },

‎packages/command-surface/src/cli-grammar/flag-declaration-admission.test.ts‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ import { test, vi } from 'vitest';
55
import type { CliFlags } from '@agent-device/contracts/command';
66
import { getFlagDefinitionsForKey } from '@agent-device/command-registry/flag-registry';
77
import type { FlagDefinition } from '@agent-device/command-registry/flag-types';
8-
import { resolveConfigBackedFlagDefaults } from '../schema/cli-config.ts';
8+
import { resolveConfigDefaults } from '../schema/cli-config.ts';
99
import { makeTempWorkspace } from '@agent-device/test-kit';
1010

1111
/**
@@ -42,7 +42,7 @@ test('project-config admission follows the declaration: an undeclared key is ref
4242
writeProjectConfig(shipped.project, { daemonBaseUrl: 'https://daemon.example.test' });
4343
assert.throws(
4444
() =>
45-
resolveConfigBackedFlagDefaults({
45+
resolveConfigDefaults({
4646
command: 'devices',
4747
cwd: shipped.project,
4848
cliFlags: OPERATOR_CLI_FLAGS,
@@ -60,8 +60,7 @@ test('project-config admission follows the declaration: an undeclared key is ref
6060
const registry = await import('@agent-device/command-registry/flag-registry');
6161
const planted = getInRegistry(registry, 'daemonBaseUrl');
6262
Object.assign(planted, { projectConfig: true });
63-
const { resolveConfigBackedFlagDefaults: derivePlanted } =
64-
await import('../schema/cli-config.ts');
63+
const { resolveConfigDefaults: derivePlanted } = await import('../schema/cli-config.ts');
6564
const workspace = makeTempWorkspace();
6665
try {
6766
writeProjectConfig(workspace.project, { daemonBaseUrl: 'https://daemon.example.test' });
@@ -71,7 +70,7 @@ test('project-config admission follows the declaration: an undeclared key is ref
7170
cliFlags: OPERATOR_CLI_FLAGS,
7271
env: { HOME: workspace.home },
7372
});
74-
assert.equal(defaults.daemonBaseUrl, 'https://daemon.example.test');
73+
assert.equal(defaults.flags.daemonBaseUrl, 'https://daemon.example.test');
7574
} finally {
7675
fs.rmSync(workspace.root, { recursive: true, force: true });
7776
}

‎packages/command-surface/src/index.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ export { isFlagSupportedForCommand } from './schema/option-schema.ts';
3636
export {
3737
applyDefaultPlatformBinding,
3838
resolveBindingSettings,
39-
resolveConfigBackedFlagDefaults,
39+
resolveConfigDefaults,
4040
type BindingSettings,
4141
} from './schema/cli-config.ts';
4242
export { mergeDefinedFlags } from './schema/merge-flags.ts';
@@ -107,3 +107,5 @@ async function prepareRequestWithMetadataFlags(
107107
...(metadata ? { metadataFlags: readMetadataCommandFlags(metadata, request.options) } : {}),
108108
};
109109
}
110+
111+
export type { DevicePin } from '@agent-device/contracts/device';

0 commit comments

Comments
 (0)