agent-desktop-linux

agent-desktop-linux

観察と操作のループ、参照、JSON エンベロープ、セッション、トレースは、どのプラットフォームでも同じです。このファイルでは、Linux 固有の差分のみを説明します。

Ubuntu 24.04 以降（x86_64 または aarch64）、サインイン中のユーザーのグラフィカルセッション、実行中の AT-SPI バスが必要です。その他のディストリビューションでは、at-spi2-core ブリッジの修正 dc0dc33 が必要です。Ubuntu 22.04 のブリッジは Action.GetActions で異常終了します。アーカイブローダーの最低要件は glibc 2.35 です。CLI は対象アプリのデスクトップセッション内で実行してください。セッションバス、ディスプレイ、ランタイムディレクトリは、その環境から取得されます。TTY でのログイン、セッション変数のない SSH シェル、バスのないコンテナ、または別ユーザーのセッションでは、アプリは検出されません。動作確認済みのデスクトップ環境は GNOME です。X11 セッションと Wayland セッションの両方が動作しますが、入力、キャプチャ、ウィンドウ制御の動作は異なります。観察とセマンティックアクションにはヘルパーツールは不要です。

機能一覧

グループ	コマンド	Linux でのステータス
観察	snapshot, find, get, is	AT-SPI を通じて X11 と Wayland で動作します。window、sheet、alert、menu に対応し、GNOME ではシェルのサーフェスも追加されます。仮想トレイの getter には制限があります。シェルのリファレンスを参照し、status を確認してください
サーフェス	list-surfaces	アプリのウィンドウ、シート、開いているメニューを一覧表示します。シェルの読み取りには snapshot --surface を使用します
ref 操作	click, right-click, type, set-value, clear, select, toggle, check, uncheck, expand, collapse, scroll-to	読み取り可能なライブ ID と、必要な AT-SPI 機能が必要です。メニューの ref 解決に関する制限はシェルのリファレンスを参照してください。X11 の headed フォールバックには使用可能なジオメトリも必要で、ID チェックを回避することはできません
ホイールスクロール	scroll, mouse-wheel	物理ホイール入力です。X11 と --headed のみ
ポインタージェスチャー	double-click, triple-click, hover, drag	--headed、X11 のみです。Wayland ではポインターの位置を指定できないため、ACTION_NOT_SUPPORTED で拒否されます
フォーカス	focus	フォーカス権限には --headed が必要です。まだ focused ではないフォーカス可能なノードに対して AT-SPI の Component.GrabFocus を呼び出します。ポインターは使用せず、状態を検証します。GTK4 アプリではこの呼び出しが拒否されるため、そこで focus は ACTION_FAILED grab_focus_rejected で終了します。そのウィンドウにフォーカスするには focus-window を使用します
キーボードとマウス	press, mouse-click, mouse-move, mouse-wheel	press とテキストキーは X11 および機能検出された Mutter Wayland セッションで動作します。ポインターコマンドは X11 と --headed のみです。references/display-servers-and-input.md を参照してください
入力の長押し	key-down, key-up, mouse-down, mouse-up	すべてのプラットフォームでフェイルクローズします。Linux では、key-down と key-up は ACTION_NOT_SUPPORTED、mouse-down と mouse-up はヘッドレス時に POLICY_DENIED、--headed 使用時に ACTION_NOT_SUPPORTED となります
アプリとウィンドウ	launch, close-app, list-windows, list-apps, focus-window, move-window, resize-window, minimize, maximize, restore	起動と一覧表示は X11 と Wayland で動作します。focus-window には X11 が必要です。その他のウィンドウ制御と正常終了には X11 クライアントが必要です。references/windows-and-lifecycle.md を参照してください
ディスプレイ	list-displays	動作します
キャプチャ	screenshot	X11：ウィンドウは権限なしでキャプチャできます。ディスプレイは非コンポジティングマネージャーの場合にのみキャプチャできます。Wayland：ポータルの同意が必要で、ディスプレイの切り抜きが適用されます。セレクターを指定しない場合はプライマリディスプレイが選択されます。references/capture-and-clipboard.md を参照してください
クリップボード	clipboard-get, clipboard-set, clipboard-clear	動作します。テキスト、画像、ファイルリストに対応します。Wayland では wl-clipboard が必要です
待機	wait	ms、--element、--window、--text、--menu、--menu-closed、--event に対応します。メニューの待機にはメニューサーフェス検出機能が使用されます。--notification は GNOME で新しい通知を待ちます
通知	list-notifications, dismiss-notification, dismiss-all-notifications, notification-action	GNOME Shell のみです。一覧表示はヘッドレスで可能です。変更操作には X11 で --headed が必要です。また、dismiss-notification と notification-action には --expected-app または --expected-title も必要です。フィールドはシェルのウィジェットレイアウトから読み取られ、GNOME Shell 46.0 でのみ検証されています。各変更操作は、その効果によって実証されます。Wayland では入力前にシェルポインターが拒否されます。通知の所有者がシェルまたはシェル自身のヘルパーでない場合は、PLATFORM_NOT_SUPPORTED が返されます。シェルのリファレンスを参照してください
シェルサーフェス	open-system-surface	system-tray と action-center のみ動作する可能性があります。system-tray には StatusNotifierWatcher が必要です（存在しない場合は watcher: absent で拒否されます）。action-center には実証済みのロールの祖先関係が必要です。quick-settings は shell_container_unproven で拒否され、taskbar は常に拒否されます。start-menu と system-tray-overflow はサポートされていませんが、--help には表示されます。シェルのリファレンスを参照してください
カーソルオーバーレイ	cursor-overlay	アクティブなセッションが必要です。下記の「カーソルオーバーレイ」を参照してください。X11 では有効化時に data.rendered: true が返されます。Wayland では設定が保存され、data.rendered: false が返されます
システム	status, permissions, version, batch, skills, session, trace	動作します

