@zenalexa/unicli 0.216.3 → 0.217.3

package/AGENTS.md

@@ -6,11 +6,12 @@
      Agent routing: unicli agents matrix && unicli agents recommend <agent>
      Run: unicli <site> <command> [args]
      Output is structured Markdown by default (non-TTY + agent UA auto-detected). Use -f json for JSON. Errors are structured envelopes to stderr.
+     Style: load skills/talk-normal/SKILL.md before writing docs or user-facing text; keep prose direct and avoid filler.
      You can fix broken adapters yourself — read the Self-Repair section. -->
 
 <!-- BEGIN COUNTS -->
 
-> <!-- STATS:site_count -->235<!-- /STATS --> sites, <!-- STATS:command_count -->1448<!-- /STATS --> commands, <!-- STATS:pipeline_step_count -->59<!-- /STATS --> pipeline steps, BM25 bilingual search. `npm install -g @zenalexa/unicli`
+> <!-- STATS:site_count -->237<!-- /STATS --> sites, <!-- STATS:command_count -->1453<!-- /STATS --> commands, <!-- STATS:pipeline_step_count -->101<!-- /STATS --> pipeline steps, BM25 bilingual search. `npm install -g @zenalexa/unicli`
 
 <!-- END COUNTS -->
 
@@ -39,7 +40,7 @@ npm install -g @zenalexa/unicli
 
 **Chinese**: zhihu (24), xiaohongshu (22), bilibili (20), douyin (13), douban (12), v2ex (12), linux-do (11), jike (10), +31 more (`unicli list`)
 
-**International**: twitter (38), instagram (26), reddit (20), tiktok (16), youtube (16), nowcoder (16), discord-app (15), lesswrong (15), +48 more (`unicli list`)
+**International**: twitter (38), instagram (26), reddit (20), tiktok (16), youtube (16), nowcoder (16), discord-app (15), lesswrong (15), +50 more (`unicli list`)
 
 **AI / ML**: antigravity (16), chatwise (16), chatgpt (15), notebooklm (15), doubao-app (13), doubao (9), doubao-web (9), perplexity (8), +13 more (`unicli list`)
 
@@ -51,9 +52,9 @@ npm install -g @zenalexa/unicli
 
 **Reference**: spotify (23), netease-music (17), linear (10), imdb (7), bitwarden (7), todoist (7), wikipedia (5), xiaoyuzhou (5), +11 more (`unicli list`)
 
-### macOS (58 cmds)
+### macOS (60 cmds)
 
-active-app, apps, apps-list, battery, bluetooth, brightness, caffeinate, calendar-create, calendar-list, calendar-today, clipboard, contacts-search, … (`unicli list --site macos`)
+active-app, app-actions, apps, apps-list, automation-smoke, battery, bluetooth, brightness, caffeinate, calendar-create, calendar-list, calendar-today, … (`unicli list --site macos`)
 
 ### Desktop (28 apps)
 
@@ -185,7 +186,7 @@ Full reference: [`docs/ADAPTER-FORMAT.md`](docs/ADAPTER-FORMAT.md).
 ```bash
 npx @zenalexa/unicli mcp serve                                # stdio (4 meta-tools)
 npx @zenalexa/unicli mcp serve --transport streamable --port 19826
-npx @zenalexa/unicli mcp serve --transport sse --port 19826   # SSE for remote
+npx @zenalexa/unicli mcp serve --transport sse --port 19826   # legacy alias for streamable
 npx @zenalexa/unicli mcp serve --auth                         # OAuth 2.1 PKCE
 ```
 
@@ -212,4 +213,4 @@ unicli lark-cli calendar +agenda   # Direct passthrough
 
 ## Version
 
-0.216.3 — Apollo · Collins
+0.217.3 — Apollo · Shepard

package/README.md

@@ -5,7 +5,7 @@
 <h1 align="center">Uni-CLI</h1>
 
 <p align="center">
-  <strong>One CLI surface for agents to operate websites, desktop apps, local tools, and other CLIs.</strong>
+  <strong>The agent execution substrate for the world's software.</strong>
 </p>
 
 <p align="center">
@@ -17,7 +17,7 @@
 </p>
 
 <p align="center">
-  Search by intent, run a real command, get a structured envelope back. If a site changes, the error points to the adapter file and step to repair.
+  Search by intent, execute governed commands across web, apps, local tools, and system capabilities, then return evidence-rich AgentEnvelopes that agents can inspect and repair.
 </p>
 
 <p align="center">
