diff --git a/packages/command-surface/src/management/app.ts b/packages/command-surface/src/management/app.ts index 77bba7d068..9de7aa211a 100644 --- a/packages/command-surface/src/management/app.ts +++ b/packages/command-surface/src/management/app.ts @@ -95,7 +95,7 @@ const openCommandMetadata = defineFieldCommandMetadata( const closeCommandMetadata = defineFieldCommandMetadata( 'close', - 'Close the named app, or close the active session app when app is omitted. The shutdown option also stops the session simulator or emulator where supported; close alone never stops the device. Android ADB close fails with android-app-close-timeout if the app stays foreground past 2s, a killed process does not exit within 10s, or a new process runs past 2s; a relaunching open accepts that new process. It fails with android-process-probe-unavailable when adb pidof cannot list the app processes; if that happens before the force-stop, the app keeps running. If close cannot confirm its cleanup on a session that holds a device claim, the session and its claim stay. A repeated close retries cleanup with the same options, except that save-script must be omitted after publication.', + 'Close the named app, or close the active session app when app is omitted. The shutdown option also stops the session simulator or emulator where supported; close alone never stops the device. Android ADB close fails with android-app-close-timeout if the app stays foreground past 2s, a killed process does not exit within 10s, or a new process runs past 2s; a relaunching open accepts that new process. For foreground timeouts, JSON details include foregroundObservations and initialProcessCount; the android_close_foreground_fence request diagnostic retains the last five probe results and timings, including when a probe throws. It fails with android-process-probe-unavailable when adb pidof cannot list the app processes; if that happens before the force-stop, the app keeps running. If close cannot confirm its cleanup on a session that holds a device claim, the session and its claim stay. A repeated close retries cleanup with the same options, except that save-script must be omitted after publication.', { app: stringField('Optional app to close.'), shutdown: booleanField('Shutdown the session/device where supported.'), diff --git a/packages/daemon/src/server/__tests__/request-router-android-foreground-evidence.test.ts b/packages/daemon/src/server/__tests__/request-router-android-foreground-evidence.test.ts new file mode 100644 index 0000000000..5702f5ded7 --- /dev/null +++ b/packages/daemon/src/server/__tests__/request-router-android-foreground-evidence.test.ts @@ -0,0 +1,97 @@ +import { test, expect, vi } from 'vitest'; +import fs from 'node:fs'; +import path from 'node:path'; +import { createTestDeviceInventoryGateways } from '@agent-device/device-selection/inventory-gateways-fixtures'; +import { createTestHostEnvironment, mkdtempForTestSync } from '@agent-device/test-kit'; +import { AppError } from '@agent-device/kernel/errors'; +import { getResolveTargetDeviceMock } from '../../__tests__/support/request-router-dispatch-mocks.ts'; +import { fakeCreateCommandSurface } from '../../__tests__/support/command-surface-fake.ts'; +import { dispatchApplicationLifecycleEffect } from '../../__tests__/support/application-lifecycle-runtime-fixture.ts'; +import { + createRequestHandler, + lifecycleDeviceRuntimeGateway, +} from '../../__tests__/support/test-device-runtime-gateway.ts'; +import { makeSessionStore } from '../../__tests__/support/store-factory.ts'; +import { LeaseRegistry } from '../../resources/lease-registry.ts'; +import { makeAndroidDevice, openRequest } from './request-router-open-harness.ts'; +import { emitDiagnostic } from '@agent-device/host-kit/diagnostics'; + +vi.mock('../../core/device/device-ready.ts', () => ({ + ensureDeviceReady: vi.fn(async () => {}), +})); +const mockResolveTargetDevice = vi.mocked(getResolveTargetDeviceMock()); +function createOpenHandler(sessionStore: ReturnType) { + return createRequestHandler({ + host: createTestHostEnvironment(), + createCommandSurface: fakeCreateCommandSurface, + logPath: path.join(mkdtempForTestSync('daemon'), 'daemon.log'), + token: 'test-token', + sessionStore, + leaseRegistry: new LeaseRegistry(), + deviceRuntimeGateway: lifecycleDeviceRuntimeGateway, + deviceInventoryGateways: createTestDeviceInventoryGateways(), + trackDownloadableArtifact: () => 'artifact-id', + }); +} + +test('open relaunch retains Android foreground probe failure in the serialized response and request artifact', async () => { + const device = makeAndroidDevice('emulator-fence'); + const failure = new AppError( + 'COMMAND_FAILED', + 'probe failed', + { reason: 'probe-failed' }, + new Error('root cause'), + ); + try { + const sessionStore = makeSessionStore('android-fence-request-'); + mockResolveTargetDevice.mockResolvedValue(device); + vi.mocked(dispatchApplicationLifecycleEffect).mockImplementationOnce(async () => { + emitDiagnostic({ + phase: 'android_close_foreground_fence', + data: { + initialProcessCount: 1, + observations: [{ startMs: 0, endMs: 10, remainingMs: 1990, result: 'error' }], + }, + }); + throw failure; + }); + const response = await createOpenHandler(sessionStore)( + openRequest('fence-session', { platform: 'android', relaunch: true }, 'fence-request', {}, [ + 'com.example.app', + ]), + ); + expect(response.ok).toBe(false); + if (response.ok) throw new Error('expected failure'); + const wire = JSON.parse(JSON.stringify(response)); + expect(wire.error).toMatchObject({ + code: 'COMMAND_FAILED', + details: { reason: 'probe-failed' }, + }); + expect(response.error.logPath).toBe( + path.join( + sessionStore.resolveDaemonStateDir(), + 'sessions', + 'fence-session', + 'requests', + 'fence-request.ndjson', + ), + ); + const events = fs + .readFileSync(response.error.logPath!, 'utf8') + .trim() + .split('\n') + .map((line) => JSON.parse(line)); + expect(events).toContainEqual( + expect.objectContaining({ + phase: 'android_close_foreground_fence', + data: { + initialProcessCount: 1, + observations: [{ startMs: 0, endMs: 10, remainingMs: 1990, result: 'error' }], + }, + }), + ); + expect(events).toContainEqual(expect.objectContaining({ phase: 'request_failed' })); + } finally { + vi.mocked(dispatchApplicationLifecycleEffect).mockReset(); + } +}); diff --git a/packages/platform-android/src/__tests__/app-lifecycle-close.test.ts b/packages/platform-android/src/__tests__/app-lifecycle-close.test.ts index 4671aa6c9a..fe82e1ddc9 100644 --- a/packages/platform-android/src/__tests__/app-lifecycle-close.test.ts +++ b/packages/platform-android/src/__tests__/app-lifecycle-close.test.ts @@ -3,7 +3,7 @@ import assert from 'node:assert/strict'; import { closeAndroidApp, openAndroidApp } from '../app-lifecycle.ts'; import { withAndroidAdbProvider } from '../adb-executor.ts'; import type { DeviceInfo } from '@agent-device/kernel/device'; -import { AppError } from '@agent-device/kernel/errors'; +import { AppError, normalizeError } from '@agent-device/kernel/errors'; import { ANDROID_EMULATOR } from './test-utils/device-fixtures.ts'; import './test-utils/android-host-test-setup.ts'; @@ -217,6 +217,17 @@ test.each([ phase, packageName: 'com.example.app', timeoutMs, + ...(phase === 'foreground' + ? { + initialProcessCount: 1, + foregroundObservations: [1750, 1800, 1850, 1900, 1950].map((ms) => ({ + startMs: ms, + endMs: ms, + remainingMs: 2000 - ms, + result: 'target', + })), + } + : {}), }); return true; }, @@ -278,12 +289,14 @@ test.each([ : assert.rejects(close, (error: unknown) => { assert.ok(error instanceof AppError); assert.equal(error.code, 'COMMAND_FAILED'); - assert.deepEqual(error.details, { - reason: 'android-app-close-timeout', - phase, - packageName: 'com.example.app', - timeoutMs: 2_000, - }); + assert.equal(error.details?.reason, 'android-app-close-timeout'); + assert.equal(error.details?.phase, phase); + assert.equal(error.details?.timeoutMs, 2_000); + if (phase === 'foreground') { + assert.deepEqual(normalizeError(error).details?.foregroundObservations, [ + { startMs: 0, endMs: completionMs, remainingMs: 0, result: 'other' }, + ]); + } return true; }); await Promise.all([result, vi.runAllTimersAsync()]); @@ -528,3 +541,70 @@ test('closeAndroidApp reports an unanswered pidof after force-stop instead of an ); assert.equal(pidofCalls, 2); }); + +test('foreground probe failure retains bounded history in request diagnostics and rethrows the original error', async () => { + vi.useFakeTimers(); + vi.setSystemTime(0); + const { withDiagnosticsScope, flushDiagnosticsToSessionFile } = + await import('@agent-device/host-kit/diagnostics'); + const fs = await import('node:fs'); + const path = await import('node:path'); + const { mkdtempForTestSync } = await import('@agent-device/test-kit'); + const logPath = path.join(mkdtempForTestSync('foreground-fence'), 'request.ndjson'); + const cause = new Error('underlying failure'); + const failure = new AppError('COMMAND_FAILED', 'probe failed', { reason: 'probe-failed' }, cause); + let probes = 0; + try { + await withDiagnosticsScope({ logPath }, async () => { + await withAndroidAdbProvider( + { + exec: async (args) => { + if (args[1] === 'dumpsys' && ++probes === 7) throw failure; + return { + stdout: + args[1] === 'dumpsys' + ? 'mCurrentFocus=Window{42 u0 com.example.app/.Main}\n' + : '123\n', + stderr: '', + exitCode: 0, + }; + }, + }, + { serial: ANDROID_EMULATOR.id }, + async () => { + const rejected = assert.rejects( + closeAndroidApp(ANDROID_EMULATOR, 'com.example.app'), + (error: unknown) => { + assert.equal(error, failure); + assert.equal(failure.cause, cause); + assert.equal(failure.details?.reason, 'probe-failed'); + return true; + }, + ); + await Promise.all([rejected, vi.runAllTimersAsync()]); + }, + ); + flushDiagnosticsToSessionFile({ force: true }); + }); + const events = fs + .readFileSync(logPath, 'utf8') + .trim() + .split('\n') + .map((line) => JSON.parse(line)); + const event = events.find((item) => item.phase === 'android_close_foreground_fence'); + assert.deepEqual(event.data, { + initialProcessCount: 1, + observations: [ + ...[100, 150, 200, 250].map((ms) => ({ + startMs: ms, + endMs: ms, + remainingMs: 2000 - ms, + result: 'target', + })), + { startMs: 300, endMs: 300, remainingMs: 1700, result: 'error' }, + ], + }); + } finally { + vi.useRealTimers(); + } +}); diff --git a/packages/platform-android/src/app-lifecycle.ts b/packages/platform-android/src/app-lifecycle.ts index fb959c6049..0d2a7344ce 100644 --- a/packages/platform-android/src/app-lifecycle.ts +++ b/packages/platform-android/src/app-lifecycle.ts @@ -1,6 +1,7 @@ import { AppError } from '@agent-device/kernel/errors'; import type { AppStateRuntimeResult } from '@agent-device/contracts/app-state-runtime'; import { Deadline, sleep } from '@agent-device/host-kit/retry'; +import { emitDiagnostic } from '@agent-device/host-kit/diagnostics'; import { isCommandTimeoutError } from '@agent-device/host-kit/command'; import type { AppsFilter } from '@agent-device/contracts/device'; import type { DeviceInfo } from '@agent-device/kernel/device'; @@ -664,8 +665,10 @@ async function stopAndroidPackage(device: DeviceInfo, packageName: string): Prom throw androidPidofUnavailableError(packageName); } await runAndroidShell(device, ['am', 'force-stop', packageName]); - const expired = await waitForAndroidPackageStopped(device, packageName, killed); - if (expired) throw androidCloseTimeoutError(packageName, expired); + const observations: ForegroundObservation[] = []; + const expired = await waitForAndroidPackageStopped(device, packageName, killed, observations); + if (expired === 'foreground') emitForegroundFenceEvidence(observations, killed.size); + if (expired) throw androidCloseTimeoutError(packageName, expired, observations, killed.size); } /** @@ -729,8 +732,16 @@ async function waitForAndroidPackageStopped( device: DeviceInfo, packageName: string, killed: ReadonlySet, + observations: ForegroundObservation[], ): Promise { - if (!(await waitForAndroidPackageNotForeground(device, packageName))) return 'foreground'; + let notForeground: boolean; + try { + notForeground = await waitForAndroidPackageNotForeground(device, packageName, observations); + } catch (error) { + emitForegroundFenceEvidence(observations, killed.size); + throw error; + } + if (!notForeground) return 'foreground'; if (!(await waitForAndroidKilledProcessesExit(device, packageName, killed))) return 'exit'; if (!(await waitForAndroidPackageProcessGone(device, packageName))) return 'process'; return undefined; @@ -754,25 +765,53 @@ const ANDROID_CLOSE_TIMEOUTS: Record< }, }; -function androidCloseTimeoutError(packageName: string, phase: AndroidStopFencePhase): AppError { +function androidCloseTimeoutError( + packageName: string, + phase: AndroidStopFencePhase, + observations: ForegroundObservation[], + initialProcessCount: number, +): AppError { const { message, timeoutMs } = ANDROID_CLOSE_TIMEOUTS[phase]; return new AppError('COMMAND_FAILED', `Android app ${packageName} ${message}`, { reason: 'android-app-close-timeout', phase, packageName, timeoutMs, + ...(phase === 'foreground' + ? { foregroundObservations: observations, initialProcessCount } + : {}), + }); +} + +type ForegroundObservation = { + startMs: number; + endMs: number; + remainingMs: number; + result: 'target' | 'other' | 'unknown' | 'error'; +}; + +function emitForegroundFenceEvidence( + observations: ForegroundObservation[], + initialProcessCount: number, +): void { + emitDiagnostic({ + phase: 'android_close_foreground_fence', + data: { initialProcessCount, observations }, }); } function waitForAndroidPackageNotForeground( device: DeviceInfo, packageName: string, + observations?: ForegroundObservation[], ): Promise { return waitForAndroidForegroundPackage( device, Deadline.fromTimeoutMs(ANDROID_CLOSE_FOCUS_TIMEOUT_MS), ANDROID_CLOSE_FOCUS_POLL_MS, (foregroundPackage) => foregroundPackage !== packageName, + observations, + packageName, ); } @@ -782,9 +821,25 @@ async function waitForAndroidForegroundPackage( deadline: Deadline, pollMs: number, matches: (foregroundPackage: string | undefined) => boolean, + observations?: ForegroundObservation[], + targetPackage?: string, ): Promise { while (!deadline.isExpired()) { - const foreground = await probeBeforeDeadline(deadline, () => readAndroidForegroundApp(device)); + const foreground = await probeBeforeDeadline(deadline, async () => { + if (!observations) return await readAndroidForegroundApp(device); + const startMs = deadline.elapsedMs(); + let result: ForegroundObservation['result'] = 'error'; + try { + const value = await readAndroidForegroundApp(device); + result = !value ? 'unknown' : value.package === targetPackage ? 'target' : 'other'; + return value; + } finally { + const endedAt = Date.now(); + const endMs = deadline.elapsedMs(endedAt); + observations.push({ startMs, endMs, remainingMs: deadline.remainingMs(endedAt), result }); + if (observations.length > 5) observations.shift(); + } + }); if (!foreground) break; if (matches(foreground.value?.package)) return true; await sleep(pollMs); diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md index 90dac45f0a..2a8dd7588a 100644 --- a/website/docs/docs/commands.md +++ b/website/docs/docs/commands.md @@ -107,6 +107,7 @@ Open apps and links: - Android React Native: `open --relaunch` needs an installed package name. Install or reinstall the APK first; `open --relaunch` is rejected. For Metro-backed JS changes, run `metro reload` before reaching for `open --relaunch`. - Android (adb): an intent target such as `open settings` records the package that opened as `appBundleId`. `open settings --relaunch` stops and restarts that app. If the intent matches more than one activity, `--relaunch` fails. - Android (ADB): `close` force-stops the app, then checks for 2 seconds that it has left the foreground, waits up to 10 seconds for the processes it killed to exit, and checks for 2 more that no new process started. If a check window ends first, `close` fails with `details.reason: android-app-close-timeout` and `details.phase` set to `foreground`, `exit`, or `process`; a process that survives the force-stop fails with `exit`, and apps Android restarts at once, such as the launcher, fail with `process`. `open --relaunch` runs the same checks but accepts a new process once the killed ones exit, because Android can restart an app at once for a background client, such as Settings on Android 17. When `pidof` cannot list the app's processes, `close` fails with `details.reason: android-process-probe-unavailable`; if that happens before the force-stop, the app keeps running. +- To diagnose an Android foreground-close timeout (`details.phase: foreground`), inspect `details.foregroundObservations` and `details.initialProcessCount` in the JSON error. The observations retain at most the last five probes: `startMs` and `endMs` are milliseconds from the start of the foreground check, `remainingMs` is the budget left when the probe ends, and `result` is `target`, `other`, or `unknown`. The process count is read before force-stop. In the [session request log](/docs/sessions#find-a-sessions-logs-and-artifacts), the `android_close_foreground_fence` diagnostic records this history as `data.observations` with `data.initialProcessCount`. If a foreground probe throws, that diagnostic also retains the history with an `error` result for the failed probe; the command reports the probe failure. - When `close` cannot confirm its cleanup on a session that holds a device claim, it fails and keeps the session and its claim, so the device is not handed on unconfirmed. Run `close` again with the same options to retry the cleanup and release the device, leaving out `--save-script` once the first attempt has published the script. Only `close`, or a successful `open`, is supported on the kept session: other commands work, but the session stays marked, so an idle daemon can still shut it down. If nobody retries, the kept session does not keep the daemon alive: when the daemon has been idle for its idle timeout and shuts down, its shutdown retries the cleanup, and a claim it still cannot confirm goes stale instead of being released. Embedded runtimes and `AGENT_DEVICE_DAEMON_IDLE_TIMEOUT_MS=0` never shut down for idleness, so there a retried `close` is the only release. - If `open --relaunch` leaves an existing session's device effects unconfirmed, the session and claim remain available for `close`, but idle shutdown can retry cleanup and leave an unconfirmed claim stale; embedded runtimes and `AGENT_DEVICE_DAEMON_IDLE_TIMEOUT_MS=0` do not shut down for idleness, so use `close` to release the claim.