First Contact

• 最初に agent-desktop status を実行してください。 supported_surfaces が空の場合、アクセシビリティバスから応答がなかったのであり、デスクトップが空という意味ではありません。 references/bus-and-permissions.md を読み、自分で起動していないバスを再起動しないでください。
• --app には、list-apps が出力する名前（gnome-calculator、 nautilus）、または実行ファイルと引数の識別情報が検証済みのデスクトップエントリー名か ID を指定します。ウィンドウタイトルや任意のレジストリラベルは指定できません。 Files などのデスクトップエントリー名は、そのエントリーが存在すれば使用できます。 list-windows --app は完全一致で検索します（エイリアスを含む）。list-apps --app は、大文字と小文字を区別せず、一覧に表示された名前の部分一致とアダプターのエイリアスの完全一致を組み合わせて検索します。
• ウィンドウ ID は不透明なアドレスで、34～70 文字です。ウィンドウのプロセスが存続している間だけ有効です。再起動後は list-windows を再実行してください。 list-apps の各行には、bundle_id（判明している場合はデスクトップ ID）と process_instance が含まれます。
• GTK4 アプリは深くネストします。 --max-depth と --skeleton はセマンティックな階層を数えるため、空のレイアウト用ラッパーも出力上の階層に加わります。-i --compact を指定しても、名前のないネストされた group ノードは表示されます。読み飛ばさないでください。
• ファイルビューが空でも、フォルダーが空とは限りません。 アイコンビューにファイル項目が表示されない場合は、利用可能なリストビューまたは詳細ビューを試し、新しいスナップショットを取得して、アプリケーションがどの項目を表示するか確認してください。
• ウィンドウが表示されても、コンテンツはまだ表示されていないことがあります。 まず wait --window "Text Editor" --app gnome-text-editor を実行し、続いてノード自身の名前、値、または説明に一致する wait --text を実行してください。ウェブエンジンを使用するアプリ（AT-SPI ツールキットメタデータから判定されます）では、ウィンドウの観察は、完全な読み取り結果が 3 回連続で一致し、ウェブドキュメントのロールまたは要求された深度制限が確認されるまで待機します。まだドキュメントがないシェルは、予算の上限に達しても未完了のままです。最初の読み取りより短い --timeout を指定すると、部分的なツリーではなく TIMEOUT が返されます。
• ジオメトリのみを使う参照には、ジオメトリが変わっていないことが必要です。 参照に記録された座標系で、位置とサイズの両方が一致している必要があります。1 ピクセルでも変化すると識別できなくなります。レイアウトの変更後やウィンドウの移動後は、古い参照を再試行せず、新しいスナップショットを取得してください。区別できない兄弟ノードは AMBIGUOUS_TARGET のままです。たとえば、3 つのタブがある Text Editor ウィンドウでは、テキストビューの矩形と状態が同じため、どのビューへの参照も、余分なタブを閉じるまでは candidate_count が 3 の AMBIGUOUS_TARGET を返します。参照は取得元のウィンドウに属するため、同じタイトルのウィンドウが 2 つあっても、それぞれの参照は対応するウィンドウで解決されます。
• Chromium アプリと Qt アプリがバスに表示されるには、起動フラグまたは変数が必要です。 Electron アプリでは不要ですが、chrome-sandbox に setuid が設定されていない場合は --no-sandbox が必要です。 references/troubleshooting.md を参照してください。
• ヘッド付きの参照操作には、フォーカスを受け取れるウィンドウが必要です。 ウィンドウマネージャーが一度もアクティブ化していないウィンドウは activation_not_granted になります。 references/windows-and-lifecycle.md を参照してください。
• GTK4 のシークレットフィールドにはテキストが表示されることがあります。 非表示になるのはパスワードロールだけです。文字が隠されている GTK4 の入力欄も、すべての観察コマンドで読み取り可能なものとして扱ってください。
• ブロックされたキーの組み合わせは、--force がないと拒否されます。 references/display-servers-and-input.md を参照してください。
• メニューロールのポップアップを開いた後は、data.surfaces を確認してください。 menu エントリーがあれば、snapshot --surface menu --app <name> -i で開けます。エントリーがない場合は、開く操作が失敗したと判断する前に wait --menu と list-surfaces を使用してください。リストベースのドロップダウンはウィンドウの一部であり、メニューサーフェスではありません。シェルのリファレンスを参照してください。
• シェルへのポインター入力には、受信先の証明が必要です。 X11 では、ヘッド付きシェルのクリックはシェル自身のツリーで証明されます。受信先が対象と一致し、位置が変わらない場合に限り、ポインターイベントが発生する前にクリックが拒否されることはありません。Wayland ではシェルのクリックは拒否されます。通知には GNOME 通知サービスが必要です。トレイのスナップショットには StatusNotifierWatcher も必要です。
• 状態ルートはプライベートでなければなりません。 グループ書き込み可能または全ユーザーがアクセス可能な AGENT_DESKTOP_HOME または ~/.agent-desktop があると、snapshot は INTERNAL で失敗します。対象に chmod 700 を実行するか、ツールに作成させてください。