@@ -28,7 +28,7 @@
 </p>
 
 <p align="center">
-  <sub><!-- STATS:site_count -->235<!-- /STATS --> sites · <!-- STATS:command_count -->1448<!-- /STATS --> commands · <!-- STATS:pipeline_step_count -->59<!-- /STATS --> pipeline steps · <!-- STATS:test_count -->7393<!-- /STATS --> tests</sub>
+  <sub><!-- STATS:site_count -->237<!-- /STATS --> sites · <!-- STATS:command_count -->1453<!-- /STATS --> commands · <!-- STATS:pipeline_step_count -->101<!-- /STATS --> pipeline steps · <!-- STATS:test_count -->7747<!-- /STATS --> tests</sub>
 </p>
 
 <p align="center">
@@ -129,26 +129,30 @@ Prefer native CLI / JSON stream / MCP for agent runtimes. Use ACP as an editor c
 
 ## What It Does
 
-Uni-CLI turns software surfaces into commands that agents can discover, run, and fix.
+Uni-CLI sits under agent applications and turns software surfaces into commands that agents can discover, execute, record, and repair.
 
-| Surface            | What you get                                                                                       |
-| ------------------ | -------------------------------------------------------------------------------------------------- |
-| Websites and APIs  | Declarative adapters for public, cookie, header, and browser-intercept workflows                   |
-| Browser automation | CDP steps for navigate, click, type, intercept, snapshot, extract, wait, and related browser work  |
-| Desktop and macOS  | System commands, app adapters, screenshots, clipboard, calendar, brightness, and local tools       |
-| External CLIs      | 58 registered pass-through bridges with install/status discovery                                   |
-| Agent backends     | Route matrix for native CLI, JSON stream, MCP, ACP, HTTP API, OpenAI-compatible, and bridge routes |
-| Output             | v2 `AgentEnvelope` in Markdown, JSON, YAML, CSV, or compact format                                 |
-| Repair             | Structured errors with `adapter_path`, failing `step`, retryability, suggestions, and alternatives |
+| Surface            | What you get                                                                                                                                                                                             |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Websites and APIs  | Declarative adapters for public, cookie, header, and browser-intercept workflows                                                                                                                         |
+| Browser automation | CDP steps for navigate, click, type, intercept, snapshot, extract, wait, and related browser work                                                                                                        |
+| Desktop and macOS  | System commands, app adapters, real-time Shortcuts/App Intent discovery, screenshots, clipboard, calendar, brightness, and local tools                                                                   |
+| External CLIs      | 58 registered pass-through bridges with install/status discovery                                                                                                                                         |
+| Agent backends     | Route matrix for native CLI, JSON stream, MCP, ACP, HTTP API, OpenAI-compatible, and bridge routes                                                                                                       |
+| Operation policy   | `open`, `confirm`, and `locked` profiles with effect/risk scopes, local deny rules, `--yes`, and persisted approval memory                                                                               |
+| Evidence           | Run traces with environment snapshots, probe/replay/compare scores, structured gate results, browser session leases with tab/auth posture, render-aware evidence, movement checks, and stale-ref details |
+| Output             | v2 `AgentEnvelope` in Markdown, JSON, YAML, CSV, or compact format                                                                                                                                       |
+| Repair             | Structured errors with `adapter_path`, failing `step`, retryability, suggestions, and alternatives                                                                                                       |
 
 ## For Agents
 
 Use search first, then run the smallest matching command.
 
 ```bash
-unicli search "twitter trending" --limit 5
-unicli twitter search "coding agents" -f json
-unicli repair twitter search
+unicli search "connect slack messages" --limit 5
+unicli slack search "deploy incident" -f json
+unicli macos app-actions --app WhatsApp -f json
+unicli macos automation-smoke -f json
+unicli repair slack search
 ```
 
 Output defaults to structured Markdown for non-TTY and agent-user-agent runs. Force a machine format when you need one:
