Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 1 addition & 1 deletion packages/command-surface/src/management/app.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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.'),
Expand Down
Original file line number Diff line number Diff line change
@@ -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<typeof makeSessionStore>) {
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();
}
});
Original file line number Diff line number Diff line change
Expand Up @@ -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';

Expand Down Expand Up @@ -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;
},
Expand Down Expand Up @@ -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()]);
Expand Down Expand Up @@ -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();
}
});
65 changes: 60 additions & 5 deletions packages/platform-android/src/app-lifecycle.ts
Original file line number Diff line number Diff line change
@@ -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';
Expand Down Expand Up @@ -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);
}

/**
Expand Down Expand Up @@ -729,8 +732,16 @@ async function waitForAndroidPackageStopped(
device: DeviceInfo,
packageName: string,
killed: ReadonlySet<string>,
observations: ForegroundObservation[],
): Promise<AndroidStopFencePhase | undefined> {
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;
Expand All @@ -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 }
: {}),
});
Comment thread
thymikee marked this conversation as resolved.
Resolved
}

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<boolean> {
return waitForAndroidForegroundPackage(
device,
Deadline.fromTimeoutMs(ANDROID_CLOSE_FOCUS_TIMEOUT_MS),
ANDROID_CLOSE_FOCUS_POLL_MS,
(foregroundPackage) => foregroundPackage !== packageName,
observations,
packageName,
);
}

Expand All @@ -782,9 +821,25 @@ async function waitForAndroidForegroundPackage(
deadline: Deadline,
pollMs: number,
matches: (foregroundPackage: string | undefined) => boolean,
observations?: ForegroundObservation[],
targetPackage?: string,
): Promise<boolean> {
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);
Expand Down
1 change: 1 addition & 0 deletions website/docs/docs/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <apk|aab> --relaunch` is rejected. For Metro-backed JS changes, run `metro reload` before reaching for `open <app> --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.

Expand Down
Loading