Skip to content

Commit 373b157

Browse files
committed
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 <[email protected]> Claude-Session: https://claude.ai/code/session_016qAu53rMak1bXMuR5U2gF4
1 parent 712fb0e commit 373b157

5 files changed

Lines changed: 59 additions & 37 deletions

File tree

‎packages/platform-linux/src/__tests__/tool-provider.test.ts‎

Lines changed: 29 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,19 @@ import {
1212
createLocalLinuxToolProvider,
1313
resolveLinuxToolProvider,
1414
withLinuxToolProvider,
15+
type LinuxToolCommandExecutor,
16+
type LinuxToolDetachedLauncher,
17+
type LinuxToolProviderOverrides,
1518
} from '../tool-provider.ts';
1619
import type { ExecDetachedExit } from '@agent-device/host-kit/command';
1720

1821
bindTestCommandHost();
1922

23+
/** For a provider that injects an executor and launches no app in the scenario. */
24+
const launchesNoApp: LinuxToolDetachedLauncher = (cmd) => {
25+
throw new Error(`this scenario launches no app: ${cmd}`);
26+
};
27+
2028
const originalPlatform = process.platform;
2129
const originalEnv = { ...process.env };
2230

@@ -29,6 +37,7 @@ beforeEach(() => {
2937
test('scoped Linux tool provider handles input discovery and command execution', async () => {
3038
const commands: Array<[string, string[]]> = [];
3139
const provider = createLocalLinuxToolProvider({
40+
launchDetached: launchesNoApp,
3241
host: { env: { ...process.env, XDG_SESSION_TYPE: 'x11' }, cwd: process.cwd() },
3342
whichCommand: async (cmd) => cmd === 'xdotool',
3443
runCommand: async (cmd, args) => {
@@ -52,6 +61,7 @@ test('scoped Linux tool provider handles input discovery and command execution',
5261
test('xdotool press skips the --sync move when the pointer already sits on the target', async () => {
5362
const commands: Array<[string, string[]]> = [];
5463
const provider = createLocalLinuxToolProvider({
64+
launchDetached: launchesNoApp,
5565
host: { env: { ...process.env, XDG_SESSION_TYPE: 'x11' }, cwd: process.cwd() },
5666
whichCommand: async (cmd) => cmd === 'xdotool',
5767
runCommand: async (cmd, args) => {
@@ -75,6 +85,7 @@ test('xdotool press skips the --sync move when the pointer already sits on the t
7585
test('scoped Linux input provider handles semantic input without host tool discovery', async () => {
7686
const inputCalls: Array<[string, string, string, string]> = [];
7787
const provider = createLocalLinuxToolProvider({
88+
launchDetached: launchesNoApp,
7889
host: { env: { ...process.env, XDG_SESSION_TYPE: 'x11' }, cwd: process.cwd() },
7990
whichCommand: async (cmd) => {
8091
throw new Error(`unexpected input discovery: ${cmd}`);
@@ -104,6 +115,7 @@ test('scoped Linux input provider handles semantic input without host tool disco
104115

105116
test('Linux tool provider scopes do not share cached input tool resolution', async () => {
106117
const providerA = createLocalLinuxToolProvider({
118+
launchDetached: launchesNoApp,
107119
host: {
108120
env: { ...process.env, XDG_SESSION_TYPE: 'x11', WAYLAND_DISPLAY: '' },
109121
cwd: process.cwd(),
@@ -112,6 +124,7 @@ test('Linux tool provider scopes do not share cached input tool resolution', asy
112124
runCommand: async () => ({ exitCode: 0, stdout: '', stderr: '' }),
113125
});
114126
const providerB = createLocalLinuxToolProvider({
127+
launchDetached: launchesNoApp,
115128
host: {
116129
env: { ...process.env, XDG_SESSION_TYPE: 'wayland', WAYLAND_DISPLAY: 'wayland-0' },
117130
cwd: process.cwd(),
@@ -154,6 +167,7 @@ test('Linux tool provider scopes do not share cached input tool resolution', asy
154167
test('local Linux desktop provider translates semantic lifecycle calls to host tools', async () => {
155168
const commands: Array<[string, string[], boolean | undefined]> = [];
156169
const provider = createLocalLinuxToolProvider({
170+
launchDetached: launchesNoApp,
157171
host: { env: { ...process.env, XDG_SESSION_TYPE: 'x11' }, cwd: process.cwd() },
158172
whichCommand: async (cmd) => cmd === 'wmctrl',
159173
runCommand: async (cmd, args, options) => {
@@ -276,25 +290,26 @@ test('local Linux desktop provider reports nothing for a launched app that exits
276290
assert.deepEqual(await launchDiagnostics({ pid: 4, exitCode: 0 }), []);
277291
});
278292

279-
test('local Linux desktop provider launches through an injected executor when it injects no launcher', async () => {
280-
const commands: Array<[string, string[], boolean | undefined]> = [];
281-
const provider = createLocalLinuxToolProvider({
282-
host: { env: process.env, cwd: process.cwd() },
283-
whichCommand: async (cmd) => cmd === 'demo-app',
284-
runCommand: async (cmd, args, options) => {
285-
commands.push([cmd, args, options?.allowFailure]);
286-
return { exitCode: 0, stdout: '', stderr: '' };
287-
},
293+
// An injected executor owns process execution, so the type refuses one without its own launcher:
294+
// the host-local detached runner must never stand in beside it. The directive fails typecheck if
295+
// the refusal goes away.
296+
test('a Linux provider that injects runCommand must also inject launchDetached', () => {
297+
const runCommand: LinuxToolCommandExecutor = async () => ({
298+
exitCode: 0,
299+
stdout: '',
300+
stderr: '',
288301
});
289-
290-
await provider.desktop.openTarget('demo-app');
291-
292-
assert.deepEqual(commands, [['demo-app', [], true]]);
302+
// @ts-expect-error runCommand without launchDetached
303+
const withoutLauncher: LinuxToolProviderOverrides = { runCommand };
304+
const withLauncher: LinuxToolProviderOverrides = { runCommand, launchDetached: launchesNoApp };
305+
assert.equal(withoutLauncher.launchDetached, undefined);
306+
assert.equal(withLauncher.launchDetached, launchesNoApp);
293307
});
294308

295309
test('local Linux desktop provider falls back to pkill when wmctrl is unavailable', async () => {
296310
const commands: Array<[string, string[], boolean | undefined]> = [];
297311
const provider = createLocalLinuxToolProvider({
312+
launchDetached: launchesNoApp,
298313
host: { env: { ...process.env, XDG_SESSION_TYPE: 'x11' }, cwd: process.cwd() },
299314
whichCommand: async () => false,
300315
runCommand: async (cmd, args, options) => {
@@ -311,6 +326,7 @@ test('local Linux desktop provider falls back to pkill when wmctrl is unavailabl
311326
test('local Linux screenshot provider translates capture to available host tool', async () => {
312327
const commands: Array<[string, string[]]> = [];
313328
const provider = createLocalLinuxToolProvider({
329+
launchDetached: launchesNoApp,
314330
host: { env: { ...process.env, XDG_SESSION_TYPE: 'x11' }, cwd: process.cwd() },
315331
whichCommand: async (cmd) => cmd === 'scrot',
316332
runCommand: async (cmd, args) => {

‎packages/platform-linux/src/tool-provider.ts‎

Lines changed: 16 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -103,19 +103,26 @@ const whichOnPath = async (cmd: string): Promise<boolean> =>
103103
await whichCmd(cmd, commandHostEnvironment().env);
104104

105105
/** A provider under construction; only the display decision is required up front. */
106-
type LinuxToolProviderParts = { display: LinuxDisplayConfig } & Partial<LinuxToolProvider>;
106+
/**
107+
* The parts a caller may supply. A caller that injects `runCommand` owns process execution, so it
108+
* also supplies `launchDetached`: the host-local detached runner never stands in beside an
109+
* injected executor.
110+
*/
111+
export type LinuxToolProviderOverrides = Partial<
112+
Omit<LinuxToolProvider, 'runCommand' | 'launchDetached'>
113+
> &
114+
(
115+
| { runCommand?: undefined; launchDetached?: LinuxToolDetachedLauncher }
116+
| { runCommand: LinuxToolCommandExecutor; launchDetached: LinuxToolDetachedLauncher }
117+
);
118+
119+
type LinuxToolProviderParts = { display: LinuxDisplayConfig } & LinuxToolProviderOverrides;
107120

108121
/** Adds the local parts a partial provider omits; every part then belongs to this instance. */
109122
function completeLocalLinuxToolProvider(provider: LinuxToolProviderParts): LinuxToolProvider {
110123
const runCommand = provider.runCommand ?? runCmd;
111124
const whichCommand = provider.whichCommand ?? whichOnPath;
112-
// A caller that injected its own executor also owns app launches: the host-local detached
113-
// runner is the default only beside the host-local `runCmd`.
114-
const launchDetached =
115-
provider.launchDetached ??
116-
(provider.runCommand === undefined
117-
? runCmdDetachedMonitored
118-
: launchThroughExecutor(provider.runCommand));
125+
const launchDetached = provider.launchDetached ?? runCmdDetachedMonitored;
119126
const display = provider.display;
120127
return {
121128
runCommand,
@@ -138,7 +145,7 @@ function completeLocalLinuxToolProvider(provider: LinuxToolProviderParts): Linux
138145
* one provider instance per composing runtime, owning its display decision (#3794).
139146
*/
140147
export function createLocalLinuxToolProvider(
141-
options: { host: HostEnvironment } & Partial<LinuxToolProvider>,
148+
options: { host: HostEnvironment } & LinuxToolProviderOverrides,
142149
): LinuxToolProvider {
143150
const { host, ...provider } = options;
144151
return completeLocalLinuxToolProvider({
@@ -188,19 +195,6 @@ export async function runLinuxToolCommand(
188195
return await resolveLinuxToolProvider().runCommand(cmd, args, options);
189196
}
190197

191-
/** A launcher over an injected executor, settling `exited` from the command's own result. */
192-
function launchThroughExecutor(runCommand: LinuxToolCommandExecutor): LinuxToolDetachedLauncher {
193-
return (cmd, args) => ({
194-
exited: runCommand(cmd, args, { allowFailure: true }).then(
195-
(result): ExecDetachedExit => ({ pid: 0, exitCode: result.exitCode }),
196-
(error: unknown): ExecDetachedExit => ({
197-
pid: 0,
198-
error: error instanceof Error ? error.message : String(error),
199-
}),
200-
),
201-
});
202-
}
203-
204198
/** What a launched app's exit says went wrong: a start failure, a non-zero exit, or a signal. */
205199
function describeLaunchExit(exit: ExecDetachedExit): Record<string, unknown> | undefined {
206200
if (exit.error !== undefined) return { error: exit.error };

‎packages/platform-web/src/agent-browser-provider.test.ts‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -159,7 +159,12 @@ test('agent-browser provider keeps typed text out of argv and error details when
159159
assert.equal(error.code, 'COMMAND_FAILED');
160160
assert.match(error.message, /^agent-browser (fill|keyboard type) failed/);
161161
assert.equal(error.details?.reason, 'text-entry-failed');
162-
assert.match(String(error.details?.hint), /snapshot -i/);
162+
assert.match(
163+
String(error.details?.hint),
164+
error.message.startsWith('agent-browser fill')
165+
? /snapshot -i/
166+
: /Focus the field again/,
167+
);
163168
assert.equal(error.message.includes(secret), false);
164169
assert.equal(JSON.stringify(error.details).includes(secret), false);
165170
return true;

‎packages/platform-web/src/agent-browser-provider.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -235,7 +235,10 @@ async function sendTextEntry(send: AgentBrowserRunJson, command: readonly string
235235
command: commandName,
236236
reason: 'text-entry-failed',
237237
// The backend ran and refused this entry, so its install is not the suspect.
238-
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.',
238+
hint:
239+
commandName === 'fill'
240+
? '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.'
241+
: 'The page refused this text entry: the focused field may have changed or gone. Focus the field again (click it) and retry type.',
239242
});
240243
}
241244

‎test/integration/provider-scenarios/linux-world.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,10 @@ export async function createLinuxDesktopWorld(): Promise<LinuxDesktopWorld> {
5454
toolCalls.push([cmd, args]);
5555
return { stdout: '', stderr: '', exitCode: 0 };
5656
},
57+
// The scripted desktop below owns app launches, so the detached launcher is never reached.
58+
launchDetached: (cmd) => {
59+
throw new Error(`the Linux world launches apps through its desktop: ${cmd}`);
60+
},
5761
desktop: {
5862
openTarget: async (target) => {
5963
desktopCalls.push(['open', target]);

0 commit comments

Comments
 (0)