@@ -156,6 +160,17 @@ Output defaults to structured Markdown for non-TTY and agent-user-agent runs. Fo
 ```bash
 UNICLI_OUTPUT=json unicli reddit hot --limit 10
 unicli hackernews top --limit 5 -f yaml
+unicli --record --permission-profile confirm twitter search "coding agents" -f json
+unicli runs list -f json
+unicli runs show <run_id> -f json
+unicli runs probe <run_id> -f json
+unicli runs replay <run_id> --permission-profile confirm --yes --min-score 1 --min-context-score 1 --min-overall-score 1 -f json
+unicli runs compare <run_id> <replay_run_id> -f json
+unicli runs compare <run_id> <replay_run_id> --min-score 1 --min-context-score 1 --min-overall-score 1 -f json
+unicli --permission-profile locked --yes --remember-approval word set-font "Inter"
+unicli approvals list -f json
+unicli approvals revoke <approval_key> -f json
+unicli browser evidence --render-aware --expect-domain example.com -f json
 ```
 
 Protocol entry points:
@@ -170,9 +185,25 @@ unicli agents matrix
 
 ACP is supported for editors and bridge tooling. The primary runtime path stays native CLI, JSON stream, or MCP when those routes are available.
 
+## Local Computer Control
+
+`unicli compute` controls installed apps through native accessibility, Electron CDP, and visual fallback transports.
+
+```bash
+unicli compute apps
+unicli compute snapshot --app Calculator --format compact
+unicli compute find --role button --name 5 --first
+unicli compute find --role input --text 8 --first
+unicli compute click @e7
+unicli doctor compute --json
+npx @zenalexa/unicli mcp serve --profile computer-use
+```
+
+Start with [Compute](docs/operate/compute.md), [Electron App Control](docs/operate/electron.md), and [Compute Troubleshooting](docs/operate/troubleshooting.md).
+
 ## Coverage
 
-The catalog is intentionally broad, but the important point is not the count. The important point is that every command is discoverable, typed, and repairable.
+The catalog is intentionally broad. Every command is discoverable, typed, and repairable.
 
 | Area                    | Examples                                                                                                    |
 | ----------------------- | ----------------------------------------------------------------------------------------------------------- |
@@ -288,9 +319,26 @@ Docs:
 
 - Auth-required sites use local cookie files under `~/.unicli/cookies/<site>.json`.
 - Browser adapters require a reachable Chrome/CDP session.
+- Permission profiles are user-selected runtime policy. The default is `open`;
+  stricter `confirm` and `locked` profiles require `--yes` or `UNICLI_APPROVE=1`
+  for blocked operations. Add `--remember-approval` with `--yes` to store the
+  same command capability and resource scope under `~/.unicli/approvals.jsonl`.
+  Resource scope covers stable metadata such as domain, account surface, app,
+  process family, and path argument slots. Use
+  `unicli approvals list`, `revoke`, and `clear` to inspect or remove remembered
+  scopes. The file stores scope metadata; runtime args stay out of approval
+  memory.
+- Local deny rules live at `~/.unicli/permission-rules.json`, or at
+  `UNICLI_PERMISSION_RULES_PATH`. They match site, command, effect, capability
+  dimensions, and resource metadata, then block before `--yes` and remembered
+  approvals. Runtime guards also check fetched domains, browser navigation
+  targets, download and output paths, and subprocess executables before the
+  request, write, or process spawn happens.
+- Run recording is opt-in. Use `--record` or `UNICLI_RECORD_RUN=1` when you need
+  append-only evidence under `~/.unicli/runs`.
 - CUA routes require a configured real backend. Declared-but-unavailable providers fail closed with structured errors.
 - User adapters and repairs live in `~/.unicli/adapters/`; committed adapters remain the package baseline.
-- If a site blocks automation or changes a private API, the correct behavior is a clear failure envelope, not a fabricated success.
+- If a site blocks automation or changes a private API, Uni-CLI returns a clear failure envelope.
 
 ## Development
 
@@ -306,5 +354,5 @@ npm run verify
 [Apache-2.0](./LICENSE)
 
 <p align="center">
-  <sub>v0.216.3 — Apollo · Collins</sub>
+  <sub>v0.217.3 — Apollo · Shepard</sub>
 </p>

package/README.zh-CN.md

@@ -5,7 +5,7 @@
 <h1 align="center">Uni-CLI</h1>
 
 <p align="center">
-  <strong>给 Agent 用的一层统一 CLI：网站、桌面 App、本地工具、外部 CLI，都变成可搜索、可执行、可修复的命令。</strong>
+  <strong>面向真实软件的 Agent 执行底座。</strong>
 </p>
 
 <p align="center">
@@ -17,7 +17,7 @@
 </p>
 
 <p align="center">
