Repository navigation
refactor(linux): move Linux desktop automation into the managed platform plugin #4872
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
thymikee
merged 12 commits into
refactor/0.22-harmonyos-platform-plugin
from
refactor/0.22-linux-platform-plugin
Nov 21, 2026
Merged
Changes from all commits
Commits
Show all changes
12 commits
Select commit
Hold shift + click to select a range
efdf003
refactor(linux): move Linux desktop automation into the managed platf…
thymikee f595d36
refactor(linux): keep the plugin's internals inside the package
thymikee b2f6c05
ci(linux): serve both Linux lanes from the installed platform plugin
thymikee 81f924c
chore(gates): scan the AT-SPI helper where the plugin now keeps it
thymikee 16e2c15
fix(linux): answer the hosted lanes the plugin actually gives them
thymikee 0b2527d
test(linux): name the routes the Ubuntu package lane shows
thymikee b0dae68
fix(linux): look up only bare command names in the host PATH
thymikee 613b503
fix(linux): accept the provider's fallback tools in the doctor toolch…
thymikee d8921e2
fix(plugins): restore the launchDetached doc comment after the rebase
thymikee ced6020
chore(package): drop a Linux marker the plugin never emits
thymikee 20877d4
docs(linux): scope the unscoped doctor note to a call with no session
thymikee ffb147d
docs(linux): scope the plugin-not-installed error to commands that fa…
thymikee File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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<LinuxCommandResult>; | ||
| whichCommand(cmd: string): Promise<boolean>; | ||
| /** | ||
| * 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<LinuxDetachedExit> }>; | ||
| /** Waits for interaction pacing between synthesized input steps. */ | ||
| sleep(milliseconds: number): Promise<void>; | ||
| desktop: LinuxDesktopProvider; | ||
| clipboard?: LinuxClipboardProvider; | ||
| screenshot?: LinuxScreenshotProvider; | ||
| accessibility?: LinuxAccessibilityProvider; | ||
| input?: LinuxInputProvider; | ||
| }>; | ||
|
|
||
| export type LinuxDesktopProvider = Readonly<{ | ||
| openTarget(target: string): Promise<void>; | ||
| closeApp(app: string): Promise<void>; | ||
| }>; | ||
|
|
||
| export type LinuxClipboardProvider = Readonly<{ | ||
| readText(): Promise<string>; | ||
| writeText(text: string): Promise<void>; | ||
| }>; | ||
|
|
||
| export type LinuxScreenshotProvider = Readonly<{ | ||
| capture( | ||
| outPath: string, | ||
| options?: Readonly<{ fullscreen?: boolean; stabilize?: boolean; surface?: SessionSurface }>, | ||
| ): Promise<void>; | ||
| }>; | ||
|
|
||
| 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<void>; | ||
| doubleClick(x: number, y: number): Promise<void>; | ||
| longPress(x: number, y: number, durationMs: number): Promise<void>; | ||
| drag(x1: number, y1: number, x2: number, y2: number, durationMs: number): Promise<void>; | ||
| scroll( | ||
| direction: ScrollDirection, | ||
| options?: Readonly<{ amount?: number; pixels?: number; durationMs?: number }>, | ||
| ): Promise<void>; | ||
| typeText(text: string, options?: Readonly<{ delayMs?: number }>): Promise<void>; | ||
| /** Sends one combination: `combo` is xdotool keysym notation, `scancodes` ydotool pairs. */ | ||
| key(combo: string, scancodes: readonly string[]): Promise<void>; | ||
| }>; | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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); |
File renamed without changes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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" | ||
| } |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.