@11agents/cli 0.1.37 → 0.1.38

package/mobile-runtime/data-templates/README.md

@@ -1,4 +1,5 @@
 # 11agents Mobile Data Templates
 
 These files seed `~/.11agents/mobile/data` during `11agents mobile setup`.
-Replace example devices and accounts with company-owned, authorized Android devices and logged-in accounts before publishing.
+`devices.example.csv` contains the stable D01-D10 device registry. Keep those hardware ids in sync across runtime machines so a physical device keeps the same Dxx id even when it is attached through a different USB port or ADB transport.
+Replace example accounts with company-owned, authorized Android accounts before publishing.

package/mobile-runtime/data-templates/devices.example.csv

@@ -1,2 +1,11 @@
-device_id,adb_serial,ip_address,brand,model,android_version,status,notes
-D01,REPLACE_WITH_ADB_SERIAL,,ExampleBrand,ExampleModel,13,active,replace with an authorized company-owned Android device
+device_id,adb_serial,hardware_id,ip_address,brand,model,android_version,status,notes
+D01,e6209341,e6209341,,,,,active,stable device registry slot 1
+D02,7441ce65,7441ce65,,,,,active,stable device registry slot 2
+D03,2eecd64c,2eecd64c,,,,,active,stable device registry slot 3
+D04,bfa3e5ba,bfa3e5ba,,,,,active,stable device registry slot 4
+D05,78d99cb0,78d99cb0,,,,,active,stable device registry slot 5
+D06,2c461593,2c461593,,,,,active,stable device registry slot 6
+D07,2cd62d93,2cd62d93,,,,,active,stable device registry slot 7
+D08,f8cabef1,f8cabef1,,,,,active,stable device registry slot 8
+D09,8b427827,8b427827,,,,,active,stable device registry slot 9
+D10,3185bee8,3185bee8,,,,,active,stable device registry slot 10

package/mobile-runtime/python/src/device_control/cli.py

@@ -4,7 +4,7 @@ import argparse
 import csv
 import json
 from concurrent.futures import ThreadPoolExecutor, as_completed
-from dataclasses import asdict
+from dataclasses import asdict, replace
 from pathlib import Path
 
 from .adb import AdbClient, resolve_adb_bin
@@ -349,7 +349,7 @@ def main() -> None:
         return
 
     if args.command == "ensure-appium":