ウィンドウを待つ

アプリのウィンドウが表示されるまで待機します（--window にはタイトルまたはタイトルの一部が必要です）：

agent-desktop wait --window "Text Editor" --app gnome-text-editor --timeout 10000

自分でウィンドウを閉じるのを待つには、閉じる前にベースラインが取得されるよう、バッチ処理してください（Calculator には未保存のドキュメントを保存するか確認するダイアログがないため、処理が中断されません）：

agent-desktop batch '[{"command":"close-app","args":{"app":"gnome-calculator"}},{"command":"wait","args":{"event":"window-closed","app":"gnome-calculator","timeout":10000}}]' --stop-on-error

誰かがウィンドウを閉じるのを監視するには、相手がウィンドウを閉じる前に agent-desktop wait --event window-closed --app gnome-text-editor --timeout 10000 を実行します。--window-closed フラグはありません。

カーソルオーバーレイ

セッションを開始し、返された ID をすべてのオーバーレイコマンドに渡します：

session_id=$(agent-desktop session start --name docs-example | jq -r '.data.session_id')
agent-desktop cursor-overlay enable --session "$session_id"
agent-desktop cursor-overlay disable --session "$session_id"
agent-desktop session end "$session_id"

セッションがない場合、cursor-overlay enable と disable は INVALID_ARGS を返します。 X11 では enable が data.rendered: true を返します。Wayland では設定を保存し、オーバーレイを描画せずに data.rendered: false を返します。

session start --cursor --multi-agent は data.rendered: false を返します。これは、エージェントが動作するまで何も描画されないためです。X11 では各エージェント ID にそれぞれ独自のカーソルが割り当てられますが、Wayland では何も描画されません。

Linux で異なる点

