agent-device 0.3.3 → 0.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-device",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Unified control plane for physical and virtual devices via an agent-driven CLI.",
   "license": "MIT",
   "author": "Callstack",

package/skills/agent-device/SKILL.md

@@ -27,7 +27,7 @@ npx -y agent-device
 
 ## Core workflow
 
-1. Open app: `open [app]` (`open` handles target selection + boot/activation in the normal flow)
+1. Open app or deep link: `open [app|url]` (`open` handles target selection + boot/activation in the normal flow)
 2. Snapshot: `snapshot` to get refs from accessibility tree
 3. Interact using refs (`click @ref`, `fill @ref "text"`)
 4. Re-snapshot after navigation/UI changes
@@ -41,8 +41,11 @@ npx -y agent-device
 agent-device boot                 # Ensure target is booted/ready without opening app
 agent-device boot --platform ios  # Boot iOS simulator
 agent-device boot --platform android # Boot Android emulator/device target
-agent-device open [app]           # Boot device/simulator; optionally launch app
-agent-device open [app] --activity com.example/.MainActivity # Android: open specific activity
+agent-device open [app|url]       # Boot device/simulator; optionally launch app or deep link URL
+agent-device open [app] --relaunch # Terminate app process first, then launch (fresh runtime)
+agent-device open [app] --activity com.example/.MainActivity # Android: open specific activity (app targets only)
+agent-device open "myapp://home" --platform android          # Android deep link
+agent-device open "https://example.com" --platform ios       # iOS simulator deep link
 agent-device close [app]          # Close app or just end session
 agent-device reinstall <app> <path> # Uninstall + install app in one command
 agent-device session list         # List active sessions
@@ -134,12 +137,14 @@ agent-device screenshot out.png
 ### Deterministic replay and updating
 
 ```bash
+agent-device open App --relaunch      # Fresh app process restart in the current session
 agent-device open App --save-script   # Save session script (.ad) on close
 agent-device replay ./session.ad      # Run deterministic replay from .ad script
 agent-device replay -u ./session.ad   # Update selector drift and rewrite .ad script in place
 ```
 
 `replay` reads `.ad` recordings.
+`--relaunch` controls launch semantics; `--save-script` controls recording. Combine only when both are needed.
 
 ### Trace logs (AX/XCTest)
 
@@ -168,10 +173,13 @@ agent-device apps --platform android --user-installed
 - Prefer `snapshot -i` to reduce output size.
 - On iOS, `xctest` is the default and does not require Accessibility permission.
 - If XCTest returns 0 nodes (foreground app changed), agent-device falls back to AX when available.
-- `open <app>` can be used within an existing session to switch apps and update the session bundle id.
+- `open <app|url>` can be used within an existing session to switch apps or open deep links.
+- `open <app>` updates session app bundle context; URL opens do not set an app bundle id.
+- Use `open <app> --relaunch` during React Native/Fast Refresh debugging when you need a fresh app process without ending the session.
 - If AX returns the Simulator window or empty tree, restart Simulator or use `--backend xctest`.
 - Use `--session <name>` for parallel sessions; avoid device contention.
-- Use `--activity <component>` on Android to launch a specific activity (e.g. TV apps with LEANBACK).
+- Use `--activity <component>` on Android to launch a specific activity (e.g. TV apps with LEANBACK); do not combine with URL opens.
+- iOS deep-link opens are simulator-only in v1.
 - Use `fill` when you want clear-then-type semantics.
 - Use `type` when you want to append/enter text without clearing.
 - On Android, prefer `fill` for important fields; it verifies entered text and retries once when IME reorders characters.

package/skills/agent-device/references/session-management.md

@@ -14,6 +14,7 @@ Sessions isolate device context. A device can only be held by one session at a t
 - Name sessions semantically.
 - Close sessions when done.
 - Use separate sessions for parallel work.