-        udids = _resolve_appium_udids(args.devices, args.device, args.udid)
+        udids = _resolve_appium_udids(args.devices, args.device, args.udid, adb)
         try:
             result = ensure_appium_server(
                 args.server,
@@ -387,12 +387,13 @@ def main() -> None:
         return
 
     if args.command == "list-devices":
-        devices = load_devices(args.devices)
+        devices = _load_devices(args.devices, adb, resolve_transports=args.health)
         connected = set(adb.list_devices()) if args.health else set()
         for device in devices.values():
             row = {
                 "device_id": device.device_id,
                 "adb_serial": device.adb_serial,
+                "hardware_id": device.hardware_id,
                 "ip_address": device.ip_address,
                 "brand": device.brand,
                 "model": device.model,
@@ -413,7 +414,7 @@ def main() -> None:
                 if args.health:
                     suffix = f" online={row['online']} battery={row.get('battery', '')} focus={row.get('focus', '')}"
                 print(
-                    f"{device.device_id} serial={device.adb_serial} ip={device.ip_address} "
+                    f"{device.device_id} serial={device.adb_serial} hardware_id={device.hardware_id} ip={device.ip_address} "
                     f"model={device.model} status={device.status}{suffix}"
                 )
         return
@@ -428,6 +429,7 @@ def main() -> None:
         row = {
             "device_id": args.device_id,
             "adb_serial": serial,
+            "hardware_id": _device_hardware_id(adb, serial) or serial,
             "ip_address": _ip_from_serial(serial),
             "brand": adb.getprop(serial, "ro.product.brand"),
             "model": adb.getprop(serial, "ro.product.model"),
@@ -443,33 +445,34 @@ def main() -> None:
         return
 
     if args.command == "connect":
-        devices = load_devices(args.devices)
+        devices = _load_devices(args.devices, adb, resolve_transports=False)
         for device in devices.values():
             if device.status != "active":
                 print(f"{device.device_id}: skipped status={device.status}")
                 continue
-            result = adb.connect(device.adb_serial)
+            target = device.ip_address or device.adb_serial
+            result = adb.connect(target)
             status = "ok" if result.ok else "fail"
-            print(f"{device.device_id} {device.adb_serial}: {status} {result.stdout or result.stderr}")
+            print(f"{device.device_id} {target}: {status} {result.stdout or result.stderr}")
         return
 
     if args.command == "health":
-        devices = load_devices(args.devices)
+        devices = _load_devices(args.devices, adb)
         connected = set(adb.list_devices())
         for device in devices.values():
             online = device.adb_serial in connected
             if not online:
-                print(f"{device.device_id}: offline serial={device.adb_serial}")
+                print(f"{device.device_id}: offline serial={device.adb_serial} hardware_id={device.hardware_id}")
                 continue
             battery = adb.battery_level(device.adb_serial)
             model = adb.getprop(device.adb_serial, "ro.product.model")
             android = adb.getprop(device.adb_serial, "ro.build.version.release")
             focus = adb.current_focus(device.adb_serial)
-            print(f"{device.device_id}: online battery={battery} model={model} android={android} focus={focus}")
+            print(f"{device.device_id}: online battery={battery} serial={device.adb_serial} hardware_id={device.hardware_id} model={model} android={android} focus={focus}")
         return
 
     if args.command == "screenshot":
-        device = _get_device(args.devices, args.device_id)
+        device = _get_device(args.devices, args.device_id, adb)
         out = Path(args.out_dir) / f"{device.device_id}.png"
         result = adb.screenshot(device.adb_serial, out)
         if result.ok:
@@ -479,7 +482,7 @@ def main() -> None:
         return
 
     if args.command == "dump-ui":
-        device = _get_device(args.devices, args.device_id)
+        device = _get_device(args.devices, args.device_id, adb)
         out = Path(args.out_dir) / f"{device.device_id}.xml"
         result = adb.dump_ui(device.adb_serial, out)
         if result.ok:
@@ -490,25 +493,25 @@ def main() -> None:
         return
 
     if args.command == "tap":
-        device = _get_device(args.devices, args.device_id)
+        device = _get_device(args.devices, args.device_id, adb)
         result = adb.tap(device.adb_serial, args.x, args.y)
         print(result.stdout or result.stderr)
         return
 
     if args.command == "keyevent":
-        device = _get_device(args.devices, args.device_id)
+        device = _get_device(args.devices, args.device_id, adb)
         result = adb.keyevent(device.adb_serial, args.keycode)
         print(result.stdout or result.stderr)
         return
 
     if args.command == "input-text":
-        device = _get_device(args.devices, args.device_id)
+        device = _get_device(args.devices, args.device_id, adb)
         result = adb.input_text(device.adb_serial, args.text)
         print(result.stdout or result.stderr)
         return
 
     if args.command == "launch":
-        device = _get_device(args.devices, args.device_id)
+        device = _get_device(args.devices, args.device_id, adb)
         result = adb.launch_package(device.adb_serial, args.package)
         print(result.stdout or result.stderr)
         return
@@ -632,7 +635,7 @@ def main() -> None:
         return
 
     if args.command == "collect-tiktok-account-metrics-adb":
-        device = _get_device(args.devices, args.device)
+        device = _get_device(args.devices, args.device, adb)
         account_id = args.account_id or f"{args.account_prefix}_{device.device_id.lower()}"
         manual_values = _load_tiktok_account_metric_values(args.values_json, args.values_file)
         collector = TikTokAccountMetricsAdbCollector(adb, artifact_root=args.artifact_root)
@@ -673,7 +676,7 @@ def main() -> None:
         return
 
     if args.command == "collect-tiktok-video-metrics-adb":
-        device = _get_device(args.devices, args.device)
+        device = _get_device(args.devices, args.device, adb)
         account_id = args.account_id or f"{args.account_prefix}_{device.device_id.lower()}"
         manual_values = _load_tiktok_video_metric_values(args.values_json, args.values_file)
         collector = TikTokVideoMetricsAdbCollector(adb, artifact_root=args.artifact_root)
@@ -715,7 +718,7 @@ def main() -> None:
         return
 
     if args.command == "publish-tiktok-adb":
-        devices = load_devices(args.devices)
+        devices = _load_devices(args.devices, adb)
         selected = _select_devices(devices, args.device, args.ranges)
         if not selected:
             raise SystemExit("No target devices. Use --device D01 or --range 1-10.")
@@ -751,7 +754,7 @@ def main() -> None:
         return
 
     if args.command in {"publish-tiktok", "publish-tiktok-appium"}:
-        devices = load_devices(args.devices)
+        devices = _load_devices(args.devices, adb)
         selected = _select_devices(devices, args.device, args.ranges)
         if not selected:
             raise SystemExit("No target devices. Use --device D03 or --range 1-5.")
@@ -787,7 +790,7 @@ def main() -> None:
         return
 
     if args.command in {"publish-reddit", "publish-reddit-adb"}:
-        devices = load_devices(args.devices)
+        devices = _load_devices(args.devices, adb)
         selected = _select_devices(devices, args.device, args.ranges)
         if not selected:
             raise SystemExit("No target devices. Use --device D01 or --range 1-10.")
@@ -832,7 +835,7 @@ def main() -> None:
         return
 
     if args.command == "publish-facebook":
-        devices = load_devices(args.devices)
+        devices = _load_devices(args.devices, adb)
         selected = _select_devices(devices, args.device, args.ranges)
         if not selected:
             raise SystemExit("No target devices. Use --device D03 or --range 1-5.")
@@ -871,7 +874,7 @@ def main() -> None:
 
     if args.command == "publish-instagram":
         _apply_instagram_publish_policy(args)
-        devices = load_devices(args.devices)
+        devices = _load_devices(args.devices, adb)
         selected = _select_devices(devices, args.device, args.ranges)
         if not selected:
             raise SystemExit("No target devices. Use --device D03 or --range 1-5.")
@@ -911,7 +914,7 @@ def main() -> None:
         return
 
     if args.command == "publish-x":
-        devices = load_devices(args.devices)
+        devices = _load_devices(args.devices, adb)
         selected = _select_devices(devices, args.device, args.ranges)
         if not selected:
             raise SystemExit("No target devices. Use --device D03 or --range 1-5.")
@@ -955,7 +958,7 @@ def main() -> None:
     if args.command == "publish-xiaohongshu":
         _apply_xiaohongshu_publish_package(args)
         _apply_xiaohongshu_live_publish_policy(args)
-        devices = load_devices(args.devices)
+        devices = _load_devices(args.devices, adb)
         selected = _select_devices(devices, args.device, args.ranges)
         if not selected:
             raise SystemExit("No target devices. Use --device Dxx or --range 1-5.")
@@ -1011,7 +1014,7 @@ def main() -> None:
         device_id = args.device or (record.device_id if record else "")
         if not device_id:
             raise SystemExit("copy-xiaohongshu-link requires --device or --record-id for a record with device_id")
-        device = _get_device(args.devices, device_id)
+        device = _get_device(args.devices, device_id, adb)
         _ensure_appium_preflight(args, [device])
         publisher = XiaohongshuAdbPublisher(
             adb,
@@ -1048,17 +1051,77 @@ def main() -> None:
         return
 
 
-def _get_device(devices_path: str, device_id: str):
+DEVICE_IDENTITY_PROPS = (
+    "ro.serialno",
+    "ro.boot.serialno",
+    "ro.vendor.boot.serialno",
+    "ro.product.serialno",
+)
+
+
+def _load_devices(devices_path: str, adb: AdbClient, *, resolve_transports: bool = True):
     devices = load_devices(devices_path)
+    if not resolve_transports:
+        return devices
+    return _resolve_device_transports(devices, adb)
+
+
+def _resolve_device_transports(devices: dict[str, object], adb: AdbClient):
+    transport_by_identity = _connected_transport_by_identity(adb)
+    if not transport_by_identity:
+        return devices
+    resolved = {}
+    for device_id, device in devices.items():
+        transport = ""
+        for identity in _device_identity_candidates(device):
+            transport = transport_by_identity.get(identity)
+            if transport:
+                break
+        resolved[device_id] = replace(device, adb_serial=transport) if transport and transport != device.adb_serial else device
+    return resolved
+
+
+def _connected_transport_by_identity(adb: AdbClient) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for transport in adb.list_devices():
+        for identity in {transport, _device_hardware_id(adb, transport)}:
+            clean = _clean_device_identity(identity)
+            if clean:
+                out[clean] = transport
+    return out
+
+
+def _device_hardware_id(adb: AdbClient, transport: str) -> str:
+    for prop in DEVICE_IDENTITY_PROPS:
+        value = adb.getprop(transport, prop).strip()
+        if value and value.lower() not in {"unknown", "null", "none"}:
+            return value
+    return ""
+
+
+def _device_identity_candidates(device) -> list[str]:
+    candidates = [
+        getattr(device, "hardware_id", ""),
+        getattr(device, "adb_serial", ""),
+    ]
+    return [clean for clean in (_clean_device_identity(item) for item in candidates) if clean]
+
+
+def _clean_device_identity(value: str) -> str:
+    return str(value or "").strip().lower()
+
+
+def _get_device(devices_path: str, device_id: str, adb: AdbClient):
+    devices = _load_devices(devices_path, adb)
     if device_id not in devices:
         raise SystemExit(f"Unknown device_id={device_id}")
     return devices[device_id]
 
 
-def _resolve_appium_udids(devices_path: str, device_ids: list[str], udids: list[str]) -> list[str]:
+def _resolve_appium_udids(devices_path: str, device_ids: list[str], udids: list[str], adb: AdbClient) -> list[str]:
     resolved = [item for item in udids if item]
     if device_ids:
-        devices = load_devices(devices_path)
+        devices = _load_devices(devices_path, adb)
         for device_id in device_ids:
             if device_id not in devices:
                 raise SystemExit(f"Unknown device_id={device_id}")

package/mobile-runtime/python/src/device_control/models.py

@@ -11,6 +11,7 @@ class Device:
     device_id: str
     adb_serial: str
     ip_address: str
+    hardware_id: str = ""
     brand: str = ""
     model: str = ""
     android_version: str = ""

package/mobile-runtime/python/src/device_control/store.py

@@ -23,6 +23,7 @@ def load_devices(path: str | Path) -> dict[str, Device]:
             device_id=row["device_id"],
             adb_serial=row["adb_serial"],
             ip_address=row.get("ip_address", ""),
+            hardware_id=row.get("hardware_id", "") or row.get("physical_id", "") or row["adb_serial"],
             brand=row.get("brand", ""),
             model=row.get("model", ""),
             android_version=row.get("android_version", ""),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@11agents/cli",
-  "version": "0.1.37",
+  "version": "0.1.38",
   "description": "11agents local runtime and telemetry CLI",
   "type": "module",
   "bin": {

package/src/commands/mobile.js

@@ -235,6 +235,104 @@ async function writeFileIfMissing(filePath, content) {
   }
 }
 
+async function mergeDeviceRegistry(filePath, templateContent) {
+  let currentContent = ''
+  try {
+    currentContent = await readFile(filePath, 'utf8')
+  } catch {
+    await mkdir(path.dirname(filePath), { recursive: true })
+    await writeFile(filePath, templateContent)
+    return
+  }
+  const current = parseCsv(currentContent)
+  const template = parseCsv(templateContent)
+  const headers = [...current.headers]
+  for (const header of template.headers) {
+    if (!headers.includes(header)) headers.push(header)
+  }
+  const rows = current.rows.map(row => ({ ...row }))
+  const rowByDeviceId = new Map(rows.map(row => [row.device_id, row]))
+  for (const seed of template.rows) {
+    const deviceId = seed.device_id
+    const existing = rowByDeviceId.get(deviceId)
+    if (!existing) {
+      rows.push({ ...seed })
+      rowByDeviceId.set(deviceId, rows[rows.length - 1])
+      continue
+    }
+    if (isCanonicalDeviceId(deviceId)) {
+      const managedCanonicalRow = /^stable device registry slot/i.test(existing.notes || '')
+      const serialChanged = existing.adb_serial && existing.adb_serial !== seed.adb_serial
+      existing.adb_serial = seed.adb_serial
+      existing.hardware_id = seed.hardware_id || seed.adb_serial
+      if (managedCanonicalRow || serialChanged) {
+        existing.brand = seed.brand || ''
+        existing.model = seed.model || ''
+        existing.android_version = seed.android_version || ''
+      }
+      if (!existing.status) existing.status = seed.status || 'active'
+      if (!existing.notes || /replace with|single-device POC/i.test(existing.notes)) existing.notes = seed.notes || ''
+    }
+  }
+  await writeFile(filePath, formatCsv(headers, rows))
+}
+
+function isCanonicalDeviceId(deviceId = '') {
+  return /^D(?:0[1-9]|10)$/.test(String(deviceId))
+}
+
+function parseCsv(text = '') {
+  const lines = String(text || '').split(/\r?\n/).filter(line => line.length)
+  if (!lines.length) return { headers: [], rows: [] }
+  const headers = parseCsvLine(lines[0])
+  return {
+    headers,
+    rows: lines.slice(1).map(line => {
+      const values = parseCsvLine(line)
+      return Object.fromEntries(headers.map((header, index) => [header, values[index] || '']))
+    }),
+  }
+}
+
+function parseCsvLine(line = '') {
+  const out = []
+  let value = ''
+  let quoted = false
+  for (let i = 0; i < line.length; i += 1) {
+    const ch = line[i]
+    if (ch === '"') {
+      if (quoted && line[i + 1] === '"') {
+        value += '"'
+        i += 1
+      } else {
+        quoted = !quoted
+      }
+      continue
+    }
+    if (ch === ',' && !quoted) {
+      out.push(value)
+      value = ''
+      continue
+    }
+    value += ch
+  }
+  out.push(value)
+  return out
+}
+
+function formatCsv(headers, rows) {
+  return [
+    headers.join(','),
+    ...rows.map(row => headers.map(header => csvCell(row[header] || '')).join(',')),
+  ].join('\n') + '\n'
+}
+
+function csvCell(value) {
+  const text = String(value ?? '')
+  if (!/[",\n\r]/.test(text)) return text
+  return `"${text.replaceAll('"', '""')}"`
+}
+
 async function scaffoldMobileHome(home) {
   await mkdir(home, { recursive: true })
   await mkdir(path.join(home, 'data'), { recursive: true })
@@ -248,7 +346,7 @@ async function scaffoldMobileHome(home) {
     path.join(home, 'data', 'accounts.csv'),
     await readFile(path.join(MOBILE_DATA_TEMPLATE_ROOT, 'accounts.example.csv'), 'utf8')
   )
-  await writeFileIfMissing(
+  await mergeDeviceRegistry(
     path.join(home, 'data', 'devices.csv'),
     await readFile(path.join(MOBILE_DATA_TEMPLATE_ROOT, 'devices.example.csv'), 'utf8')
   )