-  先按意图搜索，再执行真实命令，最后拿结构化结果。网站变了也不会假装成功，错误会告诉你哪个 adapter、哪一步、怎么修。
+  按意图发现命令，跨 Web、应用、本地工具和系统能力执行可治理操作，再返回带证据的 AgentEnvelope，方便智能体检查和修复。
 </p>
 
 <p align="center">
@@ -28,7 +28,7 @@
 </p>
 
 <p align="center">
-  <sub><!-- STATS:site_count -->235<!-- /STATS --> 个站点 · <!-- STATS:command_count -->1448<!-- /STATS --> 条命令 · <!-- STATS:pipeline_step_count -->59<!-- /STATS --> 个 pipeline step · <!-- STATS:test_count -->7393<!-- /STATS --> 个测试</sub>
+  <sub><!-- STATS:site_count -->237<!-- /STATS --> 个站点 · <!-- STATS:command_count -->1453<!-- /STATS --> 条命令 · <!-- STATS:pipeline_step_count -->101<!-- /STATS --> 个 pipeline step · <!-- STATS:test_count -->7747<!-- /STATS --> 个测试</sub>
 </p>
 
 <p align="center">
@@ -129,17 +129,19 @@ Prefer native CLI / JSON stream / MCP for agent runtimes. Use ACP as an editor c
 
 ## 它解决什么
 
-Uni-CLI 把软件表面封装成 Agent 能发现、能执行、能修的命令。
+Uni-CLI 位于 Agent 应用之下，把软件表面收敛成 Agent 能发现、能执行、能记录、能修的命令。
 
-| 表面         | 能力                                                                            |
-| ------------ | ------------------------------------------------------------------------------- |
-| 网站和 API   | public、cookie、header、browser-intercept 等 adapter                            |
-| 浏览器自动化 | CDP 的 navigate、click、type、intercept、snapshot、extract、wait 等步骤         |
-| 桌面和 macOS | 系统命令、App adapter、截图、剪贴板、日历、亮度、本地工具                       |
-| 外部 CLI     | 58 个已登记的 passthrough bridge，支持安装和状态发现                            |
-| Agent 后端   | native CLI、JSON stream、MCP、ACP、HTTP API、OpenAI-compatible、bridge 路由矩阵 |
-| 输出         | v2 `AgentEnvelope`，支持 Markdown、JSON、YAML、CSV、compact                     |
-| 修复         | 错误里带 `adapter_path`、失败 `step`、是否可重试、修复建议和替代命令            |
+| 表面         | 能力                                                                                                                                                                       |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 网站和 API   | public、cookie、header、browser-intercept 等 adapter                                                                                                                       |
+| 浏览器自动化 | CDP 的 navigate、click、type、intercept、snapshot、extract、wait 等步骤                                                                                                    |
+| 桌面和 macOS | 系统命令、App adapter、实时 Shortcuts/App Intent 发现、截图、剪贴板、日历、亮度、本地工具                                                                                  |
+| 外部 CLI     | 58 个已登记的 passthrough bridge，支持安装和状态发现                                                                                                                       |
+| Agent 后端   | native CLI、JSON stream、MCP、ACP、HTTP API、OpenAI-compatible、bridge 路由矩阵                                                                                            |
+| 操作策略     | `open`、`confirm`、`locked` profile，暴露 effect/risk scope、本地 deny 规则、`--yes` 和持久审批记忆                                                                        |
+| 执行证据     | run trace 会记录环境快照，也能 probe/replay/compare 打分并输出结构化 gate 结果；浏览器 session lease 带 tab/auth 姿态，还支持 render-aware 证据、移动检测和 stale-ref 细节 |
+| 输出         | v2 `AgentEnvelope`，支持 Markdown、JSON、YAML、CSV、compact                                                                                                                |
+| 修复         | 错误里带 `adapter_path`、失败 `step`、是否可重试、修复建议和替代命令                                                                                                       |
 
 ## 给 Agent 的入口
 
@@ -148,6 +150,8 @@ Uni-CLI 把软件表面封装成 Agent 能发现、能执行、能修的命令
 ```bash
 unicli search "推特热门" --limit 5
 unicli twitter search "coding agents" -f json
+unicli macos app-actions --app WhatsApp -f json
+unicli macos automation-smoke -f json
 unicli repair twitter search
 ```
 
