Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 0 additions & 5 deletions .fallowrc.json
Original file line number Diff line number Diff line change
Expand Up @@ -367,11 +367,6 @@
"file": "packages/platform-harmonyos/src/app-lifecycle.ts",
"exports": ["resolveHarmonyArchiveBundleName"]
},
{
// Linux package façade loader is a named external seam. Its dynamic property read is not visible to --production analysis.
"file": "packages/platform-linux/src/index.ts",
"exports": ["createLocalLinuxToolProvider"]
},
{
// Web package façade loaders are named external seams. Their dynamic property reads are not visible to --production analysis, and the timeout is pinned by the daemon teardown test.
"file": "packages/platform-web/src/index.ts",
Expand Down
7 changes: 5 additions & 2 deletions docs/adr/0001-provider-first-integration-scenarios.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ Completed process history is in git history.

> **Amended by [ADR 0019](0019-request-bound-platform-runtime.md).** Provider-first scenario coverage and semantic provider operations remain accepted.
> Request-bound runtime facets and explicit provider ownership supersede the monolithic `Interactor` and the request callback-stack topology one command at a time.
>
> **Amended 2026-11-22 (Linux).** The Linux family has no request-scoped provider seam. Its desktop vocabulary is internal to `packages/platform-linux`, and the family answers every desktop intent through the `PlatformHost` its plugin was set up with. A Provider-backed integration scenario for Linux scripts that host instead of injecting a provider. The semantic Linux operations below still hold; the plugin owns them.

## Rules at a glance

Expand Down Expand Up @@ -48,7 +50,6 @@ For commands that still use the legacy adapter, use these request-scoped provide
- Android ADB provider.
- Apple tool provider with semantic `simctl`, `devicectl`, macOS helper, and macOS host subproviders.
- Apple runner provider.
- Linux tool provider with semantic subproviders for desktop lifecycle, accessibility, clipboard, and screenshots.
- App-log provider for semantic start and stop of app log streams.
- Recording provider for semantic local and remote screen-recording start operations that would otherwise be raw host processes.

Expand All @@ -66,7 +67,7 @@ The macOS host provider owns these operations:

The reason is that remote desktop providers should not need to infer these intents from `open`, `find`, `plutil`, `pbcopy`, `pbpaste`, or `osascript`.

Linux desktop lifecycle exposes semantic `openTarget` and `closeApp` operations for two reasons:
Linux desktop lifecycle uses semantic `openTarget` and `closeApp` operations internally for two reasons:

- Provider-backed integration covers these user workflows.
- Remote desktop providers should not need to infer intent from `xdg-open`, binary launch, `wmctrl`, or `pkill`.
Expand All @@ -80,6 +81,8 @@ Linux accessibility snapshots, clipboard, screenshots, and input synthesis are a

The local implementation details `python3`/AT-SPI, `xclip`, `scrot`, `grim`, `xdotool`, and `ydotool` are not the contracts.

The Linux family keeps that vocabulary to itself: the plugin builds one provider from the host it was set up with, and no request-scoped provider is resolved for it. A Linux scenario therefore scripts the host — which desktop tools exist, and what each command answers — and asserts the desktop argv the family produced. That keeps the plugin's own tool selection under test, which an injected provider would have stepped around.

App-log stream start/stop is semantic observability behavior, not generic host process execution.
Thus, provider-backed integration injects an app-log provider, and it does not spawn `log stream` or `logcat`.

Expand Down
4 changes: 0 additions & 4 deletions packages/contracts/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -316,10 +316,6 @@
"types": "./src/macos-platform-leaf.ts",
"default": "./src/macos-platform-leaf.ts"
},
"./linux-tool-provider": {
"types": "./src/linux-tool-provider.ts",
"default": "./src/linux-tool-provider.ts"
},
"./vega-tool-provider": {
"types": "./src/vega-tool-provider.ts",
"default": "./src/vega-tool-provider.ts"
Expand Down
8 changes: 3 additions & 5 deletions packages/contracts/src/platform-plugin.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,6 @@ import type { ManagedWebBackend } from './managed-web-backend.ts';
import type { DoctorCheck } from './doctor.ts';
import type { HostDiagnosticsContext } from './host-diagnostics.ts';
import type { InventoryPlatformModule, PlatformModuleRegistry } from './platform-module.ts';
import type { LinuxToolProvider } from './linux-tool-provider.ts';
import type { MacOsPlatformLeafSelection } from './macos-platform-leaf.ts';
import type { PlatformRuntimeModule } from './platform-runtime-operations.ts';
import type { WebProvider } from './web-provider.ts';
Expand Down Expand Up @@ -146,9 +145,9 @@ export type HarmonyPlatformSelection = Readonly<{

/**
* What the core asks of the Linux plugin: the toolchain probe that answers `doctor --platform
* linux`, and the request scope the family owns. The desktop capture and every interaction the
* family runs go through the registration's runtime and interactor, which use the host the plugin
* was set up with.
* linux`. Every other Linux operation — the desktop capture, every interaction, and the host tool
* provider they all run through — the package owns, because it runs them through the host it was
* set up with. The provider never leaves the package, so the core names none of its vocabulary.
*/
export type LinuxPlatformOperations = Readonly<{
toolchainCheck(): Promise<DoctorCheck>;
Expand All @@ -159,7 +158,6 @@ export type LinuxPlatformRegistration = Readonly<{
inventoryModule: InventoryPlatformModule<'linux'>;
runtimeModule: PlatformRuntimeModule & { readonly family: 'linux' };
createInteractor: PlatformPlugin['createInteractor'];
withRequestProvider<T>(provider: LinuxToolProvider, task: () => Promise<T>): Promise<T>;
operations: LinuxPlatformOperations;
}>;

Expand Down
1 change: 0 additions & 1 deletion packages/contracts/src/platform-providers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -64,5 +64,4 @@ export type PlatformGatedProviderResolverKey =
| 'appleRunnerProvider'
| 'appleToolProvider'
| 'vegaToolProvider'
| 'linuxToolProvider'
| 'webProvider';
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ import assert from 'node:assert/strict';
import { createLinuxHostStub, type LinuxHostStub } from '../toolbox.fixtures.ts';
import { createLinuxToolProvider } from '../tool-provider.ts';
import { fillLinux, pressLinux, scrollLinux, sendKey, typeLinux } from '../input-actions.ts';
import type { LinuxToolProvider } from '@agent-device/contracts/linux-tool-provider';
import type { LinuxToolProvider } from '../tool-provider-types.ts';
import { AppError } from '@agent-device/kernel/errors';

function x11Stub(): LinuxHostStub {
Expand Down
2 changes: 1 addition & 1 deletion packages/platform-linux/src/app-lifecycle.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import type { LinuxToolProvider } from '@agent-device/contracts/linux-tool-provider';
import type { LinuxToolProvider } from './tool-provider-types.ts';
import { sendKey } from './input-actions.ts';

/**
Expand Down
2 changes: 1 addition & 1 deletion packages/platform-linux/src/atspi-bridge.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@

import { AppError } from '@agent-device/kernel/errors';
import type { RawSnapshotNode, Rect } from '@agent-device/kernel/snapshot';
import type { LinuxAccessibilityProvider } from '@agent-device/contracts/linux-tool-provider';
import type { LinuxAccessibilityProvider } from './tool-provider-types.ts';
import { normalizeAtspiRole } from './role-map.ts';
import type { LinuxCommandRunner } from './command-runner.ts';
import { createLinuxAtspiScriptResolver, LINUX_ATSPI_SCRIPT_NAME } from './atspi-script.ts';
Expand Down
2 changes: 1 addition & 1 deletion packages/platform-linux/src/clipboard.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import type { LinuxToolProvider } from '@agent-device/contracts/linux-tool-provider';
import type { LinuxToolProvider } from './tool-provider-types.ts';

export async function readLinuxClipboard(provider: LinuxToolProvider): Promise<string> {
return await provider.clipboard.readText();
Expand Down
5 changes: 1 addition & 4 deletions packages/platform-linux/src/command-runner.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,7 @@ import type {
DetachedCommandExit,
HostOperatingSystem,
} from '@agent-device/contracts/platform-runtime-host';
import type {
LinuxCommandOptions,
LinuxCommandResult,
} from '@agent-device/contracts/linux-tool-provider';
import type { LinuxCommandOptions, LinuxCommandResult } from './tool-provider-types.ts';

/**
* The plugin's route to host commands, bound to the `PlatformHost` the core handed `setup()`. The
Expand Down
2 changes: 1 addition & 1 deletion packages/platform-linux/src/display.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import type { LinuxDisplayServer } from '@agent-device/contracts/linux-tool-provider';
import type { LinuxDisplayServer } from './tool-provider-types.ts';

/** The display decision bound to one host environment. */
export type LinuxDisplayConfig = Readonly<{
Expand Down
2 changes: 1 addition & 1 deletion packages/platform-linux/src/doctor.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import type { DoctorCheck } from '@agent-device/contracts/observability';
import type { LinuxToolProvider } from '@agent-device/contracts/linux-tool-provider';
import type { LinuxToolProvider } from './tool-provider-types.ts';
import { linuxToolSlotCommands } from './tool-provider.ts';

/**
Expand Down
70 changes: 0 additions & 70 deletions packages/platform-linux/src/index.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,6 @@ test('setup registers the Linux modules and operations', () => {
assert.equal(typeof registration.inventoryModule.loadInventory, 'function');
assert.equal(typeof registration.runtimeModule.loadRuntime, 'function');
assert.equal(typeof registration.createInteractor, 'function');
assert.equal(typeof registration.withRequestProvider, 'function');
assert.equal(typeof registration.operations.toolchainCheck, 'function');
});

Expand Down Expand Up @@ -271,75 +270,6 @@ test('the Linux interactor drives the host the plugin was set up with', async ()
assert.equal(commands[0]?.env?.XDG_SESSION_TYPE, 'x11');
});

test('a request-scoped provider answers the interactor instead of the setup host', async () => {
const hostCommands: HostCommand[] = [];
const registration = setupLinuxPlatform(
createPluginHost({
env: { PATH: '/usr/bin', XDG_SESSION_TYPE: 'x11' },
tools: ['xdotool'],
commands: hostCommands,
}),
);
const scopedCommands: Array<[string, readonly string[]]> = [];
const scoped = {
display: { detectDisplayServer: () => 'x11' as const },
runCommand: async (cmd: string, args: readonly string[]) => {
scopedCommands.push([cmd, args]);
return { stdout: '', stderr: '', exitCode: 0 };
},
whichCommand: async (cmd: string) => cmd === 'xdotool',
launchDetached: () => ({ exited: Promise.resolve({ pid: 1, exitCode: 0 }) }),
sleep: async () => {},
desktop: {
openTarget: async () => {},
closeApp: async () => {},
},
// The parts this request never reaches: reading one would mean the tap went somewhere the test
// did not script, so the assertion is the throw.
clipboard: {
readText: async () => {
throw new Error('this request reads no clipboard');
},
writeText: async () => {
throw new Error('this request writes no clipboard');
},
},
screenshot: {
capture: async () => {
throw new Error('this request captures no screenshot');
},
},
accessibility: {
captureTree: async () => {
throw new Error('this request captures no tree');
},
},
};
const interactor = await registration.createInteractor(
{
platform: 'linux',
id: 'local',
name: 'builder',
kind: 'device',
target: 'desktop',
booted: true,
},
{},
{ env: {}, cwd: '/host-cwd' },
);

await registration.withRequestProvider(scoped, async () => {
await interactor.tap(1, 2);
});

assert.deepEqual(scopedCommands, [
['xdotool', ['getmouselocation', '--shell']],
['xdotool', ['mousemove', '--sync', '1', '2']],
['xdotool', ['click', '1']],
]);
assert.equal(hostCommands.length, 0);
});

test('two setups keep separate host environments', async () => {
const x11Commands: HostCommand[] = [];
const waylandCommands: HostCommand[] = [];
Expand Down
6 changes: 1 addition & 5 deletions packages/platform-linux/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ import type {
LinuxPlatformRegistration,
} from '@agent-device/contracts/platform-plugin';
import type { LinuxToolbox } from './toolbox.ts';
import type { LinuxToolProvider } from '@agent-device/contracts/linux-tool-provider';
import type { LinuxToolProvider } from './tool-provider-types.ts';

const metadata = Object.freeze({
family: 'linux',
Expand Down Expand Up @@ -75,10 +75,6 @@ function linuxPlatformPlugin() {
const { toolbox, provider } = await bind();
return createLinuxInteractor(toolbox, provider);
},
withRequestProvider: async <T>(provider: LinuxToolProvider, task: () => Promise<T>) => {
const { withLinuxToolProvider } = await import('./tool-provider.ts');
return await withLinuxToolProvider(provider, task);
},
operations: {
toolchainCheck: async () => {
const [{ linuxToolchainCheck }, { provider }] = await Promise.all([
Expand Down
5 changes: 1 addition & 4 deletions packages/platform-linux/src/input-actions.ts
Original file line number Diff line number Diff line change
@@ -1,8 +1,5 @@
import { discloseDispatchAfterSteps } from '@agent-device/kernel/errors';
import type {
LinuxInputProvider,
LinuxToolProvider,
} from '@agent-device/contracts/linux-tool-provider';
import type { LinuxInputProvider, LinuxToolProvider } from './tool-provider-types.ts';
import {
DEFAULT_SCROLL_AMOUNT,
type ScrollDirection,
Expand Down
69 changes: 26 additions & 43 deletions packages/platform-linux/src/interactor.ts
Original file line number Diff line number Diff line change
@@ -1,8 +1,7 @@
import { AppError } from '@agent-device/kernel/errors';
import { withMethodScope } from '@agent-device/kernel/scoped-provider';
import { singlePointerPlanEndpoints } from '@agent-device/gestures/gesture-plan';
import type { Interactor } from '@agent-device/contracts/interactor-types';
import type { LinuxToolProvider } from '@agent-device/contracts/linux-tool-provider';
import type { LinuxToolProvider } from './tool-provider-types.ts';
import { backLinux, closeLinuxApp, homeLinux, openLinuxApp } from './app-lifecycle.ts';
import { readLinuxClipboard, writeLinuxClipboard } from './clipboard.ts';
import {
Expand All @@ -20,49 +19,33 @@ import {
import { readLinuxTextAtPoint } from './snapshot.ts';
import { captureLinuxSurfaceSnapshot } from './surface-snapshot.ts';
import { screenshotLinux } from './screenshot.ts';
import {
hasScopedLinuxToolProvider,
resolveLinuxToolProvider,
withLinuxToolProvider,
} from './tool-provider.ts';
import type { LinuxToolbox } from './toolbox.ts';

/**
* The Linux interactor, bound to the toolbox the plugin was set up with and to the provider built on
* it: the display decision lives on that instance, never in module state, so another runtime's host
* cannot reach it (#3794). A request that scoped its own provider still wins — its scope is already
* entered when the daemon dispatches, so the interactor's provider enters only for a request that
* scoped none. Each method then resolves the provider in scope.
* cannot reach it (#3794). Every method uses that one provider — the family answers for its desktop
* only through the host it was set up with.
*/
export function createLinuxInteractor(
toolbox: LinuxToolbox,
provider: LinuxToolProvider,
): Interactor {
const body = createLinuxInteractorBody(toolbox, provider);
return withMethodScope(body, async (task) =>
hasScopedLinuxToolProvider() ? await task() : await withLinuxToolProvider(provider, task),
);
}

function createLinuxInteractorBody(toolbox: LinuxToolbox, own: LinuxToolProvider): Interactor {
// Resolved per method rather than once at construction: the request scope is entered for the
// method, and its provider is the one that must answer.
const running = () => resolveLinuxToolProvider(own);
return {
open: (app) => openLinuxApp(running(), app),
open: (app) => openLinuxApp(provider, app),
openDevice: () => Promise.resolve(),
close: (app) => closeLinuxApp(running(), app),
tap: (x, y) => pressLinux(running(), x, y),
close: (app) => closeLinuxApp(provider, app),
tap: (x, y) => pressLinux(provider, x, y),
alternateClick: async (point, button) =>
button === 'secondary'
? await rightClickLinux(running(), point.x, point.y)
: await middleClickLinux(running(), point.x, point.y),
doubleTap: (x, y) => doubleClickLinux(running(), x, y),
longPress: (x, y, durationMs) => longPressLinux(running(), x, y, durationMs),
focus: (x, y) => focusLinux(running(), x, y),
type: (text, delayMs) => typeLinux(running(), text, delayMs),
fill: (x, y, text, delayMs) => fillLinux(running(), x, y, text, delayMs),
scroll: (direction, options) => scrollLinux(running(), direction, options),
? await rightClickLinux(provider, point.x, point.y)
: await middleClickLinux(provider, point.x, point.y),
doubleTap: (x, y) => doubleClickLinux(provider, x, y),
longPress: (x, y, durationMs) => longPressLinux(provider, x, y, durationMs),
focus: (x, y) => focusLinux(provider, x, y),
type: (text, delayMs) => typeLinux(provider, text, delayMs),
fill: (x, y, text, delayMs) => fillLinux(provider, x, y, text, delayMs),
scroll: (direction, options) => scrollLinux(provider, direction, options),
performGesture: async (plan) => {
if (plan.topology !== 'single') {
throw new AppError(
Expand All @@ -71,33 +54,33 @@ function createLinuxInteractorBody(toolbox: LinuxToolbox, own: LinuxToolProvider
);
}
const { start, end } = singlePointerPlanEndpoints(plan);
await swipeLinux(running(), start.x, start.y, end.x, end.y, plan.durationMs);
await swipeLinux(provider, start.x, start.y, end.x, end.y, plan.durationMs);
},
screenshot: (outPath, options) => screenshotLinux(running(), outPath, options),
screenshot: (outPath, options) => screenshotLinux(provider, outPath, options),
// The Linux read is value-first (AXValue/title/description) where the captured tree is
// label-first, so this genuinely reads differently from its snapshot text.
readTextAtPoint: async (point, options) =>
await readLinuxTextAtPoint(toolbox, running(), point.x, point.y, options?.surface),
await readLinuxTextAtPoint(toolbox, provider, point.x, point.y, options?.surface),
snapshot: async (options) =>
await toolbox.withDiagnosticTimer(
'snapshot_capture',
async () => await captureLinuxSurfaceSnapshot(toolbox, running(), options, options?.signal),
async () => await captureLinuxSurfaceSnapshot(toolbox, provider, options, options?.signal),
{ backend: 'linux-atspi' },
),
back: () => backLinux(running()),
home: () => homeLinux(running()),
setOrientation: () => {
back: () => backLinux(provider),
home: () => homeLinux(provider),
setOrientation: async () => {
throw new AppError('UNSUPPORTED_OPERATION', 'orientation not supported on Linux');
},
appSwitcher: () => {
appSwitcher: async () => {
throw new AppError('UNSUPPORTED_OPERATION', 'appSwitcher not yet supported on Linux');
},
tvRemote: () => {
tvRemote: async () => {
throw new AppError('UNSUPPORTED_OPERATION', 'tv-remote not supported on Linux');
},
readClipboard: () => readLinuxClipboard(running()),
writeClipboard: (text) => writeLinuxClipboard(running(), text),
setSetting: () => {
readClipboard: () => readLinuxClipboard(provider),
writeClipboard: (text) => writeLinuxClipboard(provider, text),
setSetting: async () => {
throw new AppError('UNSUPPORTED_OPERATION', 'setSetting not supported on Linux');
},
};
Expand Down
5 changes: 1 addition & 4 deletions packages/platform-linux/src/linux-env.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,7 @@
*/

import { AppError } from '@agent-device/kernel/errors';
import type {
LinuxInputSelection,
LinuxToolProvider,
} from '@agent-device/contracts/linux-tool-provider';
import type { LinuxInputSelection, LinuxToolProvider } from './tool-provider-types.ts';

export async function ensureInputTool(provider: LinuxToolProvider): Promise<LinuxInputSelection> {
const display = provider.display.detectDisplayServer();
Expand Down
Loading
Loading