+- For dev loops where runtime state can persist (for example React Native Fast Refresh), use `open <app> --relaunch` to restart the app process in the same session.
 - For deterministic replay scripts, prefer selector-based actions and assertions.
 - Use `replay -u` to update selector drift during maintenance.
 

package/src/core/__tests__/open-target.test.ts

@@ -0,0 +1,16 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { isDeepLinkTarget } from '../open-target.ts';
+
+test('isDeepLinkTarget accepts URL-style deep links', () => {
+  assert.equal(isDeepLinkTarget('myapp://home'), true);
+  assert.equal(isDeepLinkTarget('https://example.com'), true);
+  assert.equal(isDeepLinkTarget('tel:123456789'), true);
+  assert.equal(isDeepLinkTarget('mailto:test@example.com'), true);
+});
+
+test('isDeepLinkTarget rejects app identifiers and malformed URLs', () => {
+  assert.equal(isDeepLinkTarget('com.example.app'), false);
+  assert.equal(isDeepLinkTarget('settings'), false);
+  assert.equal(isDeepLinkTarget('http:/x'), false);
+});

package/src/core/dispatch.ts

@@ -34,6 +34,7 @@ export type CommandFlags = {
   snapshotRaw?: boolean;
   snapshotBackend?: 'ax' | 'xctest';
   saveScript?: boolean;
+  relaunch?: boolean;
   noRecord?: boolean;
   appsFilter?: 'launchable' | 'user-installed' | 'all';
   appsMetadata?: boolean;
@@ -106,7 +107,7 @@ export async function dispatchCommand(
         await interactor.openDevice();
         return { app: null };
       }
-      await interactor.open(app, { activity: context?.activity });
+      await interactor.open(app, { activity: context?.activity, appBundleId: context?.appBundleId });
       return { app };
     }
     case 'close': {

package/src/core/open-target.ts

@@ -0,0 +1,13 @@
+export function isDeepLinkTarget(input: string): boolean {
+  const value = input.trim();
+  if (!value) return false;
+  if (/\s/.test(value)) return false;
+  const match = /^([A-Za-z][A-Za-z0-9+.-]*):(.+)$/.exec(value);
+  if (!match) return false;
+  const scheme = match[1]?.toLowerCase();
+  const rest = match[2] ?? '';
+  if (scheme === 'http' || scheme === 'https' || scheme === 'ws' || scheme === 'wss' || scheme === 'ftp' || scheme === 'ftps') {
+    return rest.startsWith('//');
+  }
+  return true;
+}

package/src/daemon/__tests__/session-store.test.ts

@@ -93,3 +93,27 @@ test('saveScript flag enables .ad session log writing', () => {
   const files = fs.readdirSync(root);
   assert.equal(files.filter((file) => file.endsWith('.ad')).length, 1);
 });
+
+test('writeSessionLog persists open --relaunch in script output', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-session-log-relaunch-'));
+  const store = new SessionStore(root);
+  const session = makeSession('default');
+  store.recordAction(session, {
+    command: 'open',
+    positionals: ['Settings'],
+    flags: { platform: 'ios', saveScript: true, relaunch: true },
+    result: {},
+  });
+  store.recordAction(session, {
+    command: 'close',
+    positionals: [],
+    flags: { platform: 'ios' },
+    result: {},
+  });
+
+  store.writeSessionLog(session);
+  const scriptFile = fs.readdirSync(root).find((file) => file.endsWith('.ad'));
+  assert.ok(scriptFile);
+  const script = fs.readFileSync(path.join(root, scriptFile!), 'utf8');
+  assert.match(script, /open "Settings" --relaunch/);
+});

package/src/daemon/handlers/__tests__/replay-heal.test.ts

@@ -365,6 +365,87 @@ test('replay --update heals selector in is command', async () => {
   assert.ok(rewrittenSelector.includes('auth_continue'));
 });
 