@@ -156,6 +160,17 @@ unicli repair twitter search
 ```bash
 UNICLI_OUTPUT=json unicli reddit hot --limit 10
 unicli hackernews top --limit 5 -f yaml
+unicli --record --permission-profile confirm twitter search "coding agents" -f json
+unicli runs list -f json
+unicli runs show <run_id> -f json
+unicli runs probe <run_id> -f json
+unicli runs replay <run_id> --permission-profile confirm --yes --min-score 1 --min-context-score 1 --min-overall-score 1 -f json
+unicli runs compare <run_id> <replay_run_id> -f json
+unicli runs compare <run_id> <replay_run_id> --min-score 1 --min-context-score 1 --min-overall-score 1 -f json
+unicli --permission-profile locked --yes --remember-approval word set-font "Inter"
+unicli approvals list -f json
+unicli approvals revoke <approval_key> -f json
+unicli browser evidence --render-aware --expect-domain example.com -f json
 ```
 
 协议入口：
@@ -172,7 +187,7 @@ ACP 作为编辑器和桥接兼容层保留。真正跑任务时，优先 native
 
 ## 覆盖范围
 
-数量不是重点，重点是每条命令都能搜索、可声明、可验证、可修。
+每条命令都能搜索、可声明、可验证、可修。
 
 | 领域          | 例子                                                                                                        |
 | ------------- | ----------------------------------------------------------------------------------------------------------- |
@@ -288,9 +303,22 @@ columns: [title, url]
 
 - 需要登录的网站使用本地 cookie 文件：`~/.unicli/cookies/<site>.json`。
 - Browser adapter 需要可连接的 Chrome/CDP。
+- Permission profile 是用户选择的运行时策略。默认是 `open`；更严格的
+  `confirm` 和 `locked` profile 会要求 `--yes` 或 `UNICLI_APPROVE=1`。
+  `--yes` 加 `--remember-approval` 会把同一条命令的 capability 和资源 scope
+  记到 `~/.unicli/approvals.jsonl`。资源 scope 来自稳定 metadata，比如域名、
+  账号面、应用、进程族和路径参数槽。用 `unicli approvals list`、`revoke`、
+  `clear` 查看或移除已记住的 scope。文件只存 scope metadata，原始运行参数留在审批记忆之外。
+- 本地 deny 规则放在 `~/.unicli/permission-rules.json`，也可以用
+  `UNICLI_PERMISSION_RULES_PATH` 指定。规则按站点、命令、effect、capability
+  维度和资源 metadata 匹配，优先级高于 `--yes` 和已记住的审批。运行时还会检查
+  fetch 域名、浏览器跳转目标、下载和输出路径、子进程可执行文件，命中后在请求、写入或
+  启动进程之前停下。
+- Run recording 是显式启用能力。需要可审查证据时使用 `--record` 或
+  `UNICLI_RECORD_RUN=1`，追加写入 `~/.unicli/runs`。
 - CUA 路由必须配置真实 backend。声明了但不可用的 provider 会失败关闭，并返回结构化错误。
 - 用户 adapter 和修复放在 `~/.unicli/adapters/`；包内 adapter 是基线。
-- 如果网站阻止自动化或私有 API 变了，正确行为是清楚失败，不是伪装成功。
+- 如果网站阻止自动化或私有 API 变了，Uni-CLI 会返回清楚的失败 envelope。
 
 ## 开发
 
@@ -306,5 +334,5 @@ npm run verify
 [Apache-2.0](./LICENSE)
 
 <p align="center">
-  <sub>v0.216.3 — Apollo · Collins</sub>
+  <sub>v0.217.3 — Apollo · Shepard</sub>
 </p>

package/crates/unicli-atspi/Cargo.toml

@@ -0,0 +1,47 @@
+[package]
+name = "unicli-atspi"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+homepage.workspace = true
+repository.workspace = true
+
+[[bin]]
+name = "unicli-atspi"
+path = "src/main.rs"
+
+[dependencies]
+anyhow.workspace = true
+clap.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+tokio.workspace = true
+tracing.workspace = true
+tracing-subscriber.workspace = true
+unicli-shared.workspace = true
+
+[target.'cfg(target_os = "linux")'.dependencies]
+atspi = { version = "0.29.0", default-features = false, features = [
+  "connection",
+  "proxies",
+  "wrappers",
+] }
+async-lock = "=3.4.1"
+async-signal = "=0.2.13"
+futures-lite = "=2.6.1"
+indexmap = "=2.11.3"
+proc-macro-crate = "=3.4.0"
+tempfile = "=3.22.0"
+toml_datetime = "=0.7.1"
+toml_edit = "=0.23.5"
+toml_parser = "=1.0.2"
+toml_writer = "=1.0.2"
+wasip2 = "=1.0.1"
+winnow = "=0.7.13"
+wit-bindgen = "=0.46.0"
+zbus = { version = "=5.11.0", features = ["async-io"], default-features = false }
+zbus_macros = "=5.11.0"
+zvariant = "=5.7.0"
+zvariant_derive = "=5.7.0"
+zvariant_utils = "=3.2.1"

