From efdf00322778c2551bd9bfcba4d52d70ce5dfb5a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 21 Nov 2026 02:01:52 +0100 Subject: [PATCH 01/12] refactor(linux): move Linux desktop automation into the managed platform plugin The packed core no longer answers for the Linux family. `@agent-device/linux` is a managed optional platform plugin like the web, Vega and HarmonyOS plugins: the composition resolves it through the same one-shot module selection, and a request that names `--platform linux` without it answers `plugin-not-installed` with its install command, while unfiltered discovery and doctor skip the family. The family's mechanics move with it. AT-SPI2 discovery and snapshotting, the X11 and Wayland input, clipboard and screenshot primitives, app lifecycle, the toolchain probe and the Python AT-SPI helper all live in the package now. Every command goes through the `PlatformHost` the composition hands to `setup`, so the plugin reads no process globals and starts no process on its own. Core keeps only the canonical platform vocabulary and the request-provider gate for the family's selection. --- .github/actions/run-gate/action.yml | 12 + .github/workflows/linux.yml | 28 +- package.json | 4 +- .../src/snapshot/snapshot-desktop-surface.ts | 8 +- packages/contracts/package.json | 4 + packages/contracts/src/linux-tool-provider.ts | 129 ++++++ packages/contracts/src/platform-plugin.ts | 31 ++ packages/platform-linux/build.mjs | 14 + .../platform-linux/linux}/atspi-dump.py | 0 packages/platform-linux/package.json | 59 ++- .../src/__tests__/atspi-bridge.test.ts | 366 +++++++-------- .../src/__tests__/clipboard.test.ts | 142 +++--- .../src/__tests__/input-actions.test.ts | 184 ++++---- .../interactor-host-isolation.test.ts | 84 ---- .../src/__tests__/snapshot.test.ts | 187 +++----- .../src/__tests__/surface-snapshot.test.ts | 86 ++-- .../src/__tests__/tool-provider.test.ts | 429 +++++++----------- .../platform-linux/src/accessibility-types.ts | 16 - packages/platform-linux/src/app-lifecycle.ts | 18 +- packages/platform-linux/src/atspi-bridge.ts | 240 ++++------ packages/platform-linux/src/atspi-script.ts | 29 ++ packages/platform-linux/src/clipboard.ts | 13 +- packages/platform-linux/src/command-runner.ts | 102 +++++ packages/platform-linux/src/display.ts | 33 +- packages/platform-linux/src/doctor.ts | 61 +++ packages/platform-linux/src/index.test.ts | 309 +++++++++++++ packages/platform-linux/src/index.ts | 187 ++++---- packages/platform-linux/src/input-actions.ts | 268 ++++++----- packages/platform-linux/src/input-tool.ts | 6 - .../platform-linux/src/interactor-facade.ts | 7 - .../platform-linux/src/interactor.test.ts | 156 +++++-- packages/platform-linux/src/interactor.ts | 110 ++--- packages/platform-linux/src/linux-env.ts | 17 +- packages/platform-linux/src/runtime.test.ts | 366 ++++++++------- packages/platform-linux/src/runtime.ts | 37 +- packages/platform-linux/src/screenshot.ts | 8 +- packages/platform-linux/src/snapshot.ts | 23 +- .../platform-linux/src/surface-snapshot.ts | 15 +- packages/platform-linux/src/tool-provider.ts | 307 ++++--------- .../platform-linux/src/toolbox.fixtures.ts | 181 ++++++++ packages/platform-linux/src/toolbox.ts | 28 ++ .../platform-linux/test/package-smoke.mjs | 329 ++++++++++++++ packages/platform-linux/tsconfig.json | 4 +- packages/plugins/src/platform.ts | 36 +- packages/plugins/src/validate.ts | 15 + pnpm-lock.yaml | 12 +- scripts/__tests__/device-lane-impact.test.ts | 2 +- scripts/capability-matrix/collect.ts | 3 +- scripts/check-affected/device-lanes.test.ts | 5 +- scripts/check-affected/device-lanes.ts | 8 +- scripts/check-package.ts | 9 + scripts/install-workspace-replay-plugins.ts | 50 +- .../layering/contracts-exports.snapshot.json | 1 + .../layering/platform-package-policy.test.ts | 82 ++-- scripts/layering/platform-package-policy.ts | 9 +- .../layering/process-globals-policy.test.ts | 8 +- scripts/layering/process-globals-policy.ts | 1 - .../contracts/platform-plugin-parity.test.ts | 6 +- .../snapshot-desktop-surface.test.ts | 65 +-- src/core/interactors/register-builtins.ts | 13 - ...m-plugin-registry-provider-routing.test.ts | 116 +++-- ...daemon-composition-platform-plugin.test.ts | 145 +++++- src/daemon-composition.ts | 5 +- ...-runtime-gateway-gesture-admission.test.ts | 9 +- ...rm-runtime-gateway-optional-family.test.ts | 35 +- ...platform-runtime-gateway-recording.test.ts | 6 +- src/platform-runtime-host-diagnostics.test.ts | 90 ++++ src/platform-runtime-host-diagnostics.ts | 7 + ...latform-runtime-linux-provider.fixtures.ts | 33 ++ src/platform-runtime.test.ts | 10 +- src/platform-runtime.ts | 9 +- src/platform-runtime/platform-plugins.ts | 18 + src/platform-runtime/plugin-host.ts | 7 + src/platform-runtime/request-providers.ts | 24 +- .../integration/provider-scenarios/harness.ts | 11 +- .../provider-scenarios/linux-world.ts | 42 +- test/repo-guards/npm-package-scripts.test.ts | 2 +- website/docs/docs/installation.md | 15 + 78 files changed, 3481 insertions(+), 2065 deletions(-) create mode 100644 packages/contracts/src/linux-tool-provider.ts create mode 100644 packages/platform-linux/build.mjs rename {linux => packages/platform-linux/linux}/atspi-dump.py (100%) delete mode 100644 packages/platform-linux/src/__tests__/interactor-host-isolation.test.ts delete mode 100644 packages/platform-linux/src/accessibility-types.ts create mode 100644 packages/platform-linux/src/atspi-script.ts create mode 100644 packages/platform-linux/src/command-runner.ts create mode 100644 packages/platform-linux/src/doctor.ts create mode 100644 packages/platform-linux/src/index.test.ts delete mode 100644 packages/platform-linux/src/input-tool.ts delete mode 100644 packages/platform-linux/src/interactor-facade.ts create mode 100644 packages/platform-linux/src/toolbox.fixtures.ts create mode 100644 packages/platform-linux/src/toolbox.ts create mode 100644 packages/platform-linux/test/package-smoke.mjs create mode 100644 src/platform-runtime-linux-provider.fixtures.ts diff --git a/.github/actions/run-gate/action.yml b/.github/actions/run-gate/action.yml index 05927133fe..66624e5313 100644 --- a/.github/actions/run-gate/action.yml +++ b/.github/actions/run-gate/action.yml @@ -24,6 +24,18 @@ runs: export AGENT_DEVICE_HOME="${AGENT_DEVICE_HOME:-$RUNNER_TEMP/agent-device-replay-plugins}" node --experimental-strip-types scripts/install-workspace-replay-plugins.ts echo "AGENT_DEVICE_HOME=$AGENT_DEVICE_HOME" >> "$GITHUB_ENV" + # The Linux device lanes drive the family through its managed plugin, so the store carries it + # before the gate runs. Staged from the workspace build the job just produced, the same way the + # replay packages are: the lane then exercises the plugin a user installs, not core code. + - name: Install the Linux platform plugin for Linux device gates + if: contains(fromJSON('["replay-linux", "linux-command-evidence"]'), inputs.gate) + shell: bash + run: | + set -euo pipefail + pnpm --filter @agent-device/linux build + export AGENT_DEVICE_HOME="${AGENT_DEVICE_HOME:-$RUNNER_TEMP/agent-device-replay-plugins}" + AGENT_DEVICE_WORKSPACE_PLUGINS=linux node --experimental-strip-types scripts/install-workspace-replay-plugins.ts + echo "AGENT_DEVICE_HOME=$AGENT_DEVICE_HOME" >> "$GITHUB_ENV" - id: run shell: bash env: diff --git a/.github/workflows/linux.yml b/.github/workflows/linux.yml index 0c1bb102df..ccd705ebc9 100644 --- a/.github/workflows/linux.yml +++ b/.github/workflows/linux.yml @@ -180,10 +180,36 @@ jobs: echo "=== AT-SPI2 Python bindings ===" python3 -c "import gi; gi.require_version('Atspi', '2.0'); from gi.repository import Atspi; print('OK')" echo "=== AT-SPI2 tree dump (quick test) ===" - python3 linux/atspi-dump.py --surface desktop --max-nodes 5 | python3 -m json.tool | head -20 || echo "::warning::AT-SPI2 tree dump returned no nodes (expected before any app is launched)" + python3 packages/platform-linux/linux/atspi-dump.py --surface desktop --max-nodes 5 | python3 -m json.tool | head -20 || echo "::warning::AT-SPI2 tree dump returned no nodes (expected before any app is launched)" echo "=== xdotool ===" xdotool version + # The Linux family is a managed plugin now, so the device lanes serve it from the plugin store + # built by this job. The plugin is installed once here and then answers the visible replies + # below, which is the evidence that a user's `plugins add` install drives this desktop. + - name: Install the Linux platform plugin + if: steps.impact.outputs.run != 'false' + run: | + set -euo pipefail + pnpm --filter @agent-device/linux pack --out "$RUNNER_TEMP/linux-plugin.tgz" + export AGENT_DEVICE_HOME="${AGENT_DEVICE_HOME:-$RUNNER_TEMP/agent-device-replay-plugins}" + echo "AGENT_DEVICE_HOME=$AGENT_DEVICE_HOME" >> "$GITHUB_ENV" + node bin/agent-device.mjs plugins add "$RUNNER_TEMP/linux-plugin.tgz" --json + node bin/agent-device.mjs plugins list --json + + - name: Drive the Linux desktop through the installed plugin + if: steps.impact.outputs.run != 'false' + run: | + set -euo pipefail + run() { printf '\n$ agent-device %s\n' "$*"; node bin/agent-device.mjs "$@" --json; } + run devices --platform linux + run doctor --platform linux + run open gnome-calculator --platform linux + run snapshot --platform linux + run press 60 100 --platform linux + run screenshot "$RUNNER_TEMP/plugin-desktop.png" --platform linux + run close gnome-calculator --platform linux + - name: Run Linux replay smoke test if: steps.impact.outputs.run != 'false' run: pnpm clean:daemon diff --git a/package.json b/package.json index fb209ff90f..0950f368e5 100644 --- a/package.json +++ b/package.json @@ -166,7 +166,7 @@ "depgraph:test": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test scripts/depgraph/model.test.ts scripts/depgraph/entries.test.ts scripts/depgraph/import-graph.test.ts scripts/depgraph/affected.test.ts scripts/depgraph/structure-summary.test.ts tools/depgraph-view/*.test.mjs", "check:production-exports": "fallow dead-code --config fallow-production-exports.json --production --unused-exports --fail-on-issues", "check:bundle-owner-files": "node --experimental-strip-types scripts/check-bundle-owner-files.ts", - "check:package": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test packages/maestro/test/package-artifact.test.mjs packages/maestro/test/package-smoke.mjs packages/replay/test/package-smoke.mjs packages/platform-web/test/package-smoke.mjs packages/platform-vega/test/package-smoke.mjs packages/platform-harmonyos/test/package-smoke.mjs && node --experimental-strip-types scripts/check-package.ts", + "check:package": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test packages/maestro/test/package-artifact.test.mjs packages/maestro/test/package-smoke.mjs packages/replay/test/package-smoke.mjs packages/platform-web/test/package-smoke.mjs packages/platform-vega/test/package-smoke.mjs packages/platform-harmonyos/test/package-smoke.mjs packages/platform-linux/test/package-smoke.mjs && node --experimental-strip-types scripts/check-package.ts", "check:provider-plugin": "node scripts/check-provider-plugin.mjs", "check:command-docs": "vitest run --project unit-core test/repo-guards/command-doc-coverage.test.ts test/repo-guards/command-doc-generated-blocks.test.ts", "generate:command-docs": "node --experimental-strip-types scripts/command-docs/generate.ts --write", @@ -249,7 +249,6 @@ "android/ime-helper/dist", "!android/ime-helper/dist/*.idsig", "!android/ime-helper/README.md", - "linux/atspi-dump.py", "server.json", "smithery.yaml", "README.md", @@ -328,7 +327,6 @@ "@agent-device/kernel": "workspace:*", "@agent-device/platform-android": "workspace:*", "@agent-device/platform-apple": "workspace:*", - "@agent-device/platform-linux": "workspace:*", "@agent-device/plugins": "workspace:*", "@agent-device/provider-limrun": "workspace:*", "@agent-device/provider-webdriver": "workspace:*", diff --git a/packages/capture-kit/src/snapshot/snapshot-desktop-surface.ts b/packages/capture-kit/src/snapshot/snapshot-desktop-surface.ts index 30c39952f7..83ed4bc856 100644 --- a/packages/capture-kit/src/snapshot/snapshot-desktop-surface.ts +++ b/packages/capture-kit/src/snapshot/snapshot-desktop-surface.ts @@ -10,14 +10,18 @@ export type SnapshotSurfaceLoader = ( signal?: AbortSignal, ) => Promise; +/** + * The surface captures the core still owns. The Linux desktop capture is not one of them: the AT-SPI + * read is that family's own mechanics, so it lives in the Linux plugin and runs over the host that + * plugin was set up with (#4676). What remains here is the macOS surface, whose projector the core + * keeps because the Apple runtime reaches it for a non-app surface. + */ export type SnapshotSurfaceLoaders = Readonly<{ - linux: SnapshotSurfaceLoader; macos: SnapshotSurfaceLoader; }>; export function createSnapshotRuntimeHost(loaders: SnapshotSurfaceLoaders): SnapshotRuntimeHost { const captureSurface: SnapshotRuntimeHost['captureSurface'] = async (device, options, signal) => { - if (device.platform === 'linux') return await loaders.linux(options, signal); requireMacOsSurfaceDevice(device); return await loaders.macos(options, signal); }; diff --git a/packages/contracts/package.json b/packages/contracts/package.json index c9d8acd066..bf99a33d61 100644 --- a/packages/contracts/package.json +++ b/packages/contracts/package.json @@ -312,6 +312,10 @@ "types": "./src/logs-runtime-plan.ts", "default": "./src/logs-runtime-plan.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" diff --git a/packages/contracts/src/linux-tool-provider.ts b/packages/contracts/src/linux-tool-provider.ts new file mode 100644 index 0000000000..fb5615fdf5 --- /dev/null +++ b/packages/contracts/src/linux-tool-provider.ts @@ -0,0 +1,129 @@ +/** + * The Linux host-tool surface a request scopes (ADR 0019 host execution). + * + * The Linux family drives desktop tools — `xdotool`, `ydotool`, a clipboard tool, a screenshot + * tool, and the AT-SPI helper — through this vocabulary. Root composition passes a resolved + * provider back to the Linux plugin without naming its implementation, exactly as it does for the + * Vega family's CLI adapter, so a request that owns a display decision and a command route hands + * them to the family instead of the family reaching process globals of its own. + */ + +import type { RawSnapshotNode } from '@agent-device/kernel/snapshot'; +import type { ClickButton } from './click-button.ts'; +import type { ScrollDirection } from './scroll-gesture.ts'; +import type { SessionSurface } from './session-surface.ts'; + +/** The Linux family's display-server vocabulary, from one detector. */ +export type LinuxDisplayServer = 'wayland' | 'x11'; + +/** The input tool one provider resolved, tagged with the display decision it resolved for. */ +export type LinuxInputTool = 'xdotool' | 'ydotool'; + +export type LinuxInputSelection = Readonly<{ tool: LinuxInputTool; display: LinuxDisplayServer }>; + +/** The AT-SPI surface one Linux capture reads: the desktop or the frontmost app. */ +export type LinuxSnapshotSurface = 'desktop' | 'frontmost-app'; + +/** What the host answered one Linux tool: its streams and its exit code. */ +export type LinuxCommandResult = Readonly<{ + stdout: string; + stderr: string; + exitCode: number; +}>; + +/** How one Linux tool call runs. */ +export type LinuxCommandOptions = Readonly<{ + allowFailure?: boolean; + timeoutMs?: number; + signal?: AbortSignal; + stdin?: string; +}>; + +/** Why a process that outlived its launch ended: a start failure, a non-zero exit, or a signal. */ +export type LinuxDetachedExit = Readonly<{ + pid: number; + exitCode?: number; + signal?: string; + error?: string; +}>; + +/** + * The desktop-provider parts one request may supply. Each part answers one semantic intent of the + * Linux interactor, so a caller that owns a surface — a scripted desktop, a display server it + * drives directly — substitutes it for the family's own tool route without reimplementing the + * interactor. The command primitives stay mandatory: every Linux tool call goes through them. + */ +export type LinuxToolProvider = Readonly<{ + /** The display decision every local tool selection in this provider shares (#3794). */ + display: Readonly<{ detectDisplayServer(): LinuxDisplayServer }>; + runCommand( + cmd: string, + args: readonly string[], + options?: LinuxCommandOptions, + ): Promise; + whichCommand(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. + */ + launchDetached( + cmd: string, + args: readonly string[], + ): Readonly<{ exited: Promise }>; + /** Waits for interaction pacing between synthesized input steps. */ + sleep(milliseconds: number): Promise; + desktop: LinuxDesktopProvider; + clipboard?: LinuxClipboardProvider; + screenshot?: LinuxScreenshotProvider; + accessibility?: LinuxAccessibilityProvider; + input?: LinuxInputProvider; +}>; + +export type LinuxDesktopProvider = Readonly<{ + openTarget(target: string): Promise; + closeApp(app: string): Promise; +}>; + +export type LinuxClipboardProvider = Readonly<{ + readText(): Promise; + writeText(text: string): Promise; +}>; + +export type LinuxScreenshotProvider = Readonly<{ + capture( + outPath: string, + options?: Readonly<{ fullscreen?: boolean; stabilize?: boolean; surface?: SessionSurface }>, + ): Promise; +}>; + +export type LinuxAccessibilityProvider = Readonly<{ + captureTree( + surface: LinuxSnapshotSurface, + options?: Readonly<{ + maxNodes?: number; + maxDepth?: number; + maxApps?: number; + signal?: AbortSignal; + }>, + ): Promise< + Readonly<{ + nodes: readonly RawSnapshotNode[]; + truncated: boolean; + surface: LinuxSnapshotSurface; + }> + >; +}>; + +export type LinuxInputProvider = Readonly<{ + click(x: number, y: number, button: ClickButton): Promise; + doubleClick(x: number, y: number): Promise; + longPress(x: number, y: number, durationMs: number): Promise; + drag(x1: number, y1: number, x2: number, y2: number, durationMs: number): Promise; + scroll( + direction: ScrollDirection, + options?: Readonly<{ amount?: number; pixels?: number; durationMs?: number }>, + ): Promise; + typeText(text: string, options?: Readonly<{ delayMs?: number }>): Promise; + /** Sends one combination: `combo` is xdotool keysym notation, `scancodes` ydotool pairs. */ + key(combo: string, scancodes: readonly string[]): Promise; +}>; diff --git a/packages/contracts/src/platform-plugin.ts b/packages/contracts/src/platform-plugin.ts index 7d21306cdc..1383c55043 100644 --- a/packages/contracts/src/platform-plugin.ts +++ b/packages/contracts/src/platform-plugin.ts @@ -2,6 +2,7 @@ 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 { PlatformRuntimeModule } from './platform-runtime-operations.ts'; import type { WebProvider } from './web-provider.ts'; import type { VegaToolProvider } from './vega-tool-provider.ts'; @@ -142,6 +143,35 @@ export type HarmonyPlatformSelection = Readonly<{ get(): HarmonyPlatformRegistration; }>; +/** + * 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. + */ +export type LinuxPlatformOperations = Readonly<{ + toolchainCheck(): Promise; +}>; + +export type LinuxPlatformRegistration = Readonly<{ + family: 'linux'; + inventoryModule: InventoryPlatformModule<'linux'>; + runtimeModule: PlatformRuntimeModule & { readonly family: 'linux' }; + createInteractor: PlatformPlugin['createInteractor']; + withRequestProvider(provider: LinuxToolProvider, task: () => Promise): Promise; + operations: LinuxPlatformOperations; +}>; + +/** + * How the running process answers for the Linux family, installed or not. `get()` raises the + * selection's own typed outcome when the plugin is absent or failed to load, so `doctor --platform + * linux` names the install command rather than reporting nothing. + */ +export type LinuxPlatformSelection = Readonly<{ + active?: LinuxPlatformRegistration; + get(): LinuxPlatformRegistration; +}>; + export type PlatformPluginSet = PlatformModuleRegistry<{ family: Platform; plugin: Plugin }>; @@ -150,6 +180,7 @@ export type PlatformModuleSelection = Readonly<{ web: WebPlatformSelection; vega: VegaPlatformSelection; harmony: HarmonyPlatformSelection; + linux: LinuxPlatformSelection; inventoryModules: readonly InventoryPlatformModule[]; runtimeModules: readonly PlatformRuntimeModule[]; reportAbsent(family: Platform): AppError; diff --git a/packages/platform-linux/build.mjs b/packages/platform-linux/build.mjs new file mode 100644 index 0000000000..d4d97afea5 --- /dev/null +++ b/packages/platform-linux/build.mjs @@ -0,0 +1,14 @@ +import { build } from 'tsdown'; +import { + assertManagedPlatformPluginFactory, + managedPlatformPluginBuildConfig, +} from '@agent-device/build-config'; +import linuxPlatformPlugin from './src/index.ts'; + +assertManagedPlatformPluginFactory( + new URL('./package.json', import.meta.url), + linuxPlatformPlugin, + 'Linux', +); + +await build(managedPlatformPluginBuildConfig); diff --git a/linux/atspi-dump.py b/packages/platform-linux/linux/atspi-dump.py similarity index 100% rename from linux/atspi-dump.py rename to packages/platform-linux/linux/atspi-dump.py diff --git a/packages/platform-linux/package.json b/packages/platform-linux/package.json index 14bc313661..e5fba6dc3d 100644 --- a/packages/platform-linux/package.json +++ b/packages/platform-linux/package.json @@ -1,27 +1,54 @@ { - "name": "@agent-device/platform-linux", - "version": "0.0.0", + "name": "@agent-device/linux", + "version": "0.22.0-dev", "private": true, "type": "module", - "description": "Linux-family platform runtime metadata and implementations for agent-device.", - "dependencies": { + "description": "Managed Linux platform plugin for agent-device.", + "exports": { + "./agent-device": { + "types": "./src/index.ts", + "default": "./src/index.ts" + } + }, + "devDependencies": { + "@agent-device/build-config": "workspace:*", "@agent-device/capture-kit": "workspace:*", "@agent-device/contracts": "workspace:*", "@agent-device/gestures": "workspace:*", "@agent-device/host-kit": "workspace:*", - "@agent-device/kernel": "workspace:*" + "@agent-device/kernel": "workspace:*", + "@agent-device/test-kit": "workspace:*", + "agent-device": "workspace:*" }, - "devDependencies": { - "@agent-device/test-kit": "workspace:*" + "engines": { + "node": ">=22.12" }, - "exports": { - ".": { - "types": "./src/index.ts", - "default": "./src/index.ts" + "files": [ + "dist", + "linux" + ], + "license": "MIT", + "agent-device": { + "apiVersion": 3, + "platform": "linux" + }, + "scripts": { + "build": "node --experimental-strip-types build.mjs", + "prepack": "pnpm build" + }, + "publishConfig": { + "exports": { + "./agent-device": { + "types": "./dist/agent-device.d.mts", + "import": "./dist/agent-device.mjs" + } }, - "./interactor": { - "types": "./src/interactor-facade.ts", - "default": "./src/interactor-facade.ts" - } - } + "access": "public" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/callstack/agent-device.git", + "directory": "packages/platform-linux" + }, + "homepage": "https://agent-device.dev/docs/commands#linux-desktop-targets" } diff --git a/packages/platform-linux/src/__tests__/atspi-bridge.test.ts b/packages/platform-linux/src/__tests__/atspi-bridge.test.ts index d043a4d446..b20354717b 100644 --- a/packages/platform-linux/src/__tests__/atspi-bridge.test.ts +++ b/packages/platform-linux/src/__tests__/atspi-bridge.test.ts @@ -1,262 +1,220 @@ -import { bindTestCommandHost } from '@agent-device/test-kit'; -import { afterAll, beforeEach, test, vi } from 'vitest'; +import { test } from 'vitest'; import assert from 'node:assert/strict'; - -vi.mock('@agent-device/host-kit/command', async (importOriginal) => { - const actual = await importOriginal(); - return { ...actual, runCmd: vi.fn(), whichCmd: vi.fn() }; -}); - -import { captureAccessibilityTree } from '../atspi-bridge.ts'; -import { runCmd, whichCmd } from '@agent-device/host-kit/command'; +import path from 'node:path'; +import { withMockedPlatform } from '@agent-device/test-kit'; +import { createLinuxHostStub, type LinuxHostStub } from '../toolbox.fixtures.ts'; +import { createLinuxToolProvider } from '../tool-provider.ts'; +import { resolveLinuxAtspiScriptPath } from '../atspi-script.ts'; import { AppError } from '@agent-device/kernel/errors'; -bindTestCommandHost(); - -const mockRunCmd = vi.mocked(runCmd); -const mockWhichCmd = vi.mocked(whichCmd); - -// Stub process.platform to 'linux' for these tests -const originalPlatform = process.platform; -beforeEach(() => { - mockRunCmd.mockReset(); - mockWhichCmd.mockReset(); - mockWhichCmd.mockResolvedValue(true); - Object.defineProperty(process, 'platform', { value: 'linux' }); -}); - -afterAll(() => { - Object.defineProperty(process, 'platform', { value: originalPlatform }); -}); - -function makePythonResult(nodes: Record[], truncated = false) { - return JSON.stringify({ nodes, truncated, surface: 'desktop' }); +/** The AT-SPI2 capture route, answering through the host the plugin was set up with. */ +function captureAtspi( + stub: LinuxHostStub, + surface: 'desktop' | 'frontmost-app' = 'desktop', + options: { maxNodes?: number; maxDepth?: number; maxApps?: number; signal?: AbortSignal } = {}, +) { + const provider = createLinuxToolProvider(stub.toolbox); + return provider.accessibility!.captureTree(surface, options); } -test('parses Python JSON output into RawSnapshotNodes with normalized roles', async () => { - mockRunCmd.mockResolvedValue({ - exitCode: 0, - stdout: makePythonResult([ - { - index: 0, - role: 'push button', - label: 'OK', - value: null, - rect: { x: 10, y: 20, width: 80, height: 30 }, - enabled: true, - selected: false, - hittable: true, - depth: 0, - parentIndex: null, - pid: 1234, - appName: 'TestApp', - windowTitle: 'Main Window', - }, - { - index: 1, - role: 'label', - label: 'Hello', - value: null, - rect: null, - enabled: true, - selected: false, - hittable: false, - depth: 1, - parentIndex: 0, - pid: 1234, - appName: 'TestApp', - windowTitle: 'Main Window', - }, - ]), - stderr: '', +function stubPython( + stdout: string, + answer: Readonly<{ exitCode?: number; stderr?: string }> = {}, +): LinuxHostStub { + return createLinuxHostStub({ + env: { PATH: '/usr/bin', XDG_SESSION_TYPE: 'x11' }, + tools: ['python3'], + respond: (executable) => + executable === 'python3' + ? { stdout, exitCode: answer.exitCode ?? 0, stderr: answer.stderr ?? '' } + : {}, }); +} - const result = await captureAccessibilityTree('desktop'); - - assert.equal(result.nodes.length, 2); - assert.equal(result.truncated, false); - assert.equal(result.surface, 'desktop'); - - // Role normalization - assert.equal(result.nodes[0]!.type, 'Button'); - assert.equal(result.nodes[0]!.role, 'push button'); - assert.equal(result.nodes[0]!.label, 'OK'); - assert.deepEqual(result.nodes[0]!.rect, { x: 10, y: 20, width: 80, height: 30 }); - - assert.equal(result.nodes[1]!.type, 'StaticText'); - assert.equal(result.nodes[1]!.role, 'label'); - assert.equal(result.nodes[1]!.parentIndex, 0); +const TREE = JSON.stringify({ + nodes: [ + { + index: 0, + role: 'push button', + label: 'OK', + rect: { x: 4, y: 8, width: 40, height: 20 }, + depth: 1, + parentIndex: 5, + pid: 411, + appName: 'Files', + windowTitle: 'Home', + }, + ], + truncated: false, + surface: 'desktop', }); -test('passes surface and limit args to Python script', async () => { - mockRunCmd.mockResolvedValue({ - exitCode: 0, - stdout: makePythonResult([]), - stderr: '', - }); +test('the AT-SPI capture runs the helper shipped with the plugin', async () => { + const stub = stubPython(TREE); - await captureAccessibilityTree('frontmost-app', { - maxNodes: 500, - maxDepth: 8, - maxApps: 10, - }); + await withMockedPlatform('linux', () => captureAtspi(stub)); - const callArgs = mockRunCmd.mock.calls[0]![1] as string[]; - assert.ok(callArgs.includes('--surface')); - assert.ok(callArgs.includes('frontmost-app')); - assert.ok(callArgs.includes('--max-nodes')); - assert.ok(callArgs.includes('500')); - assert.ok(callArgs.includes('--max-depth')); - assert.ok(callArgs.includes('8')); - assert.ok(callArgs.includes('--max-apps')); - assert.ok(callArgs.includes('10')); + const command = stub.commands[0]!; + assert.equal(command.executable, 'python3'); + assert.equal(command.args[0], resolveLinuxAtspiScriptPath()); + // The helper has to ship inside the installed package, not resolve against a repository layout. + assert.equal(path.basename(command.args[0]!), 'atspi-dump.py'); + assert.equal(path.dirname(command.args[0]!).endsWith('linux'), true); }); -test('passes capture cancellation to the AT-SPI process', async () => { - mockRunCmd.mockResolvedValue({ - exitCode: 0, - stdout: makePythonResult([]), - stderr: '', - }); - const controller = new AbortController(); +test('the AT-SPI capture passes the surface and traversal limits', async () => { + const stub = stubPython(TREE); - await captureAccessibilityTree('desktop', { signal: controller.signal }); + await withMockedPlatform('linux', () => + captureAtspi(stub, 'frontmost-app', { maxNodes: 10, maxDepth: 3, maxApps: 2 }), + ); - assert.equal(mockRunCmd.mock.calls[0]?.[2]?.signal, controller.signal); + assert.deepEqual(stub.commands[0]!.args.slice(1), [ + '--surface', + 'frontmost-app', + '--max-nodes', + '10', + '--max-depth', + '3', + '--max-apps', + '2', + ]); }); -test('throws TOOL_MISSING when python3 is not found', async () => { - mockWhichCmd.mockResolvedValue(false); +test('the AT-SPI capture falls back to the helper defaults and tolerates a non-zero probe answer', async () => { + const stub = stubPython(TREE); + + await withMockedPlatform('linux', () => captureAtspi(stub)); + + const command = stub.commands[0]!; + assert.deepEqual(command.args.slice(3), [ + '--max-nodes', + '1500', + '--max-depth', + '12', + '--max-apps', + '24', + ]); + // The helper's own failure answer is read from its exit code, so the run must not throw first. + assert.equal(command.allowFailure, true); +}); - await assert.rejects( - () => captureAccessibilityTree('desktop'), - (err: unknown) => { - assert.ok(err instanceof AppError); - assert.equal(err.code, 'TOOL_MISSING'); - assert.ok(err.message.includes('python3')); - return true; +test('the AT-SPI capture maps helper roles through the family role map', async () => { + const stub = stubPython(TREE); + + const result = await withMockedPlatform('linux', () => captureAtspi(stub)); + + assert.deepEqual(result.nodes, [ + { + index: 0, + type: 'Button', + role: 'push button', + label: 'OK', + value: undefined, + rect: { x: 4, y: 8, width: 40, height: 20 }, + enabled: undefined, + selected: undefined, + hittable: undefined, + depth: 1, + parentIndex: 5, + pid: 411, + appName: 'Files', + windowTitle: 'Home', }, - ); + ]); + assert.equal(result.surface, 'desktop'); + assert.equal(result.truncated, false); }); -test('throws TOOL_MISSING when python3-gi is missing', async () => { - mockRunCmd.mockResolvedValue({ +test('the AT-SPI capture reports the missing PyGObject bindings as a missing tool', async () => { + const stub = stubPython('', { exitCode: 1, - stdout: '', stderr: "ModuleNotFoundError: No module named 'gi'", }); await assert.rejects( - () => captureAccessibilityTree('desktop'), - (err: unknown) => { - assert.ok(err instanceof AppError); - assert.equal(err.code, 'TOOL_MISSING'); - assert.ok(err.message.includes('python3-gi')); + () => withMockedPlatform('linux', () => captureAtspi(stub)), + (error: unknown) => { + assert.ok(error instanceof AppError); + assert.equal(error.code, 'TOOL_MISSING'); + assert.match(error.message, /python3-gi/); return true; }, ); }); -test('throws COMMAND_FAILED on non-zero exit with unknown error', async () => { - mockRunCmd.mockResolvedValue({ - exitCode: 1, - stdout: '', - stderr: 'Segmentation fault', - }); +test('the AT-SPI capture reports a helper that failed for another reason', async () => { + const stub = stubPython('', { exitCode: 2, stderr: 'Display :0 not found' }); await assert.rejects( - () => captureAccessibilityTree('desktop'), - (err: unknown) => { - assert.ok(err instanceof AppError); - assert.equal(err.code, 'COMMAND_FAILED'); - assert.ok(err.message.includes('Segmentation fault')); + () => withMockedPlatform('linux', () => captureAtspi(stub)), + (error: unknown) => { + assert.ok(error instanceof AppError); + assert.equal(error.code, 'COMMAND_FAILED'); + assert.match(error.message, /Display :0 not found/); return true; }, ); }); -test('throws COMMAND_FAILED on invalid JSON output', async () => { - mockRunCmd.mockResolvedValue({ - exitCode: 0, - stdout: 'not json at all', - stderr: '', - }); +test('the AT-SPI capture reports output it cannot parse', async () => { + const stub = stubPython('not json'); await assert.rejects( - () => captureAccessibilityTree('desktop'), - (err: unknown) => { - assert.ok(err instanceof AppError); - assert.equal(err.code, 'COMMAND_FAILED'); - assert.ok(err.message.includes('invalid JSON')); + () => withMockedPlatform('linux', () => captureAtspi(stub)), + (error: unknown) => { + assert.ok(error instanceof AppError); + assert.equal(error.code, 'COMMAND_FAILED'); + assert.match(error.message, /invalid JSON/); return true; }, ); }); -test('throws COMMAND_FAILED when Python returns an error field', async () => { - mockRunCmd.mockResolvedValue({ - exitCode: 0, - stdout: JSON.stringify({ - error: 'Could not get desktop accessible. Is the accessibility bus running?', - }), - stderr: '', - }); +test('the AT-SPI capture reports the helper own error answer', async () => { + const stub = stubPython( + JSON.stringify({ nodes: [], truncated: false, surface: 'desktop', error: 'no registry' }), + ); await assert.rejects( - () => captureAccessibilityTree('desktop'), - (err: unknown) => { - assert.ok(err instanceof AppError); - assert.equal(err.code, 'COMMAND_FAILED'); - assert.ok(err.message.includes('accessibility bus')); + () => withMockedPlatform('linux', () => captureAtspi(stub)), + (error: unknown) => { + assert.ok(error instanceof AppError); + assert.equal(error.code, 'COMMAND_FAILED'); + assert.match(error.message, /AT-SPI2: no registry/); return true; }, ); }); -test('handles truncated result', async () => { - mockRunCmd.mockResolvedValue({ - exitCode: 0, - stdout: makePythonResult( - [{ index: 0, role: 'frame', label: 'Win', depth: 0, parentIndex: null }], - true, - ), - stderr: '', +test('the AT-SPI capture asks before spawning when the host has no python3', async () => { + const stub = createLinuxHostStub({ + env: { PATH: '/usr/bin', XDG_SESSION_TYPE: 'x11' }, + tools: [], }); - const result = await captureAccessibilityTree('desktop'); - assert.equal(result.truncated, true); + await assert.rejects( + () => withMockedPlatform('linux', () => captureAtspi(stub)), + (error: unknown) => { + assert.ok(error instanceof AppError); + assert.equal(error.code, 'TOOL_MISSING'); + assert.match(error.message, /python3/); + return true; + }, + ); + assert.deepEqual(stub.commands, []); }); -test('coerces null fields to undefined in node output', async () => { - mockRunCmd.mockResolvedValue({ - exitCode: 0, - stdout: makePythonResult([ - { - index: 0, - role: 'panel', - label: null, - value: null, - rect: null, - enabled: null, - selected: null, - hittable: false, - depth: 0, - parentIndex: null, - pid: null, - appName: null, - windowTitle: null, - }, - ]), - stderr: '', - }); +test('the AT-SPI capture refuses off a Linux host without touching it', async () => { + const stub = stubPython(TREE); - const result = await captureAccessibilityTree('desktop'); - const node = result.nodes[0]!; - assert.equal(node.label, undefined); - assert.equal(node.value, undefined); - assert.equal(node.rect, undefined); - assert.equal(node.parentIndex, undefined); - assert.equal(node.pid, undefined); - assert.equal(node.appName, undefined); - assert.equal(node.windowTitle, undefined); + await assert.rejects( + () => captureAtspi(stub), + (error: unknown) => { + assert.ok(error instanceof AppError); + assert.equal(error.code, 'UNSUPPORTED_PLATFORM'); + return true; + }, + ); + assert.deepEqual(stub.commands, []); }); diff --git a/packages/platform-linux/src/__tests__/clipboard.test.ts b/packages/platform-linux/src/__tests__/clipboard.test.ts index ea76377172..bea122419f 100644 --- a/packages/platform-linux/src/__tests__/clipboard.test.ts +++ b/packages/platform-linux/src/__tests__/clipboard.test.ts @@ -1,122 +1,98 @@ -import { bindTestCommandHost } from '@agent-device/test-kit'; -import { afterAll, beforeEach, test, vi } from 'vitest'; +import { test } from 'vitest'; import assert from 'node:assert/strict'; - -vi.mock('@agent-device/host-kit/command', async (importOriginal) => { - const actual = await importOriginal(); - return { ...actual, runCmd: vi.fn(), whichCmd: vi.fn() }; -}); - -import { runCmd, whichCmd } from '@agent-device/host-kit/command'; +import { createLinuxHostStub, type LinuxHostStub } from '../toolbox.fixtures.ts'; +import { createLinuxToolProvider } from '../tool-provider.ts'; import { readLinuxClipboard, writeLinuxClipboard } from '../clipboard.ts'; import { AppError } from '@agent-device/kernel/errors'; -bindTestCommandHost(); - -const mockRunCmd = vi.mocked(runCmd); -const mockWhichCmd = vi.mocked(whichCmd); - -const originalEnv = { ...process.env }; - -function setupX11(): void { - process.env['XDG_SESSION_TYPE'] = 'x11'; - delete process.env['WAYLAND_DISPLAY']; -} - -function setupWayland(): void { - process.env['XDG_SESSION_TYPE'] = 'wayland'; - process.env['WAYLAND_DISPLAY'] = 'wayland-0'; +function stubFor(display: 'x11' | 'wayland', tools: readonly string[]): LinuxHostStub { + return createLinuxHostStub({ + env: { + PATH: '/usr/bin', + XDG_SESSION_TYPE: display, + ...(display === 'wayland' ? { WAYLAND_DISPLAY: 'wayland-0' } : {}), + }, + tools, + respond: () => ({ stdout: display === 'wayland' ? 'wayland content' : 'clipboard content' }), + }); } -beforeEach(() => { - mockRunCmd.mockReset(); - mockWhichCmd.mockReset(); -}); - -afterAll(() => { - Object.assign(process.env, originalEnv); -}); +/** wl-clipboard installs `wl-paste` and `wl-copy` together, and the family probes for the pair. */ +const WAYLAND_CLIPBOARD = ['wl-paste', 'wl-copy']; -// ── X11 clipboard ──────────────────────────────────────────────────────── +// ── X11 ────────────────────────────────────────────────────────────────── test('readLinuxClipboard uses xclip on X11', async () => { - setupX11(); - mockWhichCmd.mockImplementation(async (cmd) => cmd === 'xclip'); - mockRunCmd.mockResolvedValue({ exitCode: 0, stdout: 'clipboard content', stderr: '' }); - - const result = await readLinuxClipboard(); - assert.equal(result, 'clipboard content'); - assert.equal(mockRunCmd.mock.calls[0]![0], 'xclip'); - assert.ok((mockRunCmd.mock.calls[0]![1] as string[]).includes('-o')); + const stub = stubFor('x11', ['xclip']); + + assert.equal(await readLinuxClipboard(createLinuxToolProvider(stub.toolbox)), 'clipboard content'); + const command = stub.commands[0]!; + assert.equal(command.executable, 'xclip'); + assert.deepEqual(command.args, ['-selection', 'clipboard', '-o']); + assert.equal(command.allowFailure, true); }); test('readLinuxClipboard falls back to xsel on X11', async () => { - setupX11(); - mockWhichCmd.mockImplementation(async (cmd) => cmd === 'xsel'); - mockRunCmd.mockResolvedValue({ exitCode: 0, stdout: 'from xsel', stderr: '' }); + const stub = stubFor('x11', ['xsel']); - const result = await readLinuxClipboard(); - assert.equal(result, 'from xsel'); - assert.equal(mockRunCmd.mock.calls[0]![0], 'xsel'); + assert.equal(await readLinuxClipboard(createLinuxToolProvider(stub.toolbox)), 'clipboard content'); + assert.equal(stub.commands[0]?.executable, 'xsel'); }); -test('writeLinuxClipboard uses xclip with stdin on X11', async () => { - setupX11(); - mockWhichCmd.mockImplementation(async (cmd) => cmd === 'xclip'); - mockRunCmd.mockResolvedValue({ exitCode: 0, stdout: '', stderr: '' }); +test('writeLinuxClipboard pipes the text to xclip on X11', async () => { + const stub = stubFor('x11', ['xclip']); + + await writeLinuxClipboard(createLinuxToolProvider(stub.toolbox), 'hello'); - await writeLinuxClipboard('hello'); - assert.equal(mockRunCmd.mock.calls[0]![0], 'xclip'); - assert.equal((mockRunCmd.mock.calls[0]![2] as Record).stdin, 'hello'); + const command = stub.commands[0]!; + assert.equal(command.executable, 'xclip'); + assert.equal(command.stdin, 'hello'); }); -test('readLinuxClipboard throws TOOL_MISSING when no tool on X11', async () => { - setupX11(); - mockWhichCmd.mockResolvedValue(false); +test('readLinuxClipboard refuses with TOOL_MISSING when X11 has no clipboard tool', async () => { + const stub = stubFor('x11', []); await assert.rejects( - () => readLinuxClipboard(), - (err: unknown) => { - assert.ok(err instanceof AppError); - assert.equal(err.code, 'TOOL_MISSING'); - assert.ok(err.message.includes('xclip')); + () => readLinuxClipboard(createLinuxToolProvider(stub.toolbox)), + (error: unknown) => { + assert.ok(error instanceof AppError); + assert.equal(error.code, 'TOOL_MISSING'); + assert.match(error.message, /xclip/); return true; }, ); + assert.deepEqual(stub.commands, []); }); -// ── Wayland clipboard ──────────────────────────────────────────────────── +// ── Wayland ────────────────────────────────────────────────────────────── test('readLinuxClipboard uses wl-paste on Wayland', async () => { - setupWayland(); - mockWhichCmd.mockImplementation(async (cmd) => cmd === 'wl-paste'); - mockRunCmd.mockResolvedValue({ exitCode: 0, stdout: 'wayland content', stderr: '' }); + const stub = stubFor('wayland', WAYLAND_CLIPBOARD); - const result = await readLinuxClipboard(); - assert.equal(result, 'wayland content'); - assert.equal(mockRunCmd.mock.calls[0]![0], 'wl-paste'); + assert.equal(await readLinuxClipboard(createLinuxToolProvider(stub.toolbox)), 'wayland content'); + assert.equal(stub.commands[0]?.executable, 'wl-paste'); + assert.deepEqual(stub.commands[0]?.args, ['--no-newline']); }); test('writeLinuxClipboard uses wl-copy on Wayland', async () => { - setupWayland(); - mockWhichCmd.mockImplementation(async (cmd) => cmd === 'wl-copy' || cmd === 'wl-paste'); - mockRunCmd.mockResolvedValue({ exitCode: 0, stdout: '', stderr: '' }); + const stub = stubFor('wayland', WAYLAND_CLIPBOARD); + + await writeLinuxClipboard(createLinuxToolProvider(stub.toolbox), 'copied'); - await writeLinuxClipboard('copied'); - assert.equal(mockRunCmd.mock.calls[0]![0], 'wl-copy'); - assert.ok((mockRunCmd.mock.calls[0]![1] as string[]).includes('copied')); + const command = stub.commands[0]!; + assert.equal(command.executable, 'wl-copy'); + assert.deepEqual(command.args, ['--', 'copied']); }); -test('readLinuxClipboard throws TOOL_MISSING when no tool on Wayland', async () => { - setupWayland(); - mockWhichCmd.mockResolvedValue(false); +test('readLinuxClipboard refuses with TOOL_MISSING when Wayland has no clipboard tool', async () => { + const stub = stubFor('wayland', []); await assert.rejects( - () => readLinuxClipboard(), - (err: unknown) => { - assert.ok(err instanceof AppError); - assert.equal(err.code, 'TOOL_MISSING'); - assert.ok(err.message.includes('wl-paste')); + () => readLinuxClipboard(createLinuxToolProvider(stub.toolbox)), + (error: unknown) => { + assert.ok(error instanceof AppError); + assert.equal(error.code, 'TOOL_MISSING'); + assert.match(error.message, /wl-paste/); return true; }, ); diff --git a/packages/platform-linux/src/__tests__/input-actions.test.ts b/packages/platform-linux/src/__tests__/input-actions.test.ts index 18a1b7fc78..e6961b782e 100644 --- a/packages/platform-linux/src/__tests__/input-actions.test.ts +++ b/packages/platform-linux/src/__tests__/input-actions.test.ts @@ -1,140 +1,138 @@ -import { bindTestCommandHost } from '@agent-device/test-kit'; -import { afterAll, beforeEach, test, vi } from 'vitest'; +import { test } from 'vitest'; import assert from 'node:assert/strict'; - -vi.mock('@agent-device/host-kit/command', async (importOriginal) => { - const actual = await importOriginal(); - return { ...actual, runCmd: vi.fn(), whichCmd: vi.fn() }; -}); - -import { runCmd, whichCmd } from '@agent-device/host-kit/command'; -import { fillLinux, pressLinux, scrollLinux, typeLinux, sendKey } from '../input-actions.ts'; - -bindTestCommandHost(); - -const mockRunCmd = vi.mocked(runCmd); -const mockWhichCmd = vi.mocked(whichCmd); - -const originalPlatform = process.platform; -const originalEnv = { ...process.env }; - -function setupXdotool(): void { - Object.defineProperty(process, 'platform', { value: 'linux' }); - process.env['XDG_SESSION_TYPE'] = 'x11'; - delete process.env['WAYLAND_DISPLAY']; - mockWhichCmd.mockImplementation(async (cmd) => cmd === 'xdotool'); - mockRunCmd.mockResolvedValue({ exitCode: 0, stdout: '', stderr: '' }); +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 { AppError } from '@agent-device/kernel/errors'; + +function x11Stub(): LinuxHostStub { + return createLinuxHostStub({ + env: { PATH: '/usr/bin', XDG_SESSION_TYPE: 'x11' }, + tools: ['xdotool'], + respond: () => ({}), + }); } -function setupYdotool(): void { - Object.defineProperty(process, 'platform', { value: 'linux' }); - process.env['XDG_SESSION_TYPE'] = 'wayland'; - process.env['WAYLAND_DISPLAY'] = 'wayland-0'; - mockWhichCmd.mockImplementation(async (cmd) => cmd === 'ydotool'); - mockRunCmd.mockResolvedValue({ exitCode: 0, stdout: '', stderr: '' }); +function waylandStub(): LinuxHostStub { + return createLinuxHostStub({ + env: { PATH: '/usr/bin', XDG_SESSION_TYPE: 'wayland', WAYLAND_DISPLAY: 'wayland-0' }, + tools: ['ydotool'], + respond: () => ({}), + }); } -/** Extract the [command, args] pairs from all runCmd calls. */ -function calls(): Array<[string, string[]]> { - return mockRunCmd.mock.calls.map((c) => [c[0], c[1] as string[]]); +function calls(stub: LinuxHostStub): Array<[string, readonly string[]]> { + return stub.commands.map((c) => [c.executable, c.args]); } -beforeEach(() => { - mockRunCmd.mockReset(); - mockWhichCmd.mockReset(); -}); - -afterAll(() => { - Object.defineProperty(process, 'platform', { value: originalPlatform }); - Object.assign(process.env, originalEnv); -}); +function providerOf(stub: LinuxHostStub): LinuxToolProvider { + return createLinuxToolProvider(stub.toolbox); +} -// ── xdotool tests ──────────────────────────────────────────────────────── +// ── xdotool ────────────────────────────────────────────────────────────── test('typeLinux omits --delay when delayMs is 0', async () => { - setupXdotool(); - await typeLinux('test', 0); - const c = calls(); - const typeCall = c.find(([cmd, args]) => cmd === 'xdotool' && args.includes('type')); + const stub = x11Stub(); + await typeLinux(providerOf(stub), 'test', 0); + + const typeCall = calls(stub).find( + ([cmd, args]) => cmd === 'xdotool' && (args as string[]).includes('type'), + ); assert.ok(typeCall); - assert.ok(!typeCall[1].includes('--delay')); + assert.equal((typeCall[1] as string[]).includes('--delay'), false); }); // `fill ""` is the clear-field primitive (#2063). Typing zero characters over the // Ctrl+A selection leaves the old value selected but intact, so the empty fill must delete // the selection instead. test('fillLinux deletes the select-all selection for an empty text', async () => { - setupXdotool(); - await fillLinux(10, 20, ''); - const c = calls(); - const backspaceCall = c.find(([cmd, args]) => cmd === 'xdotool' && args.includes('BackSpace')); - assert.ok(backspaceCall); - const typeCall = c.find(([cmd, args]) => cmd === 'xdotool' && args.includes('type')); - assert.equal(typeCall, undefined); + const stub = x11Stub(); + await fillLinux(providerOf(stub), 10, 20, ''); + + const args = calls(stub).map(([, a]) => a as string[]); + assert.ok(args.some((a) => a.includes('BackSpace'))); + assert.equal(args.some((a) => a.includes('type')), false); }); -test('scrollLinux preserves xdotool repeat count for non-paced scroll', async () => { - setupXdotool(); - await scrollLinux('down', { pixels: 75 }); - const c = calls(); +test('scrollLinux preserves the xdotool repeat count for non-paced scroll', async () => { + const stub = x11Stub(); + await scrollLinux(providerOf(stub), 'down', { pixels: 75 }); + assert.ok( - c.some( + calls(stub).some( ([cmd, args]) => cmd === 'xdotool' && - args.includes('click') && - args.includes('--repeat') && - args.includes('5'), + (args as string[]).includes('click') && + (args as string[]).includes('--repeat') && + (args as string[]).includes('5'), ), ); }); -// ── ydotool tests ──────────────────────────────────────────────────────── +// ── ydotool ────────────────────────────────────────────────────────────── -test('pressLinux uses ydotool mousemove + click on Wayland', async () => { - setupYdotool(); - await pressLinux(100, 200); - const c = calls(); - assert.ok( - c.some( - ([cmd, args]) => - cmd === 'ydotool' && args.includes('mousemove') && args.includes('--absolute'), - ), - ); - assert.ok( - c.some(([cmd, args]) => cmd === 'ydotool' && args.includes('click') && args.includes('0xC0')), - ); +test('pressLinux uses ydotool mousemove and click on Wayland', async () => { + const stub = waylandStub(); + await pressLinux(providerOf(stub), 100, 200); + + const args = calls(stub).map(([, a]) => a as string[]); + assert.ok(args.some((a) => a.includes('mousemove') && a.includes('--absolute'))); + assert.ok(args.some((a) => a.includes('click') && a.includes('0xC0'))); }); test('sendKey uses ydotool with scancodes', async () => { - setupYdotool(); - await sendKey('alt+Left', ['56:1', '105:1', '105:0', '56:0']); - const c = calls(); + const stub = waylandStub(); + await sendKey(providerOf(stub), 'alt+Left', ['56:1', '105:1', '105:0', '56:0']); + assert.ok( - c.some(([cmd, args]) => cmd === 'ydotool' && args.includes('key') && args.includes('56:1')), + calls(stub).some( + ([cmd, args]) => cmd === 'ydotool' && (args as string[]).includes('key') && (args as string[]).includes('56:1'), + ), ); }); test('typeLinux uses ydotool type', async () => { - setupYdotool(); - await typeLinux('hello'); - const c = calls(); + const stub = waylandStub(); + await typeLinux(providerOf(stub), 'hello'); + assert.ok( - c.some(([cmd, args]) => cmd === 'ydotool' && args.includes('type') && args.includes('hello')), + calls(stub).some( + ([cmd, args]) => cmd === 'ydotool' && (args as string[]).includes('type') && (args as string[]).includes('hello'), + ), ); }); test('scrollLinux uses ydotool mousemove --wheel for vertical scroll', async () => { - setupYdotool(); - const result = await scrollLinux('up', { pixels: 80, durationMs: 1 }); - const c = calls(); + const stub = waylandStub(); + const result = await scrollLinux(providerOf(stub), 'up', { pixels: 80, durationMs: 1 }); + assert.ok( - c.some( + calls(stub).some( ([cmd, args]) => cmd === 'ydotool' && - args.includes('mousemove') && - args.includes('--wheel') && - args.includes('-y'), + (args as string[]).includes('mousemove') && + (args as string[]).includes('--wheel') && + (args as string[]).includes('-y'), ), ); assert.equal(result.durationMs, 1); }); + +test('input synthesis refuses with TOOL_MISSING when the host has no tool for the display', async () => { + const stub = createLinuxHostStub({ + env: { PATH: '/usr/bin', XDG_SESSION_TYPE: 'x11' }, + tools: [], + }); + + await assert.rejects( + () => pressLinux(providerOf(stub), 1, 2), + (error: unknown) => { + assert.ok(error instanceof AppError); + assert.equal(error.code, 'TOOL_MISSING'); + assert.match(error.message, /xdotool/); + return true; + }, + ); + assert.deepEqual(stub.commands, []); +}); diff --git a/packages/platform-linux/src/__tests__/interactor-host-isolation.test.ts b/packages/platform-linux/src/__tests__/interactor-host-isolation.test.ts deleted file mode 100644 index b993301f8a..0000000000 --- a/packages/platform-linux/src/__tests__/interactor-host-isolation.test.ts +++ /dev/null @@ -1,84 +0,0 @@ -import { afterAll, beforeEach, test, vi } from 'vitest'; -import assert from 'node:assert/strict'; -import { bindTestCommandHost } from '@agent-device/test-kit'; - -vi.mock('@agent-device/host-kit/command', async (importOriginal) => { - const actual = await importOriginal(); - return { ...actual, runCmd: vi.fn(), whichCmd: vi.fn() }; -}); - -import { runCmd, whichCmd } from '@agent-device/host-kit/command'; -import { createLinuxInteractor } from '../interactor.ts'; -import type { HostEnvironment } from '@agent-device/kernel/source-value'; - -bindTestCommandHost(); - -// Two composing runtimes drive the plain local provider through their own hosts. Each interactor -// resolves its display decision from its own provider: A(X11) → B(Wayland) → A answers -// xdotool → ydotool → xdotool, against a process environment that claims Wayland for everyone. -// The old ambient decision answered host A's X11 for host B (#3794). - -const originalPlatform = process.platform; -const originalEnv = { ...process.env }; - -const mockRunCmd = vi.mocked(runCmd); -const mockWhichCmd = vi.mocked(whichCmd); - -function hostWithEnv(env: Record): HostEnvironment { - return { env: { ...process.env, ...env }, cwd: process.cwd() }; -} - -beforeEach(() => { - Object.defineProperty(process, 'platform', { value: 'linux' }); - // The process environment claims a Wayland session for the whole machine; neither host names - // this display, so any answer read from the process instead of the runtime host is wrong here. - process.env['WAYLAND_DISPLAY'] = 'wayland-9'; - process.env['XDG_SESSION_TYPE'] = 'wayland'; - mockRunCmd.mockReset(); - mockWhichCmd.mockReset(); - mockWhichCmd.mockImplementation(async (cmd) => cmd === 'xdotool' || cmd === 'ydotool'); - mockRunCmd.mockResolvedValue({ exitCode: 0, stdout: '', stderr: '' }); -}); - -afterAll(() => { - Object.defineProperty(process, 'platform', { value: originalPlatform }); - for (const key of Object.keys(process.env)) { - if (!(key in originalEnv)) delete process.env[key]; - } - Object.assign(process.env, originalEnv); -}); - -function synthesisCommands(): string[] { - return mockRunCmd.mock.calls - .map(([cmd, args]) => ({ cmd, first: (args as string[])[0] })) - .filter(({ cmd, first }) => cmd !== 'xdotool' || first !== 'getmouselocation') - .map(({ cmd }) => cmd); -} - -test('interactors on different hosts resolve input through their own host display', async () => { - const hostA = hostWithEnv({ WAYLAND_DISPLAY: undefined, XDG_SESSION_TYPE: 'x11' }); - const hostB = hostWithEnv({ WAYLAND_DISPLAY: 'wayland-1', XDG_SESSION_TYPE: 'wayland' }); - const interactorA = createLinuxInteractor(hostA); - const interactorB = createLinuxInteractor(hostB); - - // Phase A: the X11 host resolves xdotool from its own host env. - await interactorA.tap!(1, 2); - assert.deepEqual(synthesisCommands(), ['xdotool', 'xdotool']); - - // Phase B: the Wayland host must resolve ydotool even though A resolved xdotool first. The - // old ambient decision answered host A's X11 here, against B's own host. - mockRunCmd.mockClear(); - await interactorB.tap!(3, 4); - assert.deepEqual( - mockRunCmd.mock.calls.map(([cmd, args]) => [cmd, ...(args as string[])]), - [ - ['ydotool', 'mousemove', '--absolute', '-x', '3', '-y', '4'], - ['ydotool', 'click', '0xC0'], - ], - ); - - // Phase A again: B's Wayland answer never leaked into A's provider. - mockRunCmd.mockClear(); - await interactorA.tap!(5, 6); - assert.deepEqual(synthesisCommands(), ['xdotool', 'xdotool']); -}); diff --git a/packages/platform-linux/src/__tests__/snapshot.test.ts b/packages/platform-linux/src/__tests__/snapshot.test.ts index 88b401b7a9..21d52164c0 100644 --- a/packages/platform-linux/src/__tests__/snapshot.test.ts +++ b/packages/platform-linux/src/__tests__/snapshot.test.ts @@ -1,162 +1,103 @@ -import { beforeEach, test, vi } from 'vitest'; +import { test } from 'vitest'; import assert from 'node:assert/strict'; import type { RawSnapshotNode } from '@agent-device/kernel/snapshot'; - -const { captureAccessibilityTree } = vi.hoisted(() => ({ - captureAccessibilityTree: vi.fn(), -})); - -// snapshot.ts consumes the AT-SPI2 bridge seam; fake it rather than a generic exec mock. -vi.mock('../atspi-bridge.ts', () => ({ captureAccessibilityTree })); - +import { createLinuxHostStub } from '../toolbox.fixtures.ts'; +import { createLinuxToolProvider } from '../tool-provider.ts'; import { readLinuxTextAtPoint, snapshotLinux } from '../snapshot.ts'; -const mockCapture = vi.mocked(captureAccessibilityTree); - function node(partial: Partial & { index: number }): RawSnapshotNode { return { type: 'text', ...partial }; } -function captureNodes(nodes: RawSnapshotNode[]): void { - mockCapture.mockResolvedValue({ nodes, truncated: false, surface: 'desktop' }); +/** + * The capture route under test: the AT-SPI answer is stated by the test, so a test about which + * surface was captured, or about what the hit-test returned, needs neither Python nor a registry. + */ +function host( + nodes: readonly RawSnapshotNode[], + answer: Readonly<{ truncated?: boolean }> = {}, +): Readonly<{ + stub: ReturnType; + provider: ReturnType; + captures: Array<[string, unknown]>; +}> { + const captures: Array<[string, unknown]> = []; + const stub = createLinuxHostStub({ env: { PATH: '/usr/bin', XDG_SESSION_TYPE: 'x11' } }); + const provider = createLinuxToolProvider(stub.toolbox, { + accessibility: { + captureTree: async (surface, options) => { + captures.push([surface, { signal: options?.signal }]); + return { nodes, truncated: answer.truncated ?? false, surface }; + }, + }, + }); + return { stub, provider, captures }; } -beforeEach(() => { - mockCapture.mockReset(); -}); - test('snapshotLinux maps the app surface to the frontmost app and forwards the signal', async () => { const signal = new AbortController().signal; - captureNodes([]); + const { stub, provider, captures } = host([]); - await snapshotLinux('app', signal); + await snapshotLinux(stub.toolbox, provider, 'app', signal); - assert.deepEqual(mockCapture.mock.calls[0], ['frontmost-app', { signal }]); + assert.deepEqual(captures, [['frontmost-app', { signal }]]); }); test('snapshotLinux falls back to desktop for the unsupported menubar surface', async () => { - captureNodes([]); - - await snapshotLinux('menubar'); - - assert.equal(mockCapture.mock.calls[0]?.[0], 'desktop'); + const { stub, provider, captures } = host([]); + + await snapshotLinux(stub.toolbox, provider, 'menubar'); + + assert.deepEqual(captures.map(([surface]) => surface), ['desktop']); + // The fallback is reported through the host, so `--debug` says why the capture is the whole desktop. + assert.deepEqual(stub.diagnostics, [ + { + level: 'warn', + phase: 'linux_snapshot', + data: { message: 'menubar surface is not supported on Linux, falling back to desktop' }, + }, + ]); }); -test('readLinuxTextAtPoint prefers the deepest match and the smaller area at equal depth', async () => { - captureNodes([ - node({ - index: 0, - depth: 0, - label: 'window', - rect: { x: 0, y: 0, width: 200, height: 200 }, - }), - node({ - index: 1, - depth: 1, - label: 'outer-group', - rect: { x: 10, y: 10, width: 100, height: 100 }, - }), - node({ - index: 2, - depth: 1, - label: 'button', - rect: { x: 20, y: 20, width: 40, height: 20 }, - }), - node({ - index: 3, - depth: 1, - label: 'elsewhere', - rect: { x: 150, y: 150, width: 30, height: 30 }, - }), - node({ index: 4, depth: 2, label: 'no-rect' }), - ]); +test('snapshotLinux keeps the capture bounds the AT-SPI helper reported', async () => { + const nodes = [node({ index: 0, label: 'window' })]; + const { stub, provider } = host(nodes, { truncated: true }); - const text = await readLinuxTextAtPoint(30, 25, 'desktop'); + const result = await snapshotLinux(stub.toolbox, provider, 'desktop'); - // Deepest first among equal depths, the narrower rect wins: the 40x20 button, not the 100x100 group. - assert.equal(text, 'button'); + assert.deepEqual(result, { nodes, truncated: true }); }); -test('readLinuxTextAtPoint skips matches without readable text and reads value before label', async () => { - captureNodes([ - node({ - index: 0, - depth: 1, - label: '', - value: '', - rect: { x: 0, y: 0, width: 10, height: 10 }, - }), - node({ - index: 1, - depth: 0, - value: 'entry-value', - label: 'ignored-label', - rect: { x: 0, y: 0, width: 40, height: 40 }, - }), +test('readLinuxTextAtPoint prefers the deepest match and the smaller area at equal depth', async () => { + const { stub, provider } = host([ + node({ index: 0, depth: 0, label: 'window', rect: { x: 0, y: 0, width: 800, height: 600 } }), + node({ index: 1, depth: 3, label: 'button', rect: { x: 10, y: 10, width: 200, height: 100 } }), + node({ index: 2, depth: 3, label: 'icon', rect: { x: 50, y: 50, width: 20, height: 20 } }), ]); - assert.equal(await readLinuxTextAtPoint(5, 5, 'desktop'), 'entry-value'); -}); + const text = await readLinuxTextAtPoint(stub.toolbox, provider, 55, 55, 'desktop'); -test('readLinuxTextAtPoint reads the identifier when value and label are absent', async () => { - captureNodes([ - node({ - index: 0, - depth: 0, - identifier: 'accessibility-id', - rect: { x: 0, y: 0, width: 10, height: 10 }, - }), - ]); - - assert.equal(await readLinuxTextAtPoint(5, 5, 'desktop'), 'accessibility-id'); + assert.equal(text, 'icon'); }); -test('readLinuxTextAtPoint returns an empty string when no rect covers the point', async () => { - captureNodes([ +test('readLinuxTextAtPoint reads the value before the label', async () => { + const { stub, provider } = host([ node({ index: 0, depth: 0, - label: 'far', - rect: { x: 100, y: 100, width: 10, height: 10 }, + value: 'typed text', + label: 'field label', + rect: { x: 0, y: 0, width: 100, height: 100 }, }), ]); - assert.equal(await readLinuxTextAtPoint(0, 0, 'desktop'), ''); -}); - -test('readLinuxTextAtPoint ties depth 0 through rect area when rects are degenerate', async () => { - // A zero-width or zero-height rect still has area 0 (0 * 10 === 0 * 0), so the pair ties on - // area and resolves by tree order; and neither rect covers a point one pixel out, so the - // inclusive-boundary match, not a size fudge, decides whether anything reads at all. - captureNodes([ - node({ index: 0, depth: 0, label: 'first', rect: { x: 0, y: 0, width: 0, height: 0 } }), - node({ index: 1, depth: 0, label: 'second', rect: { x: 0, y: 0, width: 0, height: 10 } }), - ]); - - // Vitest/JS sort is stable, so equal depth and equal area resolve in tree order. - assert.equal(await readLinuxTextAtPoint(0, 0, 'desktop'), 'first'); - assert.equal(await readLinuxTextAtPoint(1, 1, 'desktop'), ''); + assert.equal(await readLinuxTextAtPoint(stub.toolbox, provider, 5, 5, 'desktop'), 'typed text'); }); -test('readLinuxTextAtPoint ranks a missing depth as depth 0, in both sort directions', async () => { - // Two fixtures pin the default to exactly 0. Here `no-depth` ties the depth-0 nodes and loses - // only on area, so any fallback above 0 (or 1) ranks it deeper than them and it — not - // `smaller` — would come back from the read. - captureNodes([ - node({ index: 0, label: 'no-depth', rect: { x: 0, y: 0, width: 100, height: 100 } }), - node({ index: 1, depth: 0, label: 'root', rect: { x: 0, y: 0, width: 100, height: 100 } }), - node({ index: 2, depth: 0, label: 'smaller', rect: { x: 0, y: 0, width: 60, height: 60 } }), - ]); - - assert.equal(await readLinuxTextAtPoint(50, 50, 'desktop'), 'smaller'); - - // The complement catches a negative fallback: the missing-depth node carries the smaller - // area, so depth 0 ranks it first among the depth-0 matches, while any fallback below 0 - // ranks it behind `root` and the read would return `root`. - captureNodes([ - node({ index: 0, depth: 0, label: 'root', rect: { x: 0, y: 0, width: 100, height: 100 } }), - node({ index: 1, label: 'no-depth', rect: { x: 0, y: 0, width: 60, height: 60 } }), +test('readLinuxTextAtPoint answers the empty string when nothing covers the point', async () => { + const { stub, provider } = host([ + node({ index: 0, depth: 0, label: 'window', rect: { x: 0, y: 0, width: 10, height: 10 } }), ]); - assert.equal(await readLinuxTextAtPoint(50, 50, 'desktop'), 'no-depth'); + assert.equal(await readLinuxTextAtPoint(stub.toolbox, provider, 500, 500, 'desktop'), ''); }); diff --git a/packages/platform-linux/src/__tests__/surface-snapshot.test.ts b/packages/platform-linux/src/__tests__/surface-snapshot.test.ts index 5593fe012f..b1657363af 100644 --- a/packages/platform-linux/src/__tests__/surface-snapshot.test.ts +++ b/packages/platform-linux/src/__tests__/surface-snapshot.test.ts @@ -1,48 +1,58 @@ -import { beforeEach, expect, test, vi } from 'vitest'; +import { test } from 'vitest'; +import assert from 'node:assert/strict'; +import type { RawSnapshotNode } from '@agent-device/kernel/snapshot'; +import { createLinuxHostStub } from '../toolbox.fixtures.ts'; +import { createLinuxToolProvider } from '../tool-provider.ts'; +import { captureLinuxSurfaceSnapshot } from '../surface-snapshot.ts'; -const { snapshotLinux } = vi.hoisted(() => ({ - snapshotLinux: vi.fn(), -})); +function node(partial: Partial & { index: number }): RawSnapshotNode { + return { type: 'text', ...partial }; +} -vi.mock('../snapshot.ts', () => ({ snapshotLinux })); +test('the Linux surface capture stamps its producer and projects the shape', async () => { + const stub = createLinuxHostStub({ env: { PATH: '/usr/bin', XDG_SESSION_TYPE: 'x11' } }); + const provider = createLinuxToolProvider(stub.toolbox, { + accessibility: { + captureTree: async surface => ({ + nodes: [node({ index: 0, label: 'Files', rect: { x: 0, y: 0, width: 10, height: 10 } })], + truncated: false, + surface, + }), + }, + }); -import { captureLinuxSurfaceSnapshot } from '../surface-snapshot.ts'; + const result = await captureLinuxSurfaceSnapshot(stub.toolbox, provider, { + surface: 'desktop', + }); -beforeEach(() => { - snapshotLinux.mockReset(); + assert.equal(result.producer, 'linux-atspi'); + assert.deepEqual( + (result.nodes ?? []).map(n => n.label), + ['Files'], + ); }); -test('Linux surface snapshots preserve interactive ancestors before depth filtering', async () => { - snapshotLinux.mockResolvedValue({ - truncated: false, - nodes: [ - { index: 0, depth: 0, type: 'Application', label: 'App' }, - { index: 1, parentIndex: 0, depth: 1, type: 'Group', label: 'Panel' }, - { index: 2, parentIndex: 1, depth: 2, type: 'Button', label: 'Continue', hittable: true }, - { index: 3, parentIndex: 1, depth: 2, type: 'StaticText', label: 'Details' }, - ], +test('the Linux surface capture applies the request projection options', async () => { + const stub = createLinuxHostStub({ env: { PATH: '/usr/bin', XDG_SESSION_TYPE: 'x11' } }); + const provider = createLinuxToolProvider(stub.toolbox, { + accessibility: { + captureTree: async surface => ({ + nodes: [ + { index: 0, type: 'Group', label: 'desktop', depth: 0 }, + { index: 1, type: 'Button', label: 'Files', depth: 1, parentIndex: 0 }, + { index: 2, type: 'StaticText', label: 'Trash', depth: 3, parentIndex: 1 }, + ], + truncated: false, + surface, + }), + }, }); - const signal = new AbortController().signal; - const result = await captureLinuxSurfaceSnapshot( - { surface: 'desktop', interactiveOnly: true, depth: 1 }, - signal, - ); + const result = await captureLinuxSurfaceSnapshot(stub.toolbox, provider, { depth: 1 }); - expect(snapshotLinux).toHaveBeenCalledWith('desktop', signal); - expect(result).toEqual({ - backend: 'linux-atspi', - producer: 'linux-atspi', - truncated: false, - nodes: [ - { index: 0, depth: 0, type: 'Application', label: 'App', parentIndex: undefined }, - { - index: 1, - parentIndex: 0, - depth: 1, - type: 'Group', - label: 'Panel', - }, - ], - }); + // The family owns the capture, and still returns the shape the rest of the system projects. + assert.deepEqual( + (result.nodes ?? []).map(n => n.label), + ['desktop', 'Files'], + ); }); diff --git a/packages/platform-linux/src/__tests__/tool-provider.test.ts b/packages/platform-linux/src/__tests__/tool-provider.test.ts index 6a8894c0ce..7b10e43c65 100644 --- a/packages/platform-linux/src/__tests__/tool-provider.test.ts +++ b/packages/platform-linux/src/__tests__/tool-provider.test.ts @@ -1,56 +1,46 @@ -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 { test } from 'vitest'; import assert from 'node:assert/strict'; +import { createLinuxHostStub, type LinuxHostStub } from '../toolbox.fixtures.ts'; +import { createLinuxToolProvider } from '../tool-provider.ts'; import { pressLinux } from '../input-actions.ts'; -import { - createLocalLinuxToolProvider, - resolveLinuxToolProvider, - withLinuxToolProvider, - type LinuxToolCommandExecutor, - type LinuxToolDetachedLauncher, - type LinuxToolProviderOverrides, -} from '../tool-provider.ts'; -import type { ExecDetachedExit } from '@agent-device/host-kit/command'; - -bindTestCommandHost(); - -/** For a provider that injects an executor and launches no app in the scenario. */ -const launchesNoApp: LinuxToolDetachedLauncher = (cmd) => { - throw new Error(`this scenario launches no app: ${cmd}`); -}; - -const originalPlatform = process.platform; -const originalEnv = { ...process.env }; - -beforeEach(() => { - Object.defineProperty(process, 'platform', { value: 'linux' }); - process.env['XDG_SESSION_TYPE'] = 'x11'; - delete process.env['WAYLAND_DISPLAY']; -}); +import type { LinuxToolProviderOverrides } from '../tool-provider.ts'; -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) => { - commands.push([cmd, args]); - return { exitCode: 0, stdout: '', stderr: '' }; - }, +function x11Stub(tools: readonly string[] = ['xdotool'], overrides: LinuxHostOverrides = {}) { + return createLinuxHostStub({ + env: { PATH: '/usr/bin', XDG_SESSION_TYPE: 'x11' }, + tools, + ...overrides, }); +} - await withLinuxToolProvider(provider, async () => { - await pressLinux(100, 200); +function waylandStub(tools: readonly string[] = ['ydotool']) { + return createLinuxHostStub({ + env: { PATH: '/usr/bin', XDG_SESSION_TYPE: 'wayland', WAYLAND_DISPLAY: 'wayland-0' }, + tools, }); +} + +type LinuxHostOverrides = Partial[0]>; + +/** + * The provider under test. Interaction pacing is replaced so a test about which tool ran never + * waits on a real clock; the pacing itself is asserted separately. + */ +function providerFor(stub: LinuxHostStub, overrides: LinuxToolProviderOverrides = {}) { + return createLinuxToolProvider(stub.toolbox, { sleep: async () => {}, ...overrides }); +} + +const tuples = ( + commands: readonly { executable: string; args: readonly string[] }[], +): Array<[string, string[]]> => + commands.map((c) => [c.executable, [...c.args]] as [string, string[]]); - assert.deepEqual(commands, [ +test('the provider routes input through the tool its host reports', async () => { + const stub = x11Stub(); + + await pressLinux(providerFor(stub), 100, 200); + + assert.deepEqual(tuples(stub.commands), [ // The position probe guards the --sync move: a no-op move emits no motion event and hangs. ['xdotool', ['getmouselocation', '--shell']], ['xdotool', ['mousemove', '--sync', '100', '200']], @@ -58,41 +48,46 @@ test('scoped Linux tool provider handles input discovery and command execution', ]); }); +test('the provider hands every command the host environment it was set up with', async () => { + const stub = x11Stub(); + + await pressLinux(providerFor(stub), 1, 2); + + assert.ok(stub.commands.length > 0); + for (const command of stub.commands) { + assert.equal(command.env?.XDG_SESSION_TYPE, 'x11'); + assert.equal(command.env?.PATH, '/usr/bin'); + } +}); + 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) => { - commands.push([cmd, args]); - const stdout = args[0] === 'getmouselocation' ? 'X=100\nY=200\nSCREEN=0\nWINDOW=1' : ''; - return { exitCode: 0, stdout, stderr: '' }; - }, + const stub = createLinuxHostStub({ + env: { PATH: '/usr/bin', XDG_SESSION_TYPE: 'x11' }, + tools: ['xdotool'], + respond: (executable, args) => + executable === 'xdotool' && args[0] === 'getmouselocation' + ? { stdout: 'X=100\nY=200\nSCREEN=0\nWINDOW=1' } + : {}, }); - await withLinuxToolProvider(provider, async () => { - await pressLinux(100, 200); - }); + await pressLinux(providerFor(stub), 100, 200); // No mousemove: moving to the current position would wait forever for a motion event. - assert.deepEqual(commands, [ + assert.deepEqual(tuples(stub.commands), [ ['xdotool', ['getmouselocation', '--shell']], ['xdotool', ['click', '1']], ]); }); -test('scoped Linux input provider handles semantic input without host tool discovery', async () => { +test('a scoped input provider answers synthesis 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}`); - }, - runCommand: async (cmd) => { - throw new Error(`unexpected host input command: ${cmd}`); + const stub = createLinuxHostStub({ + env: { PATH: '/usr/bin', XDG_SESSION_TYPE: 'x11' }, + respond: () => { + throw new Error('the injected input route owns synthesis'); }, + }); + const provider = providerFor(stub, { input: { click: async (x, y, button) => { inputCalls.push(['click', String(x), String(y), button]); @@ -106,246 +101,142 @@ test('scoped Linux input provider handles semantic input without host tool disco }, }); - await withLinuxToolProvider(provider, async () => { - await pressLinux(100, 200); - }); + await pressLinux(provider, 100, 200); assert.deepEqual(inputCalls, [['click', '100', '200', 'primary']]); + assert.deepEqual(stub.commands, []); }); -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(), - }, - whichCommand: async (cmd) => cmd === 'xdotool', - 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(), - }, - whichCommand: async (cmd) => cmd === 'ydotool', - runCommand: async () => ({ exitCode: 0, stdout: '', stderr: '' }), - }); - - await withLinuxToolProvider(providerA, async () => { - await pressLinux(1, 2); - }); +test('two providers built on different hosts keep separate display decisions (#3794)', async () => { + const x11 = x11Stub(); + await pressLinux(providerFor(x11), 1, 2); - process.env['XDG_SESSION_TYPE'] = 'wayland'; - process.env['WAYLAND_DISPLAY'] = 'wayland-0'; - const commands: Array<[string, string[]]> = []; + const wayland = waylandStub(); + await pressLinux(providerFor(wayland), 3, 4); - await withLinuxToolProvider( - createLocalLinuxToolProvider({ - host: { - env: { ...process.env, XDG_SESSION_TYPE: 'wayland', WAYLAND_DISPLAY: 'wayland-0' }, - cwd: process.cwd(), - }, - ...providerB, - runCommand: async (cmd, args) => { - commands.push([cmd, args]); - return { exitCode: 0, stdout: '', stderr: '' }; - }, - }), - async () => { - await pressLinux(3, 4); - }, + assert.equal( + tuples(x11.commands).some( + ([cmd, args]) => cmd === 'xdotool' && args.includes('mousemove') && args.includes('--sync'), + ), + true, ); - - assert.deepEqual(commands, [ + assert.deepEqual(tuples(wayland.commands), [ ['ydotool', ['mousemove', '--absolute', '-x', '3', '-y', '4']], ['ydotool', ['click', '0xC0']], ]); }); -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) => { - commands.push([cmd, args, options?.allowFailure]); - return { exitCode: 0, stdout: '', stderr: '' }; - }, - }); +test('the desktop provider translates semantic lifecycle calls to host tools', async () => { + const stub = x11Stub(['wmctrl']); + const provider = providerFor(stub); await provider.desktop.openTarget('https://example.test'); await provider.desktop.openTarget('demo.desktop'); await provider.desktop.closeApp('Demo'); - assert.deepEqual(commands, [ - ['xdg-open', ['https://example.test'], undefined], - ['xdg-open', ['demo.desktop'], true], - ['wmctrl', ['-c', 'Demo'], true], + assert.deepEqual(tuples(stub.commands), [ + ['xdg-open', ['https://example.test']], + ['xdg-open', ['demo.desktop']], + ['wmctrl', ['-c', 'Demo']], ]); + // The URL opens or fails the request; the .desktop fallback and the window close tolerate failure. + assert.deepEqual( + stub.commands.map((c) => c.allowFailure), + [undefined, true, true], + ); }); -// `open ` used to run the app as a piped child of the daemon, which kept every -// byte the app printed in daemon memory for the app's whole life. The default launcher detaches, -// for a provider built over a host and for the ambient one a call outside any runtime resolves. -test.skipIf(!fs.existsSync('/proc/self/fd')).each([ - [ - 'a host-built', - () => - createLocalLinuxToolProvider({ - host: { env: process.env, cwd: process.cwd() }, - whichCommand: async (cmd) => cmd === 'fake-desktop-app', - }), - ], - ['the ambient', () => resolveLinuxToolProvider()], -] as const)( - '%s Linux desktop provider launches an app binary detached from daemon pipes', - async (_name, makeProvider) => { - const binDir = await mkdtempForTest('linux-open-binary-'); - const report = path.join(binDir, 'stdout-target'); - fs.writeFileSync( - path.join(binDir, 'fake-desktop-app'), - `#!/bin/sh\nreadlink /proc/self/fd/2 > '${report}.tmp' && mv '${report}.tmp' '${report}'\n`, - { mode: 0o755 }, - ); - const originalPath = process.env['PATH']; - process.env['PATH'] = `${binDir}${path.delimiter}${originalPath ?? ''}`; - try { - await makeProvider().desktop.openTarget('fake-desktop-app'); - - await vi.waitFor(() => assert.ok(fs.existsSync(report))); - assert.equal(fs.readFileSync(report, 'utf8').trim(), '/dev/null'); - } finally { - process.env['PATH'] = originalPath; - } - }, -); - -test('local Linux desktop provider launches an app binary through its detached launcher', async () => { - const launches: Array<[string, string[]]> = []; - const captured: string[] = []; - const provider = createLocalLinuxToolProvider({ - host: { env: process.env, cwd: process.cwd() }, - whichCommand: async (cmd) => cmd === 'demo-app', - runCommand: async (cmd) => { - captured.push(cmd); - return { exitCode: 0, stdout: '', stderr: '' }; - }, - launchDetached: (cmd, args) => { - launches.push([cmd, args]); - return { exited: new Promise(() => {}) }; +test('the desktop provider launches an app binary through the host detached launcher', async () => { + const stub = x11Stub(['demo-app']); + + await providerFor(stub).desktop.openTarget('demo-app'); + + assert.deepEqual( + stub.launches.map((l) => [l.executable, [...l.args]]), + [['demo-app', []]], + ); + assert.deepEqual(stub.commands, []); +}); + +test('the desktop provider paces the request after a detached launch', async () => { + const stub = x11Stub(['demo-app']); + const paced: number[] = []; + const provider = createLinuxToolProvider(stub.toolbox, { + sleep: async (milliseconds) => { + paced.push(milliseconds); }, }); await provider.desktop.openTarget('demo-app'); - assert.deepEqual(launches, [['demo-app', []]]); - assert.deepEqual(captured, []); + assert.deepEqual(paced, [500]); }); -/** The `linux_app_launch` events one `openTarget` writes, once its launch has exited. */ -async function launchDiagnostics(exit: ExecDetachedExit): Promise[]> { - const logPath = path.join(await mkdtempForTest('linux-launch-diagnostics-'), 'request.ndjson'); - let exited: Promise | undefined; - const provider = createLocalLinuxToolProvider({ - host: { env: process.env, cwd: process.cwd() }, - whichCommand: async () => true, - launchDetached: () => { - exited = Promise.resolve(exit); - return { exited }; - }, - }); - return await withDiagnosticsScope({ command: 'open', debug: true, logPath }, async () => { - await provider.desktop.openTarget('demo-app'); - await exited; - const expected = countDiagnosticEventsByPhase(['linux_app_launch']); - const read = () => - (fs.existsSync(logPath) ? fs.readFileSync(logPath, 'utf8').trim().split('\n') : []) - .filter((line) => line.length > 0) - .map((line) => JSON.parse(line) as { phase: string; data?: Record }) - .filter((event) => event.phase === 'linux_app_launch'); - await vi.waitFor(() => assert.equal(read().length, expected)); - return read().map((event) => event.data ?? {}); +test('the desktop provider reports a launched app that ended badly', async () => { + const stub = createLinuxHostStub({ + env: { PATH: '/usr/bin', XDG_SESSION_TYPE: 'x11' }, + tools: ['demo-app'], + launchExit: () => ({ pid: 7, exitCode: 3 }), }); -} -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 }), []); + await providerFor(stub).desktop.openTarget('demo-app'); + await flushMicrotasks(); + + assert.deepEqual(stub.diagnostics, [ + { level: 'warn', phase: 'linux_app_launch', data: { app: 'demo-app', exitCode: 3 } }, + ]); }); -// 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. -function compileTimeInjectedExecutorNeedsLauncherProof(): void { - const runCommand: LinuxToolCommandExecutor = async () => ({ - exitCode: 0, - stdout: '', - stderr: '', +test('the desktop provider reports a launched app that could not start', async () => { + const stub = createLinuxHostStub({ + env: { PATH: '/usr/bin', XDG_SESSION_TYPE: 'x11' }, + tools: ['demo-app'], + launchExit: () => ({ pid: 0, error: 'spawn demo-app ENOENT' }), }); - // @ts-expect-error runCommand without launchDetached - const withoutLauncher: LinuxToolProviderOverrides = { runCommand }; - const withLauncher: LinuxToolProviderOverrides = { runCommand, launchDetached: launchesNoApp }; - void [withoutLauncher, withLauncher]; -} -void compileTimeInjectedExecutorNeedsLauncherProof; - -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) => { - commands.push([cmd, args, options?.allowFailure]); - return { exitCode: 0, stdout: '', stderr: '' }; + + await providerFor(stub).desktop.openTarget('demo-app'); + await flushMicrotasks(); + + assert.deepEqual(stub.diagnostics, [ + { + level: 'warn', + phase: 'linux_app_launch', + data: { app: 'demo-app', error: 'spawn demo-app ENOENT' }, }, + ]); +}); + +test('the desktop provider reports nothing for a launched app that exits cleanly', async () => { + const stub = createLinuxHostStub({ + env: { PATH: '/usr/bin', XDG_SESSION_TYPE: 'x11' }, + tools: ['demo-app'], + launchExit: () => ({ pid: 7, exitCode: 0 }), }); - await provider.desktop.closeApp('Demo'); + await providerFor(stub).desktop.openTarget('demo-app'); + await flushMicrotasks(); - assert.deepEqual(commands, [['pkill', ['-x', 'Demo'], true]]); + assert.deepEqual(stub.diagnostics, []); }); -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) => { - commands.push([cmd, args]); - return { exitCode: 0, stdout: '', stderr: '' }; - }, - }); +test('the desktop provider falls back to pkill when the host has no wmctrl', async () => { + const stub = x11Stub([]); - await provider.screenshot!.capture('/tmp/screen.png'); + await providerFor(stub).desktop.closeApp('Demo'); - assert.deepEqual(commands, [['scrot', ['/tmp/screen.png']]]); + assert.deepEqual(tuples(stub.commands), [['pkill', ['-x', 'Demo']]]); + assert.equal(stub.commands[0]?.allowFailure, true); }); -afterAll(() => { - Object.defineProperty(process, 'platform', { value: originalPlatform }); - for (const key of Object.keys(process.env)) { - if (!(key in originalEnv)) { - delete process.env[key]; - } - } - Object.assign(process.env, originalEnv); +test('the screenshot provider translates capture to the tool the host reports', async () => { + const stub = x11Stub(['scrot']); + + await providerFor(stub).screenshot!.capture('/tmp/screen.png'); + + assert.deepEqual(tuples(stub.commands), [['scrot', ['/tmp/screen.png']]]); }); + +/** Lets every promise the launch's exit already settled run, including its diagnostic. */ +async function flushMicrotasks(): Promise { + for (let index = 0; index < 8; index += 1) await Promise.resolve(); +} diff --git a/packages/platform-linux/src/accessibility-types.ts b/packages/platform-linux/src/accessibility-types.ts deleted file mode 100644 index fd42ccc04d..0000000000 --- a/packages/platform-linux/src/accessibility-types.ts +++ /dev/null @@ -1,16 +0,0 @@ -import type { RawSnapshotNode } from '@agent-device/kernel/snapshot'; - -export type LinuxSnapshotSurface = 'desktop' | 'frontmost-app'; - -export type LinuxTraversalOptions = { - maxNodes?: number; - maxDepth?: number; - maxApps?: number; - signal?: AbortSignal; -}; - -export type LinuxAccessibilityTree = { - nodes: RawSnapshotNode[]; - truncated: boolean; - surface: LinuxSnapshotSurface; -}; diff --git a/packages/platform-linux/src/app-lifecycle.ts b/packages/platform-linux/src/app-lifecycle.ts index 1e7e87a0a5..47c06e1373 100644 --- a/packages/platform-linux/src/app-lifecycle.ts +++ b/packages/platform-linux/src/app-lifecycle.ts @@ -1,5 +1,5 @@ +import type { LinuxToolProvider } from '@agent-device/contracts/linux-tool-provider'; import { sendKey } from './input-actions.ts'; -import { resolveLinuxToolProvider } from './tool-provider.ts'; /** * Open an application or URL on Linux. @@ -8,8 +8,8 @@ import { resolveLinuxToolProvider } from './tool-provider.ts'; * - A URL (opens via xdg-open) * - A .desktop file name or binary name */ -export async function openLinuxApp(app: string): Promise { - await resolveLinuxToolProvider().desktop.openTarget(app); +export async function openLinuxApp(provider: LinuxToolProvider, app: string): Promise { + await provider.desktop.openTarget(app); } /** @@ -17,22 +17,22 @@ export async function openLinuxApp(app: string): Promise { * * Uses wmctrl if available, falls back to pkill. */ -export async function closeLinuxApp(app: string): Promise { - await resolveLinuxToolProvider().desktop.closeApp(app); +export async function closeLinuxApp(provider: LinuxToolProvider, app: string): Promise { + await provider.desktop.closeApp(app); } /** * Send Alt+Left arrow to go back (standard browser/app back navigation). */ -export async function backLinux(): Promise { +export async function backLinux(provider: LinuxToolProvider): Promise { // Alt=56, Left=105 - await sendKey('alt+Left', ['56:1', '105:1', '105:0', '56:0']); + await sendKey(provider, 'alt+Left', ['56:1', '105:1', '105:0', '56:0']); } /** * Show desktop (minimize all windows) via Super+D. */ -export async function homeLinux(): Promise { +export async function homeLinux(provider: LinuxToolProvider): Promise { // Super=125, D=32 - await sendKey('super+d', ['125:1', '32:1', '32:0', '125:0']); + await sendKey(provider, 'super+d', ['125:1', '32:1', '32:0', '125:0']); } diff --git a/packages/platform-linux/src/atspi-bridge.ts b/packages/platform-linux/src/atspi-bridge.ts index 885acdfb97..01cab1a9b2 100644 --- a/packages/platform-linux/src/atspi-bridge.ts +++ b/packages/platform-linux/src/atspi-bridge.ts @@ -1,64 +1,29 @@ /** - * AT-SPI2 bridge — shells out to a Python helper that uses PyGObject - * to traverse the accessibility tree. + * The AT-SPI2 capture route: shells out to a Python helper that uses PyGObject to traverse the + * accessibility tree. * - * This avoids the fragile node-gtk native addon (ABI mismatches, - * compilation on CI, etc.) in favour of python3-gi which is the - * reference GObject Introspection consumer and is trivially available - * on every Linux distro. + * This avoids the fragile node-gtk native addon (ABI mismatches, compilation on CI) in favour of + * python3-gi, which is the reference GObject Introspection consumer and is trivially available on + * every Linux distribution. The helper ships with this package, and every command here runs through + * the host the plugin was set up with, so the capture appears in the request's exec trace. */ -import path from 'node:path'; -import { fileURLToPath } from 'node:url'; import { AppError } from '@agent-device/kernel/errors'; import type { RawSnapshotNode, Rect } from '@agent-device/kernel/snapshot'; -import { hostFileExistsSync } from '@agent-device/host-kit/host-file'; import { hostPlatform } from '@agent-device/host-kit/process'; -import { normalizeAtspiRole } from './role-map.ts'; -import { resolveLinuxToolProvider, runLinuxToolCommand } from './tool-provider.ts'; import type { - LinuxAccessibilityTree, + LinuxAccessibilityProvider, LinuxSnapshotSurface, - LinuxTraversalOptions, -} from './accessibility-types.ts'; +} from '@agent-device/contracts/linux-tool-provider'; +import { normalizeAtspiRole } from './role-map.ts'; +import type { LinuxCommandRunner } from './command-runner.ts'; +import { resolveLinuxAtspiScriptPath } from './atspi-script.ts'; -// ── Limits (matching macOS helper's SnapshotTraversalLimits) ──────────── +/** Limits matching the macOS helper's SnapshotTraversalLimits. */ const MAX_DESKTOP_APPS = 24; const MAX_NODES = 1500; const MAX_DEPTH = 12; - -const SCRIPT_NAME = 'atspi-dump.py'; - -let cachedScriptPath: string | null = null; - -/** Resolve atspi-dump.py, which lives under `linux/` at the repo/package root. */ -function resolveScriptPath(): string { - if (cachedScriptPath) return cachedScriptPath; - const thisDir = path.dirname(fileURLToPath(import.meta.url)); - - // Walk upward looking for linux/atspi-dump.py — handles both: - // /linux/ (source; this module lives in platform-linux) - // /linux/ (bundled; this module lives under dist/src/) - let dir = thisDir; - for (let i = 0; i < 6; i++) { - const candidate = path.join(dir, 'linux', SCRIPT_NAME); - if (hostFileExistsSync(candidate)) { - cachedScriptPath = candidate; - return candidate; - } - dir = path.dirname(dir); - } - - throw new AppError( - 'TOOL_MISSING', - `Cannot find ${SCRIPT_NAME}. Ensure the agent-device package is installed correctly.`, - ); -} - -// ── Public types ──────────────────────────────────────────────────────── - -export type TraversalOptions = LinuxTraversalOptions; -export type SnapshotSurface = LinuxSnapshotSurface; +const ATSPI_TIMEOUT_MS = 30_000; type PythonNode = { index: number; @@ -83,99 +48,94 @@ type PythonResult = { error?: string; }; -// ── Public API ────────────────────────────────────────────────────────── - -export async function captureAccessibilityTree( - surface: SnapshotSurface, - options: TraversalOptions = {}, -): Promise { - const provider = resolveLinuxToolProvider().accessibility; - if (provider) return await provider.captureTree(surface, options); - - if (hostPlatform() !== 'linux') { - throw new AppError('UNSUPPORTED_PLATFORM', 'AT-SPI2 bridge is only available on Linux'); - } - - if (!(await resolveLinuxToolProvider().whichCommand('python3'))) { - throw new AppError( - 'TOOL_MISSING', - 'python3 is required for AT-SPI2 accessibility snapshots on Linux.', - ); - } - - const maxNodes = options.maxNodes ?? MAX_NODES; - const maxDepth = options.maxDepth ?? MAX_DEPTH; - const maxApps = options.maxApps ?? MAX_DESKTOP_APPS; - - const scriptPath = resolveScriptPath(); - const args = [ - scriptPath, - '--surface', - surface, - '--max-nodes', - String(maxNodes), - '--max-depth', - String(maxDepth), - '--max-apps', - String(maxApps), - ]; - - const result = await runLinuxToolCommand('python3', args, { - allowFailure: true, - timeoutMs: 30_000, - signal: options.signal, - }); - - if (result.exitCode !== 0) { - const stderr = result.stderr.trim(); - if (stderr.includes('No module named') || stderr.includes('gi.require_version')) { - throw new AppError( - 'TOOL_MISSING', - 'AT-SPI2 Python bindings not found. Install python3-gi and gir1.2-atspi-2.0.', - { cause: stderr }, - ); - } - throw new AppError( - 'COMMAND_FAILED', - `AT-SPI2 snapshot failed (exit ${result.exitCode}): ${stderr || result.stdout}`, - ); - } - - let parsed: PythonResult; - try { - parsed = JSON.parse(result.stdout); - } catch { - throw new AppError( - 'COMMAND_FAILED', - `AT-SPI2 snapshot returned invalid JSON: ${result.stdout.slice(0, 200)}`, - ); - } - - if (parsed.error) { - throw new AppError('COMMAND_FAILED', `AT-SPI2: ${parsed.error}`); - } - - // Map Python output to RawSnapshotNode with normalized roles - const nodes: RawSnapshotNode[] = (parsed.nodes ?? []).map((n) => ({ - index: n.index, - type: normalizeAtspiRole(n.role), - role: n.role, - label: n.label ?? undefined, - value: n.value ?? undefined, - rect: n.rect ?? undefined, - enabled: n.enabled ?? undefined, - selected: n.selected ?? undefined, - hittable: n.hittable ?? undefined, - depth: n.depth, - parentIndex: n.parentIndex ?? undefined, - pid: n.pid ?? undefined, - appName: n.appName ?? undefined, - windowTitle: n.windowTitle ?? undefined, - })); +export type LinuxAccessibilityTree = { + nodes: RawSnapshotNode[]; + truncated: boolean; + surface: LinuxSnapshotSurface; +}; +export function createLinuxAccessibilityProvider( + commands: LinuxCommandRunner, +): LinuxAccessibilityProvider { return { - nodes, - truncated: parsed.truncated, - surface, + async captureTree(surface, options = {}) { + if (hostPlatform() !== 'linux') { + throw new AppError('UNSUPPORTED_PLATFORM', 'AT-SPI2 bridge is only available on Linux'); + } + + if (!(await commands.which('python3'))) { + throw new AppError( + 'TOOL_MISSING', + 'python3 is required for AT-SPI2 accessibility snapshots on Linux.', + ); + } + + const args = [ + resolveLinuxAtspiScriptPath(), + '--surface', + surface, + '--max-nodes', + String(options.maxNodes ?? MAX_NODES), + '--max-depth', + String(options.maxDepth ?? MAX_DEPTH), + '--max-apps', + String(options.maxApps ?? MAX_DESKTOP_APPS), + ]; + + const result = await commands.run('python3', args, { + allowFailure: true, + timeoutMs: ATSPI_TIMEOUT_MS, + ...(options.signal ? { signal: options.signal } : {}), + }); + + if (result.exitCode !== 0) { + const stderr = result.stderr.trim(); + if (stderr.includes('No module named') || stderr.includes('gi.require_version')) { + throw new AppError( + 'TOOL_MISSING', + 'AT-SPI2 Python bindings not found. Install python3-gi and gir1.2-atspi-2.0.', + { cause: stderr }, + ); + } + throw new AppError( + 'COMMAND_FAILED', + `AT-SPI2 snapshot failed (exit ${result.exitCode}): ${stderr || result.stdout}`, + ); + } + + let parsed: PythonResult; + try { + parsed = JSON.parse(result.stdout); + } catch { + throw new AppError( + 'COMMAND_FAILED', + `AT-SPI2 snapshot returned invalid JSON: ${result.stdout.slice(0, 200)}`, + ); + } + + if (parsed.error) { + throw new AppError('COMMAND_FAILED', `AT-SPI2: ${parsed.error}`); + } + + // Map Python output to RawSnapshotNode with normalized roles + const nodes: RawSnapshotNode[] = (parsed.nodes ?? []).map((n) => ({ + index: n.index, + type: normalizeAtspiRole(n.role), + role: n.role, + label: n.label ?? undefined, + value: n.value ?? undefined, + rect: n.rect ?? undefined, + enabled: n.enabled ?? undefined, + selected: n.selected ?? undefined, + hittable: n.hittable ?? undefined, + depth: n.depth, + parentIndex: n.parentIndex ?? undefined, + pid: n.pid ?? undefined, + appName: n.appName ?? undefined, + windowTitle: n.windowTitle ?? undefined, + })); + + return { nodes, truncated: parsed.truncated, surface }; + }, }; } diff --git a/packages/platform-linux/src/atspi-script.ts b/packages/platform-linux/src/atspi-script.ts new file mode 100644 index 0000000000..9b2f1bb077 --- /dev/null +++ b/packages/platform-linux/src/atspi-script.ts @@ -0,0 +1,29 @@ +import path from 'node:path'; +import { hostFileExistsSync } from '@agent-device/host-kit/host-file'; +import { AppError } from '@agent-device/kernel/errors'; + +const SCRIPT_NAME = 'atspi-dump.py'; + +/** + * The AT-SPI2 helper, shipped with this package under `linux/`. + * + * It is resolved next to the code that runs it rather than against the process working directory or + * a repository layout: from the source tree that is `/linux`, and from an installed package + * it is `/linux` beside `dist`, because the manifest ships that directory with the bundle. + * The name is resolved once per process; the first capture of a process pays the probe. + */ +let cachedScriptPath: string | undefined; + +export function resolveLinuxAtspiScriptPath(): string { + if (cachedScriptPath) return cachedScriptPath; + const candidate = path.join(path.dirname(import.meta.dirname), 'linux', SCRIPT_NAME); + if (!hostFileExistsSync(candidate)) { + throw new AppError( + 'TOOL_MISSING', + `Cannot find ${SCRIPT_NAME}. Ensure the @agent-device/linux plugin package is installed correctly.`, + { path: candidate }, + ); + } + cachedScriptPath = candidate; + return candidate; +} diff --git a/packages/platform-linux/src/clipboard.ts b/packages/platform-linux/src/clipboard.ts index 66096b0d74..f759e7f8ba 100644 --- a/packages/platform-linux/src/clipboard.ts +++ b/packages/platform-linux/src/clipboard.ts @@ -1,9 +1,12 @@ -import { resolveLinuxToolProvider } from './tool-provider.ts'; +import type { LinuxToolProvider } from '@agent-device/contracts/linux-tool-provider'; -export async function readLinuxClipboard(): Promise { - return await resolveLinuxToolProvider().clipboard!.readText(); +export async function readLinuxClipboard(provider: LinuxToolProvider): Promise { + return await provider.clipboard!.readText(); } -export async function writeLinuxClipboard(text: string): Promise { - await resolveLinuxToolProvider().clipboard!.writeText(text); +export async function writeLinuxClipboard( + provider: LinuxToolProvider, + text: string, +): Promise { + await provider.clipboard!.writeText(text); } diff --git a/packages/platform-linux/src/command-runner.ts b/packages/platform-linux/src/command-runner.ts new file mode 100644 index 0000000000..65e083d2cf --- /dev/null +++ b/packages/platform-linux/src/command-runner.ts @@ -0,0 +1,102 @@ +import path from 'node:path'; +import type { PlatformHost } from 'agent-device/plugins'; +import { AppError, normalizeError } from '@agent-device/kernel/errors'; +import { sleep } from '@agent-device/host-kit/retry'; +import type { + LinuxCommandOptions, + LinuxCommandResult, + LinuxDetachedExit, +} from '@agent-device/contracts/linux-tool-provider'; + +/** + * The plugin's route to host commands, bound to the `PlatformHost` the core handed `setup()`. The + * core owns the spawn environment, the exec trace and the filesystem probe, so a `--debug` log shows + * what this family ran under its request id, and a tool the host cannot execute answers the same way + * for an availability probe as for the spawn that probe authorized. + * + * Every spawn and every availability check goes through that host rather than this bundle's own copy + * of the host kit: the daemon's command scope never enters the bundled copy, so a spawn made from it + * would run with the daemon process environment instead of the host environment captured for the + * request, and would drop the family's traces. + */ +export type LinuxCommandRunner = Readonly<{ + run( + cmd: string, + args: readonly string[], + options?: LinuxCommandOptions, + ): Promise; + /** True when the host resolves `cmd` on its `PATH`, or when `cmd` names an executable path. */ + which(cmd: string): Promise; + /** + * Starts `cmd` detached with its output discarded and answers how it ended. A desktop app outlives + * the command that opened it, so nothing awaits this beyond its exit report. + */ + launchDetached( + cmd: string, + args: readonly string[], + ): Readonly<{ exited: Promise }>; + /** Records one family diagnostic in the request's diagnostic store. */ + diagnose( + event: Readonly<{ + level: 'debug' | 'info' | 'warn' | 'error'; + phase: string; + data: Record; + }>, + ): void; + /** Paces synthesized input steps, on the host clock the family's requests already run under. */ + sleep(milliseconds: number): Promise; +}>; + +export function createLinuxCommandRunner(host: PlatformHost): LinuxCommandRunner { + const env = host.env; + return Object.freeze({ + run: async (cmd, args, options) => await host.runCommand(cmd, [...args], { ...options, env }), + which: async (cmd) => await hostResolvesExecutable(host, env, cmd), + launchDetached: (cmd, args) => { + // A host that cannot start a process outliving the request cannot open a desktop app: waiting + // on a spawned binary would hold the request open for the app's whole life, so the family + // refuses on the spot rather than approximating it with a blocking spawn. + if (!host.launchDetached) { + throw new AppError('UNSUPPORTED_OPERATION', `Cannot start ${cmd} on this host.`, { + reason: 'host-launch-unavailable', + command: cmd, + }); + } + return { + exited: host + .launchDetached(cmd, [...args], { env }) + .then((launched) => launched.exited) + .catch((error: unknown) => ({ pid: 0, error: normalizeError(error).message })), + }; + }, + diagnose: (event) => host.emitDiagnostic(event), + sleep: async (milliseconds) => await sleep(milliseconds), + }); +} + +/** + * Whether the host can execute `cmd`. An absolute name is asked of the host directly; a bare name is + * looked up in the host `PATH` entries through the same host authority, so a probe and a spawn cannot + * disagree about a tool, and neither reads the filesystem on its own (ADR 0019). + */ +async function hostResolvesExecutable( + host: PlatformHost, + env: Readonly>, + cmd: string, +): Promise { + const candidate = cmd.trim(); + if (!candidate) return false; + if (candidate.startsWith('/')) return await host.isFileExecutable(candidate); + const directories = (env.PATH ?? '') + .split(path.delimiter) + .map((entry) => entry.trim()) + .filter(Boolean); + for (const directory of directories) { + if (await host.isFileExecutable(joinHostPath(directory, candidate))) return true; + } + return false; +} + +function joinHostPath(directory: string, file: string): string { + return path.join(directory, file); +} diff --git a/packages/platform-linux/src/display.ts b/packages/platform-linux/src/display.ts index c1cf0cb8c9..b2adb763a0 100644 --- a/packages/platform-linux/src/display.ts +++ b/packages/platform-linux/src/display.ts @@ -1,26 +1,31 @@ -import type { EnvMap, HostEnvironment } from '@agent-device/kernel/source-value'; +import type { LinuxDisplayServer } from '@agent-device/contracts/linux-tool-provider'; -/** The Linux family's display-server vocabulary, from one detector (#3794). */ -export type DisplayServer = 'wayland' | 'x11'; +/** The display decision bound to one host environment. */ +export type LinuxDisplayConfig = Readonly<{ + detectDisplayServer(): LinuxDisplayServer; +}>; /** - * The display decision bound to one host. A local provider builds it at construction from its - * runtime's host, so input, clipboard and screenshot selection share one answer that no other - * runtime's host can change (#3794). + * Reads the display server from one host's environment: the only display decision in the family. + * A Wayland session is announced by its socket or by the session type, and anything else drives X11. */ -export type LinuxDisplayConfig = { - detectDisplayServer(): DisplayServer; -}; - -/** Reads the display server from one host's environment; the only display decision in the family. */ -export function detectLinuxDisplayServer(env: Readonly): DisplayServer { +export function detectLinuxDisplayServer( + env: Readonly>, +): LinuxDisplayServer { if (env['WAYLAND_DISPLAY']) return 'wayland'; if (env['XDG_SESSION_TYPE'] === 'wayland') return 'wayland'; return 'x11'; } -export function createLinuxDisplayConfig(host: HostEnvironment): LinuxDisplayConfig { +/** + * The display decision of the host the plugin was set up with. The environment is read on each + * question rather than once here, so a session that starts a Wayland compositor mid-request is not + * pinned to the answer `setup` happened to see. + */ +export function createLinuxDisplayConfig( + readEnv: () => Readonly>, +): LinuxDisplayConfig { return Object.freeze({ - detectDisplayServer: () => detectLinuxDisplayServer(host.env), + detectDisplayServer: () => detectLinuxDisplayServer(readEnv()), }); } diff --git a/packages/platform-linux/src/doctor.ts b/packages/platform-linux/src/doctor.ts new file mode 100644 index 0000000000..3609db7e01 --- /dev/null +++ b/packages/platform-linux/src/doctor.ts @@ -0,0 +1,61 @@ +import type { DoctorCheck } from '@agent-device/contracts/observability'; +import type { LinuxToolProvider } from '@agent-device/contracts/linux-tool-provider'; + +/** + * The toolchain row `doctor --platform linux` reports. The plugin answers it over the host command + * route it was set up with, so the versions it reads are the ones the family would spawn, and nothing + * is probed through the bundle's own copy of the host kit. + * + * Linux has no single toolchain to name — the family needs an input synthesizer, a clipboard tool, a + * screenshot tool and the AT-SPI helper — so the row reports the tools it found and names the ones a + * desktop session would be missing. + */ +export async function linuxToolchainCheck( + provider: LinuxToolProvider, +): Promise { + const display = provider.display.detectDisplayServer(); + const found: string[] = []; + const missing: string[] = []; + for (const tool of requiredLinuxTools(display)) { + if (await provider.whichCommand(tool)) found.push(tool); + else missing.push(tool); + } + const evidence = { + display, + tools: found, + missingTools: missing, + }; + if (missing.length > 0) { + return { + id: 'toolchain', + status: missing.includes(inputToolFor(display)) ? 'fail' : 'warn', + summary: `Linux desktop tools: missing ${missing.join(', ')}.`, + hint: linuxInstallHint(display), + command: `${inputToolFor(display)} --version`, + evidence, + }; + } + return { + id: 'toolchain', + status: 'pass', + summary: `Linux desktop tools: ${display} session with ${found.join(', ')}.`, + command: `${inputToolFor(display)} --version`, + evidence, + }; +} + +function inputToolFor(display: 'wayland' | 'x11'): string { + return display === 'wayland' ? 'ydotool' : 'xdotool'; +} + +function requiredLinuxTools(display: 'wayland' | 'x11'): readonly string[] { + return display === 'wayland' + ? ['ydotool', 'wl-paste', 'wl-copy', 'grim', 'python3'] + : ['xdotool', 'xclip', 'scrot', 'python3']; +} + +function linuxInstallHint(display: 'wayland' | 'x11'): string { + return display === 'wayland' + ? 'Install ydotool, wl-clipboard, grim and python3-gi with your distribution package manager.' + : 'Install xdotool, xclip, scrot (or ImageMagick) and python3-gi with your distribution package manager.'; +} diff --git a/packages/platform-linux/src/index.test.ts b/packages/platform-linux/src/index.test.ts new file mode 100644 index 0000000000..59fe7d2949 --- /dev/null +++ b/packages/platform-linux/src/index.test.ts @@ -0,0 +1,309 @@ +import assert from 'node:assert/strict'; +import { test } from 'vitest'; +import type { LinuxPlatformRegistration } from '@agent-device/contracts/platform-plugin'; +import type { PlatformHost } from 'agent-device/plugins'; +import linuxPlatformPlugin from './index.ts'; + +/** One command the plugin asked the host to run. */ +type HostCommand = Readonly<{ + executable: string; + args: readonly string[]; + env: PlatformHost['env'] | undefined; +}>; + +/** + * The host the composition hands the plugin: one captured environment, and probes and spawns that + * record what the plugin asked rather than touching this machine. + */ +function createPluginHost( + input: Readonly<{ + env?: PlatformHost['env']; + tools?: Iterable; + commands?: HostCommand[]; + launches?: Array>; + }> = {}, +): PlatformHost { + const tools = input.tools ? new Set(input.tools) : undefined; + const commands = input.commands ?? []; + return { + env: input.env ?? { PATH: '/usr/bin', XDG_SESSION_TYPE: 'x11' }, + cwd: '/host-cwd', + stateDir: '/host-state', + runCommand: async (executable, args, options) => { + commands.push({ executable, args, env: options.env }); + return { stdout: '', stderr: '', exitCode: 0 }; + }, + isFileExecutable: async (candidate) => + tools === undefined ? false : tools.has(candidate.split('/').pop() ?? candidate), + launchDetached: async (executable, args) => { + input.launches?.push({ executable, args }); + return { pid: 4242, exited: Promise.resolve({ pid: 4242, exitCode: 0 }) }; + }, + emitDiagnostic: () => {}, + withDiagnosticTimer: async (_phase, operation) => await operation(), + }; +} + +function setupLinuxPlatform(host: PlatformHost = createPluginHost()): LinuxPlatformRegistration { + return linuxPlatformPlugin().contributes[0].setup(host) as LinuxPlatformRegistration; +} + +const scope = { + signal: new AbortController().signal, + diagnostics: { emit: () => undefined }, + progress: { report: () => undefined }, +}; + +test('the Linux package contributes the Linux platform family', () => { + const plugin = linuxPlatformPlugin(); + const [contribution] = plugin.contributes; + + assert.equal(plugin.apiVersion, 3); + assert.equal(plugin.contributes.length, 1); + assert.equal(contribution.kind, 'platform'); + assert.equal(contribution.family, 'linux'); +}); + +test('setup registers the Linux modules and operations', () => { + const registration = setupLinuxPlatform(); + + assert.equal(registration.family, 'linux'); + assert.equal(registration.inventoryModule.family, 'linux'); + assert.equal(registration.runtimeModule.family, 'linux'); + 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'); +}); + +test('setup binds nothing until an operation asks the host', async () => { + // Every host port throws: importing the package and calling `setup` must stay metadata-only, so + // the daemon's start-up cost does not include this family's command route. + const hostileHost = { + ...createPluginHost(), + runCommand: async () => { + throw new Error('setup must not spawn'); + }, + isFileExecutable: async () => { + throw new Error('setup must not probe'); + }, + launchDetached: () => { + throw new Error('setup must not launch'); + }, + } as PlatformHost; + + const registration = setupLinuxPlatform(hostileHost); + assert.equal(registration.family, 'linux'); +}); + +test('the Linux inventory reports the desktop device of a Linux host', async () => { + const registration = setupLinuxPlatform(); + const source = await registration.inventoryModule.loadInventory({ + hostName: 'builder', + hostOs: 'linux', + }); + + assert.deepEqual(await source.discover({}, scope), [ + { + platform: 'linux', + id: 'local', + name: 'builder', + kind: 'device', + target: 'desktop', + booted: true, + }, + ]); +}); + +test('the Linux inventory reports nothing on another host', async () => { + const registration = setupLinuxPlatform(); + const source = await registration.inventoryModule.loadInventory({ + hostName: 'laptop', + hostOs: 'darwin', + }); + + assert.deepEqual(await source.discover({}, scope), []); +}); + +test('the toolchain check probes the host the plugin was set up with', async () => { + const tools = ['xdotool', 'xclip', 'scrot', 'python3']; + const host = createPluginHost({ + env: { PATH: '/opt/tools:/usr/bin', XDG_SESSION_TYPE: 'x11' }, + tools, + }); + const probed: string[] = []; + const registration = setupLinuxPlatform({ + ...host, + isFileExecutable: async (candidate) => { + probed.push(candidate); + return await host.isFileExecutable(candidate); + }, + }); + + const check = await registration.operations.toolchainCheck(); + + assert.equal(check.id, 'toolchain'); + assert.equal(check.status, 'pass'); + // The probe is the host's, over the host PATH, for the tools the X11 session needs. + assert.deepEqual(probed, tools.map((tool) => `/opt/tools/${tool}`)); +}); + +test('the toolchain check reports the tools the host is missing', async () => { + const registration = setupLinuxPlatform( + createPluginHost({ + env: { PATH: '/usr/bin', XDG_SESSION_TYPE: 'x11' }, + tools: ['python3'], + }), + ); + + const check = await registration.operations.toolchainCheck(); + + assert.equal(check.status, 'fail'); + assert.match(check.summary, /xdotool/); + assert.deepEqual(check.evidence, { + display: 'x11', + tools: ['python3'], + missingTools: ['xdotool', 'xclip', 'scrot'], + }); +}); + +test('the toolchain check reads the display decision from the host environment (#3794)', async () => { + const registration = setupLinuxPlatform( + createPluginHost({ + env: { PATH: '/usr/bin', XDG_SESSION_TYPE: 'wayland', WAYLAND_DISPLAY: 'wayland-0' }, + tools: ['ydotool', 'wl-paste', 'wl-copy', 'grim', 'python3'], + }), + ); + + const check = await registration.operations.toolchainCheck(); + + assert.equal(check.status, 'pass'); + assert.match(check.summary, /wayland/); +}); + +test('the Linux interactor drives the host the plugin was set up with', async () => { + const commands: HostCommand[] = []; + const registration = setupLinuxPlatform( + createPluginHost({ + env: { PATH: '/usr/bin', XDG_SESSION_TYPE: 'x11' }, + tools: ['xdotool'], + commands, + }), + ); + const interactor = await registration.createInteractor( + { + platform: 'linux', + id: 'local', + name: 'builder', + kind: 'device', + target: 'desktop', + booted: true, + }, + {}, + { env: {}, cwd: '/host-cwd' }, + ); + + await interactor.tap(100, 200); + + assert.deepEqual( + commands.map((command) => [command.executable, [...command.args]]), + [ + ['xdotool', ['getmouselocation', '--shell']], + ['xdotool', ['mousemove', '--sync', '100', '200']], + ['xdotool', ['click', '1']], + ], + ); + // The environment is the setup host's, not the process's: the daemon's own environment never + // enters the bundle, and the request's display decision would be lost if it did. + 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 () => {}, + }, + }; + 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[] = []; + const device = { + platform: 'linux' as const, + id: 'local', + name: 'builder', + kind: 'device' as const, + target: 'desktop' as const, + booted: true, + }; + + const x11 = await setupLinuxPlatform( + createPluginHost({ + env: { PATH: '/usr/bin', XDG_SESSION_TYPE: 'x11' }, + tools: ['xdotool'], + commands: x11Commands, + }), + ).createInteractor(device, {}, { env: {}, cwd: '/host-cwd' }); + const wayland = await setupLinuxPlatform( + createPluginHost({ + env: { PATH: '/usr/bin', XDG_SESSION_TYPE: 'wayland', WAYLAND_DISPLAY: 'wayland-0' }, + tools: ['ydotool'], + commands: waylandCommands, + }), + ).createInteractor(device, {}, { env: {}, cwd: '/host-cwd' }); + + await x11.tap(1, 2); + await wayland.tap(3, 4); + + assert.deepEqual( + x11Commands.map((command) => command.executable), + ['xdotool', 'xdotool', 'xdotool'], + ); + assert.deepEqual( + waylandCommands.map((command) => command.executable), + ['ydotool', 'ydotool'], + ); +}); diff --git a/packages/platform-linux/src/index.ts b/packages/platform-linux/src/index.ts index 5ece85e502..cec790b7ce 100644 --- a/packages/platform-linux/src/index.ts +++ b/packages/platform-linux/src/index.ts @@ -1,112 +1,101 @@ +import type { PlatformContribution, PlatformHost } from 'agent-device/plugins'; import type { InventoryPlatformModule, PlatformModuleMetadata, } from '@agent-device/contracts/platform-module'; import type { PlatformRuntimeModule } from '@agent-device/contracts/platform-runtime-operations'; - -// fallow-ignore-next-line code-duplication -type DeferredFunction = (...args: never[]) => unknown; -type Deferred = ( - ...args: Parameters -) => Promise>>; - -function deferred(load: () => Promise): Deferred { - return (async (...args: Parameters) => - await ( - await load() - )(...args)) as unknown as Deferred; -} +import type { + LinuxPlatformOperations, + LinuxPlatformRegistration, +} from '@agent-device/contracts/platform-plugin'; +import type { LinuxToolbox } from './toolbox.ts'; +import type { LinuxToolProvider } from '@agent-device/contracts/linux-tool-provider'; const metadata = Object.freeze({ family: 'linux', } satisfies PlatformModuleMetadata); -export const runtimeModule = Object.freeze({ - ...metadata, - loadRuntime: async (host) => { - const { createLinuxPlatformRuntime } = await import('./runtime.ts'); - return createLinuxPlatformRuntime(host); - }, -} satisfies PlatformRuntimeModule); - -export const inventoryModule: InventoryPlatformModule<'linux'> = Object.freeze({ - ...metadata, - loadInventory: async (host) => { - const { createLinuxInventory } = await import('./inventory.ts'); - return createLinuxInventory(host); - }, -}); - -export type { LinuxToolProvider } from './tool-provider.ts'; +/** + * The toolbox module, resolved exactly once per process. The façade must stay metadata-eager + * (ADR-0019), so the module that binds a host's command port enters with the first operation that + * needs it rather than above it. Only the module is memoized: each `setup` call binds its own host. + */ +let toolboxModule: Promise | undefined; -export const openLinuxApp = deferred<(typeof import('./app-lifecycle.ts'))['openLinuxApp']>( - async () => (await import('./app-lifecycle.ts')).openLinuxApp, -); -export const closeLinuxApp = deferred<(typeof import('./app-lifecycle.ts'))['closeLinuxApp']>( - async () => (await import('./app-lifecycle.ts')).closeLinuxApp, -); -export const backLinux = deferred<(typeof import('./app-lifecycle.ts'))['backLinux']>( - async () => (await import('./app-lifecycle.ts')).backLinux, -); -export const homeLinux = deferred<(typeof import('./app-lifecycle.ts'))['homeLinux']>( - async () => (await import('./app-lifecycle.ts')).homeLinux, -); - -export const readLinuxClipboard = deferred<(typeof import('./clipboard.ts'))['readLinuxClipboard']>( - async () => (await import('./clipboard.ts')).readLinuxClipboard, -); -export const writeLinuxClipboard = deferred< - (typeof import('./clipboard.ts'))['writeLinuxClipboard'] ->(async () => (await import('./clipboard.ts')).writeLinuxClipboard); - -export const doubleClickLinux = deferred<(typeof import('./input-actions.ts'))['doubleClickLinux']>( - async () => (await import('./input-actions.ts')).doubleClickLinux, -); -export const fillLinux = deferred<(typeof import('./input-actions.ts'))['fillLinux']>( - async () => (await import('./input-actions.ts')).fillLinux, -); -export const focusLinux = deferred<(typeof import('./input-actions.ts'))['focusLinux']>( - async () => (await import('./input-actions.ts')).focusLinux, -); -export const longPressLinux = deferred<(typeof import('./input-actions.ts'))['longPressLinux']>( - async () => (await import('./input-actions.ts')).longPressLinux, -); -export const pressLinux = deferred<(typeof import('./input-actions.ts'))['pressLinux']>( - async () => (await import('./input-actions.ts')).pressLinux, -); -export const rightClickLinux = deferred<(typeof import('./input-actions.ts'))['rightClickLinux']>( - async () => (await import('./input-actions.ts')).rightClickLinux, -); -export const middleClickLinux = deferred<(typeof import('./input-actions.ts'))['middleClickLinux']>( - async () => (await import('./input-actions.ts')).middleClickLinux, -); -export const scrollLinux = deferred<(typeof import('./input-actions.ts'))['scrollLinux']>( - async () => (await import('./input-actions.ts')).scrollLinux, -); -export const swipeLinux = deferred<(typeof import('./input-actions.ts'))['swipeLinux']>( - async () => (await import('./input-actions.ts')).swipeLinux, -); -export const typeLinux = deferred<(typeof import('./input-actions.ts'))['typeLinux']>( - async () => (await import('./input-actions.ts')).typeLinux, -); - -export const screenshotLinux = deferred<(typeof import('./screenshot.ts'))['screenshotLinux']>( - async () => (await import('./screenshot.ts')).screenshotLinux, -); -export const captureLinuxSurfaceSnapshot = deferred< - (typeof import('./surface-snapshot.ts'))['captureLinuxSurfaceSnapshot'] ->(async () => (await import('./surface-snapshot.ts')).captureLinuxSurfaceSnapshot); -export const readLinuxTextAtPoint = deferred< - (typeof import('./snapshot.ts'))['readLinuxTextAtPoint'] ->(async () => (await import('./snapshot.ts')).readLinuxTextAtPoint); -export const createLocalLinuxToolProvider = deferred< - (typeof import('./tool-provider.ts'))['createLocalLinuxToolProvider'] ->(async () => (await import('./tool-provider.ts')).createLocalLinuxToolProvider); +/** + * A bound toolbox and the provider built on it, made on first use and then reused: a `setup` that + * never runs a command imports and builds nothing, and the operations of one setup share the one + * route it binds its host to. + */ +function linuxToolbox(host: PlatformHost) { + let bound: Promise> | undefined; + return async () => + (bound ??= (toolboxModule ??= import('./toolbox.ts')).then(async ({ createLinuxToolbox }) => { + const toolbox = createLinuxToolbox(host); + const { createLinuxToolProvider } = await import('./tool-provider.ts'); + return Object.freeze({ toolbox, provider: createLinuxToolProvider(toolbox) }); + })); +} -export async function withLinuxToolProvider( - provider: import('./tool-provider.ts').LinuxToolProvider | undefined, - fn: () => Promise, -): Promise { - const { withLinuxToolProvider: implementation } = await import('./tool-provider.ts'); - return await implementation(provider, fn); +function linuxPlatformPlugin() { + return { + apiVersion: 3, + contributes: [ + { + kind: 'platform', + family: 'linux', + // Importing this package evaluates nothing but itself, and the host is bound to a toolbox + // only when an operation first needs one. Every operation below asks the same lazy + // resolution, so one setup builds exactly one route for the whole family. + setup(host: PlatformHost): LinuxPlatformRegistration { + const bind = linuxToolbox(host); + const inventoryModule: InventoryPlatformModule<'linux'> = Object.freeze({ + ...metadata, + // The family's inventory asks the core for the host facts it names: an installed plugin + // reports the one desktop device of a Linux host and nothing anywhere else. + loadInventory: async (host) => { + const { createLinuxInventory } = await import('./inventory.ts'); + return createLinuxInventory(host); + }, + }); + const runtimeModule = Object.freeze({ + ...metadata, + loadRuntime: async (host) => { + const { createLinuxPlatformRuntime } = await import('./runtime.ts'); + const { toolbox, provider } = await bind(); + return createLinuxPlatformRuntime(host, toolbox, provider); + }, + } satisfies PlatformRuntimeModule & { readonly family: 'linux' }); + return { + family: 'linux', + inventoryModule, + runtimeModule, + createInteractor: async () => { + const { createLinuxInteractor } = await import('./interactor.ts'); + const { toolbox, provider } = await bind(); + return createLinuxInteractor(toolbox, provider); + }, + withRequestProvider: async (provider: LinuxToolProvider, task: () => Promise) => { + const { withLinuxToolProvider } = await import('./tool-provider.ts'); + return await withLinuxToolProvider(provider, task); + }, + operations: { + toolchainCheck: async () => { + const [{ linuxToolchainCheck }, { provider }] = await Promise.all([ + import('./doctor.ts'), + bind(), + ]); + return await linuxToolchainCheck(provider); + }, + } satisfies LinuxPlatformOperations, + }; + }, + }, + ], + } satisfies { + apiVersion: 3; + contributes: [Extract]; + }; } + +export { linuxPlatformPlugin as default }; diff --git a/packages/platform-linux/src/input-actions.ts b/packages/platform-linux/src/input-actions.ts index a15aba42f8..aa91a469ce 100644 --- a/packages/platform-linux/src/input-actions.ts +++ b/packages/platform-linux/src/input-actions.ts @@ -1,31 +1,25 @@ -import { ensureInputTool } from './linux-env.ts'; -import { resolveLinuxToolProvider, type LinuxPointerButton } from './tool-provider.ts'; import { discloseDispatchAfterSteps } from '@agent-device/kernel/errors'; -import { sleep } from '@agent-device/host-kit/retry'; -import type { ScrollDirection } from '@agent-device/contracts/scroll-gesture'; -import { DEFAULT_SCROLL_AMOUNT } from '@agent-device/contracts/scroll-gesture'; +import type { + LinuxInputProvider, + LinuxToolProvider, +} from '@agent-device/contracts/linux-tool-provider'; +import { + DEFAULT_SCROLL_AMOUNT, + type ScrollDirection, +} from '@agent-device/contracts/scroll-gesture'; +import { ensureInputTool } from './linux-env.ts'; // ── Low-level wrappers ───────────────────────────────────────────────── /** Per-action timeout — prevents hung xdotool/ydotool from blocking indefinitely. */ const INPUT_TIMEOUT_MS = 10_000; -async function xdotool(...args: string[]): Promise { - await resolveLinuxToolProvider().runCommand('xdotool', args, { - allowFailure: false, - timeoutMs: INPUT_TIMEOUT_MS, - }); +async function xdotool(provider: LinuxToolProvider, ...args: string[]): Promise { + await provider.runCommand('xdotool', args, { allowFailure: false, timeoutMs: INPUT_TIMEOUT_MS }); } -async function ydotool(...args: string[]): Promise { - await resolveLinuxToolProvider().runCommand('ydotool', args, { - allowFailure: false, - timeoutMs: INPUT_TIMEOUT_MS, - }); -} - -function resolveLinuxInputProvider() { - return resolveLinuxToolProvider().input; +async function ydotool(provider: LinuxToolProvider, ...args: string[]): Promise { + await provider.runCommand('ydotool', args, { allowFailure: false, timeoutMs: INPUT_TIMEOUT_MS }); } /** @@ -37,24 +31,27 @@ function resolveLinuxInputProvider() { * the pointer on its last coordinate action, and every retry of that action then dies in this * hang, reporting the retry's first coordinate step instead of the attempt's real failure. */ -async function moveTo(x: number, y: number): Promise { - const { tool } = await ensureInputTool(); +async function moveTo(provider: LinuxToolProvider, x: number, y: number): Promise { + const { tool } = await ensureInputTool(provider); if (tool === 'xdotool') { - if (await pointerAlreadyAt(x, y)) return; - await xdotool('mousemove', '--sync', String(x), String(y)); + if (await pointerAlreadyAt(provider, x, y)) return; + await xdotool(provider, 'mousemove', '--sync', String(x), String(y)); } else { - await ydotool('mousemove', '--absolute', '-x', String(x), '-y', String(y)); + await ydotool(provider, 'mousemove', '--absolute', '-x', String(x), '-y', String(y)); } } /** True when the X pointer already sits exactly on (x, y); a failed probe never blocks the move. */ -async function pointerAlreadyAt(x: number, y: number): Promise { +async function pointerAlreadyAt( + provider: LinuxToolProvider, + x: number, + y: number, +): Promise { try { - const result = await resolveLinuxToolProvider().runCommand( - 'xdotool', - ['getmouselocation', '--shell'], - { allowFailure: true, timeoutMs: INPUT_TIMEOUT_MS }, - ); + const result = await provider.runCommand('xdotool', ['getmouselocation', '--shell'], { + allowFailure: true, + timeoutMs: INPUT_TIMEOUT_MS, + }); const location = new Map( result.stdout .split('\n') @@ -73,18 +70,22 @@ async function pointerAlreadyAt(x: number, y: number): Promise { * Both `combo` (xdotool keysym notation) and `scancodes` (ydotool * key:state pairs) must be provided — ydotool requires scancodes. */ -export async function sendKey(combo: string, scancodes: string[]): Promise { - const provider = resolveLinuxInputProvider(); - if (provider) { - await provider.key(combo, scancodes); +export async function sendKey( + provider: LinuxToolProvider, + combo: string, + scancodes: string[], +): Promise { + const input: LinuxInputProvider | undefined = provider.input; + if (input) { + await input.key(combo, scancodes); return; } - const { tool } = await ensureInputTool(); + const { tool } = await ensureInputTool(provider); if (tool === 'xdotool') { - await xdotool('key', '--clearmodifiers', combo); + await xdotool(provider, 'key', '--clearmodifiers', combo); } else { - await ydotool('key', ...scancodes); + await ydotool(provider, 'key', ...scancodes); } } @@ -94,130 +95,159 @@ export async function sendKey(combo: string, scancodes: string[]): Promise // 0xC0 = BTN_LEFT with click flags, 0xC1 = BTN_RIGHT, 0xC2 = BTN_MIDDLE // These correspond to ydotool's packed button+action format. -async function clickButton(x: number, y: number, xdoBtn: string, ydoCode: string): Promise { - await moveTo(x, y); - const { tool } = await ensureInputTool(); +async function clickButton( + provider: LinuxToolProvider, + x: number, + y: number, + xdoBtn: string, + ydoCode: string, +): Promise { + await moveTo(provider, x, y); + const { tool } = await ensureInputTool(provider); if (tool === 'xdotool') { - await xdotool('click', xdoBtn); + await xdotool(provider, 'click', xdoBtn); } else { - await ydotool('click', ydoCode); + await ydotool(provider, 'click', ydoCode); } } async function clickLinuxButton( + provider: LinuxToolProvider, x: number, y: number, - button: LinuxPointerButton, + button: 'primary' | 'secondary' | 'middle', xdoBtn: string, ydoCode: string, ): Promise { - const provider = resolveLinuxInputProvider(); - if (provider) { - await provider.click(x, y, button); + if (provider.input) { + await provider.input.click(x, y, button); return; } - await clickButton(x, y, xdoBtn, ydoCode); + await clickButton(provider, x, y, xdoBtn, ydoCode); } -export async function pressLinux(x: number, y: number): Promise { - await clickLinuxButton(x, y, 'primary', '1', '0xC0'); +export async function pressLinux( + provider: LinuxToolProvider, + x: number, + y: number, +): Promise { + await clickLinuxButton(provider, x, y, 'primary', '1', '0xC0'); } -export async function rightClickLinux(x: number, y: number): Promise { - await clickLinuxButton(x, y, 'secondary', '3', '0xC1'); +export async function rightClickLinux( + provider: LinuxToolProvider, + x: number, + y: number, +): Promise { + await clickLinuxButton(provider, x, y, 'secondary', '3', '0xC1'); } -export async function middleClickLinux(x: number, y: number): Promise { - await clickLinuxButton(x, y, 'middle', '2', '0xC2'); +export async function middleClickLinux( + provider: LinuxToolProvider, + x: number, + y: number, +): Promise { + await clickLinuxButton(provider, x, y, 'middle', '2', '0xC2'); } -export async function doubleClickLinux(x: number, y: number): Promise { - const provider = resolveLinuxInputProvider(); - if (provider) { - await provider.doubleClick(x, y); +export async function doubleClickLinux( + provider: LinuxToolProvider, + x: number, + y: number, +): Promise { + if (provider.input) { + await provider.input.doubleClick(x, y); return; } - const { tool } = await ensureInputTool(); - await moveTo(x, y); + const { tool } = await ensureInputTool(provider); + await moveTo(provider, x, y); if (tool === 'xdotool') { - await xdotool('click', '--repeat', '2', '1'); + await xdotool(provider, 'click', '--repeat', '2', '1'); } else { - await ydotool('click', '0xC0'); - await ydotool('click', '0xC0'); + await ydotool(provider, 'click', '0xC0'); + await ydotool(provider, 'click', '0xC0'); } } -export async function longPressLinux(x: number, y: number, durationMs = 800): Promise { - const provider = resolveLinuxInputProvider(); - if (provider) { - await provider.longPress(x, y, durationMs); +export async function longPressLinux( + provider: LinuxToolProvider, + x: number, + y: number, + durationMs = 800, +): Promise { + if (provider.input) { + await provider.input.longPress(x, y, durationMs); return; } - const { tool } = await ensureInputTool(); - await moveTo(x, y); + const { tool } = await ensureInputTool(provider); + await moveTo(provider, x, y); if (tool === 'xdotool') { - await xdotool('mousedown', '1'); - await sleep(durationMs); - await xdotool('mouseup', '1'); + await xdotool(provider, 'mousedown', '1'); + await provider.sleep(durationMs); + await xdotool(provider, 'mouseup', '1'); } else { // ydotool v1: use click --down / --up for press-hold - await ydotool('click', '--down', '0xC0'); - await sleep(durationMs); - await ydotool('click', '--up', '0xC0'); + await ydotool(provider, 'click', '--down', '0xC0'); + await provider.sleep(durationMs); + await ydotool(provider, 'click', '--up', '0xC0'); } } -export async function focusLinux(x: number, y: number): Promise { - await pressLinux(x, y); +export async function focusLinux( + provider: LinuxToolProvider, + x: number, + y: number, +): Promise { + await pressLinux(provider, x, y); } // ── Swipe / scroll ────────────────────────────────────────────────────── export async function swipeLinux( + provider: LinuxToolProvider, x1: number, y1: number, x2: number, y2: number, durationMs = 300, ): Promise { - const provider = resolveLinuxInputProvider(); - if (provider) { - await provider.drag(x1, y1, x2, y2, durationMs); + if (provider.input) { + await provider.input.drag(x1, y1, x2, y2, durationMs); return; } - const { tool } = await ensureInputTool(); - await moveTo(x1, y1); + const { tool } = await ensureInputTool(provider); + await moveTo(provider, x1, y1); if (tool === 'xdotool') { - await xdotool('mousedown', '1'); - await xdotool('mousemove', '--sync', String(x2), String(y2)); - await sleep(durationMs); - await xdotool('mouseup', '1'); + await xdotool(provider, 'mousedown', '1'); + await xdotool(provider, 'mousemove', '--sync', String(x2), String(y2)); + await provider.sleep(durationMs); + await xdotool(provider, 'mouseup', '1'); } else { // ydotool v1: use click --down / --up for drag - await ydotool('click', '--down', '0xC0'); - await ydotool('mousemove', '--absolute', '-x', String(x2), '-y', String(y2)); - await sleep(durationMs); - await ydotool('click', '--up', '0xC0'); + await ydotool(provider, 'click', '--down', '0xC0'); + await ydotool(provider, 'mousemove', '--absolute', '-x', String(x2), '-y', String(y2)); + await provider.sleep(durationMs); + await ydotool(provider, 'click', '--up', '0xC0'); } } const DEFAULT_SCROLL_CLICKS = 5; export async function scrollLinux( + provider: LinuxToolProvider, direction: ScrollDirection, options?: { amount?: number; pixels?: number; durationMs?: number }, ): Promise> { - const provider = resolveLinuxInputProvider(); - if (provider) { - await provider.scroll(direction, options); + if (provider.input) { + await provider.input.scroll(direction, options); return scrollDurationResult(options); } - const { tool } = await ensureInputTool(); + const { tool } = await ensureInputTool(provider); // Translate amount/pixels into a discrete click count. // xdotool button clicks scroll ~15px each (3 lines × 5px). @@ -240,20 +270,20 @@ export async function scrollLinux( if (tool === 'xdotool') { const button = direction === 'up' ? '4' : direction === 'down' ? '5' : direction === 'left' ? '6' : '7'; - await runPacedScrollSteps(scrollCount, options?.durationMs, async (stepCount) => { - await xdotool('click', '--repeat', String(stepCount), button); + await runPacedScrollSteps(provider, scrollCount, options?.durationMs, async (stepCount) => { + await xdotool(provider, 'click', '--repeat', String(stepCount), button); }); } else { // ydotool: wheel events use positive/negative values if (direction === 'up' || direction === 'down') { - await runPacedScrollSteps(scrollCount, options?.durationMs, async (stepCount) => { + await runPacedScrollSteps(provider, scrollCount, options?.durationMs, async (stepCount) => { const stepValue = direction === 'up' ? String(-stepCount) : String(stepCount); - await ydotool('mousemove', '--wheel', '-y', stepValue); + await ydotool(provider, 'mousemove', '--wheel', '-y', stepValue); }); } else { - await runPacedScrollSteps(scrollCount, options?.durationMs, async (stepCount) => { + await runPacedScrollSteps(provider, scrollCount, options?.durationMs, async (stepCount) => { const stepValue = direction === 'left' ? String(-stepCount) : String(stepCount); - await ydotool('mousemove', '--wheel', '-x', stepValue); + await ydotool(provider, 'mousemove', '--wheel', '-x', stepValue); }); } } @@ -261,6 +291,7 @@ export async function scrollLinux( } async function runPacedScrollSteps( + provider: LinuxToolProvider, totalCount: number, durationMs: number | undefined, runStep: (stepCount: number) => Promise, @@ -276,7 +307,7 @@ async function runPacedScrollSteps( for (let index = 0; index < totalCount; index += 1) { await runStep(1); dispatchedSteps += 1; - if (index < totalCount - 1) await sleep(intervalMs); + if (index < totalCount - 1) await provider.sleep(intervalMs); } } catch (error) { throw discloseDispatchAfterSteps(error, dispatchedSteps); @@ -291,37 +322,46 @@ function scrollDurationResult( // ── Keyboard actions ──────────────────────────────────────────────────── -export async function typeLinux(text: string, delayMs = 0): Promise { - const provider = resolveLinuxInputProvider(); - if (provider) { - await provider.typeText(text, { delayMs }); +export async function typeLinux( + provider: LinuxToolProvider, + text: string, + delayMs = 0, +): Promise { + if (provider.input) { + await provider.input.typeText(text, { delayMs }); return; } - const { tool } = await ensureInputTool(); + const { tool } = await ensureInputTool(provider); if (tool === 'xdotool') { const args = ['type']; if (delayMs > 0) args.push('--delay', String(delayMs)); args.push('--clearmodifiers', '--', text); - await xdotool(...args); + await xdotool(provider, ...args); } else { - await ydotool('type', '--', text); + await ydotool(provider, 'type', '--', text); } } -export async function fillLinux(x: number, y: number, text: string, delayMs = 0): Promise { +export async function fillLinux( + provider: LinuxToolProvider, + x: number, + y: number, + text: string, + delayMs = 0, +): Promise { // Click to focus the field - await pressLinux(x, y); - await sleep(100); + await pressLinux(provider, x, y); + await provider.sleep(100); // Select all existing text (Ctrl+A scancodes: Ctrl=29, A=30) - await sendKey('ctrl+a', ['29:1', '30:1', '30:0', '29:0']); - await sleep(50); + await sendKey(provider, 'ctrl+a', ['29:1', '30:1', '30:0', '29:0']); + await provider.sleep(50); if (text.length === 0) { // The clear-field request (#2063): typing zero characters over the selection would leave // the old value selected but intact, so delete the selection instead (BackSpace=14). - await sendKey('BackSpace', ['14:1', '14:0']); + await sendKey(provider, 'BackSpace', ['14:1', '14:0']); return; } // Type replacement text - await typeLinux(text, delayMs); + await typeLinux(provider, text, delayMs); } diff --git a/packages/platform-linux/src/input-tool.ts b/packages/platform-linux/src/input-tool.ts deleted file mode 100644 index 3806ed2ca3..0000000000 --- a/packages/platform-linux/src/input-tool.ts +++ /dev/null @@ -1,6 +0,0 @@ -import type { DisplayServer } from './display.ts'; - -export type InputTool = 'xdotool' | 'ydotool'; - -/** The input tool one provider resolved, tagged with the display decision it resolved for. */ -export type LinuxInputSelection = { tool: InputTool; display: DisplayServer }; diff --git a/packages/platform-linux/src/interactor-facade.ts b/packages/platform-linux/src/interactor-facade.ts deleted file mode 100644 index 8bd90035b7..0000000000 --- a/packages/platform-linux/src/interactor-facade.ts +++ /dev/null @@ -1,7 +0,0 @@ -import type { Interactor } from '@agent-device/contracts/interactor-types'; -import type { HostEnvironment } from '@agent-device/kernel/source-value'; - -export async function createLinuxInteractor(host: HostEnvironment): Promise { - const { createLinuxInteractor: create } = await import('./interactor.ts'); - return create(host); -} diff --git a/packages/platform-linux/src/interactor.test.ts b/packages/platform-linux/src/interactor.test.ts index 5b7c6ec01b..e758252bfb 100644 --- a/packages/platform-linux/src/interactor.test.ts +++ b/packages/platform-linux/src/interactor.test.ts @@ -1,52 +1,138 @@ import assert from 'node:assert/strict'; -import { beforeEach, test, vi } from 'vitest'; +import { test } from 'vitest'; +import { createLinuxHostStub } from './toolbox.fixtures.ts'; import { createLinuxInteractor } from './interactor.ts'; +import { createLinuxToolProvider } from './tool-provider.ts'; import { buildGesturePlan } from '@agent-device/gestures/gesture-plan'; -import { middleClickLinux, pressLinux, rightClickLinux, swipeLinux } from './index.ts'; - -vi.mock('./index.ts', () => ({ - backLinux: vi.fn(), - captureLinuxSurfaceSnapshot: vi.fn(), - closeLinuxApp: vi.fn(), - doubleClickLinux: vi.fn(), - fillLinux: vi.fn(), - focusLinux: vi.fn(), - homeLinux: vi.fn(), - longPressLinux: vi.fn(), - middleClickLinux: vi.fn(), - openLinuxApp: vi.fn(), - pressLinux: vi.fn(), - readLinuxClipboard: vi.fn(), - readLinuxTextAtPoint: vi.fn(), - rightClickLinux: vi.fn(), - scrollLinux: vi.fn(), - screenshotLinux: vi.fn(), - swipeLinux: vi.fn(), - typeLinux: vi.fn(), - writeLinuxClipboard: vi.fn(), -})); - -beforeEach(() => vi.clearAllMocks()); - -test('Linux owns alternate buttons while the runtime binder owns primary series', async () => { - const interactor = createLinuxInteractor({ env: process.env, cwd: process.cwd() }); + +function host( + tools: readonly string[] = ['xdotool'], + overrides: Parameters[1] = {}, +) { + const stub = createLinuxHostStub({ + env: { PATH: '/usr/bin', XDG_SESSION_TYPE: 'x11' }, + tools, + respond: () => ({}), + }); + // Pacing replaced: this file is about which route each interactor method takes, not about clocks. + const provider = createLinuxToolProvider(stub.toolbox, { sleep: async () => {}, ...overrides }); + return { stub, interactor: createLinuxInteractor(stub.toolbox, provider) }; +} + +function commands(stub: ReturnType['stub']): Array<[string, readonly string[]]> { + return stub.commands.map((command) => [command.executable, command.args]); +} + +test('the Linux interactor routes alternate buttons to the alternate-button routes', async () => { + const { stub, interactor } = host(); await interactor.alternateClick!({ x: 10, y: 20 }, 'secondary'); await interactor.alternateClick!({ x: 30, y: 40 }, 'middle'); - assert.deepEqual(vi.mocked(rightClickLinux).mock.calls, [[10, 20]]); - assert.deepEqual(vi.mocked(middleClickLinux).mock.calls, [[30, 40]]); - assert.equal(vi.mocked(pressLinux).mock.calls.length, 0); + // Button 3 is the secondary button and button 2 the middle one in xdotool's numbering, and a + // primary press is never substituted for either. + assert.deepEqual(commands(stub), [ + ['xdotool', ['getmouselocation', '--shell']], + ['xdotool', ['mousemove', '--sync', '10', '20']], + ['xdotool', ['click', '3']], + ['xdotool', ['getmouselocation', '--shell']], + ['xdotool', ['mousemove', '--sync', '30', '40']], + ['xdotool', ['click', '2']], + ]); }); -test('Linux executes a planned fling as one drag with the resolved duration', async () => { +test('the Linux interactor executes a planned fling as one drag with the resolved duration', async () => { + const { stub, interactor } = host(); const plan = buildGesturePlan( { intent: 'fling', from: { x: 10, y: 20 }, to: { x: 110, y: 20 } }, { x: 0, y: 0, width: 200, height: 200 }, 'linux', ); - await createLinuxInteractor({ env: process.env, cwd: process.cwd() }).performGesture!(plan); + await interactor.performGesture!(plan); + + assert.deepEqual(commands(stub), [ + ['xdotool', ['getmouselocation', '--shell']], + ['xdotool', ['mousemove', '--sync', '10', '20']], + ['xdotool', ['mousedown', '1']], + ['xdotool', ['mousemove', '--sync', '110', '20']], + ['xdotool', ['mouseup', '1']], + ]); +}); + +test('the Linux interactor refuses a multi-touch plan', async () => { + const { stub, interactor } = host(); + const plan = buildGesturePlan( + { intent: 'pinch', scale: 2 }, + { x: 0, y: 0, width: 2000, height: 2000 }, + 'linux', + ); + assert.equal(plan.topology, 'multi'); + + await assert.rejects(() => interactor.performGesture!(plan), /Multi-touch/); + assert.deepEqual(stub.commands, []); +}); + +test('the Linux interactor routes lifecycle and clipboard intents to the desktop tools', async () => { + const { stub, interactor } = host(['xdotool', 'wmctrl', 'xdg-open', 'xclip', 'demo-app']); + + await interactor.open('demo-app'); + await interactor.close('Demo'); + await interactor.writeClipboard!('copied'); + await interactor.readClipboard!(); + + const spawned = commands(stub); + assert.deepEqual( + stub.launches.map((launch) => [launch.executable, [...launch.args]]), + [['demo-app', []]], + ); + assert.deepEqual(spawned.map(([executable]) => executable), ['wmctrl', 'xclip', 'xclip']); + assert.equal(spawned[0]![1][0], '-c'); + assert.equal(spawned[1]![1].includes('-o'), false); + assert.equal(spawned[2]![1].includes('-o'), true); +}); + +test('the Linux interactor reports the unsupported device intents rather than approximating them', async () => { + const { interactor } = host(); + + await assert.rejects(() => interactor.setOrientation!('portrait'), /orientation/); + await assert.rejects(() => interactor.appSwitcher!(), /appSwitcher/); + await assert.rejects(() => interactor.tvRemote!('back'), /tv-remote/); + await assert.rejects(() => interactor.setSetting!('darkMode', 'on'), /setSetting/); +}); + +test('the Linux interactor reports a capture through the plugin producer', async () => { + const { interactor } = host(['xdotool'], { + accessibility: { + captureTree: async surface => ({ nodes: [], truncated: false, surface }), + }, + }); + + const snapshot = await interactor.snapshot!({ surface: 'desktop' }); + + // The Linux capture is a plain one: the plugin stamps its own producer rather than asking the core + // for a desktop-surface capture. + assert.equal('producer' in snapshot ? snapshot.producer : undefined, 'linux-atspi'); +}); + +test('the Linux interactor reads text at a point from the captured tree', async () => { + const { interactor } = host(['xdotool'], { + accessibility: { + captureTree: async surface => ({ + nodes: [ + { + index: 0, + type: 'Text', + value: 'menu bar', + rect: { x: 0, y: 0, width: 400, height: 40 }, + depth: 0, + }, + ], + truncated: false, + surface, + }), + }, + }); - assert.deepEqual(vi.mocked(swipeLinux).mock.calls, [[10, 20, 110, 20, 100]]); + assert.equal(await interactor.readTextAtPoint!({ x: 5, y: 5 }), 'menu bar'); }); diff --git a/packages/platform-linux/src/interactor.ts b/packages/platform-linux/src/interactor.ts index 5c090b7b3c..d042d8ddc5 100644 --- a/packages/platform-linux/src/interactor.ts +++ b/packages/platform-linux/src/interactor.ts @@ -1,63 +1,71 @@ import { AppError } from '@agent-device/kernel/errors'; -import { withDiagnosticTimer } from '@agent-device/host-kit/diagnostics'; import { withMethodScope } from '@agent-device/kernel/scoped-provider'; -import type { HostEnvironment } from '@agent-device/kernel/source-value'; -import { - createLocalLinuxToolProvider, - hasScopedLinuxToolProvider, - withLinuxToolProvider, -} from './tool-provider.ts'; +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 { backLinux, closeLinuxApp, homeLinux, openLinuxApp } from './app-lifecycle.ts'; +import { readLinuxClipboard, writeLinuxClipboard } from './clipboard.ts'; import { - backLinux, - captureLinuxSurfaceSnapshot, - closeLinuxApp, doubleClickLinux, fillLinux, focusLinux, - homeLinux, longPressLinux, middleClickLinux, - openLinuxApp, pressLinux, rightClickLinux, - readLinuxClipboard, - readLinuxTextAtPoint, scrollLinux, - screenshotLinux, swipeLinux, typeLinux, - writeLinuxClipboard, -} from './index.ts'; -import { singlePointerPlanEndpoints } from '@agent-device/gestures/gesture-plan'; -import type { Interactor } from '@agent-device/contracts/interactor-types'; +} from './input-actions.ts'; +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'; -export function createLinuxInteractor(host: HostEnvironment): Interactor { - // The interactor builds its own provider over the composing runtime's host: the display - // decision lives on that instance, never in module state, so another runtime's host cannot - // reach it (#3794). A request-scoped provider still wins: this one enters only when the - // request scopes none. - const provider = createLocalLinuxToolProvider({ host }); - return withMethodScope(createLinuxInteractorBody(), async (task) => +/** + * 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. + */ +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(): Interactor { +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(app), + open: (app) => openLinuxApp(running(), app), openDevice: () => Promise.resolve(), - close: (app) => closeLinuxApp(app), - tap: (x, y) => pressLinux(x, y), + close: (app) => closeLinuxApp(running(), app), + tap: (x, y) => pressLinux(running(), x, y), alternateClick: async (point, button) => button === 'secondary' - ? await rightClickLinux(point.x, point.y) - : await middleClickLinux(point.x, point.y), - doubleTap: (x, y) => doubleClickLinux(x, y), - longPress: (x, y, durationMs) => longPressLinux(x, y, durationMs), - focus: (x, y) => focusLinux(x, y), - type: (text, delayMs) => typeLinux(text, delayMs), - fill: (x, y, text, delayMs) => fillLinux(x, y, text, delayMs), - scroll: (direction, options) => scrollLinux(direction, options), + ? 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), performGesture: async (plan) => { if (plan.topology !== 'single') { throw new AppError( @@ -66,23 +74,21 @@ function createLinuxInteractorBody(): Interactor { ); } const { start, end } = singlePointerPlanEndpoints(plan); - await swipeLinux(start.x, start.y, end.x, end.y, plan.durationMs); + await swipeLinux(running(), start.x, start.y, end.x, end.y, plan.durationMs); }, - screenshot: (outPath, options) => screenshotLinux(outPath, options), + screenshot: (outPath, options) => screenshotLinux(running(), 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) => { - return await readLinuxTextAtPoint(point.x, point.y, options?.surface); - }, - snapshot: async (options) => { - return await withDiagnosticTimer( + readTextAtPoint: async (point, options) => + await readLinuxTextAtPoint(toolbox, running(), point.x, point.y, options?.surface), + snapshot: async (options) => + await toolbox.withDiagnosticTimer( 'snapshot_capture', - async () => await captureLinuxSurfaceSnapshot(options, options?.signal), + async () => await captureLinuxSurfaceSnapshot(toolbox, running(), options, options?.signal), { backend: 'linux-atspi' }, - ); - }, - back: () => backLinux(), - home: () => homeLinux(), + ), + back: () => backLinux(running()), + home: () => homeLinux(running()), setOrientation: () => { throw new AppError('UNSUPPORTED_OPERATION', 'orientation not supported on Linux'); }, @@ -92,8 +98,8 @@ function createLinuxInteractorBody(): Interactor { tvRemote: () => { throw new AppError('UNSUPPORTED_OPERATION', 'tv-remote not supported on Linux'); }, - readClipboard: () => readLinuxClipboard(), - writeClipboard: (text) => writeLinuxClipboard(text), + readClipboard: () => readLinuxClipboard(running()), + writeClipboard: (text) => writeLinuxClipboard(running(), text), setSetting: () => { throw new AppError('UNSUPPORTED_OPERATION', 'setSetting not supported on Linux'); }, diff --git a/packages/platform-linux/src/linux-env.ts b/packages/platform-linux/src/linux-env.ts index b99c589ad3..e14960c08a 100644 --- a/packages/platform-linux/src/linux-env.ts +++ b/packages/platform-linux/src/linux-env.ts @@ -1,20 +1,21 @@ /** * Shared Linux input-tool resolution — display server and input tool. * - * The display decision comes from the resolved provider's bound host, never an ambient read - * (#3794). Nothing is memoized: the interactor that enters a provider is built per request, so a - * cache would not outlive the request it serves. A refusal simply throws. + * The display decision comes from the provider that is running the action, never an ambient read + * (#3794). Nothing is memoized: a refusal simply throws, and the next call asks again, which is what + * lets a tool installed while the daemon runs answer without a restart. */ import { AppError } from '@agent-device/kernel/errors'; -import { resolveLinuxToolProvider, type LinuxToolProvider } from './tool-provider.ts'; -import type { DisplayServer } from './display.ts'; -import type { LinuxInputSelection } from './input-tool.ts'; +import type { + LinuxInputSelection, + LinuxToolProvider, +} from '@agent-device/contracts/linux-tool-provider'; export async function ensureInputTool( - provider: LinuxToolProvider = resolveLinuxToolProvider(), + provider: LinuxToolProvider, ): Promise { - const display: DisplayServer = provider.display.detectDisplayServer(); + const display = provider.display.detectDisplayServer(); if (display === 'wayland') { if (await provider.whichCommand('ydotool')) return { tool: 'ydotool', display }; diff --git a/packages/platform-linux/src/runtime.test.ts b/packages/platform-linux/src/runtime.test.ts index 2b9a041bc2..54485f33a3 100644 --- a/packages/platform-linux/src/runtime.test.ts +++ b/packages/platform-linux/src/runtime.test.ts @@ -1,13 +1,15 @@ -import { expect, test, vi } from 'vitest'; +import { expect, test } from 'vitest'; import type { DeviceBinding } from '@agent-device/contracts/platform-runtime'; import type { PlatformRuntimeHost, PlatformRuntimeOperations, } from '@agent-device/contracts/platform-runtime-operations'; -import type { SnapshotRuntimeHost } from '@agent-device/contracts/snapshot-runtime'; import { HOVER_UNAVAILABLE_HINT } from '@agent-device/contracts/touch-runtime'; import type { DeviceInfo } from '@agent-device/kernel/device'; +import { createLinuxHostStub, type LinuxHostStub } from './toolbox.fixtures.ts'; +import { createLinuxToolProvider } from './tool-provider.ts'; import { createLinuxPlatformRuntime } from './runtime.ts'; +import type { LinuxSnapshotSurface } from '@agent-device/contracts/linux-tool-provider'; type LegacyLifecycleCell = Readonly<{ openTarget: boolean; @@ -17,17 +19,38 @@ type LegacyLifecycleCell = Readonly<{ portReverse: boolean; }>; +const LINUX_DEVICE = { + platform: 'linux' as const, + id: 'linux', + name: 'Linux', + kind: 'device' as const, + target: 'desktop' as const, + booted: true, +} satisfies DeviceInfo; + +/** One AT-SPI capture the runtime was asked to make: the surface and the signal it was given. */ +type CapturedAtspi = Readonly<{ surface: LinuxSnapshotSurface; signal: AbortSignal | undefined }>; + +/** Every capture the runtime asked its provider to make, newest last. */ +function createCaptureRecorder() { + const captures: CapturedAtspi[] = []; + return { + captures, + overrides: { + accessibility: { + captureTree: async (surface: LinuxSnapshotSurface, options?: { signal?: AbortSignal }) => { + captures.push({ surface, signal: options?.signal }); + return { nodes: [], truncated: false, surface }; + }, + }, + }, + }; +} + test.each([ { name: 'desktop device', - device: { - platform: 'linux' as const, - id: 'linux', - name: 'Linux', - kind: 'device' as const, - target: 'desktop' as const, - booted: true, - }, + device: LINUX_DEVICE, // Legacy open/close descriptor cell: linux.device. Runtime and prepare had no dispatch cell. legacy: { openTarget: true, @@ -39,14 +62,7 @@ test.each([ }, { name: 'synthetic emulator', - device: { - platform: 'linux' as const, - id: 'linux-emulator', - name: 'Linux emulator', - kind: 'emulator' as const, - target: 'desktop' as const, - booted: true, - }, + device: { ...LINUX_DEVICE, id: 'linux-emulator', name: 'Linux emulator', kind: 'emulator' as const }, legacy: { openTarget: false, prepareAppleRunner: false, @@ -57,14 +73,7 @@ test.each([ }, { name: 'synthetic simulator', - device: { - platform: 'linux' as const, - id: 'linux-simulator', - name: 'Linux simulator', - kind: 'simulator' as const, - target: 'desktop' as const, - booted: true, - }, + device: { ...LINUX_DEVICE, id: 'linux-simulator', name: 'Linux simulator', kind: 'simulator' as const }, legacy: { openTarget: false, prepareAppleRunner: false, @@ -78,20 +87,10 @@ test.each([ >)( 'classifies the Linux $name lifecycle denominator against the legacy dispatch cell', async ({ device, legacy }) => { - const captureSurface = vi.fn(async () => ({ - backend: 'linux-atspi' as const, - producer: 'linux-atspi' as const, - nodes: [], - truncated: false, - })); - const binding = await createLinuxPlatformRuntime(lifecycleHost(captureSurface)).bind({ + const binding = await createLinuxRuntime().bind({ device, intent: { kind: 'ordinary' }, - scope: { - signal: new AbortController().signal, - diagnostics: { emit: () => {} }, - progress: { report: () => {} }, - }, + scope: requestScope(), }); expect(binding.facts.operations.networkDump).toMatchObject({ available: false, @@ -142,32 +141,168 @@ test.each([ expect(binding.operations.captureSnapshot).toBeTypeOf( device.kind === 'device' ? 'function' : 'undefined', ); - if (device.kind === 'device') { - await binding.operations.captureSnapshot?.({ - options: { interactiveOnly: true, depth: 2, scope: 'Settings', surface: 'desktop' }, - }); - expect(captureSurface).toHaveBeenCalledWith( - device, - { interactiveOnly: true, depth: 2, scope: 'Settings', surface: 'desktop' }, - expect.any(AbortSignal), - ); - } expectLifecycleFacts(binding, legacy); }, ); -function lifecycleHost( - captureSurface: SnapshotRuntimeHost['captureSurface'] = async () => ({ - backend: 'linux-atspi' as const, - producer: 'linux-atspi' as const, - nodes: [], - truncated: false, +test('the Linux runtime captures its own surface through the AT-SPI provider', async () => { + const recorder = createCaptureRecorder(); + const runtime = createLinuxRuntime(recorder.overrides); + const binding = await runtime.bind({ + device: LINUX_DEVICE, + intent: { kind: 'ordinary' }, + scope: requestScope(), + }); + + const snapshot = await binding.operations.captureSnapshot?.({ + options: { interactiveOnly: true, depth: 2, scope: 'Settings', surface: 'desktop' }, + }); + + expect(snapshot?.producer).toBe('linux-atspi'); + // The capture is the family's own: no desktop-surface loader is asked, and the request's projection + // options are applied by the plugin. + expect(recorder.captures).toEqual([{ surface: 'desktop', signal: expect.any(AbortSignal) }]); + expect(runtime.stub.diagnostics).toEqual([]); +}); + +test('the Linux runtime asks for the frontmost app when the request names the app surface', async () => { + const recorder = createCaptureRecorder(); + const binding = await createLinuxRuntime(recorder.overrides).bind({ + device: LINUX_DEVICE, + intent: { kind: 'ordinary' }, + scope: requestScope(), + }); + + await binding.operations.captureSnapshot?.({ options: { surface: 'app' } }); + + expect(recorder.captures.map((capture) => capture.surface)).toEqual(['frontmost-app']); +}); + +// `linuxSnapshotOperations` is the direct capture owner now, so the shared +// `bindSnapshotInteractor` composition does not cover it. Note it composes against +// `request.scope.signal` rather than `request.signal` — the Linux owner takes its signal off the +// request scope, which is exactly the detail a patch application can get wrong silently. +test('the Linux surface capture composes the per-capture signal with the request scope signal', async () => { + const recorder = createCaptureRecorder(); + const scope = new AbortController(); + const binding = await createLinuxRuntime(recorder.overrides).bind({ + device: LINUX_DEVICE, + intent: { kind: 'ordinary' }, + scope: { ...requestScope(), signal: scope.signal }, + }); + + const poll = new AbortController(); + await binding.operations.captureSnapshot?.({ options: {}, signal: poll.signal }); + + const passed = recorder.captures[0]!.signal!; + expect(passed.aborted).toBe(false); + poll.abort(new DOMException('Wait deadline exceeded', 'TimeoutError')); + expect(passed.aborted).toBe(true); + + // The scope signal must still cancel too: composition adds a way to cancel, never replaces one. + const second = new AbortController(); + await binding.operations.captureSnapshot?.({ options: {}, signal: second.signal }); + const passedSecond = recorder.captures[1]!.signal!; + scope.abort(); + expect(passedSecond.aborted).toBe(true); +}); + +// R52/R53: Linux is the one owner whose gesture tiers genuinely split. Its drag primitive +// preserves a coordinate fling's endpoints but not a direction-authored fling's speed semantics +// (`gesture fling is not supported on Linux`), it synthesizes one contact, and it has no frame +// read of its own — which is why `gestureViewport` is PREFERRED rather than required. +test.each([ + ['desktop device', 'device' as const, true], + ['non-desktop kind', 'emulator' as const, false], +])('declares the Linux %s gesture and scroll cells', async (_name, kind, supported) => { + const facts = await createLinuxRuntime().inspectFacts({ + ...LINUX_DEVICE, + kind, + }); + expect(facts.operations.performGesturePlan.available).toBe(supported); + expect(facts.operations.scrollDirection.available).toBe(supported); + expect(facts.operations.performDirectionalFlingPlan.available).toBe(false); + expect(facts.operations.performMultiTouchGesturePlan.available).toBe(false); + expect(facts.operations.performTargetAuthoredDrag).toMatchObject({ + available: false, + hint: expect.stringContaining('source hold, timed movement, and destination hold'), + }); + expect(facts.operations.gestureViewport.available).toBe(false); +}); + +test('hover has no Linux interactor route; the touch family reports its typed denial', async () => { + const facts = await createLinuxRuntime().inspectFacts(LINUX_DEVICE); + const hoverDenial = { + available: false, + reason: 'unsupported-platform-leaf', + hint: HOVER_UNAVAILABLE_HINT, + }; + expect(facts.operations.hoverPoint).toEqual(hoverDenial); + expect(facts.operations.hoverRef).toEqual(hoverDenial); +}); + +test('binds the Linux coordinate-fling tier without a frame read', async () => { + const binding = await createLinuxRuntime().bind({ + device: LINUX_DEVICE, + intent: { kind: 'ordinary' }, + scope: requestScope(), + }); + expect(binding.operations.performGesturePlan).toBeTypeOf('function'); + expect(binding.operations.scrollDirection).toBeTypeOf('function'); + expect(binding.operations.performDirectionalFlingPlan).toBeUndefined(); + expect(binding.operations.performMultiTouchGesturePlan).toBeUndefined(); + expect(binding.operations.performTargetAuthoredDrag).toBeUndefined(); + // Absent, not broken: the caller derives the coordinate frame from a capture instead, which is + // exactly how a Linux gesture resolved its viewport before this migration. + expect(binding.operations.gestureViewport).toBeUndefined(); +}); + +test('refuses to bind a device of another family', async () => { + await expect( + createLinuxRuntime().bind({ + device: { ...LINUX_DEVICE, platform: 'android' as never }, + intent: { kind: 'ordinary' }, + scope: requestScope(), + }), + ).rejects.toThrow(/Linux runtime cannot bind this device/); +}); + +test('refuses an exact-owner intent for another owner', async () => { + const runtime = createLinuxRuntime(); + await expect( + runtime.bind({ + device: LINUX_DEVICE, + intent: { kind: 'exact-owner', owner: { kind: 'local', family: 'macos' } } as never, + scope: requestScope(), + }), + ).rejects.toThrow(/owner identity does not match/); +}); + +function createLinuxRuntime( + providerOverrides: Parameters[1] = {}, + stub: LinuxHostStub = createLinuxHostStub({ + env: { PATH: '/usr/bin', XDG_SESSION_TYPE: 'x11' }, + respond: () => ({}), }), -): PlatformRuntimeHost { - return { +) { + const host = { localInteractors: { resolve: async () => ({}) }, - snapshot: { captureSurface }, + clock: { sleep: async () => {} }, } as unknown as PlatformRuntimeHost; + const provider = createLinuxToolProvider(stub.toolbox, { + sleep: async () => {}, + ...providerOverrides, + }); + // The runtime owner, with the host stub attached for the tests that assert what it recorded. + return Object.assign({}, createLinuxPlatformRuntime(host, stub.toolbox, provider), { stub }); +} + +function requestScope() { + return { + signal: new AbortController().signal, + diagnostics: { emit: () => {} }, + progress: { report: () => {} }, + }; } function expectLifecycleFacts( @@ -245,120 +380,3 @@ function expectLinuxNavigationAndKeyboardFacts( expect(binding.operations[operation]).toBeUndefined(); } } - -// `linuxSnapshotOperations` is the other direct `captureSurface` caller, so the shared -// `bindSnapshotInteractor` composition does not cover it either. Note it composes against -// `request.scope.signal` rather than `request.signal` — the Linux owner takes its signal off the -// request scope, which is exactly the detail a patch application can get wrong silently. -test('the Linux surface capture composes the per-capture signal with the request scope signal', async () => { - const captureSurface = vi.fn(async () => ({ - backend: 'linux-atspi' as const, - producer: 'linux-atspi' as const, - nodes: [], - truncated: false, - })); - const scope = new AbortController(); - const binding = await createLinuxPlatformRuntime(lifecycleHost(captureSurface)).bind({ - device: { - platform: 'linux' as const, - id: 'linux', - name: 'Linux', - kind: 'device' as const, - target: 'desktop' as const, - booted: true, - }, - intent: { kind: 'ordinary' }, - scope: { - signal: scope.signal, - diagnostics: { emit: () => {} }, - progress: { report: () => {} }, - }, - }); - - const poll = new AbortController(); - await binding.operations.captureSnapshot?.({ options: {}, signal: poll.signal }); - - const passed = captureSurface.mock.calls[0]?.[2] as AbortSignal; - expect(passed.aborted).toBe(false); - poll.abort(new DOMException('Wait deadline exceeded', 'TimeoutError')); - expect(passed.aborted).toBe(true); - - // The scope signal must still cancel too: composition adds a way to cancel, never replaces one. - const second = new AbortController(); - await binding.operations.captureSnapshot?.({ options: {}, signal: second.signal }); - const passedSecond = captureSurface.mock.calls[1]?.[2] as AbortSignal; - scope.abort(); - expect(passedSecond.aborted).toBe(true); -}); - -// R52/R53: Linux is the one owner whose gesture tiers genuinely split. Its drag primitive -// preserves a coordinate fling's endpoints but not a direction-authored fling's speed semantics -// (`gesture fling is not supported on Linux`), it synthesizes one contact, and it has no frame -// read of its own — which is why `gestureViewport` is PREFERRED rather than required. -test.each([ - ['desktop device', 'device' as const, true], - ['non-desktop kind', 'emulator' as const, false], -])('declares the Linux %s gesture and scroll cells', async (_name, kind, supported) => { - const facts = await createLinuxPlatformRuntime(lifecycleHost()).inspectFacts({ - platform: 'linux', - id: 'linux', - name: 'Linux', - kind, - target: 'desktop', - booted: true, - }); - expect(facts.operations.performGesturePlan.available).toBe(supported); - expect(facts.operations.scrollDirection.available).toBe(supported); - expect(facts.operations.performDirectionalFlingPlan.available).toBe(false); - expect(facts.operations.performMultiTouchGesturePlan.available).toBe(false); - expect(facts.operations.performTargetAuthoredDrag).toMatchObject({ - available: false, - hint: expect.stringContaining('source hold, timed movement, and destination hold'), - }); - expect(facts.operations.gestureViewport.available).toBe(false); -}); - -test('hover has no Linux interactor route; the touch family reports its typed denial', async () => { - const facts = await createLinuxPlatformRuntime(lifecycleHost()).inspectFacts({ - platform: 'linux', - id: 'linux', - name: 'Linux', - kind: 'device', - target: 'desktop', - booted: true, - }); - const hoverDenial = { - available: false, - reason: 'unsupported-platform-leaf', - hint: HOVER_UNAVAILABLE_HINT, - }; - expect(facts.operations.hoverPoint).toEqual(hoverDenial); - expect(facts.operations.hoverRef).toEqual(hoverDenial); -}); - -test('binds the Linux coordinate-fling tier without a frame read', async () => { - const binding = await createLinuxPlatformRuntime(lifecycleHost()).bind({ - device: { - platform: 'linux', - id: 'linux', - name: 'Linux', - kind: 'device', - target: 'desktop', - booted: true, - }, - intent: { kind: 'ordinary' }, - scope: { - signal: new AbortController().signal, - diagnostics: { emit: () => {} }, - progress: { report: () => {} }, - }, - }); - expect(binding.operations.performGesturePlan).toBeTypeOf('function'); - expect(binding.operations.scrollDirection).toBeTypeOf('function'); - expect(binding.operations.performDirectionalFlingPlan).toBeUndefined(); - expect(binding.operations.performMultiTouchGesturePlan).toBeUndefined(); - expect(binding.operations.performTargetAuthoredDrag).toBeUndefined(); - // Absent, not broken: the caller derives the coordinate frame from a capture instead, which is - // exactly how a Linux gesture resolved its viewport before this migration. - expect(binding.operations.gestureViewport).toBeUndefined(); -}); diff --git a/packages/platform-linux/src/runtime.ts b/packages/platform-linux/src/runtime.ts index 7f0230b711..b21ef9ef37 100644 --- a/packages/platform-linux/src/runtime.ts +++ b/packages/platform-linux/src/runtime.ts @@ -13,6 +13,7 @@ import { applicationLifecycleOperationFacts, availableApplicationLifecycleOperations, } from '@agent-device/contracts/application-lifecycle-runtime'; +import { bindLocalDirectApplicationLifecycle } from '@agent-device/contracts/application-lifecycle-interaction'; import { backRuntimeOperationFacts } from '@agent-device/contracts/back-runtime'; import { elementTextRuntimeOperationFacts } from '@agent-device/contracts/element-text-runtime'; import { focusRuntimeOperationFacts } from '@agent-device/contracts/focus-runtime'; @@ -41,7 +42,10 @@ import { typeTextRuntimeOperationFacts } from '@agent-device/contracts/type-text import { touchRuntimeOperationFacts } from '@agent-device/contracts/touch-runtime'; import type { DeviceInfo } from '@agent-device/kernel/device'; import { AppError } from '@agent-device/kernel/errors'; -import { bindLocalDirectApplicationLifecycle } from '@agent-device/contracts/application-lifecycle-interaction'; +import type { LinuxToolProvider } from '@agent-device/contracts/linux-tool-provider'; +import { captureLinuxSurfaceSnapshot } from './surface-snapshot.ts'; +import { resolveLinuxToolProvider } from './tool-provider.ts'; +import type { LinuxToolbox } from './toolbox.ts'; const supported = Object.freeze({ available: true } as const); const linuxOwner = localRuntimeOwner('linux'); @@ -127,7 +131,16 @@ const linuxAudioProbeUnavailable = unavailableFact( 'unsupported-platform-leaf', 'audio is supported for web browser sessions, macOS sessions, iOS simulators, and Android emulators on macOS hosts', ); -export function createLinuxPlatformRuntime(host: PlatformRuntimeHost): PlatformRuntimeOwner { + +/** + * The Linux runtime owner. It captures its own surface: the AT-SPI read is this family's mechanics, + * so the binding runs it through the plugin's host rather than asking the core for a desktop capture. + */ +export function createLinuxPlatformRuntime( + host: PlatformRuntimeHost, + toolbox: LinuxToolbox, + provider: LinuxToolProvider, +): PlatformRuntimeOwner { return Object.freeze({ owner: linuxOwner, ownsDevice: (device) => device.platform === 'linux', @@ -157,7 +170,7 @@ export function createLinuxPlatformRuntime(host: PlatformRuntimeHost): PlatformR operations: Object.freeze({ ...availableApplicationLifecycleOperations(lifecycle, facts.operations), ...(facts.operations.captureSnapshot.available - ? linuxSnapshotOperations(host, request) + ? linuxSnapshotOperations(toolbox, provider, request) : {}), ...linuxInteractionOperations(host, request, facts), }), @@ -309,14 +322,22 @@ function linuxTouchFacts(device: DeviceInfo) { } function linuxSnapshotOperations( - host: PlatformRuntimeHost, + toolbox: LinuxToolbox, + provider: LinuxToolProvider, request: Parameters[0], ) { const captureSnapshot = async (input: CaptureSnapshotInput) => - await host.snapshot.captureSurface( - request.device, - input.options, - captureSnapshotSignal(request.scope.signal, input), + await toolbox.withDiagnosticTimer( + 'snapshot_capture', + async () => + await captureLinuxSurfaceSnapshot( + toolbox, + // The provider the request scoped, when it scoped one; otherwise this runtime's own. + resolveLinuxToolProvider(provider), + input.options, + captureSnapshotSignal(request.scope.signal, input), + ), + { backend: 'linux-atspi' }, ); return Object.freeze({ captureSnapshot, diff --git a/packages/platform-linux/src/screenshot.ts b/packages/platform-linux/src/screenshot.ts index 46b245067c..7c5e399f0b 100644 --- a/packages/platform-linux/src/screenshot.ts +++ b/packages/platform-linux/src/screenshot.ts @@ -1,8 +1,10 @@ -import { resolveLinuxToolProvider, type LinuxScreenshotOptions } from './tool-provider.ts'; +import type { ScreenshotOptions } from '@agent-device/contracts/interactor-types'; +import type { LinuxToolProvider } from '@agent-device/contracts/linux-tool-provider'; export async function screenshotLinux( + provider: LinuxToolProvider, outPath: string, - options?: LinuxScreenshotOptions, + options?: ScreenshotOptions, ): Promise { - await resolveLinuxToolProvider().screenshot!.capture(outPath, options); + await provider.screenshot!.capture(outPath, options); } diff --git a/packages/platform-linux/src/snapshot.ts b/packages/platform-linux/src/snapshot.ts index 80b7bfe39f..3440731ef7 100644 --- a/packages/platform-linux/src/snapshot.ts +++ b/packages/platform-linux/src/snapshot.ts @@ -1,7 +1,7 @@ import type { RawSnapshotNode } from '@agent-device/kernel/snapshot'; -import { captureAccessibilityTree, type SnapshotSurface } from './atspi-bridge.ts'; +import type { LinuxToolProvider } from '@agent-device/contracts/linux-tool-provider'; +import type { LinuxToolbox } from './toolbox.ts'; import type { SessionSurface } from '@agent-device/contracts/session'; -import { emitDiagnostic } from '@agent-device/host-kit/diagnostics'; /** * Map the session-level surface to an AT-SPI2 surface. @@ -9,11 +9,14 @@ import { emitDiagnostic } from '@agent-device/host-kit/diagnostics'; * (used for in-app XCTest sessions) is treated as 'frontmost-app' on Linux. * The 'menubar' surface is not yet supported; it falls back to 'desktop'. */ -function resolveLinuxSurface(surface: SessionSurface | undefined): SnapshotSurface { +function resolveLinuxSurface( + toolbox: LinuxToolbox, + surface: SessionSurface | undefined, +): 'desktop' | 'frontmost-app' { if (surface === 'desktop') return 'desktop'; if (surface === 'frontmost-app' || surface === 'app') return 'frontmost-app'; if (surface === 'menubar') { - emitDiagnostic({ + toolbox.commands.diagnose({ level: 'warn', phase: 'linux_snapshot', data: { message: 'menubar surface is not supported on Linux, falling back to desktop' }, @@ -23,27 +26,31 @@ function resolveLinuxSurface(surface: SessionSurface | undefined): SnapshotSurfa } export async function snapshotLinux( + toolbox: LinuxToolbox, + provider: LinuxToolProvider, surface: SessionSurface | undefined, signal?: AbortSignal, ): Promise<{ nodes: RawSnapshotNode[]; truncated?: boolean; }> { - const linuxSurface = resolveLinuxSurface(surface); - const result = await captureAccessibilityTree(linuxSurface, { signal }); + const linuxSurface = resolveLinuxSurface(toolbox, surface); + const result = await provider.accessibility!.captureTree(linuxSurface, { signal }); return { - nodes: result.nodes, + nodes: [...result.nodes], truncated: result.truncated, }; } export async function readLinuxTextAtPoint( + toolbox: LinuxToolbox, + provider: LinuxToolProvider, x: number, y: number, surface: SessionSurface | undefined, ): Promise { - const { nodes } = await snapshotLinux(surface); + const { nodes } = await snapshotLinux(toolbox, provider, surface); const matches = nodes .filter((node) => { const rect = node.rect; diff --git a/packages/platform-linux/src/surface-snapshot.ts b/packages/platform-linux/src/surface-snapshot.ts index dd4f4785d9..261cbdeb5f 100644 --- a/packages/platform-linux/src/surface-snapshot.ts +++ b/packages/platform-linux/src/surface-snapshot.ts @@ -1,13 +1,24 @@ import { stampSnapshotIdentity } from '@agent-device/contracts/snapshot-producers'; import type { CaptureSnapshotInput } from '@agent-device/contracts/snapshot-runtime'; import { shapeDesktopSurfaceSnapshot } from '@agent-device/capture-kit/snapshot-desktop-projection'; +import { snapshotLinux } from './snapshot.ts'; +import { resolveLinuxToolProvider } from './tool-provider.ts'; +import type { LinuxToolProvider } from '@agent-device/contracts/linux-tool-provider'; +import type { LinuxToolbox } from './toolbox.ts'; +/** + * One Linux surface capture, shaped like every other desktop surface capture. The core no longer + * routes this: the family's runtime owns it, so a `snapshot` of a Linux device runs here and lands in + * the request's exec trace through the host the plugin was set up with. + */ export async function captureLinuxSurfaceSnapshot( + toolbox: LinuxToolbox, + own: LinuxToolProvider, options: CaptureSnapshotInput['options'], signal?: AbortSignal, ) { - const { snapshotLinux } = await import('./snapshot.ts'); - const result = await snapshotLinux(options?.surface, signal); + const provider = resolveLinuxToolProvider(own); + const result = await snapshotLinux(toolbox, provider, options?.surface, signal); return shapeDesktopSurfaceSnapshot( stampSnapshotIdentity( { nodes: result.nodes, truncated: result.truncated }, diff --git a/packages/platform-linux/src/tool-provider.ts b/packages/platform-linux/src/tool-provider.ts index 423fb2c5f6..a27ce9bf4d 100644 --- a/packages/platform-linux/src/tool-provider.ts +++ b/packages/platform-linux/src/tool-provider.ts @@ -1,179 +1,78 @@ -import type { ClickButton } from '@agent-device/contracts/click-button'; -import type { ScrollDirection } from '@agent-device/contracts/scroll-gesture'; import { AppError } from '@agent-device/kernel/errors'; -import { - runCmd, - runCmdDetachedMonitored, - whichCmd, - type ExecDetachedExit, - type ExecOptions, - type ExecResult, - commandHostEnvironment, -} from '@agent-device/host-kit/command'; -import { emitDiagnostic } from '@agent-device/host-kit/diagnostics'; -import { sleep } from '@agent-device/host-kit/retry'; - import { createScopedProvider } from '@agent-device/kernel/scoped-provider'; -import type { HostEnvironment } from '@agent-device/kernel/source-value'; - import type { - LinuxAccessibilityTree, - LinuxSnapshotSurface, - LinuxTraversalOptions, -} from './accessibility-types.ts'; -import { - createLinuxDisplayConfig, - detectLinuxDisplayServer, - type LinuxDisplayConfig, -} from './display.ts'; + LinuxClipboardProvider, + LinuxDesktopProvider, + LinuxScreenshotProvider, + LinuxToolProvider, +} from '@agent-device/contracts/linux-tool-provider'; +import { createLinuxAccessibilityProvider } from './atspi-bridge.ts'; +import type { LinuxToolbox } from './toolbox.ts'; +import { createLinuxDisplayConfig } from './display.ts'; -export type LinuxToolCommandExecutor = ( - cmd: string, - args: string[], - options?: ExecOptions, -) => Promise; +export type { LinuxToolProvider } from '@agent-device/contracts/linux-tool-provider'; -export type LinuxToolAvailabilityChecker = (cmd: string) => Promise; +/** The parts a caller may supply over the family's own tool route, each answering one intent. */ +export type LinuxToolProviderOverrides = Partial>; /** - * 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. + * Builds the local provider for one host: every Linux tool call it makes runs through the toolbox the + * plugin was set up with, and the display decision comes from that host's environment, never an + * ambient read (#3794). */ -export type LinuxToolDetachedLauncher = ( - cmd: string, - args: string[], -) => { exited: Promise }; - -export type LinuxDesktopProvider = { - openTarget(target: string): Promise; - closeApp(app: string): Promise; -}; - -export type LinuxClipboardProvider = { - readText(): Promise; - writeText(text: string): Promise; -}; - -export type LinuxScreenshotOptions = { - fullscreen?: boolean; - stabilize?: boolean; - surface?: string; -}; - -export type LinuxScreenshotProvider = { - capture(outPath: string, options?: LinuxScreenshotOptions): Promise; -}; - -export type LinuxAccessibilityProvider = { - captureTree( - surface: LinuxSnapshotSurface, - options?: LinuxTraversalOptions, - ): Promise; -}; - -export type LinuxPointerButton = ClickButton; - -export type LinuxInputProvider = { - click(x: number, y: number, button: LinuxPointerButton): Promise; - doubleClick(x: number, y: number): Promise; - longPress(x: number, y: number, durationMs: number): Promise; - drag(x1: number, y1: number, x2: number, y2: number, durationMs: number): Promise; - scroll( - direction: ScrollDirection, - options?: { amount?: number; pixels?: number; durationMs?: number }, - ): Promise; - typeText(text: string, options?: { delayMs?: number }): Promise; - key(combo: string, scancodes: string[]): Promise; -}; - -export type LinuxToolProvider = { - /** The bound display decision every local tool selection in this provider shares (#3794). */ - display: LinuxDisplayConfig; - runCommand: LinuxToolCommandExecutor; - whichCommand: LinuxToolAvailabilityChecker; - launchDetached: LinuxToolDetachedLauncher; - desktop: LinuxDesktopProvider; - clipboard?: LinuxClipboardProvider; - screenshot?: LinuxScreenshotProvider; - accessibility?: LinuxAccessibilityProvider; - input?: LinuxInputProvider; -}; - -const whichOnPath = async (cmd: string): Promise => - await whichCmd(cmd, commandHostEnvironment().env); - -/** A provider under construction; only the display decision is required up front. */ -/** - * The parts a caller may supply. A caller that injects `runCommand` owns process execution, so it - * also supplies `launchDetached`: the host-local detached runner never stands in beside an - * injected executor. - */ -export type LinuxToolProviderOverrides = Partial< - Omit -> & - ( - | { runCommand?: undefined; launchDetached?: LinuxToolDetachedLauncher } - | { runCommand: LinuxToolCommandExecutor; launchDetached: LinuxToolDetachedLauncher } - ); - -type LinuxToolProviderParts = { display: LinuxDisplayConfig } & LinuxToolProviderOverrides; - -/** Adds the local parts a partial provider omits; every part then belongs to this instance. */ -function completeLocalLinuxToolProvider(provider: LinuxToolProviderParts): LinuxToolProvider { - const runCommand = provider.runCommand ?? runCmd; - const whichCommand = provider.whichCommand ?? whichOnPath; - const launchDetached = provider.launchDetached ?? runCmdDetachedMonitored; - const display = provider.display; - return { - runCommand, - whichCommand, - launchDetached, +export function createLinuxToolProvider( + toolbox: LinuxToolbox, + overrides: LinuxToolProviderOverrides = {}, +): LinuxToolProvider { + // The command primitives are resolved first, and the family's own semantic parts are built on the + // resolved ones: a caller that replaces the command route or the pacing replaces it for the whole + // provider, not only for the methods it named. The display decision is never replaced: it is read + // from the host this toolbox was set up with, which is what makes it the same decision the tools + // this provider spawns were resolved for (#3794). + const commands = withCommandOverrides(toolbox.commands, overrides); + const display = createLinuxDisplayConfig(() => toolbox.env); + return Object.freeze({ display, - desktop: - provider.desktop ?? createLocalLinuxDesktopProvider(runCommand, whichCommand, launchDetached), - clipboard: - provider.clipboard ?? createLocalLinuxClipboardProvider(runCommand, whichCommand, display), - screenshot: - provider.screenshot ?? createLocalLinuxScreenshotProvider(runCommand, whichCommand, display), - ...(provider.accessibility ? { accessibility: provider.accessibility } : {}), - ...(provider.input ? { input: provider.input } : {}), - }; + runCommand: commands.run, + whichCommand: commands.which, + launchDetached: commands.launchDetached, + sleep: commands.sleep, + desktop: overrides.desktop ?? createLinuxDesktopProvider(commands), + clipboard: overrides.clipboard ?? createLinuxClipboardProvider(commands, display), + screenshot: overrides.screenshot ?? createLinuxScreenshotProvider(commands, display), + accessibility: overrides.accessibility ?? createLinuxAccessibilityProvider(commands), + ...(overrides.input ? { input: overrides.input } : {}), + }); } -/** - * Builds a local provider that reads its configuration from `host`, never from the ambient one: - * one provider instance per composing runtime, owning its display decision (#3794). - */ -export function createLocalLinuxToolProvider( - options: { host: HostEnvironment } & LinuxToolProviderOverrides, -): LinuxToolProvider { - const { host, ...provider } = options; - return completeLocalLinuxToolProvider({ - ...provider, - display: provider.display ?? createLinuxDisplayConfig(host), +function withCommandOverrides( + commands: LinuxToolbox['commands'], + overrides: LinuxToolProviderOverrides, +): LinuxToolbox['commands'] { + return Object.freeze({ + run: overrides.runCommand ?? commands.run, + which: overrides.whichCommand ?? commands.which, + launchDetached: overrides.launchDetached ?? commands.launchDetached, + sleep: overrides.sleep ?? commands.sleep, + diagnose: commands.diagnose, }); } /** - * The fallback for callers outside every composed runtime (standalone leaf calls, scripts that - * name no host): it reads the display decision from the command host of the call, like the - * ambient read it replaces. A composed runtime binds its own host at `createLinuxInteractor`, so - * its display decision never comes from here (#3794). + * The request scope the Linux family owns. Root composition resolves a provider for a request and + * hands it back to the plugin through the registration's `withRequestProvider`, which enters it for + * the request's work. The interactor and the runtime read the entered provider in preference to the + * one built from their own host, so a request that owns a display decision and a command route is the + * only one that answers for it. */ -// Names no executor, so the host-local defaults apply, including the detached app launcher. -const localLinuxToolProvider = completeLocalLinuxToolProvider({ - display: { - detectDisplayServer: () => detectLinuxDisplayServer(commandHostEnvironment().env), - }, -}); - -const linuxToolProviderScope = createScopedProvider( - localLinuxToolProvider, - completeLocalLinuxToolProvider, -); - -export function resolveLinuxToolProvider(provider?: LinuxToolProvider): LinuxToolProvider { - return linuxToolProviderScope.resolve(provider); +const linuxToolProviderScope = createScopedProvider< + LinuxToolProvider | undefined, + LinuxToolProvider +>(undefined); + +/** The provider this call should use: the one a request scoped, else the caller's own. */ +export function resolveLinuxToolProvider(own: LinuxToolProvider): LinuxToolProvider { + return linuxToolProviderScope.resolve() ?? own; } export function hasScopedLinuxToolProvider(): boolean { @@ -187,102 +86,92 @@ export async function withLinuxToolProvider( return await linuxToolProviderScope.run(provider, fn); } -export async function runLinuxToolCommand( - cmd: string, - args: string[], - options?: ExecOptions, -): Promise { - return await resolveLinuxToolProvider().runCommand(cmd, args, options); -} - -/** What a launched app's exit says went wrong: a start failure, a non-zero exit, or a signal. */ -function describeLaunchExit(exit: ExecDetachedExit): Record | undefined { - if (exit.error !== undefined) return { error: exit.error }; - if (exit.signal !== undefined) return { signal: exit.signal }; - if (exit.exitCode !== undefined && exit.exitCode !== 0) return { exitCode: exit.exitCode }; - return undefined; -} - -function createLocalLinuxDesktopProvider( - runCommand: LinuxToolCommandExecutor, - whichCommand: LinuxToolAvailabilityChecker, - launchDetached: LinuxToolDetachedLauncher, +export function createLinuxDesktopProvider( + commands: LinuxToolbox['commands'], ): LinuxDesktopProvider { return { async openTarget(target) { if (target.includes('://') || target.startsWith('/')) { - await runCommand('xdg-open', [target]); + await commands.run('xdg-open', [target]); return; } - 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 launchDetached(target, []).exited.then((exit) => { + if (await commands.which(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 commands.launchDetached(target, []).exited.then((exit) => { const failure = describeLaunchExit(exit); if (failure === undefined) return; - emitDiagnostic({ + commands.diagnose({ level: 'warn', phase: 'linux_app_launch', data: { app: target, ...failure }, }); }); - await sleep(500); + await commands.sleep(500); return; } - await runCommand('xdg-open', [target], { allowFailure: true }); + await commands.run('xdg-open', [target], { allowFailure: true }); }, async closeApp(app) { - if (await whichCommand('wmctrl')) { - await runCommand('wmctrl', ['-c', app], { allowFailure: true }); + if (await commands.which('wmctrl')) { + await commands.run('wmctrl', ['-c', app], { allowFailure: true }); return; } - await runCommand('pkill', ['-x', app], { allowFailure: true }); + await commands.run('pkill', ['-x', app], { allowFailure: true }); }, }; } -function createLocalLinuxClipboardProvider( - runCommand: LinuxToolCommandExecutor, - whichCommand: LinuxToolAvailabilityChecker, - display: LinuxDisplayConfig, +export function createLinuxClipboardProvider( + commands: LinuxToolbox['commands'], + display: LinuxToolProvider['display'], ): LinuxClipboardProvider { return { async readText() { - const tool = await resolveLocalLinuxTool(whichCommand, display, LOCAL_CLIPBOARD_TOOLS); + const tool = await resolveLocalLinuxTool(commands, display, LOCAL_CLIPBOARD_TOOLS); const command = LOCAL_CLIPBOARD_READ_COMMANDS[tool]; - return (await runCommand(command.cmd, command.args, command.options)).stdout; + return (await commands.run(command.cmd, command.args, command.options)).stdout; }, async writeText(text) { - const tool = await resolveLocalLinuxTool(whichCommand, display, LOCAL_CLIPBOARD_TOOLS); + const tool = await resolveLocalLinuxTool(commands, display, LOCAL_CLIPBOARD_TOOLS); const command = LOCAL_CLIPBOARD_WRITE_COMMANDS[tool](text); - await runCommand(command.cmd, command.args, command.options); + await commands.run(command.cmd, command.args, command.options); }, }; } -function createLocalLinuxScreenshotProvider( - runCommand: LinuxToolCommandExecutor, - whichCommand: LinuxToolAvailabilityChecker, - display: LinuxDisplayConfig, +export function createLinuxScreenshotProvider( + commands: LinuxToolbox['commands'], + display: LinuxToolProvider['display'], ): LinuxScreenshotProvider { return { async capture(outPath) { - const tool = await resolveLocalLinuxTool(whichCommand, display, LOCAL_SCREENSHOT_TOOLS); + const tool = await resolveLocalLinuxTool(commands, display, LOCAL_SCREENSHOT_TOOLS); const command = LOCAL_SCREENSHOT_COMMANDS[tool](outPath); - await runCommand(command.cmd, command.args, command.options); + await commands.run(command.cmd, command.args, command.options); }, }; } +/** What a launched app's exit says went wrong: a start failure, a non-zero exit, or a signal. */ +function describeLaunchExit( + exit: Awaited['exited']>, +): Record | undefined { + if (exit.error !== undefined) return { error: exit.error }; + if (exit.signal !== undefined) return { signal: exit.signal }; + if (exit.exitCode !== undefined && exit.exitCode !== 0) return { exitCode: exit.exitCode }; + return undefined; +} + type LocalLinuxClipboardTool = 'wl-clipboard' | 'xclip' | 'xsel'; type LocalLinuxScreenshotTool = 'grim' | 'gnome-screenshot' | 'scrot' | 'import'; type LocalLinuxToolCommand = { cmd: string; args: string[]; - options?: ExecOptions; + options?: { allowFailure?: boolean; timeoutMs?: number; stdin?: string }; }; type LocalLinuxToolCandidate = { tool: T; @@ -375,13 +264,13 @@ const LOCAL_SCREENSHOT_COMMANDS: Record< }; async function resolveLocalLinuxTool( - whichCommand: LinuxToolAvailabilityChecker, - display: LinuxDisplayConfig, + commands: LinuxToolbox['commands'], + display: LinuxToolProvider['display'], config: LocalLinuxToolConfig, ): Promise { const server = display.detectDisplayServer(); for (const candidate of config[server]) { - if (await whichCommand(candidate.command)) return candidate.tool; + if (await commands.which(candidate.command)) return candidate.tool; } throw new AppError('TOOL_MISSING', server === 'wayland' ? config.waylandError : config.x11Error); } diff --git a/packages/platform-linux/src/toolbox.fixtures.ts b/packages/platform-linux/src/toolbox.fixtures.ts new file mode 100644 index 0000000000..7a95d66faf --- /dev/null +++ b/packages/platform-linux/src/toolbox.fixtures.ts @@ -0,0 +1,181 @@ +import fs from 'node:fs'; +import path from 'node:path'; +import { mkdtempForTestSync } from '@agent-device/test-kit'; +import type { HostEnvironment } from '@agent-device/kernel/source-value'; +import type { PlatformHost } from 'agent-device/plugins'; +import type { LinuxCommandResult, LinuxDetachedExit } from '@agent-device/contracts/linux-tool-provider'; +import { createLinuxToolbox, type LinuxToolbox } from './toolbox.ts'; + +/** One command this stubbed host was asked to run, plus the environment it was handed. */ +export type LinuxHostStubCommand = Readonly<{ + executable: string; + args: readonly string[]; + env: HostEnvironment['env'] | undefined; + timeoutMs: number | undefined; + allowFailure: boolean | undefined; + stdin: string | undefined; + signal: AbortSignal | undefined; +}>; + +/** One detached launch the plugin asked the host to start. */ +export type LinuxHostStubLaunch = Readonly<{ + executable: string; + args: readonly string[]; + env: HostEnvironment['env'] | undefined; +}>; + +export type LinuxHostStub = Readonly<{ + toolbox: LinuxToolbox; + host: PlatformHost; + /** Every command the plugin asked the host to run, in order. */ + commands: LinuxHostStubCommand[]; + /** Every detached launch the plugin asked the host to start, in order. */ + launches: LinuxHostStubLaunch[]; + /** Every diagnostic the plugin recorded through the host, in order. */ + diagnostics: LinuxHostDiagnostic[]; + /** Queues one answer for the next command; exit code 0 is the common case. */ + answer(answer?: Partial & Readonly<{ stdout?: string }>): void; + /** Queues one exit for the next detached launch. */ + answerLaunch(exit: LinuxDetachedExit): void; +}>; + +/** One family diagnostic the plugin recorded through the host. */ +export type LinuxHostDiagnostic = Readonly<{ + level: string; + phase: string; + data: Record; +}>; + +const NO_ANSWER: LinuxCommandResult = Object.freeze({ + stdout: '', + stderr: 'linux-host-stub: no answer queued', + exitCode: 1, +}); + +/** + * Binds the plugin's toolbox to an in-memory host for colocated unit tests: nothing spawns, and + * every command and detached launch the plugin asks for is recorded with the environment the plugin + * built. Tests assert on the argv and on which tools the host reported, which is what this family's + * tool contract is. + */ +export function createLinuxHostStub( + input: Readonly<{ + env?: Readonly>; + /** Tools the host can execute. When set, `isFileExecutable` answers from it alone. */ + tools?: Iterable; + /** Answers one command. Takes precedence over the queued answers. */ + respond?: ( + executable: string, + args: readonly string[], + ) => Partial & Readonly<{ stdout?: string }>; + /** Rejected one command, the way the host rejects a spawn it cannot start. */ + reject?: (executable: string, args: readonly string[]) => Error; + /** Answers a detached launch. Takes precedence over the queued exits. */ + launchExit?: (executable: string, args: readonly string[]) => LinuxDetachedExit; + }> = {}, +): LinuxHostStub { + const env = input.env ?? { PATH: '/usr/bin' }; + const tools = input.tools ? new Set(input.tools) : undefined; + const commands: LinuxHostStubCommand[] = []; + const launches: LinuxHostStubLaunch[] = []; + const answers: LinuxCommandResult[] = []; + const launchExits: LinuxDetachedExit[] = []; + const diagnostics: LinuxHostDiagnostic[] = []; + const host = Object.freeze({ + env, + cwd: '/host-cwd', + stateDir: '/host-state', + emitDiagnostic: (event: LinuxHostDiagnostic) => { + diagnostics.push(event); + }, + withDiagnosticTimer: async (_phase: string, operation: () => Promise) => + await operation(), + // The availability probe the plugin is allowed to make: the tool list stands in for the host's + // `PATH`, so a test states which desktop tools exist rather than writing executables. + isFileExecutable: async (candidate: string) => + tools === undefined ? false : tools.has(path.basename(candidate)), + runCommand: async ( + executable: string, + args: string[], + options: { + env?: Readonly>; + timeoutMs?: number; + allowFailure?: boolean; + stdin?: string; + signal?: AbortSignal; + }, + ): Promise => { + commands.push({ + executable, + args, + env: options.env, + timeoutMs: options.timeoutMs, + allowFailure: options.allowFailure, + stdin: options.stdin, + signal: options.signal, + }); + if (input.reject) throw input.reject(executable, args); + if (input.respond) return toResult(input.respond(executable, args)); + return answers.shift() ?? NO_ANSWER; + }, + launchDetached: async ( + executable: string, + args: string[], + options: { env?: Readonly> }, + ) => { + launches.push({ executable, args, env: options.env }); + const queued = + input.launchExit?.(executable, args) ?? launchExits.shift() ?? { pid: 1, exitCode: 0 }; + return { pid: queued.pid, exited: Promise.resolve(queued) }; + }, + }) as unknown as PlatformHost; + return Object.freeze({ + toolbox: createLinuxToolbox(host), + host, + commands, + launches, + diagnostics, + answer: (answer) => { + answers.push(toResult(answer)); + }, + answerLaunch: (exit) => { + launchExits.push(exit); + }, + }); +} + +/** The provider built on the stub host, with one semantic part replaced. */ +export function createLinuxToolboxWith( + toolbox: LinuxToolbox, + overrides: Readonly<{ commands?: LinuxToolbox['commands'] }>, +): LinuxToolbox { + return Object.freeze({ ...toolbox, ...overrides }); +} + +/** + * A directory holding one executable stand-in tool, for the tests that need the host to resolve a + * bare name through a real `PATH` rather than through a stated tool list. + */ +export function createLinuxToolDirectory( + name: string, + contents = '#!/bin/sh\nexit 0\n', +): string { + const root = mkdtempForTestSync(`linux-tool-${name}-`); + fs.writeFileSync(path.join(root, name), contents, { mode: 0o755 }); + return root; +} + +/** One command the plugin asked the host to run, as `[executable, args]`. */ +export function linuxCommandTuple( + command: LinuxHostStubCommand, +): [string, readonly string[]] { + return [command.executable, command.args]; +} + +function toResult(answer: (Partial & { stdout?: string }) | undefined) { + return Object.freeze({ + stdout: answer?.stdout ?? '', + stderr: answer?.stderr ?? '', + exitCode: answer?.exitCode ?? 0, + }); +} diff --git a/packages/platform-linux/src/toolbox.ts b/packages/platform-linux/src/toolbox.ts new file mode 100644 index 0000000000..53ea559a28 --- /dev/null +++ b/packages/platform-linux/src/toolbox.ts @@ -0,0 +1,28 @@ +import { createLinuxCommandRunner, type LinuxCommandRunner } from './command-runner.ts'; +import type { PlatformHost } from 'agent-device/plugins'; + +/** + * Everything the Linux family needs from the machine it runs on, built once from the `PlatformHost` + * the core hands `setup()`, and shared by inventory, the runtime, the interactor and the capture. + * + * It exists so the plugin never reaches for process globals of its own. The package is bundled with + * its own copy of the host kit, and the daemon's command scope never enters that copy, so a spawn + * made through it would run with the daemon's environment and outside the request's exec trace. + * Going through the host keeps resolution, environment and diagnostics where the core put them. + */ +export type LinuxToolbox = Readonly<{ + /** Host commands, availability probes, detached launches and family diagnostics. */ + commands: LinuxCommandRunner; + /** The host environment the plugin was set up with: the display decision reads it (#3794). */ + env: PlatformHost['env']; + /** Timings for this family's operations, in the request's diagnostic store. */ + withDiagnosticTimer: PlatformHost['withDiagnosticTimer']; +}>; + +export function createLinuxToolbox(host: PlatformHost): LinuxToolbox { + return Object.freeze({ + commands: createLinuxCommandRunner(host), + env: host.env, + withDiagnosticTimer: host.withDiagnosticTimer, + }); +} diff --git a/packages/platform-linux/test/package-smoke.mjs b/packages/platform-linux/test/package-smoke.mjs new file mode 100644 index 0000000000..4e6763e25b --- /dev/null +++ b/packages/platform-linux/test/package-smoke.mjs @@ -0,0 +1,329 @@ +import assert from 'node:assert/strict'; +import { execFileSync } from 'node:child_process'; +import fs from 'node:fs'; +import os from 'node:os'; +import path from 'node:path'; +import { test } from 'node:test'; + +const repo = path.resolve(import.meta.dirname, '../../..'); + +/** + * A stand-in for one Linux desktop session: the input synthesizer, clipboard, screenshot tool and + * AT-SPI helper the family asks a desktop for. Each stub answers one canned reply and appends its + * argv plus the `PATH` and `DISPLAY` it was spawned with, so the test can prove which executable ran, + * with what arguments, and through which host environment. The paths are baked into the stubs rather + * than passed by environment: the plugin builds each spawn environment from the host it was set up + * with, so nothing this fixture needs travels through it. + */ +function desktopToolStubSource(tool, logFile, reply) { + return [ + '#!/usr/bin/env node', + "const fs = require('node:fs');", + 'const args = process.argv.slice(2);', + 'const joined = args.join(" ");', + 'fs.appendFileSync(' + + JSON.stringify(logFile) + + String.raw`, "TOOL: " + ${JSON.stringify(tool)} + "\nARGS: " + joined + "\nPATH: " + process.env.PATH + "\nDISPLAY: " + (process.env.DISPLAY || "") + "\n");`, + String.raw`const answer = (text) => process.stdout.write(text + "\n");`, + reply, + ].join('\n'); +} + +/** The AT-SPI helper's reply: two nodes for one window, in the shape `atspi-dump.py` prints. */ +function atspiStubSource(logFile) { + const tree = JSON.stringify({ + nodes: [ + { + index: 0, + role: 'frame', + label: 'Stub Window', + rect: { x: 0, y: 0, width: 400, height: 300 }, + enabled: true, + hittable: true, + depth: 0, + }, + { + index: 1, + role: 'push button', + label: 'OK', + rect: { x: 40, y: 80, width: 60, height: 30 }, + enabled: true, + hittable: true, + depth: 1, + parentIndex: 0, + }, + ], + truncated: false, + surface: 'desktop', + }); + return [ + '#!/usr/bin/env node', + "const fs = require('node:fs');", + 'const args = process.argv.slice(2);', + 'fs.appendFileSync(' + + JSON.stringify(logFile) + + String.raw`, "TOOL: python3\nARGS: " + args.map((a) => (a.includes("/") ? "