• Firefox/Gecko の select は、change または input イベントを発生させずに選択値を変更することがあるため、依存するページハンドラーが実行されません。値の読み戻しが一致していても、結果は delivered_unverified のままです。続行する前に、依存するアプリケーションの動作を確認してください。値の読み戻しだけでは、確定の証明になりません。
• 同じ GTK4 ボタンに対する 2 回の click 呼び出しが約 250 ms 未満の間隔で行われると、1 回しか動作しません。どちらも delivered_unverified を伴う ok: true を返します。1 つのボタンを複数回クリックするには、クリックの間に効果が現れるのを待ってください。結果を表示する要素に対して wait --element <ref> --predicate value --value <expected> を使うか、wait 300 を使います。
• Ref アクションは、ポインターを動かしたりアクティブなウィンドウを変更したりしない、セマンティックな AT-SPI 呼び出しです。--headed の場合、ref の click、right-click、type はまず物理入力を試し、not_delivered の拒否があった場合にのみセマンティックアクションにフォールバックします（Windows では逆です）。Wayland では、headed のポインターコマンドと headed の select は、wayland_session が原因の ACTION_NOT_SUPPORTED ですぐに拒否されます。headed の type には Mutter RemoteDesktop の機能が必要です。すべてのルールについては references/display-servers-and-input.md を参照してください。
• select はまずセマンティックな方法を試し、次にポインターを使う方法を試します。ポインターを使う方法には、X11 で明示的な --headed リクエストが必要です。Qt コンボボックスのセマンティックな選択ではポップアップの行がハイライトされるだけなので、ヘッドレスでの選択は、そのハイライトを変更する前に POLICY_DENIED、種別 pointer_required で拒否されます。headed の場合、ツールキットのインデックスを行に対応付けられないリスト（GTK4 リスト）では、行をクリックして selected 状態を確認します。セマンティックなオープナーがないコンボボックス（libadwaita のコンボ行）では、コンボボックスをクリックして開き、ポップアップ自身のリストから選択肢を選び、コンボボックスに表示される値を確認します。ヘッドレスの場合、リストは selection_index_unproven で拒否され、セマンティックなオープナーがないコンボボックスは、すでに選択肢が表示されている場合を除き、POLICY_DENIED、種別 pointer_required で拒否されます。独自のトグルで開く GTK4 ドロップダウンでは、--headed を指定せずに select を実行でき、表示される値が確認されます。
• Ref には、安全なセマンティック変更方法がない場合があります。その場合、ヘッドレスのリクエストは hidden や disabled の状態を推測したり、物理入力に切り替えたりせず、未サポートアクションのエラーを返します。GTK4 のエントリーとパスワードの Activate アクションはその一例です。フィールドを編集するには type を使うか、ポインターでクリックする意図がある場合は明示的に --headed をリクエストしてください。
• ネイティブ Wayland の Qt コンボボックスを開くと、そのアクションを呼び出す前に ACTION_NOT_SUPPORTED、種別 native_popup_requires_input が返されます。Qt でこのポップアップを表示するには、ユーザー入力シリアルが必要です。すでに開いているコンボボックスは閉じることができます。Xwayland を使用していることが確認された Qt ウィンドウでは、セマンティックなオープナーが引き続き利用できます。
• ヘッドレスの type は EditableText を介して書き込みます。ターミナルのテキストノードは Terminal という名前の textfield で、唯一のアクションは RightClick です。これに対するヘッドレスの type は、チェック supported_action とともに POLICY_DENIED となり、値は null です。キー入力を受け付けるのは --headed の場合のみです。
• キーコンボでは、cmd と meta は Super キーを表します。キー名は、macOS と Windows のキー名に X keysym 名を加えたものです。press で指定できるのはマッピング済みのキーのみです。レイアウトで入力できない文字は type で扱います。
• ウィンドウ操作は X11 クライアントに対して動作します。focus-window と headed のスコープ付き press には X11 セッションが必要です。ヘッドレスのスコープ付き press には、どちらのディスプレイサーバーでも対象が実際にフォーカスされている必要があります。別のワークスペースにあるウィンドウにフォーカスすると、ユーザーの現在のデスクトップが切り替わることがあります。
• Linux の境界情報または境界ハッシュを持つ正確な FFI ref には、ref が名前または識別子も持っている場合でも、ウィンドウ相対のジオメトリーが必要です。ジオメトリーを含まない ID ref はサポートされています。

参考資料

• references/bus-and-permissions.md：バスのブートストラップ、バスの3つの状態、status と permissions の出力、状態ルートのルール。
• references/display-servers-and-input.md：X11 と Wayland の比較表、press、type、ポインター、ホイール、ドラッグ、ブロックされるキーの組み合わせ、キー名。
• references/windows-and-lifecycle.md：launch、close-app、ウィンドウ操作、フォーカス、ワークスペース、停止中のアプリ、バックグラウンドでの press。
• references/capture-and-clipboard.md：X11 と Wayland での screenshot、Wayland の同意ダイアログ、クリップボードの所有者とヘルパー。
• references/shell-tray-and-notifications.md：メニューと GTK4 のポップオーバー、GNOME の概要／トップバー、シェルの読み取りと入力、通知の識別情報ガード、SNI と AppIndicator の要件と拒否事項、サンドボックスのガイダンス。
• references/troubleshooting.md：症状と原因の対応表、Chromium、Electron、Qt のフラグ、ツールキットの制限、platform_detail を含むエラーコード。

バイナリから任意のファイルを読み取れます： agent-desktop skills get agent-desktop-linux references/troubleshooting.md