package/crates/unicli-atspi/README.md

@@ -0,0 +1,6 @@
+# unicli-atspi
+
+Linux AT-SPI sidecar for Uni-CLI compute.
+
+P0 only establishes the buildable crate. The JSON-Lines stdio protocol and
+AT-SPI actions land in P4.

package/crates/unicli-atspi/src/errors.rs

@@ -0,0 +1,213 @@
+use serde_json::Value;
+use unicli_shared::{SidecarError, SidecarResponse};
+
+pub type HandlerResult = Result<Value, AtspiError>;
+
+#[derive(Debug, Clone)]
+pub struct AtspiError {
+    reason: String,
+    suggestion: String,
+    minimum_capability: Option<String>,
+    r#ref: Option<String>,
+    exit_code: u8,
+}
+
+impl AtspiError {
+    pub fn unavailable(reason: impl Into<String>) -> Self {
+        Self {
+            reason: reason.into(),
+            suggestion:
+                "run on Linux with the native AT-SPI backend available, or fall back to CUA".into(),
+            minimum_capability: None,
+            r#ref: None,
+            exit_code: 69,
+        }
+    }
+
+    pub fn invalid_input(reason: impl Into<String>) -> Self {
+        Self {
+            reason: reason.into(),
+            suggestion:
+                "pass a desktop-atspi stable top-level window ref from atspi_snapshot or atspi_find"
+                    .into(),
+            minimum_capability: Some("desktop-atspi.invalid_input".into()),
+            r#ref: None,
+            exit_code: 78,
+        }
+    }
+
+    #[allow(dead_code)] // Used by native Linux AT-SPI handlers.
+    pub fn no_element(r#ref: impl Into<String>) -> Self {
+        let r#ref = r#ref.into();
+        Self {
+            reason: format!("no AT-SPI element matched {ref}"),
+            suggestion: "re-snapshot; the ref may be stale".into(),
+            minimum_capability: Some("desktop-atspi.no_element".into()),
+            r#ref: Some(r#ref),
+            exit_code: 66,
+        }
+    }
+
+    pub fn not_invokable(r#ref: impl Into<String>) -> Self {
+        let r#ref = r#ref.into();
+        Self {
+            reason: format!("AT-SPI element {ref} does not expose a native action"),
+            suggestion: "try CUA fallback, set-value, press, or focus before retrying".into(),
+            minimum_capability: Some("desktop-atspi.not_invokable".into()),
+            r#ref: Some(r#ref),
+            exit_code: 69,
+        }
+    }
+
+    #[allow(dead_code)] // Used by the native Linux AT-SPI connection path.
+    pub fn dbus_blocked(reason: impl Into<String>) -> Self {
+        Self {
+            reason: reason.into(),
+            suggestion: "start the user AT-SPI D-Bus daemon".into(),
+            minimum_capability: Some("desktop-atspi.dbus_blocked".into()),
+            r#ref: None,
+            exit_code: 69,
+        }
+    }
+
+    #[allow(dead_code)] // Used when a target app exposes no useful AT-SPI tree.
+    pub fn no_a11y_attr(reason: impl Into<String>) -> Self {
+        Self {
+            reason: reason.into(),
+            suggestion: "enable accessibility support for the target app".into(),
+            minimum_capability: Some("desktop-atspi.no_a11y_attr".into()),
+            r#ref: None,
+            exit_code: 69,
+        }
+    }
+
+    #[allow(dead_code)] // Used by Wayland fallback input dispatch.
+    pub fn wayland_input_missing(reason: impl Into<String>) -> Self {
+        Self {
+            reason: reason.into(),
+            suggestion: "install ydotool or another supported Wayland input helper".into(),
+            minimum_capability: Some("desktop-atspi.wayland-input".into()),
+            r#ref: None,
+            exit_code: 69,
+        }
+    }
+
+    #[allow(dead_code)] // Used by X11 fallback input dispatch.
+    pub fn x11_input_missing(reason: impl Into<String>) -> Self {
+        Self {
+            reason: reason.into(),
+            suggestion: "install xdotool for X11 fallback input".into(),
+            minimum_capability: Some("desktop-atspi.x11-input".into()),
+            r#ref: None,
+            exit_code: 69,
+        }
+    }
+}
+
+pub trait IntoSidecarResponse {
+    fn into_response(self, id: u64, kind: String) -> SidecarResponse;
+}
+
+impl IntoSidecarResponse for HandlerResult {
+    fn into_response(self, id: u64, kind: String) -> SidecarResponse {
+        match self {
+            Ok(data) => SidecarResponse::ok(id, kind, data),
+            Err(err) => {
+                let minimum_capability = err
+                    .minimum_capability
+                    .unwrap_or_else(|| format!("desktop-atspi.{kind}"));
+                SidecarResponse {
+                    id,
+                    kind: kind.clone(),
+                    ok: false,
+                    data: None,
+                    error: Some(SidecarError {
+                        transport: "desktop-atspi".into(),
+                        action: kind,
+                        reason: err.reason,
+                        suggestion: err.suggestion,
+                        minimum_capability,
+                        exit_code: err.exit_code,
+                        stable_token: None,
+                        r#ref: err.r#ref,
+                    }),
+                }
+            }
+        }
+    }
+}
+
+pub fn backend_unavailable() -> AtspiError {
+    if cfg!(target_os = "linux") {
+        AtspiError::unavailable(backend_unavailable_reason("linux"))
+    } else {
+        AtspiError::unavailable(backend_unavailable_reason(std::env::consts::OS))
+    }
+}
+
+fn backend_unavailable_reason(target_os: &str) -> String {
+    if target_os == "linux" {
+        "Linux AT-SPI backend is unavailable for this request".into()
+    } else {
+        format!("desktop-atspi is only available on Linux; current target is {target_os}")
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn error_for(err: AtspiError) -> unicli_shared::SidecarError {
+        let response = Err::<Value, _>(err).into_response(9, "atspi_invoke".into());
+        response.error.expect("error response")
+    }
+
+    #[test]
+    fn no_element_uses_semantic_minimum_capability() {
+        let error = error_for(AtspiError::no_element("@e42"));
+        assert_eq!(error.minimum_capability, "desktop-atspi.no_element");
+        assert_eq!(error.r#ref.as_deref(), Some("@e42"));
+        assert_eq!(error.exit_code, 66);
+    }
+
+    #[test]
+    fn not_invokable_uses_semantic_minimum_capability() {
+        let error = error_for(AtspiError::not_invokable("@e42"));
+        assert_eq!(error.minimum_capability, "desktop-atspi.not_invokable");
+        assert_eq!(error.r#ref.as_deref(), Some("@e42"));
+        assert_eq!(error.exit_code, 69);
+    }
+
+    #[test]
+    fn dbus_blocked_uses_semantic_minimum_capability() {
+        let error = error_for(AtspiError::dbus_blocked("AT-SPI D-Bus is unavailable"));
+        assert_eq!(error.minimum_capability, "desktop-atspi.dbus_blocked");
+        assert_eq!(error.exit_code, 69);
+    }
+
+    #[test]
+    fn wayland_input_uses_semantic_minimum_capability() {
+        let error = error_for(AtspiError::wayland_input_missing("ydotool is missing"));
+        assert_eq!(error.minimum_capability, "desktop-atspi.wayland-input");
+    }
+
+    #[test]
+    fn no_a11y_attr_uses_semantic_minimum_capability() {
+        let error = error_for(AtspiError::no_a11y_attr("no accessibility attributes"));
+        assert_eq!(error.minimum_capability, "desktop-atspi.no_a11y_attr");
+    }
+
+    #[test]
+    fn x11_input_uses_semantic_minimum_capability() {
+        let error = error_for(AtspiError::x11_input_missing("xdotool is missing"));
+        assert_eq!(error.minimum_capability, "desktop-atspi.x11-input");
+    }
+
+    #[test]
+    fn backend_unavailable_reason_does_not_claim_native_traversal_pending() {
+        let reason = backend_unavailable_reason("linux");
+
+        assert!(!reason.contains("pending"));
+        assert!(reason.contains("unavailable"));
+    }
+}