+test('replay --update heals numeric get text drift when numeric candidate value is unique', async () => {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-replay-heal-get-numeric-'));
+  const sessionsDir = path.join(tempRoot, 'sessions');
+  const replayPath = path.join(tempRoot, 'replay.ad');
+  const sessionStore = new SessionStore(sessionsDir);
+  const sessionName = 'heal-get-numeric-session';
+  sessionStore.set(sessionName, makeSession(sessionName));
+
+  writeReplayFile(replayPath, {
+    ts: Date.now(),
+    command: 'get',
+    positionals: ['text', 'role="statictext" label="2" || label="2"'],
+    flags: {},
+    result: {},
+  });
+
+  const invokeCalls: string[] = [];
+  const invoke = async (request: DaemonRequest): Promise<DaemonResponse> => {
+    if (request.command !== 'get') {
+      return { ok: false, error: { code: 'INVALID_ARGS', message: `unexpected command ${request.command}` } };
+    }
+    const selector = request.positionals?.[1] ?? '';
+    invokeCalls.push(selector);
+    if (selector.includes('label="2"')) {
+      return { ok: false, error: { code: 'COMMAND_FAILED', message: 'selector stale' } };
+    }
+    if (selector.includes('label="20"')) {
+      return { ok: true, data: { text: '20' } };
+    }
+    return { ok: false, error: { code: 'COMMAND_FAILED', message: 'unexpected selector' } };
+  };
+
+  const dispatch = async (): Promise<Record<string, unknown> | void> => {
+    return {
+      nodes: [
+        {
+          index: 0,
+          type: 'XCUIElementTypeStaticText',
+          label: '20',
+          rect: { x: 0, y: 100, width: 100, height: 24 },
+          enabled: true,
+          hittable: true,
+        },
+        {
+          index: 1,
+          type: 'XCUIElementTypeStaticText',
+          label: 'Version: 0.84.0',
+          rect: { x: 0, y: 200, width: 220, height: 17 },
+          enabled: true,
+          hittable: true,
+        },
+      ],
+      truncated: false,
+      backend: 'xctest',
+    };
+  };
+
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'replay',
+      positionals: [replayPath],
+      flags: { replayUpdate: true },
+    },
+    sessionName,
+    logPath: path.join(tempRoot, 'daemon.log'),
+    sessionStore,
+    invoke,
+    dispatch,
+  });
+
+  assert.ok(response);
+  assert.equal(response.ok, true, JSON.stringify(response));
+  if (response.ok) {
+    assert.equal(response.data?.healed, 1);
+    assert.equal(response.data?.replayed, 1);
+  }
+  assert.equal(invokeCalls.length, 2);
+});
+
 test('replay rejects legacy JSON payload files', async () => {
   const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-replay-json-rejected-'));
   const sessionsDir = path.join(tempRoot, 'sessions');

package/src/daemon/handlers/__tests__/session.test.ts

@@ -120,3 +120,221 @@ test('boot succeeds for supported device in session', async () => {
     assert.equal(response.data?.booted, true);
   }
 });
+
+test('open URL on existing iOS session clears stale app bundle id', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'ios-session';
+  sessionStore.set(
+    sessionName,
+    {
+      ...makeSession(sessionName, {
+        platform: 'ios',
+        id: 'sim-1',
+        name: 'iPhone 15',
+        kind: 'simulator',
+        booted: true,
+      }),
+      appBundleId: 'com.example.old',
+      appName: 'Old App',
+    },
+  );
+
+  let dispatchedContext: Record<string, unknown> | undefined;
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'open',
+      positionals: ['https://example.com/path'],
+      flags: {},
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    dispatch: async (_device, _command, _positionals, _out, context) => {
+      dispatchedContext = context as Record<string, unknown> | undefined;
+      return {};
+    },
+    ensureReady: async () => {},
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, true);
+  const updated = sessionStore.get(sessionName);
+  assert.equal(updated?.appBundleId, undefined);
+  assert.equal(updated?.appName, 'https://example.com/path');
+  assert.equal(dispatchedContext?.appBundleId, undefined);
+});
+
+test('open app on existing iOS session resolves and stores bundle id', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'ios-session';
+  sessionStore.set(
+    sessionName,
+    {
+      ...makeSession(sessionName, {
+        platform: 'ios',
+        id: 'sim-1',
+        name: 'iPhone 15',
+        kind: 'simulator',
+        booted: true,
+      }),
+      appBundleId: 'com.example.old',
+      appName: 'Old App',
+    },
+  );
+
+  let dispatchedContext: Record<string, unknown> | undefined;
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'open',
+      positionals: ['settings'],
+      flags: {},
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    dispatch: async (_device, _command, _positionals, _out, context) => {
+      dispatchedContext = context as Record<string, unknown> | undefined;
+      return {};
+    },
+    ensureReady: async () => {},
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, true);
+  const updated = sessionStore.get(sessionName);
+  assert.equal(updated?.appBundleId, 'com.apple.Preferences');
+  assert.equal(updated?.appName, 'settings');
+  assert.equal(dispatchedContext?.appBundleId, 'com.apple.Preferences');
+});
+
+test('open --relaunch closes and reopens active session app', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'android-session';
+  sessionStore.set(
+    sessionName,
+    {
+      ...makeSession(sessionName, {
+        platform: 'android',
+        id: 'emulator-5554',
+        name: 'Pixel Emulator',
+        kind: 'emulator',
+        booted: true,
+      }),
+      appName: 'com.example.app',
+    },
+  );
+
+  const calls: Array<{ command: string; positionals: string[] }> = [];
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'open',
+      positionals: [],
+      flags: { relaunch: true },
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    dispatch: async (_device, command, positionals) => {
+      calls.push({ command, positionals });
+      return {};
+    },
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, true);
+  assert.equal(calls.length, 2);
+  assert.deepEqual(calls[0], { command: 'close', positionals: ['com.example.app'] });
+  assert.deepEqual(calls[1], { command: 'open', positionals: ['com.example.app'] });
+});
+
+test('open --relaunch rejects URL targets', async () => {
+  const sessionStore = makeSessionStore();
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'open',
+      positionals: ['https://example.com/path'],
+      flags: { relaunch: true },
+    },
+    sessionName: 'default',
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, false);
+  if (response && !response.ok) {
+    assert.equal(response.error.code, 'INVALID_ARGS');
+    assert.match(response.error.message, /does not support URL targets/i);
+  }
+});
+
+test('open --relaunch fails without app when no session exists', async () => {
+  const sessionStore = makeSessionStore();
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'open',
+      positionals: [],
+      flags: { relaunch: true },
+    },
+    sessionName: 'default',
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, false);
+  if (response && !response.ok) {
+    assert.equal(response.error.code, 'INVALID_ARGS');
+    assert.match(response.error.message, /requires an app argument/i);
+  }
+});
+
+test('replay parses open --relaunch flag and replays open with relaunch semantics', async () => {
+  const sessionStore = makeSessionStore();
+  const replayRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-replay-relaunch-'));
+  const replayPath = path.join(replayRoot, 'relaunch.ad');
+  fs.writeFileSync(replayPath, 'open "Settings" --relaunch\n');
+
+  const invoked: DaemonRequest[] = [];
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'replay',
+      positionals: [replayPath],
+      flags: {},
+    },
+    sessionName: 'default',
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: async (req) => {
+      invoked.push(req);
+      return { ok: true, data: {} };
+    },
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, true);
+  if (response && response.ok) {
+    assert.equal(response.data?.replayed, 1);
+  }
+  assert.equal(invoked.length, 1);
+  assert.equal(invoked[0]?.command, 'open');
+  assert.deepEqual(invoked[0]?.positionals, ['Settings']);
+  assert.equal(invoked[0]?.flags?.relaunch, true);
+});

package/src/daemon/handlers/interaction.ts

@@ -310,6 +310,7 @@ export async function handleInteractionCommands(params: {
       platform: session.device.platform,
       requireRect: false,
       requireUnique: true,
+      disambiguateAmbiguous: sub === 'text',
     });
     if (!resolved) {
       return {