From 72d87715ae0b190be58f05f6db5ffcd4e23c8d14 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 15:43:35 +0000 Subject: [PATCH 01/23] fix(platform-web): send fill and type text to agent-browser on stdin Web fill, fillRef, and typeText passed the typed text as agent-browser argv, which every host user can read in the process table, and copied that argv into error details. Text entry now runs as a one-entry batch read from stdin; a failed entry raises a typed text-entry-failed error whose details carry no text. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016qAu53rMak1bXMuR5U2gF4 --- .../src/agent-browser-provider.test.ts | 70 +++++++++++++++++-- .../src/agent-browser-provider.ts | 49 +++++++++++-- .../provider-scenarios/web-provider.test.ts | 18 +++-- 3 files changed, 118 insertions(+), 19 deletions(-) diff --git a/packages/platform-web/src/agent-browser-provider.test.ts b/packages/platform-web/src/agent-browser-provider.test.ts index 651a5c8bfc..10a173e4f0 100644 --- a/packages/platform-web/src/agent-browser-provider.test.ts +++ b/packages/platform-web/src/agent-browser-provider.test.ts @@ -35,6 +35,7 @@ bindTestCommandHost(); type AgentBrowserCall = { cmd: string; args: readonly string[]; + stdin?: string; }; const mockProviderStartupCleanup = vi.mocked(providerStartupCleanupMock); @@ -101,7 +102,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'], @@ -109,8 +110,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'], @@ -119,6 +120,50 @@ 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. + return agentBrowserJsonResult( + [{ command, error: 'Unknown ref: e9', result: null, success: false }], + 1, + ); + }; + await withCommandExecutorOverride(executor, async () => { + for (const attempt of [ + () => provider.fillRef?.('@e9', secret), + () => provider.typeText(secret), + () => provider.fill(11, 22, secret), + ]) { + await assert.rejects(attempt, (error: unknown) => { + assert.ok(error instanceof AppError); + assert.equal(error.code, 'COMMAND_FAILED'); + assert.equal(error.message, 'Unknown ref: e9'); + assert.equal(error.details?.reason, 'text-entry-failed'); + assert.equal(JSON.stringify(error.details).includes(secret), false); + return true; + }); + } + }); + for (const call of calls) assert.equal(call.args.includes(secret), false); }); }); @@ -463,8 +508,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 } : {}, @@ -476,9 +531,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; } @@ -737,7 +793,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..76e45bf531 100644 --- a/packages/platform-web/src/agent-browser-provider.ts +++ b/packages/platform-web/src/agent-browser-provider.ts @@ -127,16 +127,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 +173,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 +197,40 @@ function createAgentBrowserSendLedger(runJson: (args: string[]) => Promise { + const data = await send(['batch'], { stdin: JSON.stringify([command]) }); + const entry: unknown = Array.isArray(data) && data.length === 1 ? data[0] : undefined; + const commandName = command[0] ?? 'batch'; + if (!isBatchEntry(entry)) { + throw new AppError('COMMAND_FAILED', `agent-browser returned an unusable ${commandName} result`, { + cmd: AGENT_BROWSER, + args: ['batch'], + command: commandName, + reason: 'text-entry-result-unusable', + hint: AGENT_BROWSER_DOCTOR_HINT, + }); + } + if (entry.success === true) return; + throw new AppError( + 'COMMAND_FAILED', + typeof entry.error === 'string' ? entry.error : `agent-browser ${commandName} failed`, + { + cmd: AGENT_BROWSER, + args: ['batch'], + command: commandName, + reason: 'text-entry-failed', + hint: AGENT_BROWSER_DOCTOR_HINT, + }, + ); +} + type ScrollStep = { distance?: number; delayAfterMs: number; @@ -416,6 +450,7 @@ type AgentBrowserBatchEntry = { command?: unknown; success?: unknown; result?: unknown; + error?: unknown; }; /** 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'; From 4f4a2c716eb57f192b313a67050854bc6cd277ec Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 15:45:34 +0000 Subject: [PATCH 02/23] fix(provider-webdriver): retry session delete and keep status on non-JSON errors A gateway error with a non-JSON body (a 502 HTML page) threw before the status was read, so it carried no status, was never retried, and lost its dispatch disclosure. The status now decides as for a JSON error; the raw body is truncated evidence. DELETE /session/{id} had a single attempt, so one transient failure left a billed session with nothing left to retry it. It now uses the idempotent retry budget, and a W3C invalid session id answer reads as the session already ended. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016qAu53rMak1bXMuR5U2gF4 --- .../src/runtime-session-allocation.test.ts | 47 +++++++++++++++++++ .../src/webdriver-client.ts | 13 ++++- ...bdriver-interactor-mutation-resend.test.ts | 14 ++++-- .../src/webdriver-transport.test.ts | 41 ++++++++++++++++ .../src/webdriver-transport.ts | 44 +++++++++++++++-- 5 files changed, 150 insertions(+), 9 deletions(-) diff --git a/packages/provider-webdriver/src/runtime-session-allocation.test.ts b/packages/provider-webdriver/src/runtime-session-allocation.test.ts index 4b5fcf9e9d..98d0d8534c 100644 --- a/packages/provider-webdriver/src/runtime-session-allocation.test.ts +++ b/packages/provider-webdriver/src/runtime-session-allocation.test.ts @@ -493,6 +493,43 @@ test('a release the provider refused reports the session left running', async () } }); +/** + * `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. + */ +for (const { name, answers } of [ + { + name: 'a transient delete failure is retried', + answers: [{ status: 502, body: 'Bad Gateway' }], + }, + { + name: 'a delete answered invalid session id', + answers: [ + { + status: 404, + body: { value: { error: 'invalid session id', message: 'session not found' } }, + }, + ], + }, +] as const) { + test(`${name} confirms the release`, async () => { + const hub = startWebDriverHub({ deleteAnswers: answers }); + globalThis.fetch = hub.fetch; + const runtime = makeRuntime({ requestPolicy: { retryAttempts: 1, retryDelayMs: 1 } }); + const lease = makeLease(); + + try { + await runtime.leaseLifecycle.allocate!(lease); + assert.deepEqual(await settle(() => runtime.leaseLifecycle.release!(lease)), { + status: 'resolved', + value: { provider: 'webdriver-test', providerSessionId: 'session-1' }, + }); + } finally { + await runtime.shutdown(); + } + }); +} + /** * A create the hub refused still hands back what the provider prepared, and that hand-back is the * plugin's own code too. A `cleanup` that never answers there would keep the allocation from answering, @@ -656,10 +693,13 @@ function startWebDriverHub( deleteFailure?: string; heldDeletes?: number; createFailure?: string; + /** Answers the hub gives to the first `DELETE`s, in order, before it ends sessions normally. */ + deleteAnswers?: readonly Readonly<{ status: number; body: unknown }>[]; }> = {}, ) { const created: string[] = []; const deleted: string[] = []; + const deleteAnswers = [...(options.deleteAnswers ?? [])]; let deletesToHold = options.heldDeletes ?? 0; let deleteFailure = options.deleteFailure; const held: (() => void)[] = []; @@ -712,6 +752,13 @@ function startWebDriverHub( 500, ); } + const answer = deleteAnswers.shift(); + if (answer) { + return new Response( + typeof answer.body === 'string' ? answer.body : JSON.stringify(answer.body), + { status: answer.status }, + ); + } deleted.push(sessionId); signalForDelete(sessionId).report(); } 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-mutation-resend.test.ts b/packages/provider-webdriver/src/webdriver-interactor-mutation-resend.test.ts index 1be3905290..e718ed966c 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'), }, @@ -210,9 +215,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 +231,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-transport.test.ts b/packages/provider-webdriver/src/webdriver-transport.test.ts index 7cfe696c18..264b305ff3 100644 --- a/packages/provider-webdriver/src/webdriver-transport.test.ts +++ b/packages/provider-webdriver/src/webdriver-transport.test.ts @@ -305,6 +305,47 @@ 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); +}); + +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); + 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..1b182553a0 100644 --- a/packages/provider-webdriver/src/webdriver-transport.ts +++ b/packages/provider-webdriver/src/webdriver-transport.ts @@ -210,8 +210,10 @@ 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) : {}) }; + // A gateway in front of the driver can answer an error with a non-JSON page (a `502 `). + // Its status still decides retry and dispatch disclosure, so the raw body is only evidence. + const payload = text ? (parseJsonOrUndefined(text) ?? truncateBody(text)) : {}; const error = webdriverError(status, payload); if (isWebDriverRouteUnsupported(error)) { emitWebDriverDiagnostic(WEBDRIVER_ROUTE_UNSUPPORTED_REASON, { @@ -322,14 +324,36 @@ 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.', + { status, text: truncateBody(text) }, + error, + ); + } +} + +function parseJsonOrUndefined(text: string): unknown { + try { + return 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 @@ -360,6 +384,18 @@ function webdriverError(status: number, payload: unknown): AppError { /** 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. From 7d6a730dd59e9204be2a03520889ed7bd1ba1191 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 15:48:34 +0000 Subject: [PATCH 03/23] fix(provider-webdriver): route system buttons and app opens per Appium driver UiAutomator2 registers no `mobile: pressButton`, so Android home and app-switcher now press KEYCODE_HOME and KEYCODE_APP_SWITCH through `mobile: pressKey`. XCUITest pressButton has no app-switcher button, so the iOS capability map now declares appSwitcher unsupported and the command refuses before the driver. openDevice sent `mobile: activateApp` with no app id, which both drivers reject; a leased session is already the foreground device, so it now sends nothing. An iOS deep link names its app `bundleId`, the field the XCUITest extension reads, instead of `package`. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016qAu53rMak1bXMuR5U2gF4 --- .../provider-webdriver/src/capabilities.ts | 10 +++-- ...bdriver-interactor-hardware-button.test.ts | 31 +++++++++++++ ...bdriver-interactor-mutation-resend.test.ts | 17 +++++-- .../src/webdriver-interactor.test.ts | 45 +++++++++++++++++++ .../src/webdriver-interactor.ts | 34 +++++++++++--- 5 files changed, 125 insertions(+), 12 deletions(-) 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/webdriver-interactor-hardware-button.test.ts b/packages/provider-webdriver/src/webdriver-interactor-hardware-button.test.ts index 34ea274c5b..4ea0021c19 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,37 @@ test('iOS volume presses ride mobile pressButton and power refuses before the dr }); }); +// PROV2-1: 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'; + }); + 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 e718ed966c..8e5bc063bb 100644 --- a/packages/provider-webdriver/src/webdriver-interactor-mutation-resend.test.ts +++ b/packages/provider-webdriver/src/webdriver-interactor-mutation-resend.test.ts @@ -149,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': { diff --git a/packages/provider-webdriver/src/webdriver-interactor.test.ts b/packages/provider-webdriver/src/webdriver-interactor.test.ts index 1f04e65b4b..d7a48e4a60 100644 --- a/packages/provider-webdriver/src/webdriver-interactor.test.ts +++ b/packages/provider-webdriver/src/webdriver-interactor.test.ts @@ -969,3 +969,48 @@ test.each([true, false, 'failed'] as const)( ); }, ); + +/** 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.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 }, + ]); } /** From ec5e57c737ae81857a182c7bc8bb639cb868cfef Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 15:50:11 +0000 Subject: [PATCH 04/23] fix(contracts): carry open --relaunch through the direct lifecycle binding The shared direct lifecycle closed before a relaunch only when an owner opted in, and otherwise never forwarded terminateRunningApp, so on Linux, web, HarmonyOS, Vega, and the CDP TV owner `open --relaunch` returned success after a plain open. `closeBeforeRelaunch` is now a required choice: the local direct owners close first, and an owner whose open restarts the app (CDP TV) receives terminateRunningApp. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016qAu53rMak1bXMuR5U2gF4 --- .../application-lifecycle-interaction.test.ts | 64 +++++++++++++++++++ .../src/application-lifecycle-interaction.ts | 11 +++- packages/tv-cdp/src/runtime.ts | 2 + 3 files changed, 75 insertions(+), 2 deletions(-) diff --git a/packages/contracts/src/application-lifecycle-interaction.test.ts b/packages/contracts/src/application-lifecycle-interaction.test.ts index ca8212c59e..2ea36421dc 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; +} + +// CONTR3-1: 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/tv-cdp/src/runtime.ts b/packages/tv-cdp/src/runtime.ts index 09fc795e0a..3be197e367 100644 --- a/packages/tv-cdp/src/runtime.ts +++ b/packages/tv-cdp/src/runtime.ts @@ -334,6 +334,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 = { From 7c01598d5a393af04b8ab8735a05b2120d383468 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 15:51:31 +0000 Subject: [PATCH 05/23] fix(tv-cdp): drop unreadable CDP frames instead of throwing in the socket handler A non-JSON frame, a non-object message, or a throwing event listener threw inside the WebSocket message handler, which Node reports as an uncaught exception that ends the daemon. The handler now drops an unreadable frame with a debug diagnostic, isolates each listener, and the page log tolerates events that lack their payload fields. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016qAu53rMak1bXMuR5U2gF4 --- packages/tv-cdp/src/cdp.test.ts | 85 ++++++++++++++++++++++++++++ packages/tv-cdp/src/cdp.ts | 37 +++++++++++- packages/tv-cdp/src/page-log.test.ts | 14 +++++ packages/tv-cdp/src/page-log.ts | 15 +++-- 4 files changed, 142 insertions(+), 9 deletions(-) create mode 100644 packages/tv-cdp/src/cdp.test.ts diff --git a/packages/tv-cdp/src/cdp.test.ts b/packages/tv-cdp/src/cdp.test.ts new file mode 100644 index 0000000000..aa03ff2bac --- /dev/null +++ b/packages/tv-cdp/src/cdp.test.ts @@ -0,0 +1,85 @@ +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.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`; +} + +// PROV-9: 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', '{"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(() => { + throw new Error('listener failed'); + }); + 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 8e38502c29..1ebf488251 100644 --- a/packages/tv-cdp/src/cdp.ts +++ b/packages/tv-cdp/src/cdp.ts @@ -1,3 +1,4 @@ +import { emitDiagnostic } from '@agent-device/host-kit/diagnostics'; import { AppError } from '@agent-device/kernel/errors'; import { createReplyWaiters } from './replies.ts'; @@ -28,6 +29,19 @@ type CdpMessage = { 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; + } +} + +function isRecord(value: unknown): value is Record { + return typeof value === 'object' && value !== null && !Array.isArray(value); +} + export async function listTargets(port: number): Promise { const response = await fetch(`http://localhost:${port}/json`, { signal: AbortSignal.timeout(5000), @@ -63,10 +77,27 @@ 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) { + emitDiagnostic({ level: 'debug', phase: 'tv_cdp_frame_unreadable', data: { target: target.url } }); + return; + } + if (typeof message.method === 'string') { + const params = isRecord(message.params) ? message.params : {}; + for (const listener of listeners) { + try { + listener(message.method, params); + } catch (error) { + emitDiagnostic({ + level: 'debug', + phase: 'tv_cdp_event_listener_failed', + data: { method: message.method, error: String(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..ddbcfd50dd 100644 --- a/packages/tv-cdp/src/page-log.test.ts +++ b/packages/tv-cdp/src/page-log.test.ts @@ -78,3 +78,17 @@ test('the buffer keeps only the most recent lines', () => { assert.equal(lines.length, 5000); assert.match(lines[0]!, /line 5$/); }); + +// PROV-9: 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' }); + + assert.equal( + log.tail(10), + '2026-10-30T12:00:00.000Z exception unknown\n2026-10-30T12:00:00.000Z console.log \n', + ); +}); diff --git a/packages/tv-cdp/src/page-log.ts b/packages/tv-cdp/src/page-log.ts index a252706a23..210de706da 100644 --- a/packages/tv-cdp/src/page-log.ts +++ b/packages/tv-cdp/src/page-log.ts @@ -52,16 +52,19 @@ 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 as RemoteObject[]) : []; + 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}` : ''}`); }, }; From 890dd170f07636a43b0941b0cefbb9e667dddd35 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 15:53:04 +0000 Subject: [PATCH 06/23] fix(provider-webdriver): bound and type hosted app uploads, stream the build postHubAppUpload had no deadline, let a network failure escape as a raw TypeError, and reported a rejected credential as generic COMMAND_FAILED; appFileUploadForm read the whole build into memory. The upload now runs under a 15 minute deadline combined with the caller signal, wraps transport failures with a typed reason and their cause, answers 401/403 as UNAUTHORIZED, and streams the file through a file-backed blob. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016qAu53rMak1bXMuR5U2gF4 --- packages/provider-testmu/src/testmu.test.ts | 1 - .../src/browserstack.test.ts | 1 - .../src/webdriver-utils.test.ts | 42 +++++++++++++ .../provider-webdriver/src/webdriver-utils.ts | 61 ++++++++++++++----- 4 files changed, 89 insertions(+), 16 deletions(-) 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/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/webdriver-utils.test.ts b/packages/provider-webdriver/src/webdriver-utils.test.ts index 9073922b1c..eeadb0d644 100644 --- a/packages/provider-webdriver/src/webdriver-utils.test.ts +++ b/packages/provider-webdriver/src/webdriver-utils.test.ts @@ -80,6 +80,48 @@ 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 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..fee3540f3e 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,22 @@ 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 longest one app upload may run. Builds of a few hundred MB on a slow uplink take minutes, so + * this bounds a stalled transfer, not a slow one. + */ +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 +115,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.`, { From 66cc078a938ec6f804f879e9b0c0563063a615c5 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 15:53:47 +0000 Subject: [PATCH 07/23] fix(provider-webdriver): look up Device Farm artifacts in the session's region Artifact lookup preferred AWS_REGION over the region in the session ARN, so a session created with --aws-region in another region listed its artifacts against the wrong region and failed. The ARN names where the session ran and now decides; the environment is the fallback. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016qAu53rMak1bXMuR5U2gF4 --- .../src/aws-device-farm-provider.test.ts | 21 +++++++++++++++++++ .../src/aws-device-farm-provider.ts | 6 ++++-- 2 files changed, 25 insertions(+), 2 deletions(-) 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..4f0824e3be 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,27 @@ 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', + }); + + assert.ok(commands.length > 0); + 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 }) => { From f488459b3f9d207e7f3bf1e7fa7868fa85887291 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 15:55:18 +0000 Subject: [PATCH 08/23] fix(platform-linux): launch an app binary detached from daemon pipes `open ` ran the app through the captured command runner, which pipes stdio and appends every output chunk to memory until the child exits, so a long-running desktop app grew daemon memory without bound. The app now runs detached with ignored stdio; a spawn failure still emits the linux_app_launch diagnostic. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016qAu53rMak1bXMuR5U2gF4 --- .../src/__tests__/tool-provider.test.ts | 39 ++++++++++++++++++- packages/platform-linux/src/tool-provider.ts | 8 +++- 2 files changed, 43 insertions(+), 4 deletions(-) diff --git a/packages/platform-linux/src/__tests__/tool-provider.test.ts b/packages/platform-linux/src/__tests__/tool-provider.test.ts index 1bd97bdf03..faede7c773 100644 --- a/packages/platform-linux/src/__tests__/tool-provider.test.ts +++ b/packages/platform-linux/src/__tests__/tool-provider.test.ts @@ -1,5 +1,7 @@ -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 assert from 'node:assert/strict'; import { pressLinux } from '../input-actions.ts'; import { createLocalLinuxToolProvider, withLinuxToolProvider } from '../tool-provider.ts'; @@ -162,6 +164,39 @@ test('local Linux desktop provider translates semantic lifecycle calls to host t ]); }); +// PROV-6: `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. +test.skipIf(!fs.existsSync('/proc/self/fd'))( + 'local Linux desktop provider launches an app binary detached from daemon pipes', + async () => { + 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 { + const provider = createLocalLinuxToolProvider({ + host: { env: process.env, cwd: process.cwd() }, + whichCommand: async (cmd) => cmd === 'fake-desktop-app', + runCommand: async (cmd) => { + throw new Error(`the app launch must not run as a captured command: ${cmd}`); + }, + }); + + await provider.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 falls back to pkill when wmctrl is unavailable', async () => { const commands: Array<[string, string[], boolean | undefined]> = []; const provider = createLocalLinuxToolProvider({ diff --git a/packages/platform-linux/src/tool-provider.ts b/packages/platform-linux/src/tool-provider.ts index 645523a2dd..76f42999e6 100644 --- a/packages/platform-linux/src/tool-provider.ts +++ b/packages/platform-linux/src/tool-provider.ts @@ -3,6 +3,7 @@ import type { ScrollDirection } from '@agent-device/contracts/scroll-gesture'; import { AppError } from '@agent-device/kernel/errors'; import { runCmd, + runCmdDetachedMonitored, whichCmd, type ExecOptions, type ExecResult, @@ -180,11 +181,14 @@ 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 runCmdDetachedMonitored(target, []).exited.then((exit) => { + if (exit.error === undefined) return; emitDiagnostic({ level: 'warn', phase: 'linux_app_launch', - data: { app: target, error: String(error) }, + data: { app: target, error: exit.error }, }); }); await sleep(500); From 1a9094424c99226fce638f0a9a5bdfee84d97088 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 15:56:07 +0000 Subject: [PATCH 09/23] style: format provider remediation changes Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016qAu53rMak1bXMuR5U2gF4 --- .../application-lifecycle-interaction.test.ts | 2 +- .../src/__tests__/tool-provider.test.ts | 2 +- .../src/agent-browser-provider.test.ts | 3 ++- .../platform-web/src/agent-browser-provider.ts | 18 +++++++++++------- ...ebdriver-interactor-hardware-button.test.ts | 2 +- .../src/webdriver-transport.ts | 3 ++- packages/tv-cdp/src/cdp.test.ts | 8 ++++++-- packages/tv-cdp/src/cdp.ts | 6 +++++- packages/tv-cdp/src/page-log.test.ts | 2 +- 9 files changed, 30 insertions(+), 16 deletions(-) diff --git a/packages/contracts/src/application-lifecycle-interaction.test.ts b/packages/contracts/src/application-lifecycle-interaction.test.ts index 2ea36421dc..33b2414b73 100644 --- a/packages/contracts/src/application-lifecycle-interaction.test.ts +++ b/packages/contracts/src/application-lifecycle-interaction.test.ts @@ -108,7 +108,7 @@ function lifecycleRecordingInteractor(calls: string[]): Interactor { } as unknown as Interactor; } -// CONTR3-1: the local direct owners (Linux, web, HarmonyOS, Vega) do not replace a running app on +// 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[] = []; diff --git a/packages/platform-linux/src/__tests__/tool-provider.test.ts b/packages/platform-linux/src/__tests__/tool-provider.test.ts index faede7c773..638fe62916 100644 --- a/packages/platform-linux/src/__tests__/tool-provider.test.ts +++ b/packages/platform-linux/src/__tests__/tool-provider.test.ts @@ -164,7 +164,7 @@ test('local Linux desktop provider translates semantic lifecycle calls to host t ]); }); -// PROV-6: `open ` used to run the app as a piped child of the daemon, which kept every +// `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. test.skipIf(!fs.existsSync('/proc/self/fd'))( 'local Linux desktop provider launches an app binary detached from daemon pipes', diff --git a/packages/platform-web/src/agent-browser-provider.test.ts b/packages/platform-web/src/agent-browser-provider.test.ts index 10a173e4f0..1c2781a25c 100644 --- a/packages/platform-web/src/agent-browser-provider.test.ts +++ b/packages/platform-web/src/agent-browser-provider.test.ts @@ -138,7 +138,8 @@ test('agent-browser provider keeps typed text out of argv and error details when 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] === '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. diff --git a/packages/platform-web/src/agent-browser-provider.ts b/packages/platform-web/src/agent-browser-provider.ts index 76e45bf531..863e349b89 100644 --- a/packages/platform-web/src/agent-browser-provider.ts +++ b/packages/platform-web/src/agent-browser-provider.ts @@ -209,13 +209,17 @@ async function sendTextEntry(send: AgentBrowserRunJson, command: readonly string const entry: unknown = Array.isArray(data) && data.length === 1 ? data[0] : undefined; const commandName = command[0] ?? 'batch'; if (!isBatchEntry(entry)) { - throw new AppError('COMMAND_FAILED', `agent-browser returned an unusable ${commandName} result`, { - cmd: AGENT_BROWSER, - args: ['batch'], - command: commandName, - reason: 'text-entry-result-unusable', - hint: AGENT_BROWSER_DOCTOR_HINT, - }); + throw new AppError( + 'COMMAND_FAILED', + `agent-browser returned an unusable ${commandName} result`, + { + cmd: AGENT_BROWSER, + args: ['batch'], + command: commandName, + reason: 'text-entry-result-unusable', + hint: AGENT_BROWSER_DOCTOR_HINT, + }, + ); } if (entry.success === true) return; throw new AppError( 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 4ea0021c19..e2c666c319 100644 --- a/packages/provider-webdriver/src/webdriver-interactor-hardware-button.test.ts +++ b/packages/provider-webdriver/src/webdriver-interactor-hardware-button.test.ts @@ -64,7 +64,7 @@ test('iOS volume presses ride mobile pressButton and power refuses before the dr }); }); -// PROV2-1: UiAutomator2 registers no `mobile: pressButton`, and XCUITest's pressButton names are +// 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[] = []; diff --git a/packages/provider-webdriver/src/webdriver-transport.ts b/packages/provider-webdriver/src/webdriver-transport.ts index 1b182553a0..d502baffc0 100644 --- a/packages/provider-webdriver/src/webdriver-transport.ts +++ b/packages/provider-webdriver/src/webdriver-transport.ts @@ -210,7 +210,8 @@ export class WebDriverTransport { timeoutMs, requestSignal, ); - if (ok) return { status, value: readWebDriverValue(text ? parseJsonResponse(text, status) : {}) }; + if (ok) + return { status, value: readWebDriverValue(text ? parseJsonResponse(text, status) : {}) }; // A gateway in front of the driver can answer an error with a non-JSON page (a `502 `). // Its status still decides retry and dispatch disclosure, so the raw body is only evidence. const payload = text ? (parseJsonOrUndefined(text) ?? truncateBody(text)) : {}; diff --git a/packages/tv-cdp/src/cdp.test.ts b/packages/tv-cdp/src/cdp.test.ts index aa03ff2bac..5c6c9a1ec6 100644 --- a/packages/tv-cdp/src/cdp.test.ts +++ b/packages/tv-cdp/src/cdp.test.ts @@ -67,11 +67,15 @@ async function pageSending(beforeAnswer: readonly string[]): Promise { return `ws://127.0.0.1:${address.port}/devtools/page/1`; } -// PROV-9: a throw inside the WebSocket message handler is an uncaught exception, which ends the +// 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', '{"method":"Log.entryAdded","params":7}']); - const session = await connectCdp({ title: 'page', url: 'http://tv/page/', webSocketDebuggerUrl: url }); + const session = await connectCdp({ + title: 'page', + url: 'http://tv/page/', + webSocketDebuggerUrl: url, + }); cleanups.push(() => session.close()); const events: string[] = []; session.on(() => { diff --git a/packages/tv-cdp/src/cdp.ts b/packages/tv-cdp/src/cdp.ts index 1ebf488251..f5b2ec895f 100644 --- a/packages/tv-cdp/src/cdp.ts +++ b/packages/tv-cdp/src/cdp.ts @@ -82,7 +82,11 @@ export async function connectCdp(target: CdpTarget): Promise { socket.onmessage = (event) => { const message = parseCdpMessage(event.data); if (message === undefined) { - emitDiagnostic({ level: 'debug', phase: 'tv_cdp_frame_unreadable', data: { target: target.url } }); + emitDiagnostic({ + level: 'debug', + phase: 'tv_cdp_frame_unreadable', + data: { target: target.url }, + }); return; } if (typeof message.method === 'string') { diff --git a/packages/tv-cdp/src/page-log.test.ts b/packages/tv-cdp/src/page-log.test.ts index ddbcfd50dd..30050a08bd 100644 --- a/packages/tv-cdp/src/page-log.test.ts +++ b/packages/tv-cdp/src/page-log.test.ts @@ -79,7 +79,7 @@ test('the buffer keeps only the most recent lines', () => { assert.match(lines[0]!, /line 5$/); }); -// PROV-9: an old TV Chromium can send an event without the field the handler reads. +// 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); From 5fe13fc29064e6001a6769d84e62fb6cf5426bc6 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 16:09:24 +0000 Subject: [PATCH 10/23] test(provider-webdriver): keep new cases within the file line limit Moves the session-delete release cases to runtime-session.test.ts and the app-open interactor cases to their own file, so neither existing test file passes the 1000-line lint limit. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016qAu53rMak1bXMuR5U2gF4 --- .../src/runtime-session-allocation.test.ts | 47 ----------------- .../src/runtime-session.test.ts | 33 ++++++++++++ .../src/webdriver-interactor-app-open.test.ts | 50 +++++++++++++++++++ .../src/webdriver-interactor.test.ts | 45 ----------------- 4 files changed, 83 insertions(+), 92 deletions(-) create mode 100644 packages/provider-webdriver/src/webdriver-interactor-app-open.test.ts diff --git a/packages/provider-webdriver/src/runtime-session-allocation.test.ts b/packages/provider-webdriver/src/runtime-session-allocation.test.ts index 98d0d8534c..4b5fcf9e9d 100644 --- a/packages/provider-webdriver/src/runtime-session-allocation.test.ts +++ b/packages/provider-webdriver/src/runtime-session-allocation.test.ts @@ -493,43 +493,6 @@ test('a release the provider refused reports the session left running', async () } }); -/** - * `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. - */ -for (const { name, answers } of [ - { - name: 'a transient delete failure is retried', - answers: [{ status: 502, body: 'Bad Gateway' }], - }, - { - name: 'a delete answered invalid session id', - answers: [ - { - status: 404, - body: { value: { error: 'invalid session id', message: 'session not found' } }, - }, - ], - }, -] as const) { - test(`${name} confirms the release`, async () => { - const hub = startWebDriverHub({ deleteAnswers: answers }); - globalThis.fetch = hub.fetch; - const runtime = makeRuntime({ requestPolicy: { retryAttempts: 1, retryDelayMs: 1 } }); - const lease = makeLease(); - - try { - await runtime.leaseLifecycle.allocate!(lease); - assert.deepEqual(await settle(() => runtime.leaseLifecycle.release!(lease)), { - status: 'resolved', - value: { provider: 'webdriver-test', providerSessionId: 'session-1' }, - }); - } finally { - await runtime.shutdown(); - } - }); -} - /** * A create the hub refused still hands back what the provider prepared, and that hand-back is the * plugin's own code too. A `cleanup` that never answers there would keep the allocation from answering, @@ -693,13 +656,10 @@ function startWebDriverHub( deleteFailure?: string; heldDeletes?: number; createFailure?: string; - /** Answers the hub gives to the first `DELETE`s, in order, before it ends sessions normally. */ - deleteAnswers?: readonly Readonly<{ status: number; body: unknown }>[]; }> = {}, ) { const created: string[] = []; const deleted: string[] = []; - const deleteAnswers = [...(options.deleteAnswers ?? [])]; let deletesToHold = options.heldDeletes ?? 0; let deleteFailure = options.deleteFailure; const held: (() => void)[] = []; @@ -752,13 +712,6 @@ function startWebDriverHub( 500, ); } - const answer = deleteAnswers.shift(); - if (answer) { - return new Response( - typeof answer.body === 'string' ? answer.body : JSON.stringify(answer.body), - { status: answer.status }, - ); - } deleted.push(sessionId); signalForDelete(sessionId).report(); } 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-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.test.ts b/packages/provider-webdriver/src/webdriver-interactor.test.ts index d7a48e4a60..1f04e65b4b 100644 --- a/packages/provider-webdriver/src/webdriver-interactor.test.ts +++ b/packages/provider-webdriver/src/webdriver-interactor.test.ts @@ -969,48 +969,3 @@ test.each([true, false, 'failed'] as const)( ); }, ); - -/** 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 }]])}`, - ]); - } -}); From 0ea8e908d3b6b100fb8f0870f48cb2509861c5c8 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 16:49:48 +0000 Subject: [PATCH 11/23] test: fix typecheck in the new web and CDP test cases Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016qAu53rMak1bXMuR5U2gF4 --- packages/platform-web/src/agent-browser-provider.test.ts | 2 +- packages/tv-cdp/src/cdp.test.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/platform-web/src/agent-browser-provider.test.ts b/packages/platform-web/src/agent-browser-provider.test.ts index 1c2781a25c..1b6982275f 100644 --- a/packages/platform-web/src/agent-browser-provider.test.ts +++ b/packages/platform-web/src/agent-browser-provider.test.ts @@ -150,7 +150,7 @@ test('agent-browser provider keeps typed text out of argv and error details when }; await withCommandExecutorOverride(executor, async () => { for (const attempt of [ - () => provider.fillRef?.('@e9', secret), + async () => await provider.fillRef?.('@e9', secret), () => provider.typeText(secret), () => provider.fill(11, 22, secret), ]) { diff --git a/packages/tv-cdp/src/cdp.test.ts b/packages/tv-cdp/src/cdp.test.ts index 5c6c9a1ec6..a9fdb58574 100644 --- a/packages/tv-cdp/src/cdp.test.ts +++ b/packages/tv-cdp/src/cdp.test.ts @@ -44,7 +44,7 @@ async function pageSending(beforeAnswer: readonly string[]): Promise { 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.alloc(0); + 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)) { From bb5054c596c4b248ad9924db8f6ecc6fda880854 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 17:13:56 +0000 Subject: [PATCH 12/23] fix(providers): address review findings on text entry, CDP frames, and transport - Web text entry checks that the one-entry batch answer echoes the command it sent, and its failure message no longer carries the backend's error text, which could quote the typed text. - A CDP frame whose method is not a string is dropped instead of answering a pending request; a listener's thrown value is described without String(), and null console arguments are skipped. - A 2xx WebDriver answer that is not JSON discloses dispatched unknown; a non-2xx JSON null body stays null. - Tests: upload deadline actually fires, the iOS app-switcher refusal names its operation, and Device Farm runs exactly two lookups. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016qAu53rMak1bXMuR5U2gF4 --- .../src/agent-browser-provider.test.ts | 24 +++++++++++++++--- .../src/agent-browser-provider.ts | 6 +++-- .../src/aws-device-farm-provider.test.ts | 3 ++- ...bdriver-interactor-hardware-button.test.ts | 6 ++++- .../src/webdriver-transport.test.ts | 1 + .../src/webdriver-transport.ts | 11 +++++--- .../src/webdriver-utils.test.ts | 25 +++++++++++++++++++ packages/tv-cdp/src/cdp.test.ts | 11 ++++++-- packages/tv-cdp/src/cdp.ts | 15 ++++++++--- packages/tv-cdp/src/page-log.test.ts | 11 +++++++- packages/tv-cdp/src/page-log.ts | 7 +++++- 11 files changed, 102 insertions(+), 18 deletions(-) diff --git a/packages/platform-web/src/agent-browser-provider.test.ts b/packages/platform-web/src/agent-browser-provider.test.ts index 1b6982275f..88db0ec8b7 100644 --- a/packages/platform-web/src/agent-browser-provider.test.ts +++ b/packages/platform-web/src/agent-browser-provider.test.ts @@ -142,9 +142,10 @@ test('agent-browser provider keeps typed text out of argv and error details when 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. + // 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: 'Unknown ref: e9', result: null, success: false }], + [{ command, error: `could not type ${secret}`, result: null, success: false }], 1, ); }; @@ -157,8 +158,9 @@ test('agent-browser provider keeps typed text out of argv and error details when await assert.rejects(attempt, (error: unknown) => { assert.ok(error instanceof AppError); assert.equal(error.code, 'COMMAND_FAILED'); - assert.equal(error.message, 'Unknown ref: e9'); + assert.match(error.message, /^agent-browser (fill|keyboard type) failed/); assert.equal(error.details?.reason, 'text-entry-failed'); + assert.equal(error.message.includes(secret), false); assert.equal(JSON.stringify(error.details).includes(secret), false); return true; }); @@ -168,6 +170,22 @@ test('agent-browser provider keeps typed text out of argv and error details when }); }); +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; + }); + }); + }); +}); + test('agent-browser provider runs provider-startup cleanup before the first managed command', async () => { const events: string[] = []; mockProviderStartupCleanup.mockImplementation(async () => { diff --git a/packages/platform-web/src/agent-browser-provider.ts b/packages/platform-web/src/agent-browser-provider.ts index 863e349b89..c43313b65a 100644 --- a/packages/platform-web/src/agent-browser-provider.ts +++ b/packages/platform-web/src/agent-browser-provider.ts @@ -208,7 +208,7 @@ async function sendTextEntry(send: AgentBrowserRunJson, command: readonly string const data = await send(['batch'], { stdin: JSON.stringify([command]) }); const entry: unknown = Array.isArray(data) && data.length === 1 ? data[0] : undefined; const commandName = command[0] ?? 'batch'; - if (!isBatchEntry(entry)) { + if (!isBatchEntry(entry) || !sameBatchCommand(entry.command, command)) { throw new AppError( 'COMMAND_FAILED', `agent-browser returned an unusable ${commandName} result`, @@ -222,9 +222,11 @@ async function sendTextEntry(send: AgentBrowserRunJson, command: readonly string ); } 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', - typeof entry.error === 'string' ? entry.error : `agent-browser ${commandName} failed`, + `agent-browser ${command.slice(0, commandName === 'keyboard' ? 2 : 1).join(' ')} failed${target}`, { cmd: AGENT_BROWSER, args: ['batch'], 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 4f0824e3be..dfefb64486 100644 --- a/packages/provider-webdriver/src/aws-device-farm-provider.test.ts +++ b/packages/provider-webdriver/src/aws-device-farm-provider.test.ts @@ -69,7 +69,8 @@ test('artifact lookup runs in the region of the session ARN, not the environment providerSessionId: 'arn:aws:devicefarm:us-west-2:123:session:project-a/session-a/00000', }); - assert.ok(commands.length > 0); + // 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(' ')); } 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 e2c666c319..d1cbaec8cf 100644 --- a/packages/provider-webdriver/src/webdriver-interactor-hardware-button.test.ts +++ b/packages/provider-webdriver/src/webdriver-interactor-hardware-button.test.ts @@ -90,7 +90,11 @@ test('iOS home rides mobile pressButton and the app switcher refuses before the }); await ios.home!(); await assert.rejects(ios.appSwitcher!(), (error: unknown) => { - return error instanceof AppError && error.code === 'UNSUPPORTED_OPERATION'; + return ( + error instanceof AppError && + error.code === 'UNSUPPORTED_OPERATION' && + error.details?.operation === 'appSwitcher' + ); }); assert.deepEqual(transcript, ['mobile: pressButton [{"name":"home"}]']); }); diff --git a/packages/provider-webdriver/src/webdriver-transport.test.ts b/packages/provider-webdriver/src/webdriver-transport.test.ts index 264b305ff3..1729a8d305 100644 --- a/packages/provider-webdriver/src/webdriver-transport.test.ts +++ b/packages/provider-webdriver/src/webdriver-transport.test.ts @@ -342,6 +342,7 @@ test('a 2xx with a non-JSON body names its status', async () => { 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; }); }); diff --git a/packages/provider-webdriver/src/webdriver-transport.ts b/packages/provider-webdriver/src/webdriver-transport.ts index d502baffc0..b0e0596232 100644 --- a/packages/provider-webdriver/src/webdriver-transport.ts +++ b/packages/provider-webdriver/src/webdriver-transport.ts @@ -214,7 +214,8 @@ export class WebDriverTransport { return { status, value: readWebDriverValue(text ? parseJsonResponse(text, status) : {}) }; // A gateway in front of the driver can answer an error with a non-JSON page (a `502 `). // Its status still decides retry and dispatch disclosure, so the raw body is only evidence. - const payload = text ? (parseJsonOrUndefined(text) ?? truncateBody(text)) : {}; + const parsed = text ? parseJsonBody(text) : { json: {} }; + const payload = parsed === undefined ? truncateBody(text) : parsed.json; const error = webdriverError(status, payload); if (isWebDriverRouteUnsupported(error)) { emitWebDriverDiagnostic(WEBDRIVER_ROUTE_UNSUPPORTED_REASON, { @@ -335,15 +336,17 @@ function parseJsonResponse(text: string, status: number): unknown { throw new AppError( 'COMMAND_FAILED', 'WebDriver response was not valid JSON.', - { status, text: truncateBody(text) }, + // A 2xx means the driver ran the request; only its answer is unreadable. + { status, text: truncateBody(text), ...dispatchDisclosure('unknown') }, error, ); } } -function parseJsonOrUndefined(text: string): unknown { +/** 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.parse(text) as unknown; + return { json: JSON.parse(text) as unknown }; } catch { return undefined; } diff --git a/packages/provider-webdriver/src/webdriver-utils.test.ts b/packages/provider-webdriver/src/webdriver-utils.test.ts index eeadb0d644..d2b62f826f 100644 --- a/packages/provider-webdriver/src/webdriver-utils.test.ts +++ b/packages/provider-webdriver/src/webdriver-utils.test.ts @@ -104,6 +104,31 @@ test('the hub upload helper types a rejected credential and keeps a transport fa }); }); +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) => { diff --git a/packages/tv-cdp/src/cdp.test.ts b/packages/tv-cdp/src/cdp.test.ts index a9fdb58574..dbb52b6756 100644 --- a/packages/tv-cdp/src/cdp.test.ts +++ b/packages/tv-cdp/src/cdp.test.ts @@ -70,7 +70,13 @@ async function pageSending(beforeAnswer: readonly string[]): Promise { // 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', '{"method":"Log.entryAdded","params":7}']); + 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/', @@ -79,7 +85,8 @@ test('an unreadable frame or a failing event listener leaves the pending request cleanups.push(() => session.close()); const events: string[] = []; session.on(() => { - throw new Error('listener failed'); + // `String()` throws for a value without a primitive conversion. + throw Object.create(null); }); session.on((method, params) => events.push(`${method} ${JSON.stringify(params)}`)); diff --git a/packages/tv-cdp/src/cdp.ts b/packages/tv-cdp/src/cdp.ts index f5b2ec895f..e9dbf08335 100644 --- a/packages/tv-cdp/src/cdp.ts +++ b/packages/tv-cdp/src/cdp.ts @@ -23,7 +23,7 @@ export type CdpSession = Readonly<{ type CdpMessage = { id?: number; - method?: string; + method?: unknown; params?: Record; result?: unknown; error?: { message: string; code: number }; @@ -38,6 +38,12 @@ function parseCdpMessage(data: unknown): CdpMessage | 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); } @@ -89,7 +95,10 @@ export async function connectCdp(target: CdpTarget): Promise { }); return; } - if (typeof message.method === 'string') { + 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 { @@ -98,7 +107,7 @@ export async function connectCdp(target: CdpTarget): Promise { emitDiagnostic({ level: 'debug', phase: 'tv_cdp_event_listener_failed', - data: { method: message.method, error: String(error) }, + data: { method: message.method, error: describeThrown(error) }, }); } } diff --git a/packages/tv-cdp/src/page-log.test.ts b/packages/tv-cdp/src/page-log.test.ts index 30050a08bd..7911e9809e 100644 --- a/packages/tv-cdp/src/page-log.test.ts +++ b/packages/tv-cdp/src/page-log.test.ts @@ -86,9 +86,18 @@ test('events missing their payload fields do not throw', () => { 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\n2026-10-30T12:00:00.000Z console.log \n', + [ + '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 210de706da..21b27f83fe 100644 --- a/packages/tv-cdp/src/page-log.ts +++ b/packages/tv-cdp/src/page-log.ts @@ -52,7 +52,12 @@ export function createPageLog(now = () => new Date()): PageLog { const handlers: Readonly) => void>> = { 'Runtime.consoleAPICalled': (params) => { - const args = Array.isArray(params.args) ? (params.args as RemoteObject[]) : []; + 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) => { From cfed7a313ade87e578afbeac4545bee099472a3b Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 17:15:58 +0000 Subject: [PATCH 13/23] fix(platform-web): drop backend output from text-entry failures A failed text-entry batch call could still quote the typed text through the generic error paths: stdout and stderr from a non-JSON answer or a non-zero exit, and the envelope's error text. Text-entry failures now keep only an allowlist of details (cmd, args, exitCode, dispatched, reason, timeoutMs, hint), a generic message, and no cause chain. A caller cancellation passes through unchanged. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016qAu53rMak1bXMuR5U2gF4 --- .../src/agent-browser-provider.test.ts | 33 +++++++++ .../src/agent-browser-provider.ts | 73 +++++++++++++------ 2 files changed, 82 insertions(+), 24 deletions(-) diff --git a/packages/platform-web/src/agent-browser-provider.test.ts b/packages/platform-web/src/agent-browser-provider.test.ts index 88db0ec8b7..e33b3380ad 100644 --- a/packages/platform-web/src/agent-browser-provider.test.ts +++ b/packages/platform-web/src/agent-browser-provider.test.ts @@ -170,6 +170,39 @@ test('agent-browser provider keeps typed text out of argv and error details when }); }); +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 refuses a text entry answer that echoes another command', async () => { await withManagedAgentBrowserProvider({ session: 'web-session' }, async (provider) => { const executor = async (): Promise => diff --git a/packages/platform-web/src/agent-browser-provider.ts b/packages/platform-web/src/agent-browser-provider.ts index c43313b65a..89fff1a72f 100644 --- a/packages/platform-web/src/agent-browser-provider.ts +++ b/packages/platform-web/src/agent-browser-provider.ts @@ -205,36 +205,61 @@ function createAgentBrowserSendLedger(runJson: AgentBrowserRunJson): { * verdict decides the outcome. */ async function sendTextEntry(send: AgentBrowserRunJson, command: readonly string[]): Promise { - const data = await send(['batch'], { stdin: JSON.stringify([command]) }); - const entry: unknown = Array.isArray(data) && data.length === 1 ? data[0] : undefined; const commandName = command[0] ?? 'batch'; - if (!isBatchEntry(entry) || !sameBatchCommand(entry.command, command)) { - throw new AppError( - 'COMMAND_FAILED', - `agent-browser returned an unusable ${commandName} result`, - { - cmd: AGENT_BROWSER, - args: ['batch'], - command: commandName, - reason: 'text-entry-result-unusable', - hint: AGENT_BROWSER_DOCTOR_HINT, - }, - ); + const label = `agent-browser ${command.slice(0, commandName === 'keyboard' ? 2 : 1).join(' ')}`; + let data: unknown; + try { + data = await send(['batch'], { stdin: JSON.stringify([command]) }); + } catch (error) { + throw textEntryFailure(error, label, commandName); } - 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', - `agent-browser ${command.slice(0, commandName === 'keyboard' ? 2 : 1).join(' ')} failed${target}`, - { + 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-failed', + 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', + hint: AGENT_BROWSER_DOCTOR_HINT, + }); +} + +/** + * The details a text-entry failure may carry. Backend output (`stdout`, `stderr`, the envelope's + * error and message) and the cause chain are dropped: any of them can quote the typed text. + */ +const TEXT_ENTRY_FAILURE_DETAIL_KEYS = [ + 'cmd', + 'args', + 'exitCode', + 'dispatched', + 'reason', + 'timeoutMs', + 'hint', +] as const; + +/** + * Rebuilds a failed text-entry backend call without anything the backend printed. A caller's + * cancellation is not an `AppError` and passes through unchanged. + */ +function textEntryFailure(error: unknown, label: string, commandName: string): unknown { + if (!(error instanceof AppError)) return error; + const details: Record = { command: commandName }; + for (const key of TEXT_ENTRY_FAILURE_DETAIL_KEYS) { + if (error.details?.[key] !== undefined) details[key] = error.details[key]; + } + return new AppError(error.code, `${label} failed`, details); } type ScrollStep = { From 699781862f915c4f5ac3bdd31a2fcab84b6c0c88 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 17:18:42 +0000 Subject: [PATCH 14/23] fix(tv-cdp): load the diagnostics emitter only on the error path The listener guard imported host-kit diagnostics eagerly, which grew the tv-cdp eager import closure from 6 to 8 modules and failed the eager closure budget. The emitter now loads with a function-scoped import when an unreadable frame or a failing listener is reported. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016qAu53rMak1bXMuR5U2gF4 --- packages/tv-cdp/src/cdp.ts | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/packages/tv-cdp/src/cdp.ts b/packages/tv-cdp/src/cdp.ts index e9dbf08335..b0dbf22c3a 100644 --- a/packages/tv-cdp/src/cdp.ts +++ b/packages/tv-cdp/src/cdp.ts @@ -1,4 +1,3 @@ -import { emitDiagnostic } from '@agent-device/host-kit/diagnostics'; import { AppError } from '@agent-device/kernel/errors'; import { createReplyWaiters } from './replies.ts'; @@ -38,6 +37,16 @@ function parseCdpMessage(data: unknown): CdpMessage | 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; @@ -88,11 +97,7 @@ export async function connectCdp(target: CdpTarget): Promise { socket.onmessage = (event) => { const message = parseCdpMessage(event.data); if (message === undefined) { - emitDiagnostic({ - level: 'debug', - phase: 'tv_cdp_frame_unreadable', - data: { target: target.url }, - }); + emitCdpDiagnostic('tv_cdp_frame_unreadable', { target: target.url }); return; } if (message.method !== undefined) { @@ -104,10 +109,9 @@ export async function connectCdp(target: CdpTarget): Promise { try { listener(message.method, params); } catch (error) { - emitDiagnostic({ - level: 'debug', - phase: 'tv_cdp_event_listener_failed', - data: { method: message.method, error: describeThrown(error) }, + emitCdpDiagnostic('tv_cdp_event_listener_failed', { + method: message.method, + error: describeThrown(error), }); } } From 51da70727e324a3f6feb86efc14a2401477c588c Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 17:49:45 +0000 Subject: [PATCH 15/23] fix(platform-web): scrub only executed backend output from text-entry failures The previous scrub rebuilt every text-entry failure with a generic message, which replaced setup guidance for a missing backend and the message of a canceled request. Redaction now happens where the output enters the error: a failure read from the executed batch's answer gets a generic message and loses stdout, stderr, the envelope error, and its cause; a run failure keeps its code and message and loses only the captured output; a failure from before the command ran passes through unchanged. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016qAu53rMak1bXMuR5U2gF4 --- .../src/agent-browser-provider.test.ts | 54 ++++++++- .../src/agent-browser-provider.ts | 111 +++++++++++------- 2 files changed, 122 insertions(+), 43 deletions(-) diff --git a/packages/platform-web/src/agent-browser-provider.test.ts b/packages/platform-web/src/agent-browser-provider.test.ts index e33b3380ad..d0788ef0b2 100644 --- a/packages/platform-web/src/agent-browser-provider.test.ts +++ b/packages/platform-web/src/agent-browser-provider.test.ts @@ -26,7 +26,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'; @@ -203,6 +203,58 @@ test('agent-browser provider keeps typed text out of every backend failure shape }); }); +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 => diff --git a/packages/platform-web/src/agent-browser-provider.ts b/packages/platform-web/src/agent-browser-provider.ts index 89fff1a72f..a9dea00088 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 { @@ -207,12 +212,10 @@ function createAgentBrowserSendLedger(runJson: AgentBrowserRunJson): { async function sendTextEntry(send: AgentBrowserRunJson, command: readonly string[]): Promise { const commandName = command[0] ?? 'batch'; const label = `agent-browser ${command.slice(0, commandName === 'keyboard' ? 2 : 1).join(' ')}`; - let data: unknown; - try { - data = await send(['batch'], { stdin: JSON.stringify([command]) }); - } catch (error) { - throw textEntryFailure(error, label, commandName); - } + 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`, { @@ -235,33 +238,6 @@ async function sendTextEntry(send: AgentBrowserRunJson, command: readonly string }); } -/** - * The details a text-entry failure may carry. Backend output (`stdout`, `stderr`, the envelope's - * error and message) and the cause chain are dropped: any of them can quote the typed text. - */ -const TEXT_ENTRY_FAILURE_DETAIL_KEYS = [ - 'cmd', - 'args', - 'exitCode', - 'dispatched', - 'reason', - 'timeoutMs', - 'hint', -] as const; - -/** - * Rebuilds a failed text-entry backend call without anything the backend printed. A caller's - * cancellation is not an `AppError` and passes through unchanged. - */ -function textEntryFailure(error: unknown, label: string, commandName: string): unknown { - if (!(error instanceof AppError)) return error; - const details: Record = { command: commandName }; - for (const key of TEXT_ENTRY_FAILURE_DETAIL_KEYS) { - if (error.details?.[key] !== undefined) details[key] = error.details[key]; - } - return new AppError(error.code, `${label} failed`, details); -} - type ScrollStep = { distance?: number; delayAfterMs: number; @@ -551,19 +527,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, From 5e8b88d32cbee980ec0d602f1830866435884739 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 18:10:13 +0000 Subject: [PATCH 16/23] fix(platform-linux): report app launch exits and inject the detached launcher The detached `open ` launch reported only a spawn failure and called the detached runner directly, past the provider's injectable executors. A launch that exits non-zero or is killed by a signal now emits the linux_app_launch diagnostic from the typed exit fields, and the launcher is a `launchDetached` provider seam beside `runCommand` with the detached runner as its default, so the app still never runs as a captured child. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016qAu53rMak1bXMuR5U2gF4 --- .../src/__tests__/tool-provider.test.ts | 59 +++++++++++++++++-- packages/platform-linux/src/tool-provider.ts | 32 ++++++++-- 2 files changed, 82 insertions(+), 9 deletions(-) diff --git a/packages/platform-linux/src/__tests__/tool-provider.test.ts b/packages/platform-linux/src/__tests__/tool-provider.test.ts index 638fe62916..1833cbc5a6 100644 --- a/packages/platform-linux/src/__tests__/tool-provider.test.ts +++ b/packages/platform-linux/src/__tests__/tool-provider.test.ts @@ -2,6 +2,10 @@ 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'; @@ -165,9 +169,9 @@ 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. +// byte the app printed in daemon memory for the app's whole life. The default launcher detaches. test.skipIf(!fs.existsSync('/proc/self/fd'))( - 'local Linux desktop provider launches an app binary detached from daemon pipes', + 'local Linux desktop provider launches an app binary detached from daemon pipes by default', async () => { const binDir = await mkdtempForTest('linux-open-binary-'); const report = path.join(binDir, 'stdout-target'); @@ -182,9 +186,6 @@ test.skipIf(!fs.existsSync('/proc/self/fd'))( const provider = createLocalLinuxToolProvider({ host: { env: process.env, cwd: process.cwd() }, whichCommand: async (cmd) => cmd === 'fake-desktop-app', - runCommand: async (cmd) => { - throw new Error(`the app launch must not run as a captured command: ${cmd}`); - }, }); await provider.desktop.openTarget('fake-desktop-app'); @@ -197,6 +198,54 @@ test.skipIf(!fs.existsSync('/proc/self/fd'))( }, ); +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, []); +}); + +test('local Linux desktop provider reports a launch that fails, exits non-zero, or is signalled', async () => { + const exits = [ + { pid: 1, error: 'spawn demo-app ENOENT' }, + { pid: 2, exitCode: 3 }, + { pid: 3, signal: 'SIGKILL' as const }, + { pid: 4, exitCode: 0 }, + ]; + const settled: Promise[] = []; + const provider = createLocalLinuxToolProvider({ + host: { env: process.env, cwd: process.cwd() }, + whichCommand: async () => true, + launchDetached: () => { + const exited = Promise.resolve(exits[settled.length]!); + settled.push(exited); + return { exited }; + }, + }); + + await withDiagnosticsScope({ command: 'open' }, async () => { + for (const _exit of exits) await provider.desktop.openTarget('demo-app'); + await Promise.all(settled); + // The three failures each report once; a clean exit reports nothing. + assert.equal(countDiagnosticEventsByPhase(['linux_app_launch']), 3); + }); +}); + test('local Linux desktop provider falls back to pkill when wmctrl is unavailable', async () => { const commands: Array<[string, string[], boolean | undefined]> = []; const provider = createLocalLinuxToolProvider({ diff --git a/packages/platform-linux/src/tool-provider.ts b/packages/platform-linux/src/tool-provider.ts index 76f42999e6..f5c8fb5e59 100644 --- a/packages/platform-linux/src/tool-provider.ts +++ b/packages/platform-linux/src/tool-provider.ts @@ -5,6 +5,7 @@ import { runCmd, runCmdDetachedMonitored, whichCmd, + type ExecDetachedExit, type ExecOptions, type ExecResult, commandHostEnvironment, @@ -34,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; @@ -81,6 +91,7 @@ export type LinuxToolProvider = { display: LinuxDisplayConfig; runCommand: LinuxToolCommandExecutor; whichCommand: LinuxToolAvailabilityChecker; + launchDetached: LinuxToolDetachedLauncher; desktop: LinuxDesktopProvider; clipboard?: LinuxClipboardProvider; screenshot?: LinuxScreenshotProvider; @@ -98,12 +109,15 @@ type LinuxToolProviderParts = { display: LinuxDisplayConfig } & Partial | 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) { @@ -183,12 +206,13 @@ function createLocalLinuxDesktopProvider( if (await whichCommand(target)) { // 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 runCmdDetachedMonitored(target, []).exited.then((exit) => { - if (exit.error === undefined) return; + 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: exit.error }, + data: { app: target, ...failure }, }); }); await sleep(500); From aa7de0d12721e9d609fb401c363774a71fa6ff9d Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 18:23:32 +0000 Subject: [PATCH 17/23] test(platform-linux): assert each launch exit outcome reports its own diagnostic The launch-report test counted three events across four exits, which a path reporting twice could mask. Each exit now runs in its own diagnostics scope, and the test checks the written event: a start error, exit code 3, and SIGKILL each emit exactly one event carrying that field, and a clean exit emits none. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016qAu53rMak1bXMuR5U2gF4 --- .../src/__tests__/tool-provider.test.ts | 52 +++++++++++++------ 1 file changed, 36 insertions(+), 16 deletions(-) diff --git a/packages/platform-linux/src/__tests__/tool-provider.test.ts b/packages/platform-linux/src/__tests__/tool-provider.test.ts index 1833cbc5a6..f3cc10a784 100644 --- a/packages/platform-linux/src/__tests__/tool-provider.test.ts +++ b/packages/platform-linux/src/__tests__/tool-provider.test.ts @@ -9,6 +9,7 @@ import { import assert from 'node:assert/strict'; import { pressLinux } from '../input-actions.ts'; import { createLocalLinuxToolProvider, withLinuxToolProvider } from '../tool-provider.ts'; +import type { ExecDetachedExit } from '@agent-device/host-kit/command'; bindTestCommandHost(); @@ -220,30 +221,49 @@ test('local Linux desktop provider launches an app binary through its detached l assert.deepEqual(captured, []); }); -test('local Linux desktop provider reports a launch that fails, exits non-zero, or is signalled', async () => { - const exits = [ - { pid: 1, error: 'spawn demo-app ENOENT' }, - { pid: 2, exitCode: 3 }, - { pid: 3, signal: 'SIGKILL' as const }, - { pid: 4, exitCode: 0 }, - ]; - const settled: Promise[] = []; +/** 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: () => { - const exited = Promise.resolve(exits[settled.length]!); - settled.push(exited); + exited = Promise.resolve(exit); return { exited }; }, }); - - await withDiagnosticsScope({ command: 'open' }, async () => { - for (const _exit of exits) await provider.desktop.openTarget('demo-app'); - await Promise.all(settled); - // The three failures each report once; a clean exit reports nothing. - assert.equal(countDiagnosticEventsByPhase(['linux_app_launch']), 3); + 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 }), []); }); test('local Linux desktop provider falls back to pkill when wmctrl is unavailable', async () => { From beb299d639b05e7ba84dd13fb9f8e91f40f2cdec Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 18:34:25 +0000 Subject: [PATCH 18/23] fix(provider-webdriver): never read a non-JSON error page as an unsupported route Since the non-JSON error body became truncated evidence, a gateway's HTML 404, 405, or 501 page matched the bare-status unsupported-route rule, so app activation, termination, and orientation fell back to a sibling mutation that could repeat an action that already ran. A non-JSON error answer is now built from its status alone with dispatched unknown and never carries the route-unsupported reason. A JSON answer keeps the existing W3C-code-or-bare-status rule. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016qAu53rMak1bXMuR5U2gF4 --- .../src/webdriver-client.test.ts | 26 +++++++++++++++++++ .../src/webdriver-transport.test.ts | 25 ++++++++++++++++++ .../src/webdriver-transport.ts | 19 +++++++++++--- 3 files changed, 67 insertions(+), 3 deletions(-) diff --git a/packages/provider-webdriver/src/webdriver-client.test.ts b/packages/provider-webdriver/src/webdriver-client.test.ts index c10fed4d10..301f8c0a65 100644 --- a/packages/provider-webdriver/src/webdriver-client.test.ts +++ b/packages/provider-webdriver/src/webdriver-client.test.ts @@ -132,6 +132,32 @@ test('source aborts an in-flight provider request when its binding is cancelled' // #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. +// 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']); + } +}); + test('createSession does not retry a transient create failure', async () => { let calls = 0; globalThis.fetch = async () => { diff --git a/packages/provider-webdriver/src/webdriver-transport.test.ts b/packages/provider-webdriver/src/webdriver-transport.test.ts index 1729a8d305..61bb44bf4c 100644 --- a/packages/provider-webdriver/src/webdriver-transport.test.ts +++ b/packages/provider-webdriver/src/webdriver-transport.test.ts @@ -330,6 +330,31 @@ test('a 5xx with a non-JSON body keeps its status, dispatch disclosure, and idem 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', diff --git a/packages/provider-webdriver/src/webdriver-transport.ts b/packages/provider-webdriver/src/webdriver-transport.ts index b0e0596232..404bc9df14 100644 --- a/packages/provider-webdriver/src/webdriver-transport.ts +++ b/packages/provider-webdriver/src/webdriver-transport.ts @@ -212,10 +212,9 @@ export class WebDriverTransport { ); if (ok) return { status, value: readWebDriverValue(text ? parseJsonResponse(text, status) : {}) }; - // A gateway in front of the driver can answer an error with a non-JSON page (a `502 `). - // Its status still decides retry and dispatch disclosure, so the raw body is only evidence. const parsed = text ? parseJsonBody(text) : { json: {} }; - const payload = parsed === undefined ? truncateBody(text) : parsed.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, { @@ -385,6 +384,20 @@ 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'; From df1edbb4a53c84ad8c49d5e3ab77fc1e8ae6e1ce Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 19:10:11 +0000 Subject: [PATCH 19/23] fix(platform-linux): launch through an injected executor unless a launcher is given A caller that injected runCommand but no launchDetached got the host-local detached runner, which silently bypassed its executor. The detached runner is now the default only beside the default runCmd; otherwise launches go through the injected executor. Also: the upload deadline comment now says it is a total deadline, the activation test no longer splits the #1774 comment from its test, and the unread `error` field on AgentBrowserBatchEntry is gone. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016qAu53rMak1bXMuR5U2gF4 --- .../src/__tests__/tool-provider.test.ts | 16 ++++++++++++++ packages/platform-linux/src/tool-provider.ts | 21 ++++++++++++++++++- .../src/agent-browser-provider.ts | 1 - .../src/webdriver-client.test.ts | 6 +++--- .../provider-webdriver/src/webdriver-utils.ts | 5 +++-- 5 files changed, 42 insertions(+), 7 deletions(-) diff --git a/packages/platform-linux/src/__tests__/tool-provider.test.ts b/packages/platform-linux/src/__tests__/tool-provider.test.ts index f3cc10a784..3799a644bd 100644 --- a/packages/platform-linux/src/__tests__/tool-provider.test.ts +++ b/packages/platform-linux/src/__tests__/tool-provider.test.ts @@ -266,6 +266,22 @@ test('local Linux desktop provider reports nothing for a launched app that exits assert.deepEqual(await launchDiagnostics({ pid: 4, exitCode: 0 }), []); }); +test('local Linux desktop provider launches through an injected executor when it injects no launcher', async () => { + const commands: Array<[string, string[], boolean | undefined]> = []; + const provider = createLocalLinuxToolProvider({ + host: { env: process.env, cwd: process.cwd() }, + whichCommand: async (cmd) => cmd === 'demo-app', + runCommand: async (cmd, args, options) => { + commands.push([cmd, args, options?.allowFailure]); + return { exitCode: 0, stdout: '', stderr: '' }; + }, + }); + + await provider.desktop.openTarget('demo-app'); + + assert.deepEqual(commands, [['demo-app', [], true]]); +}); + test('local Linux desktop provider falls back to pkill when wmctrl is unavailable', async () => { const commands: Array<[string, string[], boolean | undefined]> = []; const provider = createLocalLinuxToolProvider({ diff --git a/packages/platform-linux/src/tool-provider.ts b/packages/platform-linux/src/tool-provider.ts index f5c8fb5e59..562074b319 100644 --- a/packages/platform-linux/src/tool-provider.ts +++ b/packages/platform-linux/src/tool-provider.ts @@ -109,7 +109,13 @@ type LinuxToolProviderParts = { display: LinuxDisplayConfig } & Partial ({ + exited: runCommand(cmd, args, { allowFailure: true }).then( + (result): ExecDetachedExit => ({ pid: 0, exitCode: result.exitCode }), + (error: unknown): ExecDetachedExit => ({ + pid: 0, + error: error instanceof Error ? error.message : String(error), + }), + ), + }); +} + /** 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 }; diff --git a/packages/platform-web/src/agent-browser-provider.ts b/packages/platform-web/src/agent-browser-provider.ts index a9dea00088..42b76c9727 100644 --- a/packages/platform-web/src/agent-browser-provider.ts +++ b/packages/platform-web/src/agent-browser-provider.ts @@ -457,7 +457,6 @@ type AgentBrowserBatchEntry = { command?: unknown; success?: unknown; result?: unknown; - error?: unknown; }; /** diff --git a/packages/provider-webdriver/src/webdriver-client.test.ts b/packages/provider-webdriver/src/webdriver-client.test.ts index 301f8c0a65..e71da72c35 100644 --- a/packages/provider-webdriver/src/webdriver-client.test.ts +++ b/packages/provider-webdriver/src/webdriver-client.test.ts @@ -129,9 +129,6 @@ test('source aborts an in-flight provider request when its binding is cancelled' assert.equal(requestSignal?.aborted, true); }); -// #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. // 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 [ @@ -158,6 +155,9 @@ test('app activation falls back on a W3C unknown command but not on a gateway 40 } }); +// #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. test('createSession does not retry a transient create failure', async () => { let calls = 0; globalThis.fetch = async () => { diff --git a/packages/provider-webdriver/src/webdriver-utils.ts b/packages/provider-webdriver/src/webdriver-utils.ts index fee3540f3e..631e85bd1a 100644 --- a/packages/provider-webdriver/src/webdriver-utils.ts +++ b/packages/provider-webdriver/src/webdriver-utils.ts @@ -93,8 +93,9 @@ export async function appFileUploadForm( } /** - * The longest one app upload may run. Builds of a few hundred MB on a slow uplink take minutes, so - * this bounds a stalled transfer, not a slow one. + * 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; From 0f6aa69295d99e19b48476972e2c481af16b66c4 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 19:14:14 +0000 Subject: [PATCH 20/23] fix(platform-web): point a refused text entry at a fresh snapshot, not setup A live stale-ref fill showed text-entry-failed carrying the "run web setup" hint, but the backend ran and refused the entry. The hint now tells the caller to take a new snapshot and retry with its ref. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016qAu53rMak1bXMuR5U2gF4 --- packages/platform-web/src/agent-browser-provider.test.ts | 1 + packages/platform-web/src/agent-browser-provider.ts | 3 ++- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/packages/platform-web/src/agent-browser-provider.test.ts b/packages/platform-web/src/agent-browser-provider.test.ts index d0788ef0b2..78387c1059 100644 --- a/packages/platform-web/src/agent-browser-provider.test.ts +++ b/packages/platform-web/src/agent-browser-provider.test.ts @@ -160,6 +160,7 @@ test('agent-browser provider keeps typed text out of argv and error details when assert.equal(error.code, 'COMMAND_FAILED'); assert.match(error.message, /^agent-browser (fill|keyboard type) failed/); assert.equal(error.details?.reason, 'text-entry-failed'); + assert.match(String(error.details?.hint), /snapshot -i/); assert.equal(error.message.includes(secret), false); assert.equal(JSON.stringify(error.details).includes(secret), false); return true; diff --git a/packages/platform-web/src/agent-browser-provider.ts b/packages/platform-web/src/agent-browser-provider.ts index 42b76c9727..a467b25041 100644 --- a/packages/platform-web/src/agent-browser-provider.ts +++ b/packages/platform-web/src/agent-browser-provider.ts @@ -234,7 +234,8 @@ async function sendTextEntry(send: AgentBrowserRunJson, command: readonly string args: ['batch'], command: commandName, reason: 'text-entry-failed', - hint: AGENT_BROWSER_DOCTOR_HINT, + // The backend ran and refused this entry, so its install is not the suspect. + hint: 'The page refused this text entry: the target may have changed or gone. Run snapshot -i again and retry with the ref it reports.', }); } From 7047de8e1d2a55437269b861e1a5af098a359e8a Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 20:14:05 +0000 Subject: [PATCH 21/23] fix(platform-linux): keep the detached app launch on the ambient provider The ambient Linux tool provider named `runCommand: runCmd` explicitly, so after the injected-executor rule it launched apps through the captured runCmd instead of the detached runner. It now names no executor and takes the host-local defaults. A real-process test pins the ambient provider: the launched app's stderr is /dev/null, where it was a socket before. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016qAu53rMak1bXMuR5U2gF4 --- .../src/__tests__/tool-provider.test.ts | 32 ++++++++++++------- packages/platform-linux/src/tool-provider.ts | 3 +- 2 files changed, 22 insertions(+), 13 deletions(-) diff --git a/packages/platform-linux/src/__tests__/tool-provider.test.ts b/packages/platform-linux/src/__tests__/tool-provider.test.ts index 3799a644bd..cd61e3ea1c 100644 --- a/packages/platform-linux/src/__tests__/tool-provider.test.ts +++ b/packages/platform-linux/src/__tests__/tool-provider.test.ts @@ -8,7 +8,11 @@ import { } 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, +} from '../tool-provider.ts'; import type { ExecDetachedExit } from '@agent-device/host-kit/command'; bindTestCommandHost(); @@ -170,10 +174,21 @@ 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. -test.skipIf(!fs.existsSync('/proc/self/fd'))( - 'local Linux desktop provider launches an app binary detached from daemon pipes by default', - async () => { +// 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( @@ -184,12 +199,7 @@ test.skipIf(!fs.existsSync('/proc/self/fd'))( const originalPath = process.env['PATH']; process.env['PATH'] = `${binDir}${path.delimiter}${originalPath ?? ''}`; try { - const provider = createLocalLinuxToolProvider({ - host: { env: process.env, cwd: process.cwd() }, - whichCommand: async (cmd) => cmd === 'fake-desktop-app', - }); - - await provider.desktop.openTarget('fake-desktop-app'); + await makeProvider().desktop.openTarget('fake-desktop-app'); await vi.waitFor(() => assert.ok(fs.existsSync(report))); assert.equal(fs.readFileSync(report, 'utf8').trim(), '/dev/null'); diff --git a/packages/platform-linux/src/tool-provider.ts b/packages/platform-linux/src/tool-provider.ts index 562074b319..31b9faef9e 100644 --- a/packages/platform-linux/src/tool-provider.ts +++ b/packages/platform-linux/src/tool-provider.ts @@ -153,9 +153,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), }, From 373b157c24b9ba1572c6d6eecbb9e559ebc3f583 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 20:54:59 +0000 Subject: [PATCH 22/23] refactor(platform-linux): require a launcher beside an injected executor LinuxToolProviderOverrides is now a union: a caller that injects runCommand must also inject launchDetached, so the host-local detached runner never stands in beside an injected executor. The presence-keyed default and launchThroughExecutor are gone; fixtures that inject runCommand pass a launcher, and a compile-time pin keeps the refusal. The ambient-provider detachment test stays. A refused web text entry now hints per command: fill retries with a fresh snapshot ref, and type (which takes no ref) focuses the field again and retries. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016qAu53rMak1bXMuR5U2gF4 --- .../src/__tests__/tool-provider.test.ts | 42 +++++++++++++------ packages/platform-linux/src/tool-provider.ts | 38 +++++++---------- .../src/agent-browser-provider.test.ts | 7 +++- .../src/agent-browser-provider.ts | 5 ++- .../provider-scenarios/linux-world.ts | 4 ++ 5 files changed, 59 insertions(+), 37 deletions(-) diff --git a/packages/platform-linux/src/__tests__/tool-provider.test.ts b/packages/platform-linux/src/__tests__/tool-provider.test.ts index cd61e3ea1c..200f6f51c2 100644 --- a/packages/platform-linux/src/__tests__/tool-provider.test.ts +++ b/packages/platform-linux/src/__tests__/tool-provider.test.ts @@ -12,11 +12,19 @@ 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 }; @@ -29,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) => { @@ -52,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) => { @@ -75,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}`); @@ -104,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(), @@ -112,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(), @@ -154,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) => { @@ -276,25 +290,26 @@ test('local Linux desktop provider reports nothing for a launched app that exits assert.deepEqual(await launchDiagnostics({ pid: 4, exitCode: 0 }), []); }); -test('local Linux desktop provider launches through an injected executor when it injects no launcher', async () => { - const commands: Array<[string, string[], boolean | undefined]> = []; - const provider = createLocalLinuxToolProvider({ - host: { env: process.env, cwd: process.cwd() }, - whichCommand: async (cmd) => cmd === 'demo-app', - runCommand: async (cmd, args, options) => { - commands.push([cmd, args, options?.allowFailure]); - return { exitCode: 0, stdout: '', stderr: '' }; - }, +// 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: '', }); - - await provider.desktop.openTarget('demo-app'); - - assert.deepEqual(commands, [['demo-app', [], true]]); + // @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) => { @@ -311,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 31b9faef9e..423fb2c5f6 100644 --- a/packages/platform-linux/src/tool-provider.ts +++ b/packages/platform-linux/src/tool-provider.ts @@ -103,19 +103,26 @@ 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; - // A caller that injected its own executor also owns app launches: the host-local detached - // runner is the default only beside the host-local `runCmd`. - const launchDetached = - provider.launchDetached ?? - (provider.runCommand === undefined - ? runCmdDetachedMonitored - : launchThroughExecutor(provider.runCommand)); + const launchDetached = provider.launchDetached ?? runCmdDetachedMonitored; const display = provider.display; return { runCommand, @@ -138,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({ @@ -188,19 +195,6 @@ export async function runLinuxToolCommand( return await resolveLinuxToolProvider().runCommand(cmd, args, options); } -/** A launcher over an injected executor, settling `exited` from the command's own result. */ -function launchThroughExecutor(runCommand: LinuxToolCommandExecutor): LinuxToolDetachedLauncher { - return (cmd, args) => ({ - exited: runCommand(cmd, args, { allowFailure: true }).then( - (result): ExecDetachedExit => ({ pid: 0, exitCode: result.exitCode }), - (error: unknown): ExecDetachedExit => ({ - pid: 0, - error: error instanceof Error ? error.message : String(error), - }), - ), - }); -} - /** 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 }; diff --git a/packages/platform-web/src/agent-browser-provider.test.ts b/packages/platform-web/src/agent-browser-provider.test.ts index 7f7515242c..576c710c3a 100644 --- a/packages/platform-web/src/agent-browser-provider.test.ts +++ b/packages/platform-web/src/agent-browser-provider.test.ts @@ -159,7 +159,12 @@ test('agent-browser provider keeps typed text out of argv and error details when assert.equal(error.code, 'COMMAND_FAILED'); assert.match(error.message, /^agent-browser (fill|keyboard type) failed/); assert.equal(error.details?.reason, 'text-entry-failed'); - assert.match(String(error.details?.hint), /snapshot -i/); + assert.match( + String(error.details?.hint), + error.message.startsWith('agent-browser fill') + ? /snapshot -i/ + : /Focus the field again/, + ); assert.equal(error.message.includes(secret), false); assert.equal(JSON.stringify(error.details).includes(secret), false); return true; diff --git a/packages/platform-web/src/agent-browser-provider.ts b/packages/platform-web/src/agent-browser-provider.ts index a467b25041..13de02c166 100644 --- a/packages/platform-web/src/agent-browser-provider.ts +++ b/packages/platform-web/src/agent-browser-provider.ts @@ -235,7 +235,10 @@ async function sendTextEntry(send: AgentBrowserRunJson, command: readonly string command: commandName, reason: 'text-entry-failed', // The backend ran and refused this entry, so its install is not the suspect. - hint: 'The page refused this text entry: the target may have changed or gone. Run snapshot -i again and retry with the ref it reports.', + 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.', }); } 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]); From f1d7af33bd2137c6d10614129767ed21627310c7 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 21:21:00 +0000 Subject: [PATCH 23/23] test(platform-web): pin each text-entry operation to its own hint The assertion chose the expected hint from the error message, so a regression that relabelled typeText as fill would still pass. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016qAu53rMak1bXMuR5U2gF4 --- .../src/agent-browser-provider.test.ts | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) diff --git a/packages/platform-web/src/agent-browser-provider.test.ts b/packages/platform-web/src/agent-browser-provider.test.ts index 576c710c3a..29820622f8 100644 --- a/packages/platform-web/src/agent-browser-provider.test.ts +++ b/packages/platform-web/src/agent-browser-provider.test.ts @@ -149,22 +149,17 @@ test('agent-browser provider keeps typed text out of argv and error details when ); }; await withCommandExecutorOverride(executor, async () => { - for (const attempt of [ - async () => await provider.fillRef?.('@e9', secret), - () => provider.typeText(secret), - () => provider.fill(11, 22, secret), - ]) { + 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.match(error.message, /^agent-browser (fill|keyboard type) 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), - error.message.startsWith('agent-browser fill') - ? /snapshot -i/ - : /Focus the field again/, - ); + 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;