diff --git a/packages/contracts/src/application-lifecycle-interaction.test.ts b/packages/contracts/src/application-lifecycle-interaction.test.ts index ca8212c59e..33b2414b73 100644 --- a/packages/contracts/src/application-lifecycle-interaction.test.ts +++ b/packages/contracts/src/application-lifecycle-interaction.test.ts @@ -5,6 +5,7 @@ import type { OpenApplicationInput } from './application-lifecycle-runtime.ts'; import { bindDirectApplicationLifecycle, bindLocalApplicationLifecycleInteractor, + bindLocalDirectApplicationLifecycle, bindProviderApplicationLifecycleInteractor, invokeApplicationOpen, } from './application-lifecycle-interaction.ts'; @@ -74,6 +75,7 @@ test('direct lifecycle owners preserve the daemon runtime launch URL follow-up', binding, owner: 'Linux', openTargetIdentity: 'app-name', + closeBeforeRelaunch: true, }); await lifecycle.openApplication( @@ -92,6 +94,68 @@ test('direct lifecycle owners preserve the daemon runtime launch URL follow-up', expect(calls[1]?.options).toHaveProperty('launchArgs', undefined); }); +/** An interactor that records each open and close it receives, in order. */ +function lifecycleRecordingInteractor(calls: string[]): Interactor { + return { + open: async (app: string, options?: { terminateRunningApp?: boolean }) => { + calls.push(`open ${app} terminate=${String(options?.terminateRunningApp)}`); + }, + openDevice: async () => undefined, + close: async (app: string) => { + calls.push(`close ${app}`); + }, + setSetting: async () => undefined, + } as unknown as Interactor; +} + +// The local direct owners (Linux, web, HarmonyOS, Vega) do not replace a running app on +// open, so a relaunch that reached only `open` left the app running as it was. +test('a local direct owner closes the running app before a relaunch open', async () => { + const calls: string[] = []; + const lifecycle = bindLocalDirectApplicationLifecycle({ + owner: 'Linux', + openTargetIdentity: 'app-name', + host: { resolve: async () => lifecycleRecordingInteractor(calls) }, + device: LINUX_DEVICE, + signal: new AbortController().signal, + }); + + await lifecycle.openApplication( + openInput({ target: 'gedit', positionals: ['gedit'], appBundleId: undefined, relaunch: true }), + ); + await lifecycle.openApplication( + openInput({ target: 'gedit', positionals: ['gedit'], appBundleId: undefined }), + ); + + expect(calls).toEqual([ + 'close gedit', + 'open gedit terminate=undefined', + 'open gedit terminate=undefined', + ]); +}); + +test('an owner whose open restarts the app receives the relaunch as terminateRunningApp', async () => { + const calls: string[] = []; + const lifecycle = bindDirectApplicationLifecycle({ + binding: bindProviderApplicationLifecycleInteractor({ + device: IOS_SIMULATOR, + signal: new AbortController().signal, + resolveInteractor: () => lifecycleRecordingInteractor(calls), + }), + owner: 'provider', + openTargetIdentity: 'bundle-id', + closeBeforeRelaunch: false, + }); + + await lifecycle.openApplication(openInput({ relaunch: true })); + await lifecycle.openApplication(openInput()); + + expect(calls).toEqual([ + 'open com.example.app terminate=true', + 'open com.example.app terminate=false', + ]); +}); + test.each([ { name: 'more than two positionals', diff --git a/packages/contracts/src/application-lifecycle-interaction.ts b/packages/contracts/src/application-lifecycle-interaction.ts index 5b0e5c085f..ef1abca297 100644 --- a/packages/contracts/src/application-lifecycle-interaction.ts +++ b/packages/contracts/src/application-lifecycle-interaction.ts @@ -268,8 +268,12 @@ export type DirectApplicationLifecycleParams = Readonly<{ /** Names the owner in the failure reported for an operation it does not implement. */ owner: string; openTargetIdentity: DirectOpenTargetIdentity; - /** Owners whose native open does not replace a running application close it first. */ - closeBeforeRelaunch?: boolean; + /** + * How `open --relaunch` restarts a running application. `true`: the binding closes it before the + * open, for owners whose native open does not replace a running application. `false`: the + * interactor's open receives `terminateRunningApp` and owns the restart. + */ + closeBeforeRelaunch: boolean; /** Port reverse is the one non-direct operation a provider owner may still implement. */ configureProviderPortReverse?: ApplicationLifecycleRuntimeOperations['configureProviderPortReverse']; }>; @@ -327,6 +331,7 @@ async function openDirectApplication( positionals: input.positionals, appBundleId: input.appBundleId, execution: input.execution, + ...(params.closeBeforeRelaunch ? {} : { terminateRunningApp: input.relaunch }), }); const followUpUrl = followUpRuntimeLaunchUrl(input); if (followUpUrl) { @@ -405,6 +410,8 @@ export function bindLocalDirectApplicationLifecycle( return bindDirectApplicationLifecycle({ owner: params.owner, openTargetIdentity: params.openTargetIdentity, + // No local direct owner (Linux, web, HarmonyOS, Vega) replaces a running app on open. + closeBeforeRelaunch: true, binding: bindLocalApplicationLifecycleInteractor({ device: params.device, signal: params.signal, diff --git a/packages/platform-linux/src/__tests__/tool-provider.test.ts b/packages/platform-linux/src/__tests__/tool-provider.test.ts index 1bd97bdf03..200f6f51c2 100644 --- a/packages/platform-linux/src/__tests__/tool-provider.test.ts +++ b/packages/platform-linux/src/__tests__/tool-provider.test.ts @@ -1,11 +1,30 @@ -import { bindTestCommandHost } from '@agent-device/test-kit'; -import { afterAll, beforeEach, test } from 'vitest'; +import { bindTestCommandHost, mkdtempForTest } from '@agent-device/test-kit'; +import fs from 'node:fs'; +import path from 'node:path'; +import { afterAll, beforeEach, test, vi } from 'vitest'; +import { + countDiagnosticEventsByPhase, + withDiagnosticsScope, +} from '@agent-device/host-kit/diagnostics'; import assert from 'node:assert/strict'; import { pressLinux } from '../input-actions.ts'; -import { createLocalLinuxToolProvider, withLinuxToolProvider } from '../tool-provider.ts'; +import { + createLocalLinuxToolProvider, + resolveLinuxToolProvider, + withLinuxToolProvider, + type LinuxToolCommandExecutor, + type LinuxToolDetachedLauncher, + type LinuxToolProviderOverrides, +} from '../tool-provider.ts'; +import type { ExecDetachedExit } from '@agent-device/host-kit/command'; bindTestCommandHost(); +/** For a provider that injects an executor and launches no app in the scenario. */ +const launchesNoApp: LinuxToolDetachedLauncher = (cmd) => { + throw new Error(`this scenario launches no app: ${cmd}`); +}; + const originalPlatform = process.platform; const originalEnv = { ...process.env }; @@ -18,6 +37,7 @@ beforeEach(() => { test('scoped Linux tool provider handles input discovery and command execution', async () => { const commands: Array<[string, string[]]> = []; const provider = createLocalLinuxToolProvider({ + launchDetached: launchesNoApp, host: { env: { ...process.env, XDG_SESSION_TYPE: 'x11' }, cwd: process.cwd() }, whichCommand: async (cmd) => cmd === 'xdotool', runCommand: async (cmd, args) => { @@ -41,6 +61,7 @@ test('scoped Linux tool provider handles input discovery and command execution', test('xdotool press skips the --sync move when the pointer already sits on the target', async () => { const commands: Array<[string, string[]]> = []; const provider = createLocalLinuxToolProvider({ + launchDetached: launchesNoApp, host: { env: { ...process.env, XDG_SESSION_TYPE: 'x11' }, cwd: process.cwd() }, whichCommand: async (cmd) => cmd === 'xdotool', runCommand: async (cmd, args) => { @@ -64,6 +85,7 @@ test('xdotool press skips the --sync move when the pointer already sits on the t test('scoped Linux input provider handles semantic input without host tool discovery', async () => { const inputCalls: Array<[string, string, string, string]> = []; const provider = createLocalLinuxToolProvider({ + launchDetached: launchesNoApp, host: { env: { ...process.env, XDG_SESSION_TYPE: 'x11' }, cwd: process.cwd() }, whichCommand: async (cmd) => { throw new Error(`unexpected input discovery: ${cmd}`); @@ -93,6 +115,7 @@ test('scoped Linux input provider handles semantic input without host tool disco test('Linux tool provider scopes do not share cached input tool resolution', async () => { const providerA = createLocalLinuxToolProvider({ + launchDetached: launchesNoApp, host: { env: { ...process.env, XDG_SESSION_TYPE: 'x11', WAYLAND_DISPLAY: '' }, cwd: process.cwd(), @@ -101,6 +124,7 @@ test('Linux tool provider scopes do not share cached input tool resolution', asy runCommand: async () => ({ exitCode: 0, stdout: '', stderr: '' }), }); const providerB = createLocalLinuxToolProvider({ + launchDetached: launchesNoApp, host: { env: { ...process.env, XDG_SESSION_TYPE: 'wayland', WAYLAND_DISPLAY: 'wayland-0' }, cwd: process.cwd(), @@ -143,6 +167,7 @@ test('Linux tool provider scopes do not share cached input tool resolution', asy test('local Linux desktop provider translates semantic lifecycle calls to host tools', async () => { const commands: Array<[string, string[], boolean | undefined]> = []; const provider = createLocalLinuxToolProvider({ + launchDetached: launchesNoApp, host: { env: { ...process.env, XDG_SESSION_TYPE: 'x11' }, cwd: process.cwd() }, whichCommand: async (cmd) => cmd === 'wmctrl', runCommand: async (cmd, args, options) => { @@ -162,9 +187,129 @@ test('local Linux desktop provider translates semantic lifecycle calls to host t ]); }); +// `open ` used to run the app as a piped child of the daemon, which kept every +// byte the app printed in daemon memory for the app's whole life. The default launcher detaches, +// for a provider built over a host and for the ambient one a call outside any runtime resolves. +test.skipIf(!fs.existsSync('/proc/self/fd')).each([ + [ + 'a host-built', + () => + createLocalLinuxToolProvider({ + host: { env: process.env, cwd: process.cwd() }, + whichCommand: async (cmd) => cmd === 'fake-desktop-app', + }), + ], + ['the ambient', () => resolveLinuxToolProvider()], +] as const)( + '%s Linux desktop provider launches an app binary detached from daemon pipes', + async (_name, makeProvider) => { + const binDir = await mkdtempForTest('linux-open-binary-'); + const report = path.join(binDir, 'stdout-target'); + fs.writeFileSync( + path.join(binDir, 'fake-desktop-app'), + `#!/bin/sh\nreadlink /proc/self/fd/2 > '${report}.tmp' && mv '${report}.tmp' '${report}'\n`, + { mode: 0o755 }, + ); + const originalPath = process.env['PATH']; + process.env['PATH'] = `${binDir}${path.delimiter}${originalPath ?? ''}`; + try { + await makeProvider().desktop.openTarget('fake-desktop-app'); + + await vi.waitFor(() => assert.ok(fs.existsSync(report))); + assert.equal(fs.readFileSync(report, 'utf8').trim(), '/dev/null'); + } finally { + process.env['PATH'] = originalPath; + } + }, +); + +test('local Linux desktop provider launches an app binary through its detached launcher', async () => { + const launches: Array<[string, string[]]> = []; + const captured: string[] = []; + const provider = createLocalLinuxToolProvider({ + host: { env: process.env, cwd: process.cwd() }, + whichCommand: async (cmd) => cmd === 'demo-app', + runCommand: async (cmd) => { + captured.push(cmd); + return { exitCode: 0, stdout: '', stderr: '' }; + }, + launchDetached: (cmd, args) => { + launches.push([cmd, args]); + return { exited: new Promise(() => {}) }; + }, + }); + + await provider.desktop.openTarget('demo-app'); + + assert.deepEqual(launches, [['demo-app', []]]); + assert.deepEqual(captured, []); +}); + +/** The `linux_app_launch` events one `openTarget` writes, once its launch has exited. */ +async function launchDiagnostics(exit: ExecDetachedExit): Promise[]> { + const logPath = path.join(await mkdtempForTest('linux-launch-diagnostics-'), 'request.ndjson'); + let exited: Promise | undefined; + const provider = createLocalLinuxToolProvider({ + host: { env: process.env, cwd: process.cwd() }, + whichCommand: async () => true, + launchDetached: () => { + exited = Promise.resolve(exit); + return { exited }; + }, + }); + return await withDiagnosticsScope({ command: 'open', debug: true, logPath }, async () => { + await provider.desktop.openTarget('demo-app'); + await exited; + const expected = countDiagnosticEventsByPhase(['linux_app_launch']); + const read = () => + (fs.existsSync(logPath) ? fs.readFileSync(logPath, 'utf8').trim().split('\n') : []) + .filter((line) => line.length > 0) + .map((line) => JSON.parse(line) as { phase: string; data?: Record }) + .filter((event) => event.phase === 'linux_app_launch'); + await vi.waitFor(() => assert.equal(read().length, expected)); + return read().map((event) => event.data ?? {}); + }); +} + +test.each([ + [ + 'a start failure', + { pid: 1, error: 'spawn demo-app ENOENT' }, + { error: 'spawn demo-app ENOENT' }, + ], + ['a non-zero exit', { pid: 2, exitCode: 3 }, { exitCode: 3 }], + ['a signal', { pid: 3, signal: 'SIGKILL' }, { signal: 'SIGKILL' }], +] as const)( + 'local Linux desktop provider reports %s of a launched app once', + async (_name, exit, field) => { + assert.deepEqual(await launchDiagnostics(exit), [{ app: 'demo-app', ...field }]); + }, +); + +test('local Linux desktop provider reports nothing for a launched app that exits cleanly', async () => { + assert.deepEqual(await launchDiagnostics({ pid: 4, exitCode: 0 }), []); +}); + +// An injected executor owns process execution, so the type refuses one without its own launcher: +// the host-local detached runner must never stand in beside it. The directive fails typecheck if +// the refusal goes away. +test('a Linux provider that injects runCommand must also inject launchDetached', () => { + const runCommand: LinuxToolCommandExecutor = async () => ({ + exitCode: 0, + stdout: '', + stderr: '', + }); + // @ts-expect-error runCommand without launchDetached + const withoutLauncher: LinuxToolProviderOverrides = { runCommand }; + const withLauncher: LinuxToolProviderOverrides = { runCommand, launchDetached: launchesNoApp }; + assert.equal(withoutLauncher.launchDetached, undefined); + assert.equal(withLauncher.launchDetached, launchesNoApp); +}); + test('local Linux desktop provider falls back to pkill when wmctrl is unavailable', async () => { const commands: Array<[string, string[], boolean | undefined]> = []; const provider = createLocalLinuxToolProvider({ + launchDetached: launchesNoApp, host: { env: { ...process.env, XDG_SESSION_TYPE: 'x11' }, cwd: process.cwd() }, whichCommand: async () => false, runCommand: async (cmd, args, options) => { @@ -181,6 +326,7 @@ test('local Linux desktop provider falls back to pkill when wmctrl is unavailabl test('local Linux screenshot provider translates capture to available host tool', async () => { const commands: Array<[string, string[]]> = []; const provider = createLocalLinuxToolProvider({ + launchDetached: launchesNoApp, host: { env: { ...process.env, XDG_SESSION_TYPE: 'x11' }, cwd: process.cwd() }, whichCommand: async (cmd) => cmd === 'scrot', runCommand: async (cmd, args) => { diff --git a/packages/platform-linux/src/tool-provider.ts b/packages/platform-linux/src/tool-provider.ts index 645523a2dd..423fb2c5f6 100644 --- a/packages/platform-linux/src/tool-provider.ts +++ b/packages/platform-linux/src/tool-provider.ts @@ -3,7 +3,9 @@ import type { ScrollDirection } from '@agent-device/contracts/scroll-gesture'; import { AppError } from '@agent-device/kernel/errors'; import { runCmd, + runCmdDetachedMonitored, whichCmd, + type ExecDetachedExit, type ExecOptions, type ExecResult, commandHostEnvironment, @@ -33,6 +35,15 @@ export type LinuxToolCommandExecutor = ( export type LinuxToolAvailabilityChecker = (cmd: string) => Promise; +/** + * Starts a process that outlives the call, with its output discarded, and settles `exited` when it + * ends: with `error` when it could not start, else with its exit code or signal. + */ +export type LinuxToolDetachedLauncher = ( + cmd: string, + args: string[], +) => { exited: Promise }; + export type LinuxDesktopProvider = { openTarget(target: string): Promise; closeApp(app: string): Promise; @@ -80,6 +91,7 @@ export type LinuxToolProvider = { display: LinuxDisplayConfig; runCommand: LinuxToolCommandExecutor; whichCommand: LinuxToolAvailabilityChecker; + launchDetached: LinuxToolDetachedLauncher; desktop: LinuxDesktopProvider; clipboard?: LinuxClipboardProvider; screenshot?: LinuxScreenshotProvider; @@ -91,18 +103,34 @@ const whichOnPath = async (cmd: string): Promise => await whichCmd(cmd, commandHostEnvironment().env); /** A provider under construction; only the display decision is required up front. */ -type LinuxToolProviderParts = { display: LinuxDisplayConfig } & Partial; +/** + * The parts a caller may supply. A caller that injects `runCommand` owns process execution, so it + * also supplies `launchDetached`: the host-local detached runner never stands in beside an + * injected executor. + */ +export type LinuxToolProviderOverrides = Partial< + Omit +> & + ( + | { runCommand?: undefined; launchDetached?: LinuxToolDetachedLauncher } + | { runCommand: LinuxToolCommandExecutor; launchDetached: LinuxToolDetachedLauncher } + ); + +type LinuxToolProviderParts = { display: LinuxDisplayConfig } & LinuxToolProviderOverrides; /** Adds the local parts a partial provider omits; every part then belongs to this instance. */ function completeLocalLinuxToolProvider(provider: LinuxToolProviderParts): LinuxToolProvider { const runCommand = provider.runCommand ?? runCmd; const whichCommand = provider.whichCommand ?? whichOnPath; + const launchDetached = provider.launchDetached ?? runCmdDetachedMonitored; const display = provider.display; return { runCommand, whichCommand, + launchDetached, display, - desktop: provider.desktop ?? createLocalLinuxDesktopProvider(runCommand, whichCommand), + desktop: + provider.desktop ?? createLocalLinuxDesktopProvider(runCommand, whichCommand, launchDetached), clipboard: provider.clipboard ?? createLocalLinuxClipboardProvider(runCommand, whichCommand, display), screenshot: @@ -117,7 +145,7 @@ function completeLocalLinuxToolProvider(provider: LinuxToolProviderParts): Linux * one provider instance per composing runtime, owning its display decision (#3794). */ export function createLocalLinuxToolProvider( - options: { host: HostEnvironment } & Partial, + options: { host: HostEnvironment } & LinuxToolProviderOverrides, ): LinuxToolProvider { const { host, ...provider } = options; return completeLocalLinuxToolProvider({ @@ -132,9 +160,8 @@ export function createLocalLinuxToolProvider( * ambient read it replaces. A composed runtime binds its own host at `createLinuxInteractor`, so * its display decision never comes from here (#3794). */ +// Names no executor, so the host-local defaults apply, including the detached app launcher. const localLinuxToolProvider = completeLocalLinuxToolProvider({ - runCommand: runCmd, - whichCommand: whichOnPath, display: { detectDisplayServer: () => detectLinuxDisplayServer(commandHostEnvironment().env), }, @@ -168,9 +195,18 @@ export async function runLinuxToolCommand( return await resolveLinuxToolProvider().runCommand(cmd, args, options); } +/** What a launched app's exit says went wrong: a start failure, a non-zero exit, or a signal. */ +function describeLaunchExit(exit: ExecDetachedExit): Record | undefined { + if (exit.error !== undefined) return { error: exit.error }; + if (exit.signal !== undefined) return { signal: exit.signal }; + if (exit.exitCode !== undefined && exit.exitCode !== 0) return { exitCode: exit.exitCode }; + return undefined; +} + function createLocalLinuxDesktopProvider( runCommand: LinuxToolCommandExecutor, whichCommand: LinuxToolAvailabilityChecker, + launchDetached: LinuxToolDetachedLauncher, ): LinuxDesktopProvider { return { async openTarget(target) { @@ -180,11 +216,15 @@ function createLocalLinuxDesktopProvider( } if (await whichCommand(target)) { - runCommand(target, [], { allowFailure: true }).catch((error) => { + // A desktop app outlives the command that opened it. Run detached with its output + // discarded: a piped child would keep everything it prints in daemon memory until it exits. + void launchDetached(target, []).exited.then((exit) => { + const failure = describeLaunchExit(exit); + if (failure === undefined) return; emitDiagnostic({ level: 'warn', phase: 'linux_app_launch', - data: { app: target, error: String(error) }, + data: { app: target, ...failure }, }); }); await sleep(500); diff --git a/packages/platform-web/src/agent-browser-provider.test.ts b/packages/platform-web/src/agent-browser-provider.test.ts index 7fee14ca91..29820622f8 100644 --- a/packages/platform-web/src/agent-browser-provider.test.ts +++ b/packages/platform-web/src/agent-browser-provider.test.ts @@ -25,7 +25,7 @@ import { createAgentBrowserWebProvider } from './agent-browser-provider.ts'; import { buildSelectFocusedContentEvalScript } from './agent-browser-select-content.ts'; import type { WebSnapshotResult } from './provider.ts'; import { withCommandExecutorOverride, type ExecResult } from '@agent-device/host-kit/command'; -import { AppError } from '@agent-device/kernel/errors'; +import { AppError, createRequestCanceledError } from '@agent-device/kernel/errors'; import { buildSelectorChainForNode, resolveRecordedTarget } from '@agent-device/selectors'; import { attachRefs } from '@agent-device/kernel/snapshot'; @@ -34,6 +34,7 @@ bindTestCommandHost(); type AgentBrowserCall = { cmd: string; args: readonly string[]; + stdin?: string; }; const mockProviderStartupCleanup = vi.mocked(providerStartupCleanupMock); @@ -100,7 +101,7 @@ test('agent-browser provider maps supported operations to session-scoped JSON co ['mouse', 'down', '--json', '--session', 'web-session'], ['mouse', 'up', '--json', '--session', 'web-session'], ['eval', buildSelectFocusedContentEvalScript(11, 22), '--json', '--session', 'web-session'], - ['keyboard', 'type', 'Ada', '--json', '--session', 'web-session'], + ['batch', '--json', '--session', 'web-session'], // The empty fill (#2063) deletes the in-page selection instead of typing zero // characters over it, which would leave the old value intact. ['mouse', 'move', '11', '22', '--json', '--session', 'web-session'], @@ -108,8 +109,8 @@ test('agent-browser provider maps supported operations to session-scoped JSON co ['mouse', 'up', '--json', '--session', 'web-session'], ['eval', buildSelectFocusedContentEvalScript(11, 22), '--json', '--session', 'web-session'], ['press', 'Backspace', '--json', '--session', 'web-session'], - ['fill', '@e2', 'Grace', '--json', '--session', 'web-session'], - ['keyboard', 'type', 'hello', '--json', '--session', 'web-session'], + ['batch', '--json', '--session', 'web-session'], + ['batch', '--json', '--session', 'web-session'], ['scroll', 'down', '400', '--json', '--session', 'web-session'], ['scroll', 'up', '34', '--json', '--session', 'web-session'], ['scroll', 'up', '33', '--json', '--session', 'web-session'], @@ -118,6 +119,155 @@ test('agent-browser provider maps supported operations to session-scoped JSON co ['close', '--json', '--session', 'web-session'], ], ); + // Typed text reaches the backend only on stdin, never in its process-table-visible argv. + assert.deepEqual( + calls.filter((call) => call.args[0] === 'batch').map((call) => JSON.parse(call.stdin ?? '')), + [[['keyboard', 'type', 'Ada']], [['fill', '@e2', 'Grace']], [['keyboard', 'type', 'hello']]], + ); + }); +}); + +test('agent-browser provider keeps typed text out of argv and error details when a text entry fails', async () => { + await withManagedAgentBrowserProvider({ session: 'web-session' }, async (provider) => { + const secret = 'hunter2-secret'; + const calls: AgentBrowserCall[] = []; + const executor = async ( + cmd: string, + args: readonly string[], + options: { stdin?: string | Buffer }, + ): Promise => { + const cliArgs = recordAgentBrowserCall(calls, cmd, args, options.stdin); + if (cliArgs[0] === 'eval') + return agentBrowserJsonResult({ success: true, data: { result: 'selected' } }); + if (cliArgs[0] !== 'batch') return agentBrowserJsonResult({ success: true, data: {} }); + const [command] = JSON.parse(String(options.stdin)) as string[][]; + // The backend prints the entry list and exits 1 when an entry fails; its error text is not + // carried, because nothing proves it never quotes the text. + return agentBrowserJsonResult( + [{ command, error: `could not type ${secret}`, result: null, success: false }], + 1, + ); + }; + await withCommandExecutorOverride(executor, async () => { + for (const [attempt, command, hint] of [ + [async () => await provider.fillRef?.('@e9', secret), 'fill', /snapshot -i/], + [() => provider.typeText(secret), 'keyboard type', /Focus the field again/], + [() => provider.fill(11, 22, secret), 'keyboard type', /Focus the field again/], + ] as const) { + await assert.rejects(attempt, (error: unknown) => { + assert.ok(error instanceof AppError); + assert.equal(error.code, 'COMMAND_FAILED'); + assert.ok(error.message.startsWith(`agent-browser ${command} failed`), error.message); + assert.equal(error.details?.reason, 'text-entry-failed'); + assert.match(String(error.details?.hint), hint); + assert.equal(error.message.includes(secret), false); + assert.equal(JSON.stringify(error.details).includes(secret), false); + return true; + }); + } + }); + for (const call of calls) assert.equal(call.args.includes(secret), false); + }); +}); + +test('agent-browser provider keeps typed text out of every backend failure shape', async () => { + const secret = 'hunter2-secret'; + const shapes: Record = { + // Not JSON at all: the generic parser would quote stdout and stderr. + 'non-JSON output': { stdout: `typed ${secret}`, stderr: `echo ${secret}`, exitCode: 1 }, + // A failure envelope: its error text and message are the backend's. + 'failure envelope': agentBrowserJsonResult({ success: false, error: `bad ${secret}` }, 1), + // A JSON object with a non-zero exit: the generic path would quote stdout and stderr. + 'object with a non-zero exit': { + stdout: JSON.stringify({ data: { typed: secret } }), + stderr: `stderr ${secret}`, + exitCode: 2, + }, + }; + await withManagedAgentBrowserProvider({ session: 'web-session' }, async (provider) => { + for (const [shape, result] of Object.entries(shapes)) { + await withCommandExecutorOverride( + async () => result, + async () => { + await assert.rejects(provider.typeText(secret), (error: unknown) => { + assert.ok(error instanceof AppError, shape); + assert.equal(error.code, 'COMMAND_FAILED', shape); + assert.equal(error.message, 'agent-browser keyboard type failed', shape); + assert.equal(error.cause, undefined, shape); + assert.equal(JSON.stringify(error.details).includes(secret), false, shape); + return true; + }); + }, + ); + } + }); +}); + +test('agent-browser provider keeps a text entry failure from before the command ran intact', async () => { + await withManagedAgentBrowserProvider({ session: 'web-session' }, async (provider) => { + const missing = new AppError('TOOL_MISSING', 'agent-browser backend is not installed', { + hint: 'Run `agent-device web setup` to install the managed web backend.', + }); + const canceled = createRequestCanceledError({ cmd: 'node' }); + for (const failure of [missing, canceled]) { + await withCommandExecutorOverride( + async () => { + throw failure; + }, + async () => { + await assert.rejects(provider.typeText('hunter2-secret'), (error: unknown) => { + assert.ok(error instanceof AppError); + assert.equal(error.code, failure.code); + assert.equal(error.message, failure.message); + assert.equal(error.details?.hint, failure.details?.hint); + assert.equal(error.details?.reason, failure.details?.reason); + return true; + }); + }, + ); + } + }); +}); + +test('agent-browser provider keeps a text entry timeout but drops the output it captured', async () => { + const secret = 'hunter2-secret'; + await withManagedAgentBrowserProvider({ session: 'web-session' }, async (provider) => { + await withCommandExecutorOverride( + async () => { + throw new AppError('COMMAND_FAILED', 'node timed out after 30000ms', { + stdout: `typed ${secret}`, + stderr: '', + exitCode: 1, + timeoutMs: 30_000, + }); + }, + async () => { + await assert.rejects(provider.typeText(secret), (error: unknown) => { + assert.ok(error instanceof AppError); + assert.equal(error.message, 'node timed out after 30000ms'); + assert.equal(error.details?.timeoutMs, 30_000); + assert.equal(error.cause, undefined); + assert.equal(JSON.stringify(error.details).includes(secret), false); + return true; + }); + }, + ); + }); +}); + +test('agent-browser provider refuses a text entry answer that echoes another command', async () => { + await withManagedAgentBrowserProvider({ session: 'web-session' }, async (provider) => { + const executor = async (): Promise => + agentBrowserJsonResult([ + { command: ['keyboard', 'type', 'other'], error: null, result: {}, success: true }, + ]); + await withCommandExecutorOverride(executor, async () => { + await assert.rejects(provider.typeText('hello'), (error: unknown) => { + assert.ok(error instanceof AppError); + assert.equal(error.details?.reason, 'text-entry-result-unusable'); + return true; + }); + }); }); }); @@ -462,8 +612,18 @@ test('agent-browser provider preserves Node version guidance for missing managed }); function recordingExecutor(calls: AgentBrowserCall[], selectionResult: string = 'selected') { - return async (cmd: string, args: readonly string[]): Promise => { - const cliArgs = recordAgentBrowserCall(calls, cmd, args); + return async ( + cmd: string, + args: readonly string[], + options: { stdin?: string | Buffer } = {}, + ): Promise => { + const cliArgs = recordAgentBrowserCall(calls, cmd, args, options.stdin); + if (cliArgs[0] === 'batch') { + const commands = JSON.parse(String(options.stdin)) as string[][]; + return agentBrowserJsonResult( + commands.map((command) => ({ command, error: null, result: {}, success: true })), + ); + } return agentBrowserJsonResult({ success: true, data: cliArgs[0] === 'eval' ? { result: selectionResult } : {}, @@ -475,9 +635,10 @@ function recordAgentBrowserCall( calls: AgentBrowserCall[], cmd: string, args: readonly string[], + stdin?: string | Buffer, ): string[] { const cliArgs = managedAgentBrowserCliArgs(args); - calls.push({ cmd, args: cliArgs }); + calls.push({ cmd, args: cliArgs, ...(typeof stdin === 'string' ? { stdin } : {}) }); return cliArgs; } @@ -736,7 +897,7 @@ test('agent-browser provider fill selects in the page and never presses a select assert.deepEqual(presses, ['Backspace']); assert.deepEqual( sent.map(([command]) => command), - ['mouse', 'mouse', 'mouse', 'eval', 'keyboard', 'mouse', 'mouse', 'mouse', 'eval', 'press'], + ['mouse', 'mouse', 'mouse', 'eval', 'batch', 'mouse', 'mouse', 'mouse', 'eval', 'press'], ); }); }); diff --git a/packages/platform-web/src/agent-browser-provider.ts b/packages/platform-web/src/agent-browser-provider.ts index 5a75d4e7ce..13de02c166 100644 --- a/packages/platform-web/src/agent-browser-provider.ts +++ b/packages/platform-web/src/agent-browser-provider.ts @@ -62,6 +62,11 @@ type AgentBrowserProviderOptions = { type AgentBrowserRunOptions = { signal?: AbortSignal; stdin?: string; + /** + * Set when stdin carries caller text: names the command in a failure whose backend output + * (stdout, stderr, the envelope's error) is dropped, because that output can quote the text. + */ + textEntryLabel?: string; }; export function createAgentBrowserWebProvider(options: AgentBrowserProviderOptions): WebProvider { @@ -127,16 +132,16 @@ export function createAgentBrowserWebProvider(options: AgentBrowserProviderOptio await sends.send(['press', 'Backspace']); return; } - await sends.send(['keyboard', 'type', text]); + await sendTextEntry(sends.send, ['keyboard', 'type', text]); } catch (error) { throw sends.discloseDispatch(error); } }, async fillRef(ref, text) { - await runJson(['fill', browserRefSelector(ref), text]); + await sendTextEntry(runJson, ['fill', browserRefSelector(ref), text]); }, async typeText(text) { - await runJson(['keyboard', 'type', text]); + await sendTextEntry(runJson, ['keyboard', 'type', text]); }, async scroll(direction, scrollOptions) { await runPacedScroll(runJson, direction, scrollOptions); @@ -173,21 +178,21 @@ async function runPacedScroll( } /** One backend send for a compound operation, counted by {@link createAgentBrowserSendLedger}. */ -type AgentBrowserSend = (args: string[]) => Promise; +type AgentBrowserSend = AgentBrowserRunJson; /** * Counts the backend sends of one compound web operation that returned, and discloses them on * its failure through the shared rule: `no` survives only while nothing was sent, so a counted * send makes the failure `unknown` with `details.dispatchedSteps`. */ -function createAgentBrowserSendLedger(runJson: (args: string[]) => Promise): { +function createAgentBrowserSendLedger(runJson: AgentBrowserRunJson): { send: AgentBrowserSend; discloseDispatch(error: unknown): unknown; } { let dispatchedSteps = 0; return { - send: async (args) => { - const data = await runJson(args); + send: async (args, run) => { + const data = await runJson(args, run); dispatchedSteps += 1; return data; }, @@ -197,6 +202,46 @@ function createAgentBrowserSendLedger(runJson: (args: string[]) => Promise { + const commandName = command[0] ?? 'batch'; + const label = `agent-browser ${command.slice(0, commandName === 'keyboard' ? 2 : 1).join(' ')}`; + const data = await send(['batch'], { + stdin: JSON.stringify([command]), + textEntryLabel: label, + }); + const entry: unknown = Array.isArray(data) && data.length === 1 ? data[0] : undefined; + if (!isBatchEntry(entry) || !sameBatchCommand(entry.command, command)) { + throw new AppError('COMMAND_FAILED', `${label} returned an unusable result`, { + cmd: AGENT_BROWSER, + args: ['batch'], + command: commandName, + reason: 'text-entry-result-unusable', + hint: AGENT_BROWSER_DOCTOR_HINT, + }); + } + if (entry.success === true) return; + // The backend's own error text is not carried: nothing proves it does not quote the text. + const target = commandName === 'fill' ? ` for ${command[1]}` : ''; + throw new AppError('COMMAND_FAILED', `${label} failed${target}`, { + cmd: AGENT_BROWSER, + args: ['batch'], + command: commandName, + reason: 'text-entry-failed', + // The backend ran and refused this entry, so its install is not the suspect. + hint: + commandName === 'fill' + ? 'The page refused this text entry: the field may have changed or gone. Run snapshot -i again and retry fill with the ref it reports.' + : 'The page refused this text entry: the focused field may have changed or gone. Focus the field again (click it) and retry type.', + }); +} + type ScrollStep = { distance?: number; delayAfterMs: number; @@ -485,19 +530,70 @@ async function runAgentBrowserJson( options: AgentBrowserProviderOptions; } & AgentBrowserRunOptions, ): Promise { - const { session, options, signal, stdin } = params; + const { session, options, signal, stdin, textEntryLabel } = params; const cliArgs = [...args, '--json', ...(session ? ['--session', session] : [])]; - return await runAgentBrowserCommand( - cliArgs, - options, - (result) => { - const parsed = parseAgentBrowserJson(result.stdout, result.stderr, cliArgs, result.exitCode); - return unwrapAgentBrowserJson(parsed, result, cliArgs); - }, - { signal, stdin }, + const interpret = (result: { stdout: string; stderr: string; exitCode: number }) => { + const parsed = parseAgentBrowserJson(result.stdout, result.stderr, cliArgs, result.exitCode); + return unwrapAgentBrowserJson(parsed, result, cliArgs); + }; + if (textEntryLabel === undefined) { + return await runAgentBrowserCommand(cliArgs, options, interpret, { signal, stdin }); + } + try { + return await runAgentBrowserCommand( + cliArgs, + options, + (result) => { + try { + return interpret(result); + } catch (error) { + throw withoutBackendAnswer(error, textEntryLabel); + } + }, + { signal, stdin }, + ); + } catch (error) { + throw withoutBackendOutput(error); + } +} + +/** Detail keys that hold what an executed backend command printed. */ +const BACKEND_OUTPUT_DETAIL_KEYS: ReadonlySet = new Set([ + 'stdout', + 'stderr', + 'agentBrowserError', +]); + +function hasBackendOutput(error: AppError): boolean { + return Object.keys(error.details ?? {}).some((key) => BACKEND_OUTPUT_DETAIL_KEYS.has(key)); +} + +function detailsWithoutBackendOutput(error: AppError): Record { + return Object.fromEntries( + Object.entries(error.details ?? {}).filter(([key]) => !BACKEND_OUTPUT_DETAIL_KEYS.has(key)), ); } +/** + * A failure read from the answer of a text-entry command that ran: its message and cause come + * from that answer (the envelope's message, a JSON parser's quote of stdout), so both are replaced + * along with the output details. The code, hint, and dispatch disclosure stay. + */ +function withoutBackendAnswer(error: unknown, label: string): unknown { + if (!(error instanceof AppError)) return error; + return new AppError(error.code, `${label} failed`, detailsWithoutBackendOutput(error)); +} + +/** + * A text-entry run failure keeps its code, message, and guidance; only the output an executed + * command printed (and the cause that repeats it) is dropped. A failure from before the command + * ran (the backend missing, a cancellation) carries no output and passes through unchanged. + */ +function withoutBackendOutput(error: unknown): unknown { + if (!(error instanceof AppError) || !hasBackendOutput(error)) return error; + return new AppError(error.code, error.message, detailsWithoutBackendOutput(error)); +} + async function runAgentBrowserCommand( cliArgs: string[], options: AgentBrowserProviderOptions, diff --git a/packages/provider-testmu/src/testmu.test.ts b/packages/provider-testmu/src/testmu.test.ts index 5825c4ffe8..af2fb63c9a 100644 --- a/packages/provider-testmu/src/testmu.test.ts +++ b/packages/provider-testmu/src/testmu.test.ts @@ -203,7 +203,6 @@ test('TestMu upload reads the lt:// reference and aborts while the request is in }); globalThis.fetch = async (_input, init) => await new Promise((_resolve, reject) => { - assert.equal(init?.signal, controller.signal); init?.signal?.addEventListener('abort', () => reject(init.signal?.reason), { once: true }); started(); }); diff --git a/packages/provider-webdriver/src/aws-device-farm-provider.test.ts b/packages/provider-webdriver/src/aws-device-farm-provider.test.ts index 978705be72..dfefb64486 100644 --- a/packages/provider-webdriver/src/aws-device-farm-provider.test.ts +++ b/packages/provider-webdriver/src/aws-device-farm-provider.test.ts @@ -54,6 +54,28 @@ test('lease preparation reads the connect selectors before any host command runs ); }); +test('artifact lookup runs in the region of the session ARN, not the environment region', async () => { + const commands: string[][] = []; + const { webDriver } = awsDeviceFarmProvider.create({ + ...host({ AWS_REGION: 'eu-west-1' }), + runHostCommand: async (command, args) => { + commands.push([command, ...args]); + return { stdout: '{"artifacts":[]}', stderr: '', exitCode: 0 }; + }, + }); + + await webDriver.listArtifacts!({ + provider: 'aws-device-farm', + providerSessionId: 'arn:aws:devicefarm:us-west-2:123:session:project-a/session-a/00000', + }); + + // One lookup each for the FILE and LOG artifacts. + assert.equal(commands.length, 2); + for (const command of commands) { + assert.equal(command[command.indexOf('--region') + 1], 'us-west-2', command.join(' ')); + } +}); + test('the factory connects through the lazy callbacks', async () => { const { connection } = awsDeviceFarmProvider.create(host({ AWS_REGION: 'eu-west-1' })); const { profile } = await connection.resolve({ diff --git a/packages/provider-webdriver/src/aws-device-farm-provider.ts b/packages/provider-webdriver/src/aws-device-farm-provider.ts index bf0956e869..6938e38afa 100644 --- a/packages/provider-webdriver/src/aws-device-farm-provider.ts +++ b/packages/provider-webdriver/src/aws-device-farm-provider.ts @@ -44,9 +44,11 @@ function createAwsDeviceFarmProvider( await listAwsDeviceFarmCloudArtifacts( provider, providerSessionId, + // The session ARN names the region the session ran in, which `--aws-region` may have chosen + // over the environment's region. client( - readAwsDeviceFarmSelectorFromEnv(env, 'awsRegion') ?? - readAwsDeviceFarmRegionFromArn(providerSessionId ?? ''), + readAwsDeviceFarmRegionFromArn(providerSessionId ?? '') ?? + readAwsDeviceFarmSelectorFromEnv(env, 'awsRegion'), ), ), prepareSession: async ({ req, lease, base }) => { diff --git a/packages/provider-webdriver/src/browserstack.test.ts b/packages/provider-webdriver/src/browserstack.test.ts index 663713063a..2f77e2c4a6 100644 --- a/packages/provider-webdriver/src/browserstack.test.ts +++ b/packages/provider-webdriver/src/browserstack.test.ts @@ -26,7 +26,6 @@ test('BrowserStack upload aborts while the provider request is in flight', async await fs.writeFile(appPath, 'placeholder'); globalThis.fetch = async (_input, init) => await new Promise((_resolve, reject) => { - assert.equal(init?.signal, controller.signal); if (init?.signal?.aborted) { reject(init.signal.reason); return; diff --git a/packages/provider-webdriver/src/capabilities.ts b/packages/provider-webdriver/src/capabilities.ts index 9389ba3e8b..567d52e49b 100644 --- a/packages/provider-webdriver/src/capabilities.ts +++ b/packages/provider-webdriver/src/capabilities.ts @@ -108,15 +108,15 @@ const BASE_WEBDRIVER_CAPABILITIES: CloudWebDriverCapabilityMap = { back: supported, home: { support: 'partial', - note: 'Uses provider/Appium mobile pressButton support where available.', + note: 'Presses the XCUITest `mobile: pressButton` home button on iOS and KEYCODE_HOME through `mobile: pressKey` on Android.', }, orientation: { support: 'partial', note: 'Uses the WebDriver rotation/orientation endpoints; four-way rotation collapses to portrait/landscape on drivers that only accept the two-way endpoint. Rotates the current display, so an activity that does not pin its orientation may need rotating again once it is foreground.', }, appSwitcher: { - support: 'partial', - note: 'Uses provider/Appium mobile pressButton support where available.', + support: 'unsupported', + note: 'XCUITest `mobile: pressButton` has no app-switcher button.', }, volumeUp: { support: 'partial', @@ -169,6 +169,10 @@ export function createCloudWebDriverCapabilities(options: { options.platform === 'android' ? { ...BASE_WEBDRIVER_CAPABILITIES, + appSwitcher: { + support: 'partial', + note: 'Presses KEYCODE_APP_SWITCH through `mobile: pressKey`.', + }, volumeUp: androidHardwareButton, volumeDown: androidHardwareButton, power: androidHardwareButton, diff --git a/packages/provider-webdriver/src/runtime-session.test.ts b/packages/provider-webdriver/src/runtime-session.test.ts index 4429903b7e..0da1fd2b88 100644 --- a/packages/provider-webdriver/src/runtime-session.test.ts +++ b/packages/provider-webdriver/src/runtime-session.test.ts @@ -73,6 +73,39 @@ test('a create-timeout surfaces provider evidence for the maybe-leaked session', } }); +/** + * `DELETE /session/{id}` is idempotent: one transient hub failure is retried rather than left as a + * billed session, and a hub that no longer knows the session (`invalid session id`) has ended it. + */ +test.each([ + ['a transient delete failure is retried', 502, 'Bad Gateway'], + [ + 'a delete answered invalid session id', + 404, + JSON.stringify({ value: { error: 'invalid session id', message: 'session not found' } }), + ], +] as const)('%s confirms the release', async (_name, status, body) => { + const deletes: number[] = []; + globalThis.fetch = async (input, init) => { + const method = init?.method ?? new Request(input as RequestInfo).method; + if (method !== 'DELETE') return jsonResponse({ sessionId: 'session-1', capabilities: {} }); + deletes.push(deletes.length); + return deletes.length === 1 ? new Response(body, { status }) : jsonResponse({ value: null }); + }; + const runtime = makeRuntime({ requestPolicy: { retryAttempts: 1, retryDelayMs: 1 } }); + const lease = makeLease(); + + try { + await runtime.leaseLifecycle.allocate!(lease); + assert.deepEqual(await runtime.leaseLifecycle.release!(lease), { + provider: 'webdriver-test', + providerSessionId: 'session-1', + }); + } finally { + await runtime.shutdown(); + } +}); + test('cloud artifact lookup does not accept a provider session id without its lease', async () => { let listCalls = 0; const runtime = makeRuntime({ diff --git a/packages/provider-webdriver/src/webdriver-client.test.ts b/packages/provider-webdriver/src/webdriver-client.test.ts index c10fed4d10..e71da72c35 100644 --- a/packages/provider-webdriver/src/webdriver-client.test.ts +++ b/packages/provider-webdriver/src/webdriver-client.test.ts @@ -129,6 +129,32 @@ test('source aborts an in-flight provider request when its binding is cancelled' assert.equal(requestSignal?.aborted, true); }); +// App activation falls back to `mobile: activateApp` only on the driver's own refusal of the route. +test('app activation falls back on a W3C unknown command but not on a gateway 404 page', async () => { + for (const [first, fallsBack] of [ + [ + () => + new Response(JSON.stringify({ value: { error: 'unknown command', message: 'x' } }), { + status: 404, + headers: { 'Content-Type': 'application/json' }, + }), + true, + ], + [() => new Response('Not Found', { status: 404 }), false], + ] as const) { + const routes: string[] = []; + const client = await connectedClient(async (input, init) => { + const url = new URL(input instanceof Request ? input.url : String(input)); + routes.push(url.pathname.endsWith('/execute/sync') ? 'sibling' : 'route'); + return routes.length === 1 ? first() : webDriverResponse(200, { value: null })(input, init); + }); + const activation = client.activateApp('com.example.app'); + if (fallsBack) await activation; + else await assert.rejects(activation); + assert.deepEqual(routes, fallsBack ? ['route', 'sibling'] : ['route']); + } +}); + // #1774: `POST /session` is the one non-idempotent request, and a retry after a // failed create is a second billed device session. A 5xx that the transport // would retry on any other route must reach the caller unretried here. diff --git a/packages/provider-webdriver/src/webdriver-client.ts b/packages/provider-webdriver/src/webdriver-client.ts index 095b6fc858..c0f98d849b 100644 --- a/packages/provider-webdriver/src/webdriver-client.ts +++ b/packages/provider-webdriver/src/webdriver-client.ts @@ -2,6 +2,7 @@ import fs from 'node:fs/promises'; import { AppError } from '@agent-device/kernel/errors'; import { emitWebDriverDiagnostic, + isWebDriverInvalidSession, isWebDriverRouteUnsupported, WebDriverTransport, type WebDriverAuth, @@ -101,9 +102,19 @@ export class WebDriverClient { return session; } + /** + * `DELETE /session/{id}` is idempotent, so it gets the retry budget: one transient failure must + * not leave a billed session. A driver that answers `invalid session id` no longer has the + * session, which is the outcome the delete asked for, including when an earlier attempt landed + * before its answer was lost. + */ async deleteSession(): Promise { const sessionId = this.requireSessionId(); - await this.requestValue('DELETE', `/session/${sessionId}`); + try { + await this.requestValue('DELETE', `/session/${sessionId}`, undefined, { idempotent: true }); + } catch (error) { + if (!isWebDriverInvalidSession(error)) throw error; + } this.sessionId = undefined; } diff --git a/packages/provider-webdriver/src/webdriver-interactor-app-open.test.ts b/packages/provider-webdriver/src/webdriver-interactor-app-open.test.ts new file mode 100644 index 0000000000..bb0489d509 --- /dev/null +++ b/packages/provider-webdriver/src/webdriver-interactor-app-open.test.ts @@ -0,0 +1,50 @@ +import assert from 'node:assert/strict'; +import { test } from 'vitest'; +import { createCloudWebDriverCapabilities } from './capabilities.ts'; +import type { WebDriverClient } from './webdriver-client.ts'; +import { createWebDriverInteractor } from './webdriver-interactor.ts'; + +/** A client that records every method called on it, with its arguments. */ +function lifecycleRecordingClient(calls: string[]): WebDriverClient { + return new Proxy({} as WebDriverClient, { + get: + (_target, method) => + async (...args: unknown[]) => { + calls.push(`${String(method)} ${JSON.stringify(args)}`); + }, + }); +} + +// Both Appium drivers require an app id for `mobile: activateApp`; a leased session is already the +// foreground device, so opening the device sends nothing. +test('openDevice sends no driver request on either backend', async () => { + for (const platform of ['android', 'ios'] as const) { + const calls: string[] = []; + const interactor = createWebDriverInteractor({ + client: lifecycleRecordingClient(calls), + backend: platform === 'ios' ? 'xctest' : 'android', + capabilities: createCloudWebDriverCapabilities({ provider: 'test', platform }), + }); + await interactor.openDevice?.(); + assert.deepEqual(calls, [], platform); + } +}); + +// XCUITest's `mobile: deepLink` reads `bundleId`; UiAutomator2's reads `package`. +test('a deep link names the target app in the field each driver reads', async () => { + for (const [platform, target] of [ + ['android', { package: 'com.example.app' }], + ['ios', { bundleId: 'com.example.app' }], + ] as const) { + const calls: string[] = []; + const interactor = createWebDriverInteractor({ + client: lifecycleRecordingClient(calls), + backend: platform === 'ios' ? 'xctest' : 'android', + capabilities: createCloudWebDriverCapabilities({ provider: 'test', platform }), + }); + await interactor.open('com.example.app', { url: 'example://home' }); + assert.deepEqual(calls, [ + `executeScript ${JSON.stringify(['mobile: deepLink', [{ url: 'example://home', ...target }]])}`, + ]); + } +}); diff --git a/packages/provider-webdriver/src/webdriver-interactor-hardware-button.test.ts b/packages/provider-webdriver/src/webdriver-interactor-hardware-button.test.ts index 34ea274c5b..d1cbaec8cf 100644 --- a/packages/provider-webdriver/src/webdriver-interactor-hardware-button.test.ts +++ b/packages/provider-webdriver/src/webdriver-interactor-hardware-button.test.ts @@ -64,6 +64,41 @@ test('iOS volume presses ride mobile pressButton and power refuses before the dr }); }); +// UiAutomator2 registers no `mobile: pressButton`, and XCUITest's pressButton names are +// home, volumeup, and volumedown only. +test('Android home and app switcher press their keycodes through mobile pressKey', async () => { + const transcript: string[] = []; + const android = createWebDriverInteractor({ + client: recordingClient(transcript), + backend: 'android', + capabilities: createCloudWebDriverCapabilities({ provider: 'test', platform: 'android' }), + }); + await android.home!(); + await android.appSwitcher!(); + assert.deepEqual(transcript, [ + 'mobile: pressKey [{"keycode":3}]', + 'mobile: pressKey [{"keycode":187}]', + ]); +}); + +test('iOS home rides mobile pressButton and the app switcher refuses before the driver', async () => { + const transcript: string[] = []; + const ios = createWebDriverInteractor({ + client: recordingClient(transcript), + backend: 'xctest', + capabilities: createCloudWebDriverCapabilities({ provider: 'test', platform: 'ios' }), + }); + await ios.home!(); + await assert.rejects(ios.appSwitcher!(), (error: unknown) => { + return ( + error instanceof AppError && + error.code === 'UNSUPPORTED_OPERATION' && + error.details?.operation === 'appSwitcher' + ); + }); + assert.deepEqual(transcript, ['mobile: pressButton [{"name":"home"}]']); +}); + test('Android power presses KEYCODE_POWER through mobile pressKey', async () => { const transcript: string[] = []; const android = createWebDriverInteractor({ diff --git a/packages/provider-webdriver/src/webdriver-interactor-mutation-resend.test.ts b/packages/provider-webdriver/src/webdriver-interactor-mutation-resend.test.ts index 1be3905290..8e5bc063bb 100644 --- a/packages/provider-webdriver/src/webdriver-interactor-mutation-resend.test.ts +++ b/packages/provider-webdriver/src/webdriver-interactor-mutation-resend.test.ts @@ -111,6 +111,11 @@ type MutatingRouteRow = { /** A route the grid answers as unsupported so `act` reaches the hung sibling route. */ unsupportedRoute?: string; createSession?: false; + /** + * The route is idempotent even though it mutates, so a timeout is resent once: ending a session + * twice ends the same session. + */ + idempotent?: true; }; const MUTATING_ROUTES: Record = { @@ -118,7 +123,7 @@ const MUTATING_ROUTES: Record = { act: ({ client }) => client.createSession({ platformName: 'Android' }), createSession: false, }, - 'DELETE /session/:id': { act: ({ client }) => client.deleteSession() }, + 'DELETE /session/:id': { act: ({ client }) => client.deleteSession(), idempotent: true }, 'POST /session/:id/appium/device/install_app': { act: ({ client }) => client.installApp('/tmp/app.apk'), }, @@ -144,15 +149,24 @@ const MUTATING_ROUTES: Record = { 'mobile: deepLink': { act: ({ interactor }) => interactor.open('com.example.app', { url: 'example://home' }), }, - 'mobile: activateApp': { act: ({ interactor }) => interactor.openDevice() }, + 'mobile: activateApp': { + act: ({ client }) => client.activateApp('com.example.app'), + unsupportedRoute: 'POST /session/:id/appium/device/activate_app', + }, 'mobile: terminateApp': { act: ({ client }) => client.terminateApp('com.example.app'), unsupportedRoute: 'POST /session/:id/appium/device/terminate_app', }, 'mobile: pressButton': { - act: async ({ interactor }) => { - assert.ok(interactor.home); - await interactor.home(); + // Only XCUITest has pressButton; the Android legs press keycodes. + act: async ({ client }) => { + const ios = createWebDriverInteractor({ + client, + backend: 'xctest', + capabilities: createCloudWebDriverCapabilities({ provider: 'test', platform: 'ios' }), + }); + assert.ok(ios.home); + await ios.home(); }, }, 'mobile: setClipboard': { @@ -210,9 +224,10 @@ test('the mutating-route table covers every mutating route the provider sends', }); // A resend after a timeout cannot tell whether the first attempt's side effect already landed, so -// every mutating route gets one send and discloses that its outcome is unresolved. +// every mutating route that is not idempotent gets one send and discloses that its outcome is +// unresolved. for (const [route, row] of Object.entries(MUTATING_ROUTES)) { - test(`a timed-out ${route} is sent once`, async () => { + test(`a timed-out ${route} is sent ${row.idempotent ? 'twice' : 'once'}`, async () => { const connected = await connectedWebDriverInteractor({ hangRoute: route, unsupportedRoute: row.unsupportedRoute, @@ -225,7 +240,7 @@ for (const [route, row] of Object.entries(MUTATING_ROUTES)) { return true; }); - assert.equal(connected.sendsTo(route), 1); + assert.equal(connected.sendsTo(route), row.idempotent ? 2 : 1); }); } diff --git a/packages/provider-webdriver/src/webdriver-interactor.ts b/packages/provider-webdriver/src/webdriver-interactor.ts index 746b11c9da..966234c37e 100644 --- a/packages/provider-webdriver/src/webdriver-interactor.ts +++ b/packages/provider-webdriver/src/webdriver-interactor.ts @@ -95,6 +95,9 @@ export type WebDriverInteractorOptions = { targetId?: string; }; +/** The Android keyevents for the system buttons, as the local Android owner sends them. */ +const ANDROID_SYSTEM_BUTTON_KEYCODES = { home: 3, appSwitcher: 187 } as const; + export function createWebDriverInteractor(options: WebDriverInteractorOptions): Interactor { return new WebDriverInteractor( options.client, @@ -133,7 +136,9 @@ class WebDriverInteractor implements Interactor { }, ): Promise { if (options?.url) { - await this.client.executeScript('mobile: deepLink', [{ url: options.url, package: app }]); + // XCUITest's deep-link extension names the target app `bundleId`; UiAutomator2's `package`. + const target = this.backend === 'xctest' ? { bundleId: app } : { package: app }; + await this.client.executeScript('mobile: deepLink', [{ url: options.url, ...target }]); return; } const appId = options?.appBundleId ?? app; @@ -141,9 +146,11 @@ class WebDriverInteractor implements Interactor { await this.client.activateApp(appId); } - async openDevice(): Promise { - await this.client.executeScript('mobile: activateApp', [{}]); - } + /** + * A leased cloud session is already the foreground device, so there is nothing to raise. Both + * Appium drivers require an app id for `mobile: activateApp`. + */ + async openDevice(): Promise {} async close(app: string): Promise { if (!app) return; @@ -373,8 +380,19 @@ class WebDriverInteractor implements Interactor { await this.client.back(); } + /** + * UiAutomator2 registers no `mobile: pressButton`, so Android presses KEYCODE_HOME through + * `mobile: pressKey`, the keyevent the local Android owner sends. XCUITest presses its `home` + * button. + */ async home(): Promise { this.requireSupport('home'); + if (this.backend === 'android') { + await this.client.executeScript('mobile: pressKey', [ + { keycode: ANDROID_SYSTEM_BUTTON_KEYCODES.home }, + ]); + return; + } await this.client.executeScript('mobile: pressButton', [{ name: 'home' }]); } @@ -383,9 +401,15 @@ class WebDriverInteractor implements Interactor { await setWebDriverOrientation(this.client, this.backend, orientation); } + /** + * Android presses KEYCODE_APP_SWITCH through `mobile: pressKey`. XCUITest `mobile: pressButton` + * has no app-switcher button, so the iOS capability map refuses before this leg. + */ async appSwitcher(): Promise { this.requireSupport('appSwitcher'); - await this.client.executeScript('mobile: pressButton', [{ name: 'appSwitch' }]); + await this.client.executeScript('mobile: pressKey', [ + { keycode: ANDROID_SYSTEM_BUTTON_KEYCODES.appSwitcher }, + ]); } /** diff --git a/packages/provider-webdriver/src/webdriver-transport.test.ts b/packages/provider-webdriver/src/webdriver-transport.test.ts index 7cfe696c18..61bb44bf4c 100644 --- a/packages/provider-webdriver/src/webdriver-transport.test.ts +++ b/packages/provider-webdriver/src/webdriver-transport.test.ts @@ -305,6 +305,73 @@ test('a 5xx response to a POST discloses an unresolved outcome and is not resent assert.equal(calls, 1); }); +test('a 5xx with a non-JSON body keeps its status, dispatch disclosure, and idempotent retry', async () => { + const transport = new WebDriverTransport({ + clientVersion: '0.0.0-test', + endpoint: 'http://cloud-webdriver.test/wd/hub/', + requestPolicy: { timeoutMs: 30_000, retryAttempts: 1, retryDelayMs: 1 }, + }); + let calls = 0; + globalThis.fetch = async () => { + calls += 1; + return new Response('502 Bad Gateway', { + status: 502, + headers: { 'Content-Type': 'text/html' }, + }); + }; + + await assert.rejects(transport.requestValue('GET', '/session/wd-1/source'), (error: unknown) => { + assert.ok(error instanceof AppError); + assert.equal(error.details?.status, 502); + assert.equal(error.details?.dispatched, 'unknown'); + assert.equal(error.details?.response, '502 Bad Gateway'); + return true; + }); + assert.equal(calls, 2); +}); + +// A gateway's HTML 404/405/501 page carries no W3C error code: it is not the driver refusing the +// route, so the caller must not fall back to a sibling route that could repeat the action. +for (const status of [404, 405, 501]) { + test(`a non-JSON HTTP ${status} page is not an unsupported route`, async () => { + const transport = new WebDriverTransport({ + clientVersion: '0.0.0-test', + endpoint: 'http://cloud-webdriver.test/wd/hub/', + requestPolicy: { timeoutMs: 30_000, retryAttempts: 0 }, + }); + globalThis.fetch = async () => + new Response('Not Found', { status, headers: { 'Content-Type': 'text/html' } }); + + await assert.rejects( + transport.requestValue('POST', '/session/wd-1/appium/device/activate_app', {}), + (error: unknown) => { + assert.ok(error instanceof AppError); + assert.equal(isWebDriverRouteUnsupported(error), false); + assert.equal(error.details?.status, status); + assert.equal(error.details?.dispatched, 'unknown'); + return true; + }, + ); + }); +} + +test('a 2xx with a non-JSON body names its status', async () => { + const transport = new WebDriverTransport({ + clientVersion: '0.0.0-test', + endpoint: 'http://cloud-webdriver.test/wd/hub/', + requestPolicy: { timeoutMs: 30_000, retryAttempts: 0 }, + }); + globalThis.fetch = async () => new Response('ok', { status: 200 }); + + await assert.rejects(transport.requestValue('GET', '/status'), (error: unknown) => { + assert.ok(error instanceof AppError); + assert.equal(error.message, 'WebDriver response was not valid JSON.'); + assert.equal(error.details?.status, 200); + assert.equal(error.details?.dispatched, 'unknown'); + return true; + }); +}); + const ROUTE_ANSWERS: readonly { status: number; body: unknown; unsupported: boolean }[] = [ { status: 404, body: { value: { error: 'unknown command', message: 'x' } }, unsupported: true }, { status: 405, body: { value: { error: 'unknown method', message: 'x' } }, unsupported: true }, diff --git a/packages/provider-webdriver/src/webdriver-transport.ts b/packages/provider-webdriver/src/webdriver-transport.ts index d452f30347..404bc9df14 100644 --- a/packages/provider-webdriver/src/webdriver-transport.ts +++ b/packages/provider-webdriver/src/webdriver-transport.ts @@ -210,8 +210,11 @@ export class WebDriverTransport { timeoutMs, requestSignal, ); - const payload = text ? parseJsonResponse(text) : {}; - if (ok) return { status, value: readWebDriverValue(payload) }; + if (ok) + return { status, value: readWebDriverValue(text ? parseJsonResponse(text, status) : {}) }; + const parsed = text ? parseJsonBody(text) : { json: {} }; + if (parsed === undefined) throw nonJsonAnswerError(status, text); + const payload = parsed.json; const error = webdriverError(status, payload); if (isWebDriverRouteUnsupported(error)) { emitWebDriverDiagnostic(WEBDRIVER_ROUTE_UNSUPPORTED_REASON, { @@ -322,14 +325,38 @@ function readWebDriverValue(payload: unknown): unknown { return payload; } -function parseJsonResponse(text: string): unknown { +/** The longest raw response body an error carries as evidence. */ +const RESPONSE_BODY_EVIDENCE_LIMIT = 500; + +function parseJsonResponse(text: string, status: number): unknown { try { return JSON.parse(text) as unknown; } catch (error) { - throw new AppError('COMMAND_FAILED', 'WebDriver response was not valid JSON.', { text }, error); + throw new AppError( + 'COMMAND_FAILED', + 'WebDriver response was not valid JSON.', + // A 2xx means the driver ran the request; only its answer is unreadable. + { status, text: truncateBody(text), ...dispatchDisclosure('unknown') }, + error, + ); + } +} + +/** The parsed body, boxed so a JSON `null` stays distinct from a body that is not JSON. */ +function parseJsonBody(text: string): { json: unknown } | undefined { + try { + return { json: JSON.parse(text) as unknown }; + } catch { + return undefined; } } +function truncateBody(text: string): string { + return text.length > RESPONSE_BODY_EVIDENCE_LIMIT + ? `${text.slice(0, RESPONSE_BODY_EVIDENCE_LIMIT)}…` + : text; +} + function webdriverError(status: number, payload: unknown): AppError { const value = payload && typeof payload === 'object' && 'value' in payload @@ -357,9 +384,35 @@ function webdriverError(status: number, payload: unknown): AppError { }); } +/** + * A non-JSON error answer comes from something in front of the driver (a gateway's `502 ` + * or a proxy's `404` page), not from the driver. Its status still decides retry, but it is never + * the driver's refusal of a route, so no sibling route is tried, and it cannot say whether the + * driver received the request. The raw body is truncated evidence only. + */ +function nonJsonAnswerError(status: number, text: string): AppError { + return new AppError('COMMAND_FAILED', `WebDriver request failed with HTTP ${status}.`, { + status, + response: truncateBody(text), + ...dispatchDisclosure('unknown'), + }); +} + /** Machine-readable `details.reason` of a driver answer that it does not implement the route. */ const WEBDRIVER_ROUTE_UNSUPPORTED_REASON = 'webdriver_route_unsupported'; +/** + * The driver answered with the W3C `invalid session id` error: the session it was asked about does + * not exist (never did, was deleted, or timed out on the driver). + */ +export function isWebDriverInvalidSession(error: unknown): error is AppError { + return ( + error instanceof AppError && + error.details?.status === 404 && + w3cErrorCode(error.details.response)?.toLowerCase() === 'invalid session id' + ); +} + /** * The details of a refusal the driver answered before running anything: it does not implement * the route. A command that tried every route it has and was refused by each carries the same. diff --git a/packages/provider-webdriver/src/webdriver-utils.test.ts b/packages/provider-webdriver/src/webdriver-utils.test.ts index 9073922b1c..d2b62f826f 100644 --- a/packages/provider-webdriver/src/webdriver-utils.test.ts +++ b/packages/provider-webdriver/src/webdriver-utils.test.ts @@ -80,6 +80,73 @@ test('the hub upload helper fails typed with the status on an error page or a mi } }); +test('the hub upload helper types a rejected credential and keeps a transport failure as the cause', async () => { + for (const status of [401, 403]) { + globalThis.fetch = async () => new Response('{"message":"bad key"}', { status }); + await assert.rejects(postHubAppUpload(new FormData(), hub), (error: unknown) => { + assert.ok(error instanceof AppError); + assert.equal(error.code, 'UNAUTHORIZED'); + assert.equal(error.details?.status, status); + return true; + }); + } + + const networkFailure = new TypeError('fetch failed'); + globalThis.fetch = async () => { + throw networkFailure; + }; + await assert.rejects(postHubAppUpload(new FormData(), hub), (error: unknown) => { + assert.ok(error instanceof AppError); + assert.equal(error.code, 'COMMAND_FAILED'); + assert.equal(error.details?.reason, 'hub_app_upload_transport_failed'); + assert.equal(error.cause, networkFailure); + return true; + }); +}); + +test('the hub upload helper fails typed when its deadline ends a stalled upload', async () => { + // Only the deadline the upload arms can end this fetch; without it the spy is never called. + const deadline = new AbortController(); + const timeoutSpy = vi.spyOn(AbortSignal, 'timeout').mockImplementation(() => deadline.signal); + globalThis.fetch = async (_input, init) => + await new Promise((_resolve, reject) => { + init?.signal?.addEventListener('abort', () => reject(init.signal?.reason as Error)); + }); + try { + const pending = postHubAppUpload(new FormData(), hub); + assert.deepEqual(timeoutSpy.mock.calls, [[15 * 60_000]]); + const timeout = new DOMException('The operation was aborted due to timeout', 'TimeoutError'); + deadline.abort(timeout); + await assert.rejects(pending, (error: unknown) => { + assert.ok(error instanceof AppError); + assert.equal(error.code, 'COMMAND_FAILED'); + assert.equal(error.details?.reason, 'hub_app_upload_timeout'); + assert.equal(error.cause, timeout); + return true; + }); + } finally { + timeoutSpy.mockRestore(); + } +}); + +test('the hub upload helper bounds the request and keeps a caller cancellation as is', async () => { + let requestSignal: AbortSignal | undefined; + globalThis.fetch = async (_input, init) => { + requestSignal = init?.signal ?? undefined; + return await new Promise((_resolve, reject) => { + init?.signal?.addEventListener('abort', () => reject(init.signal?.reason as Error)); + }); + }; + const controller = new AbortController(); + const pending = postHubAppUpload(new FormData(), hub, controller.signal); + await vi.waitFor(() => assert.ok(requestSignal)); + // The request carries a deadline even when the caller gave a signal of its own. + assert.notEqual(requestSignal, controller.signal); + const canceled = new Error('client disconnected'); + controller.abort(canceled); + await assert.rejects(pending, (error: unknown) => error === canceled); +}); + test('the hub install adapter uploads the build and launches the hinted app', async () => { const upload = vi.fn(async () => 'hub://APP2'); const signal = new AbortController().signal; diff --git a/packages/provider-webdriver/src/webdriver-utils.ts b/packages/provider-webdriver/src/webdriver-utils.ts index d10669977c..631e85bd1a 100644 --- a/packages/provider-webdriver/src/webdriver-utils.ts +++ b/packages/provider-webdriver/src/webdriver-utils.ts @@ -1,5 +1,5 @@ import fs from 'node:fs'; -import { readFile, stat } from 'node:fs/promises'; +import { stat } from 'node:fs/promises'; import path from 'node:path'; import type { CliFlags } from '@agent-device/contracts/command'; import type { @@ -87,13 +87,23 @@ export async function appFileUploadForm( ); } const form = new FormData(); - form.set(fileField, new Blob([await readFile(appPath)]), path.basename(appPath)); + // A file-backed blob streams the build into the request instead of holding it in memory. + form.set(fileField, await fs.openAsBlob(appPath), path.basename(appPath)); return form; } /** - * POSTs an app upload to a hosted hub and returns the hub's app reference. A non-2xx answer, a - * body that is not JSON, or one without a reference is `COMMAND_FAILED` with the HTTP status. + * The total deadline for one app upload, from request start to answer. It is not an idle timeout: + * a healthy upload that is still sending after 15 minutes is aborted too. Builds of a few hundred + * MB on a slow uplink take minutes, so it is set well above that. + */ +const HUB_APP_UPLOAD_TIMEOUT_MS = 15 * 60_000; + +/** + * POSTs an app upload to a hosted hub and returns the hub's app reference. A 401/403 is + * `UNAUTHORIZED`; any other non-2xx answer, a body that is not JSON, or one without a reference is + * `COMMAND_FAILED` with the HTTP status. A transport failure or the upload deadline is + * `COMMAND_FAILED` with its cause; the caller's own cancellation keeps its reason. */ export async function postHubAppUpload( form: FormData, @@ -106,16 +116,40 @@ export async function postHubAppUpload( }, signal?: AbortSignal, ): Promise { - const response = await fetch(options.endpoint, { - method: 'POST', - headers: { - ...agentDeviceRequestHeaders(options.clientVersion), - Authorization: basicAuthHeader(options.auth), - }, - body: form, - signal, - }); - const json = await readProviderJsonBody(response); + const timeoutSignal = AbortSignal.timeout(HUB_APP_UPLOAD_TIMEOUT_MS); + let response: Response; + let json: unknown; + try { + response = await fetch(options.endpoint, { + method: 'POST', + headers: { + ...agentDeviceRequestHeaders(options.clientVersion), + Authorization: basicAuthHeader(options.auth), + }, + body: form, + signal: signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal, + }); + json = await readProviderJsonBody(response); + } catch (error) { + if (signal?.aborted) throw error; + const timedOut = timeoutSignal.aborted; + throw new AppError( + 'COMMAND_FAILED', + `${options.service} app upload failed.`, + { + reason: timedOut ? 'hub_app_upload_timeout' : 'hub_app_upload_transport_failed', + ...(timedOut ? { timeoutMs: HUB_APP_UPLOAD_TIMEOUT_MS } : {}), + hint: `Check network access to the ${options.service} upload API, then retry.`, + }, + error, + ); + } + if (response.status === 401 || response.status === 403) { + throw new AppError('UNAUTHORIZED', `${options.service} rejected the app upload credentials.`, { + status: response.status, + hint: `Check the ${options.service} username and access key.`, + }); + } const appReference = options.readAppReference(json)?.trim(); if (!response.ok || !appReference) { throw new AppError('COMMAND_FAILED', `${options.service} app upload failed.`, { diff --git a/packages/tv-cdp/src/cdp.test.ts b/packages/tv-cdp/src/cdp.test.ts new file mode 100644 index 0000000000..dbb52b6756 --- /dev/null +++ b/packages/tv-cdp/src/cdp.test.ts @@ -0,0 +1,96 @@ +import assert from 'node:assert/strict'; +import { createHash } from 'node:crypto'; +import { once } from 'node:events'; +import { createServer, type IncomingMessage } from 'node:http'; +import type { Duplex } from 'node:stream'; +import { afterEach, test } from 'vitest'; + +import { connectCdp } from './cdp.ts'; + +const cleanups: (() => Promise | void)[] = []; +afterEach(async () => { + for (const cleanup of cleanups.splice(0).reverse()) await cleanup(); +}); + +function textFrame(text: string): Buffer { + const payload = Buffer.from(text); + assert.ok(payload.length < 126, 'the fake page sends short frames only'); + return Buffer.concat([Buffer.from([0x81, payload.length]), payload]); +} + +function readMaskedText(buffer: Buffer): { text: string; rest: Buffer } | null { + if (buffer.length < 2) return null; + const length = buffer[1]! & 0x7f; + assert.ok(length < 126, 'the client sends short frames only'); + if (buffer.length < 6 + length) return null; + const mask = buffer.subarray(2, 6); + const payload = Buffer.from(buffer.subarray(6, 6 + length)); + for (let i = 0; i < payload.length; i += 1) payload[i] = payload[i]! ^ mask[i % 4]!; + return { text: payload.toString('utf8'), rest: buffer.subarray(6 + length) }; +} + +/** + * A page that, before it answers each request, sends `beforeAnswer` frames: frames an old TV + * Chromium or a proxy in between may produce, which the session must survive. + */ +async function pageSending(beforeAnswer: readonly string[]): Promise { + const sockets = new Set(); + const server = createServer(); + server.on('upgrade', (request: IncomingMessage, socket: Duplex) => { + sockets.add(socket); + const accept = createHash('sha1') + .update(`${request.headers['sec-websocket-key']}258EAFA5-E914-47DA-95CA-C5AB0DC85B11`) + .digest('base64'); + socket.write( + `HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: ${accept}\r\n\r\n`, + ); + let pending: Buffer = Buffer.alloc(0); + socket.on('data', (chunk: Buffer) => { + pending = Buffer.concat([pending, chunk]); + for (let read = readMaskedText(pending); read; read = readMaskedText(pending)) { + pending = read.rest; + const { id } = JSON.parse(read.text) as { id: number }; + for (const text of beforeAnswer) socket.write(textFrame(text)); + socket.write(textFrame(JSON.stringify({ id, result: { ok: true } }))); + } + }); + }); + server.listen(0, '127.0.0.1'); + await once(server, 'listening'); + const address = server.address(); + assert.ok(address && typeof address !== 'string'); + cleanups.push(async () => { + for (const socket of sockets) socket.destroy(); + server.close(); + await once(server, 'close'); + }); + return `ws://127.0.0.1:${address.port}/devtools/page/1`; +} + +// A throw inside the WebSocket message handler is an uncaught exception, which ends the +// daemon rather than one request. +test('an unreadable frame or a failing event listener leaves the pending request answered', async () => { + const url = await pageSending([ + 'not json', + 'null', + // A method that is not a name must not answer the pending request it shares an id with. + '{"id":1,"method":7,"result":{"ok":false}}', + '{"method":"Log.entryAdded","params":7}', + ]); + const session = await connectCdp({ + title: 'page', + url: 'http://tv/page/', + webSocketDebuggerUrl: url, + }); + cleanups.push(() => session.close()); + const events: string[] = []; + session.on(() => { + // `String()` throws for a value without a primitive conversion. + throw Object.create(null); + }); + session.on((method, params) => events.push(`${method} ${JSON.stringify(params)}`)); + + assert.deepEqual(await session.send('Runtime.enable'), { ok: true }); + // The listener after a failing one still hears the event, with the malformed params dropped. + assert.deepEqual(events, ['Log.entryAdded {}']); +}); diff --git a/packages/tv-cdp/src/cdp.ts b/packages/tv-cdp/src/cdp.ts index 423dbabd2c..01fb2b63ca 100644 --- a/packages/tv-cdp/src/cdp.ts +++ b/packages/tv-cdp/src/cdp.ts @@ -22,12 +22,41 @@ export type CdpSession = Readonly<{ type CdpMessage = { id?: number; - method?: string; + method?: unknown; params?: Record; result?: unknown; error?: { message: string; code: number }; }; +function parseCdpMessage(data: unknown): CdpMessage | undefined { + try { + const message: unknown = JSON.parse(String(data)); + return isRecord(message) ? (message as CdpMessage) : undefined; + } catch { + return undefined; + } +} + +/** + * Records a debug event in the request diagnostics. The emitter loads on demand because these + * events are rare and this module sits in the package's eager import closure. + */ +function emitCdpDiagnostic(phase: string, data: Record): void { + void import('@agent-device/host-kit/diagnostics') + .then(({ emitDiagnostic }) => emitDiagnostic({ level: 'debug', phase, data })) + .catch(() => undefined); +} + +/** Never throws: a listener can throw a value that `String()` cannot convert. */ +function describeThrown(error: unknown): string { + if (error instanceof Error) return error.message; + return typeof error === 'string' ? error : 'non-error thrown value'; +} + +function isRecord(value: unknown): value is Record { + return typeof value === 'object' && value !== null && !Array.isArray(value); +} + /** Keeps the error that ended an operation and names a page tunnel removal that failed with it. */ export function withTunnelRemoval(primary: unknown, removal: unknown): AppError { const failure = asAppError(primary, 'COMMAND_FAILED'); @@ -75,10 +104,29 @@ export async function connectCdp(target: CdpTarget): Promise { const replies = createReplyWaiters(); const listeners: ((method: string, params: Record) => void)[] = []; const closeListeners: (() => void)[] = []; + // A throw from a WebSocket listener is an uncaught exception that ends the process, so a frame + // this session cannot read is dropped with a diagnostic and the session keeps serving requests. socket.onmessage = (event) => { - const message = JSON.parse(String(event.data)) as CdpMessage; - if (message.method) { - for (const listener of listeners) listener(message.method, message.params ?? {}); + const message = parseCdpMessage(event.data); + if (message === undefined) { + emitCdpDiagnostic('tv_cdp_frame_unreadable', { target: target.url }); + return; + } + if (message.method !== undefined) { + // A frame that names a method is an event; one whose method is not a name is unreadable, + // and never a reply, even when it carries an id. + if (typeof message.method !== 'string') return; + const params = isRecord(message.params) ? message.params : {}; + for (const listener of listeners) { + try { + listener(message.method, params); + } catch (error) { + emitCdpDiagnostic('tv_cdp_event_listener_failed', { + method: message.method, + error: describeThrown(error), + }); + } + } } else if (message.id !== undefined) { replies.deliver(String(message.id), message); } diff --git a/packages/tv-cdp/src/page-log.test.ts b/packages/tv-cdp/src/page-log.test.ts index 58473e458d..7911e9809e 100644 --- a/packages/tv-cdp/src/page-log.test.ts +++ b/packages/tv-cdp/src/page-log.test.ts @@ -78,3 +78,26 @@ test('the buffer keeps only the most recent lines', () => { assert.equal(lines.length, 5000); assert.match(lines[0]!, /line 5$/); }); + +// An old TV Chromium can send an event without the field the handler reads. +test('events missing their payload fields do not throw', () => { + const log = createPageLog(fixedClock); + + log.record('Runtime.exceptionThrown', {}); + log.record('Log.entryAdded', {}); + log.record('Runtime.consoleAPICalled', { type: 'log', args: 'not a list' }); + log.record('Runtime.consoleAPICalled', { + type: 'log', + args: [null, { type: 'string', value: 'kept' }], + }); + + assert.equal( + log.tail(10), + [ + '2026-10-30T12:00:00.000Z exception unknown', + '2026-10-30T12:00:00.000Z console.log ', + '2026-10-30T12:00:00.000Z console.log kept', + '', + ].join('\n'), + ); +}); diff --git a/packages/tv-cdp/src/page-log.ts b/packages/tv-cdp/src/page-log.ts index a252706a23..21b27f83fe 100644 --- a/packages/tv-cdp/src/page-log.ts +++ b/packages/tv-cdp/src/page-log.ts @@ -52,16 +52,24 @@ export function createPageLog(now = () => new Date()): PageLog { const handlers: Readonly) => void>> = { 'Runtime.consoleAPICalled': (params) => { - const args = (params.args as RemoteObject[] | undefined) ?? []; - push(`console.${params.type} ${args.map(describe).join(' ')}`); + const args = Array.isArray(params.args) + ? params.args.filter( + (argument): argument is RemoteObject => + typeof argument === 'object' && argument !== null, + ) + : []; + push(`console.${String(params.type)} ${args.map(describe).join(' ')}`); }, 'Runtime.exceptionThrown': (params) => { - const details = params.exceptionDetails as { text: string; exception?: RemoteObject }; - push(`exception ${details.exception?.description ?? details.text}`); + const details = params.exceptionDetails as + | { text?: string; exception?: RemoteObject } + | undefined; + push(`exception ${details?.exception?.description ?? details?.text ?? 'unknown'}`); }, 'Log.entryAdded': (params) => { - const entry = params.entry as { level: string; text: string; url?: string }; - push(`log.${entry.level} ${entry.text}${entry.url ? ` ${entry.url}` : ''}`); + const entry = params.entry as { level?: string; text?: string; url?: string } | undefined; + if (!entry) return; + push(`log.${String(entry.level)} ${String(entry.text)}${entry.url ? ` ${entry.url}` : ''}`); }, }; diff --git a/packages/tv-cdp/src/runtime.ts b/packages/tv-cdp/src/runtime.ts index a71e31569d..558d9e6de7 100644 --- a/packages/tv-cdp/src/runtime.ts +++ b/packages/tv-cdp/src/runtime.ts @@ -350,6 +350,8 @@ function createTvPlatformRuntime( const lifecycle = bindDirectApplicationLifecycle({ owner: label, openTargetIdentity: 'bundle-id', + // The page interactor relaunches the TV app itself when asked to terminate it. + closeBeforeRelaunch: false, binding: bindProviderApplicationLifecycleInteractor({ device, signal, resolveInteractor }), }); const appOperations: Pick = { diff --git a/test/integration/provider-scenarios/linux-world.ts b/test/integration/provider-scenarios/linux-world.ts index bf6f30b172..2a832e3f80 100644 --- a/test/integration/provider-scenarios/linux-world.ts +++ b/test/integration/provider-scenarios/linux-world.ts @@ -54,6 +54,10 @@ export async function createLinuxDesktopWorld(): Promise { toolCalls.push([cmd, args]); return { stdout: '', stderr: '', exitCode: 0 }; }, + // The scripted desktop below owns app launches, so the detached launcher is never reached. + launchDetached: (cmd) => { + throw new Error(`the Linux world launches apps through its desktop: ${cmd}`); + }, desktop: { openTarget: async (target) => { desktopCalls.push(['open', target]); diff --git a/test/integration/provider-scenarios/web-provider.test.ts b/test/integration/provider-scenarios/web-provider.test.ts index 953462e119..a4dfd247c5 100644 --- a/test/integration/provider-scenarios/web-provider.test.ts +++ b/test/integration/provider-scenarios/web-provider.test.ts @@ -223,9 +223,20 @@ test('non-dense browser refs survive snapshot storage and routed fill and click' host: { env: process.env, cwd: process.cwd() }, }); await withCommandExecutorOverride( - async (_command, args) => { - const [command, ref, text] = args.slice(1); + async (_command, args, options) => { + const [command, ref] = args.slice(1); let data: unknown = {}; + if (command === 'batch') { + // Typed text arrives on stdin as a one-entry batch, never in argv. + const entries = JSON.parse(String(options.stdin)) as string[][]; + const results = entries.map((entry) => { + assert.equal(entry[0], 'fill', `Unexpected batch entry: ${entry}`); + calls.push(entry); + values[entry[1]!] = entry[2]!; + return { command: entry, error: null, result: {}, success: true }; + }); + return { stdout: JSON.stringify(results), stderr: '', exitCode: 0 }; + } if (command === 'snapshot') { data = { snapshot: [ @@ -239,9 +250,6 @@ test('non-dense browser refs survive snapshot storage and routed fill and click' e4: { role: 'button', name: 'Sign in' }, }, }; - } else if (command === 'fill') { - calls.push(['fill', ref!, text!]); - values[ref!] = text!; } else if (command === 'click') { calls.push(['click', ref!]); signedIn = ref === '@e4';