Skip to content

👾 Open Computer Use – Open-Source Alternative to Codex Computer Use

fix(computer-use-cli): prefer legacy bundled plugin

Leo281e909eb96b
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 824363c..d58ea1f 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -92,7 +92,7 @@
## 关键边界
- 开源版当前不复刻官方闭源实现里的 caller signing、私有 IPC、完整 overlay choreography 和 plugin 自安装逻辑。
-- 因为官方 `SkyComputerUseClient` 带有宿主侧 launch constraints,普通 stdio MCP client 在本机上可能被系统直接杀掉;如果要探测官方 bundled `computer-use`,默认应通过 `scripts/computer-use-cli` 的 app-server 模式走已签名的 Codex 宿主。
+- 因为官方 `SkyComputerUseClient` 带有宿主侧 launch constraints,普通 stdio MCP client 在本机上可能被系统直接杀掉;如果要探测官方 bundled `computer-use`,`scripts/computer-use-cli` 的 app-server 模式现在只适合做工具清单和协议面观察。官方 `1.0.755` 的真实 tool call 还会经过 service-side sender authorization / active IPC client 追踪,外部 raw helper 即使走已签名 Codex binary,也可能返回 `Sender process is not authenticated`;需要真实使用官方工具时应走正常 Codex agent/tool 调用链,开源版则继续提供可直连的 `open-computer-use` MCP server。
- 当前权限引导已经具备可运行 app、深链、拖拽辅助,以及一版更接近官方的 accessory panel 入场动画和返回 affordance;点击链路也已经补上独立 visual cursor、官方 asset fallback 和相对目标 window 的排序逻辑,但整体还没有完全复刻官方那套嵌入式 choreography / host 集成 / session approval 体验。
- screenshot 当前使用系统窗口截图 API,但默认直接以 MCP `image` content block 的 base64 PNG 返回,不再把普通 app 截图落盘到仓库或临时目录。
- 会话状态现在是进程内内存态,保存每个 app 最近一次 snapshot 和 element index 映射。
diff --git a/docs/exec-plans/active/20260417-official-tool-alignment.md b/docs/exec-plans/active/20260417-official-tool-alignment.md
index 983835e..28a3fa5 100644
--- a/docs/exec-plans/active/20260417-official-tool-alignment.md
+++ b/docs/exec-plans/active/20260417-official-tool-alignment.md
@@ -55,10 +55,10 @@
- `swift test`
- `go run . list-tools --transport app-server`
- `go run . list-tools --transport direct --server-bin ../../.build/debug/OpenComputerUse`
- - `go run . call list_apps --transport app-server`
- `go run . call list_apps --transport direct --server-bin ../../.build/debug/OpenComputerUse`
- 手工检查:
- 官方与开源 `tools/list` 的 9 个 tool surface 能一眼对齐。
+ - 官方 bundled `computer-use` 的 raw app-server helper 当前只用于 `tools/list` 探测;真实 tool call 走正常 Codex agent/tool 调用链或本仓库 direct server。
- `get_app_state` 文本不再暴露 `_NS:` 内部 identifier、frame 噪音和过量 cell 递归。
- `appNotFound`、安全拒绝等错误形态与官方一致地回到 `content` + `isError: true`。
- 观测检查:
diff --git a/docs/histories/2026-04/20260421-1624-document-official-computer-use-sender-auth.md b/docs/histories/2026-04/20260421-1624-document-official-computer-use-sender-auth.md
new file mode 100644
index 0000000..bffe913
--- /dev/null
+++ b/docs/histories/2026-04/20260421-1624-document-official-computer-use-sender-auth.md
@@ -0,0 +1,33 @@
+## [2026-04-21 16:24] | Task: 记录官方 computer-use sender auth 变化
+
+### 🤖 Execution Context
+* **Agent ID**: `Codex`
+* **Base Model**: `GPT-5`
+* **Runtime**: `Codex CLI`
+
+### 📥 User Query
+> 调查 `computer-use-cli` 通过 `app-server` 调用官方 bundled `computer-use` 返回 `Sender process is not authenticated` 的原因,并判断是否仍能直接调用。
+
+### 🛠 Changes Overview
+**Scope:** `docs/`, `scripts/computer-use-cli/`
+
+**Key Actions:**
+- **[Runtime Finding]**: 记录官方 `computer-use` `1.0.755` 中 raw app-server helper 只能稳定列 tools,实际 tool call 会被 service-side sender authorization 拒绝。
+- **[Docs Sync]**: 更新 `computer-use-cli` README、参考文档和架构边界,避免后续继续把 raw `mcpServer/tool/call` 当作官方 Computer Use 的通用直连入口。
+- **[CLI Test Target]**: 将 `computer-use-cli` 的 bundled plugin 自动发现调整为本地兼容性测试优先解析 `1.0.750`,并新增 `COMPUTER_USE_PLUGIN_VERSION` / `--plugin-version` 用于显式切换测试版本;app-server 模式会把解析出的测试版本作为临时 `mcp_servers."computer-use"` 覆盖传给 Codex host,`--plugin-version host` 可回到 host 自身配置。
+- **[Verification]**: `resolve-server` 默认解析到非 translocated 的 `~/.codex/plugins/computer-use` 旧安装根;`list-tools --transport app-server` 可列出 9 个工具且呈现旧版 schema;`call list_apps --transport app-server` 在当前工作区可返回应用列表。cache 里的 `1.0.750` 带 `com.apple.quarantine` 时会被 LaunchServices AppTranslocation,并返回 `Apple event error -1708: Unknown error`。
+- **[Bug Fix]**: 修正 app-server 临时 MCP 覆盖的 `-c` key 写法。Codex CLI override 不解析 quoted dotted key,`mcp_servers."computer-use".command` 会落到错误 key;改为 `mcp_servers.computer-use.command` 后覆盖才真正生效。
+- **[Bug Fix]**: 默认旧版测试目标优先选 `~/.codex/plugins/computer-use`,并用 manifest version 校验它确实是 `1.0.750`,避免 cache 目录 quarantine 导致 AppTranslocation。
+
+### 🧠 Design Intent (Why)
+官方 `SkyComputerUseClient` 的 parent launch constraint 只解释了“谁能启动 client”,不能解释已经通过 Apple Events/TCC 后仍被拒绝的工具调用。文档需要把 parent constraint、Apple Events/TCC、service-side sender authorization / active IPC client 追踪分开写,后续对比官方和开源实现时才不会混淆根因。
+
+### 📁 Files Modified
+- `docs/ARCHITECTURE.md`
+- `docs/exec-plans/active/20260417-official-tool-alignment.md`
+- `docs/references/codex-computer-use-cli.md`
+- `docs/references/codex-computer-use-reverse-engineering/runtime-and-host-dependencies.md`
+- `scripts/computer-use-cli/README.md`
+- `scripts/computer-use-cli/app_server.go`
+- `scripts/computer-use-cli/main.go`
+- `scripts/computer-use-cli/main_test.go`
diff --git a/docs/references/codex-computer-use-cli.md b/docs/references/codex-computer-use-cli.md
index ec964bb..4bffdd1 100644
--- a/docs/references/codex-computer-use-cli.md
+++ b/docs/references/codex-computer-use-cli.md
@@ -17,7 +17,7 @@
- 官方 Go MCP SDK 自带示例也会失败
- crash report 指向 `Launch Constraint Violation` / `CODESIGNING`
-结论是:这不是单纯的 MCP 协议兼容问题,而是宿主签名/父进程约束。要探测官方 bundled `computer-use`,应优先借助已签名的 Codex 宿主,通过 `codex app-server` 走 `mcpServer/tool/call`。
+结论是:这不是单纯的 MCP 协议兼容问题,而是宿主签名/父进程约束,以及官方 service 自己的 sender authorization。要探测官方 bundled `computer-use` 的工具清单,可以借助已签名的 Codex 宿主,通过 `codex app-server` 走 `mcpServerStatus/list`;真实 tool call 不应再依赖这个 raw helper。
## 目录位置
@@ -29,20 +29,36 @@ scripts/computer-use-cli/
## AI 默认用法
-如果任务目标是“验证官方 Codex 自带的 `computer-use` 能不能列工具、能不能调某个 tool”,优先这样跑:
+如果任务目标是“验证官方 Codex 自带的 `computer-use` 能不能列工具”,优先这样跑:
```bash
cd scripts/computer-use-cli
-go run . list-tools
-go run . call list_apps
-go run . call get_app_state --args '{"app":"Feishu"}'
+go run . list-tools --transport app-server
```
+如果任务目标是验证可脚本化 tool call,优先指向本仓库的 `open-computer-use` direct server。
+
默认 `auto` 模式会自动选择:
-- 官方 bundled `computer-use` -> `app-server`
+- 官方 bundled `computer-use` -> `app-server`,当前只适合作为工具清单探测路径
- 显式传入的非 Sky server binary -> `direct`
+本地兼容性测试默认优先解析 `~/.codex/plugins/computer-use` 里的非 translocated
+`1.0.750` 旧安装根,并检查它的 plugin manifest version。没有这份旧根时再回退到
+`~/.codex/plugins/cache/.../1.0.750`,最后回退到最新安装版本。需要对比其他版本时显式传:
+
+```bash
+COMPUTER_USE_PLUGIN_VERSION=1.0.755 go run . resolve-server
+go run . resolve-server --plugin-version latest
+go run . list-tools --transport app-server --plugin-version host
+```
+
+`--plugin-root` / `--server-bin` 的优先级高于版本选择。版本选择只影响
+`resolve-server`、direct launch 的目标路径,以及传给 `codex app-server` 的临时
+`mcp_servers."computer-use"` 覆盖。需要完全使用 Codex host 自己的 MCP 配置时,
+传 `--plugin-version host`。Codex CLI 的 `-c` override 只按 `.` 拆 key,不解析 quoted
+dotted key,所以实现里实际使用的是 `mcp_servers.computer-use.*`。
+
## 两种 transport
### 1. `app-server`
@@ -52,7 +68,6 @@ go run . call get_app_state --args '{"app":"Feishu"}'
```bash
cd scripts/computer-use-cli
go run . list-tools --transport app-server
-go run . call list_apps --transport app-server
```
这个模式会:
@@ -61,11 +76,24 @@ go run . call list_apps --transport app-server
2. 建一个 ephemeral thread
3. 通过 `mcpServer/tool/call` 调目标 server
+截至官方 bundled `computer-use` `1.0.755`,这条 raw helper 路径只能继续稳定用于工具清单探测;实际 `mcpServer/tool/call` 可能返回:
+
+```text
+Apple event error -10000: Sender process is not authenticated
+```
+
+复查日志显示 Apple Events/TCC 已经接受请求,随后 `SkyComputerUseService` 在自己的 sender authorization / active IPC client 追踪层拒绝了调用。因此它不是一个可依赖的“外部直接调用官方 computer-use”的通用入口。需要真实调用官方工具时,优先使用正常 Codex agent/tool 调用链;需要可脚本化直连时,使用本仓库的 `open-computer-use` direct 模式。
+
+本地兼容性测试会默认把 app-server 的 `computer-use` MCP 配置临时覆盖到 `1.0.750`。
+在当前工作区,cache 里的 `1.0.750` 带 `com.apple.quarantine`,LaunchServices 会把
+service AppTranslocation,`call list_apps` 会返回 `Apple event error -1708: Unknown error`;
+非 translocated 的 `~/.codex/plugins/computer-use` 旧安装根可以正常调用 `list_apps`。
+
如果本机 Codex 可执行不在默认位置,可以显式指定:
```bash
CODEX_APP_SERVER_BIN=/Applications/Codex.app/Contents/Resources/codex \
-go run . call list_apps --transport app-server
+go run . list-tools --transport app-server
```
### 2. `direct`
@@ -102,5 +130,5 @@ go test ./...
```bash
cd scripts/computer-use-cli
go run . list-tools
-go run . call list_apps
+go run . call list_apps --transport direct --server-bin /path/to/open-computer-use
```
diff --git a/docs/references/codex-computer-use-reverse-engineering/runtime-and-host-dependencies.md b/docs/references/codex-computer-use-reverse-engineering/runtime-and-host-dependencies.md
index 868f8eb..ff49324 100644
--- a/docs/references/codex-computer-use-reverse-engineering/runtime-and-host-dependencies.md
+++ b/docs/references/codex-computer-use-reverse-engineering/runtime-and-host-dependencies.md
@@ -280,6 +280,36 @@ status=137
- 私有 XPC / app group / bundle 发现机制
- 或其他不直接暴露给任意外部进程的宿主内通信
+### 17. `1.0.755` 对 raw app-server helper 增加了 service-side sender authorization
+
+2026-04-21 复查官方 bundled `computer-use` `1.0.755` 时,同一台机器上出现了新的分叉行为:
+
+- `scripts/computer-use-cli` 的 `app-server` 模式仍然可以通过 `mcpServerStatus/list` 看到官方 `computer-use` 的 9 个 tools。
+- 但从外部 shell 启动一个临时 `codex app-server`,再调用 `mcpServer/tool/call list_apps`,返回:
+
+```text
+Apple event error -10000: Sender process is not authenticated
+```
+
+系统日志把这次失败分成了两段:
+
+- `SkyComputerUseClient` 通过 Apple Events 向 `SkyComputerUseService` 发送 `SkCu/SndR` 请求。
+- TCC 对这次 Apple Events 请求返回 `ACCESS GRANTED`。
+- 随后 service 侧出现多次签名 / trust 校验 activity,并输出 `Computer Use` 分类下的错误日志。
+- 失败路径没有出现 `Tracking Computer Use IPC client process ...`。
+
+对照同一轮里正常 Codex agent/tool 调用官方 `computer-use`:
+
+- `list_apps` 可以成功返回。
+- service 会先启动 `Codex AppServer Thread Events` observer,并连接到 `codex-ipc` socket。
+- service 随后记录 `Tracking Computer Use IPC client process ...`。
+
+所以当前更准确的判断是:
+
+- `codex app-server` 这个二进制由 OpenAI 签名,只能满足 `SkyComputerUseClient` 的 parent launch constraint。
+- 满足 parent launch constraint 并不等于 tool call 已经通过官方 Computer Use 的 sender authorization。
+- 官方 service 还要求请求来自它能认证并追踪的 Codex/ComputerUse IPC client;外部 helper 临时创建的 raw app-server thread 现在不再能稳定复用这条私有链路。
+
## 当前推断
### 1. client 很可能不是独立产品边界,而是宿主绑定的桥接层
@@ -297,6 +327,9 @@ status=137
- macOS launch constraint 直接拦截外部自动化拉起
- 证据:`CODESIGNING / Launch Constraint Violation`
- 证据:`Has Parent Launch Constraints`
+- service-side sender authorization 拒绝 raw helper 发起的工具调用
+ - 证据:Apple Events/TCC 已 `ACCESS GRANTED` 后仍返回 `Sender process is not authenticated`
+ - 证据:成功路径会记录 active Computer Use IPC client,失败路径不会
- 宿主集成层内部还依赖 Codex appserver / auth / plugin lifecycle
- 证据:`CodexAppServerJSONRPCConnection`
- 证据:`CodexAppServerAuthProvider`
@@ -323,7 +356,7 @@ status=137
- `SkyComputerUseClient_Parent.coderequirement` 里的 parent launch constraint 除 team identifier 外还有没有更细的约束来源?
- `turn-ended` 子命令除了会话清理,还会不会参与审批状态同步、idle timeout 刷新或后台 app 回收?
- `approvedBundleIdentifiers` 的持久化位置在哪里,是否只保存在进程内?
-- 有没有办法通过受约束的父进程链、合法宿主 wrapper 或系统认可的启动方式绕过当前的 parent launch constraint?
+- 官方是否有计划暴露受支持的本地调试入口,让外部工具在不复用私有 sender authorization 的情况下探测 bundled `computer-use`?
- `codex-ipc/ipc-501.sock` 上跑的具体 JSON-RPC 方法和认证过程是什么?
## 下一批分析建议
diff --git a/scripts/computer-use-cli/README.md b/scripts/computer-use-cli/README.md
index a93586d..0b62046 100644
--- a/scripts/computer-use-cli/README.md
+++ b/scripts/computer-use-cli/README.md
@@ -6,9 +6,9 @@ This directory is intended to be run from `scripts/computer-use-cli/` inside the
```bash
cd scripts/computer-use-cli
-go run . list-tools
-go run . call list_apps
-go run . call-seq --calls-file /tmp/calls.json
+go run . list-tools --transport app-server
+go run . call list_apps --transport direct --server-bin /path/to/open-computer-use
+go run . call-seq --transport direct --server-bin /path/to/open-computer-use --calls-file /tmp/calls.json
```
It supports two transports:
@@ -18,26 +18,26 @@ It supports two transports:
`auto` is the default:
-- for the official bundled proprietary `computer-use`, it uses `app-server`
+- for the official bundled proprietary `computer-use`, it uses `app-server`; this is currently reliable for inventory probes, not raw tool calls
- for explicitly provided non-Sky binaries such as `open-computer-use`, it uses `direct`
## Commands
```bash
go run . resolve-server
-go run . list-tools
-go run . call list_apps
-go run . call get_app_state --args '{"app":"Feishu"}'
-go run . call-seq --calls-file /tmp/calls.json
+go run . list-tools --transport app-server
+go run . call list_apps --transport direct --server-bin /path/to/open-computer-use
+go run . call get_app_state --transport direct --server-bin /path/to/open-computer-use --args '{"app":"Feishu"}'
+go run . call-seq --transport direct --server-bin /path/to/open-computer-use --calls-file /tmp/calls.json
```
Explicit transport examples:
```bash
go run . list-tools --transport app-server
-go run . call list_apps --transport app-server
+go run . list-tools --transport direct --server-bin /path/to/open-computer-use
go run . call list_apps --transport direct --server-bin /path/to/open-computer-use
-go run . call-seq --transport app-server --calls-file /tmp/calls.json
+go run . call-seq --transport direct --server-bin /path/to/open-computer-use --calls-file /tmp/calls.json
```
Flags can appear either before or after the tool name for `call`:
@@ -82,10 +82,24 @@ By default, the CLI auto-discovers the official bundled `computer-use` plugin un
~/.codex/plugins/cache/openai-bundled/computer-use/<version>
```
+For local compatibility testing, auto-discovery currently prefers a non-translocated
+`1.0.750` root at `~/.codex/plugins/computer-use` when that root is present and
+its plugin manifest reports `1.0.750`. If that root is not available, the CLI
+falls back to the installed cache version under `~/.codex/plugins/cache/...`,
+then to the newest installed version. Use an explicit version selector when you
+need a different target:
+
+```bash
+COMPUTER_USE_PLUGIN_VERSION=1.0.755 go run . resolve-server
+go run . resolve-server --plugin-version latest
+go run . list-tools --transport app-server --plugin-version host
+```
+
You can override that with:
```bash
COMPUTER_USE_PLUGIN_ROOT=/path/to/plugin-root
+COMPUTER_USE_PLUGIN_VERSION=1.0.755
COMPUTER_USE_SERVER_BIN=/path/to/server-binary
```
@@ -93,14 +107,22 @@ or the equivalent flags:
```bash
--plugin-root /path/to/plugin-root
+--plugin-version 1.0.755
--server-bin /path/to/server-binary
```
+`--plugin-root` and `--server-bin` take precedence over `--plugin-version`.
+The version selector affects CLI target resolution, direct launches, and the
+temporary `mcp_servers."computer-use"` override passed to `codex app-server`.
+Use `--plugin-version host` when you want app-server mode to leave the Codex
+host config untouched. Codex CLI config overrides do not parse quoted dotted
+keys, so the app-server override intentionally uses `mcp_servers.computer-use.*`.
+
For app-server mode, you can also override the Codex host binary:
```bash
CODEX_APP_SERVER_BIN=/Applications/Codex.app/Contents/Resources/codex
-go run . call list_apps --transport app-server
+go run . list-tools --transport app-server
```
## Verified behavior in this workspace
@@ -108,7 +130,9 @@ go run . call list_apps --transport app-server
- Direct mode successfully connects to the local `open-computer-use` stdio server and can both `list-tools` and `call list_apps`.
- Direct mode against the official bundled proprietary `computer-use` exits during initialization when launched outside Codex.
- That same failure reproduces with the official Go SDK example client `examples/client/listfeatures`, so the issue is not specific to this CLI.
-- App-server mode successfully calls the official bundled `computer-use` tools through the signed Codex host. `list_apps` works in this workspace.
+- App-server mode can still list the official bundled `computer-use` tools through a signed Codex binary.
+- As of official bundled `computer-use` `1.0.755`, raw `mcpServer/tool/call` from this external helper can return `Sender process is not authenticated` even though Apple Events/TCC accepts the request. The supported path for official tool calls is a normal Codex agent/tool invocation; this helper should not be treated as a general bypass for the proprietary service-side sender authorization.
+- For local compatibility tests, this CLI now prefers bundled `computer-use` `1.0.750` from the non-quarantined `~/.codex/plugins/computer-use` root and passes the resolved target to `codex app-server` as a temporary MCP override. In this workspace, cache copies with `com.apple.quarantine` can be AppTranslocated and return `Apple event error -1708`; the non-translocated root can call `list_apps`.
Example working invocation against `open-computer-use`:
@@ -130,9 +154,8 @@ go run . call-seq \
--calls-file examples/textedit-set-value-click-raise-seq.json
```
-Example working invocation against the official bundled `computer-use`:
+Example inventory probe against the official bundled `computer-use`:
```bash
-go run . call list_apps --transport app-server
-go run . call-seq --transport app-server --calls-file /tmp/calls.json
+go run . list-tools --transport app-server
```
diff --git a/scripts/computer-use-cli/app_server.go b/scripts/computer-use-cli/app_server.go
index b677cd7..2a9e52d 100644
--- a/scripts/computer-use-cli/app_server.go
+++ b/scripts/computer-use-cli/app_server.go
@@ -128,13 +128,17 @@ func connectAppServer(ctx context.Context, flags commonFlags) (*appServerSession
if err != nil {
return nil, err
}
+ appServerArgs, err := resolveAppServerArgs(flags)
+ if err != nil {
+ return nil, err
+ }
threadCwd, err := resolveThreadCwd(flags)
if err != nil {
return nil, err
}
- cmd := exec.Command(appServerBin, "app-server")
+ cmd := exec.Command(appServerBin, appServerArgs...)
cmd.Dir = threadCwd
cmd.Stderr = os.Stderr
@@ -167,6 +171,31 @@ func connectAppServer(ctx context.Context, flags commonFlags) (*appServerSession
return session, nil
}
+func resolveAppServerArgs(flags commonFlags) ([]string, error) {
+ args := []string{"app-server"}
+ if useHostAppServerConfig(flags) {
+ return args, nil
+ }
+
+ target, err := resolveTarget(flags)
+ if err != nil {
+ return nil, err
+ }
+
+ serverName := firstNonEmpty(flags.serverName, defaultAppServerServerName)
+ configPrefix := "mcp_servers." + serverName
+ return append(args,
+ "-c", configPrefix+".command="+strconv.Quote(target.ServerBin),
+ "-c", configPrefix+".args=[\"mcp\"]",
+ "-c", configPrefix+".cwd="+strconv.Quote(target.PluginRoot),
+ ), nil
+}
+
+func useHostAppServerConfig(flags commonFlags) bool {
+ selector := firstNonEmpty(flags.pluginVersion, os.Getenv(pluginVersionEnvVar))
+ return strings.EqualFold(strings.TrimSpace(selector), "host")
+}
+
func (s *appServerSession) Close() error {
if s.stdin != nil {
_ = s.stdin.Close()
diff --git a/scripts/computer-use-cli/main.go b/scripts/computer-use-cli/main.go
index 4ac743e..f746d94 100644
--- a/scripts/computer-use-cli/main.go
+++ b/scripts/computer-use-cli/main.go
@@ -24,14 +24,19 @@ const (
cliVersion = "0.1.22"
defaultTimeout = 60 * time.Second
pluginRootEnvVar = "COMPUTER_USE_PLUGIN_ROOT"
+ pluginVersionEnvVar = "COMPUTER_USE_PLUGIN_VERSION"
serverBinEnvVar = "COMPUTER_USE_SERVER_BIN"
+ defaultLegacyPluginRoot = ".codex/plugins/computer-use"
defaultPluginVersionsDir = ".codex/plugins/cache/openai-bundled/computer-use"
+ defaultPluginManifest = ".codex-plugin/plugin.json"
defaultServerRelativeBin = "Codex Computer Use.app/Contents/SharedSupport/SkyComputerUseClient.app/Contents/MacOS/SkyComputerUseClient"
+ defaultTestPluginVersion = "1.0.750"
)
type commonFlags struct {
transport string
pluginRoot string
+ pluginVersion string
serverBin string
appServerBin string
serverName string
@@ -57,6 +62,10 @@ type toolCallOutput struct {
Result *mcp.CallToolResult `json:"result"`
}
+type pluginManifest struct {
+ Version string `json:"version"`
+}
+
type rpcSession struct {
conn mcp.Connection
nextID int64
@@ -322,6 +331,7 @@ func runCallSeq(ctx context.Context, args []string, stdout io.Writer, stderr io.
func addCommonFlags(fs *flag.FlagSet, flags *commonFlags) {
fs.StringVar(&flags.transport, "transport", transportAuto, "Connection mode: auto, direct, or app-server")
fs.StringVar(&flags.pluginRoot, "plugin-root", "", "Path to the installed computer-use plugin root")
+ fs.StringVar(&flags.pluginVersion, "plugin-version", "", "Installed bundled computer-use version to select when auto-discovering; use latest for newest installed or host to leave app-server config untouched")
fs.StringVar(&flags.serverBin, "server-bin", "", "Path to the SkyComputerUseClient executable")
fs.StringVar(&flags.appServerBin, "app-server-bin", "", "Path to the Codex binary used for app-server proxy mode")
fs.StringVar(&flags.serverName, "server-name", defaultAppServerServerName, "Server name to target in app-server mode")
@@ -554,8 +564,12 @@ func resolveTarget(flags commonFlags) (resolvedTarget, error) {
}
if pluginRoot == "" {
- var err error
- pluginRoot, err = discoverPluginRoot()
+ pluginVersion, requirePluginVersion, err := resolvePluginVersionSelector(flags.pluginVersion)
+ if err != nil {
+ return resolvedTarget{}, err
+ }
+
+ pluginRoot, err = discoverPluginRoot(pluginVersion, requirePluginVersion)
if err != nil {
return resolvedTarget{}, err
}
@@ -619,13 +633,53 @@ func validateTarget(target resolvedTarget) (resolvedTarget, error) {
return target, nil
}
-func discoverPluginRoot() (string, error) {
+func resolvePluginVersionSelector(flagValue string) (string, bool, error) {
+ explicit := firstNonEmpty(flagValue, os.Getenv(pluginVersionEnvVar))
+ if explicit == "" {
+ return defaultTestPluginVersion, false, nil
+ }
+
+ switch strings.ToLower(strings.TrimSpace(explicit)) {
+ case "latest", "newest", "auto", "host":
+ return "", false, nil
+ }
+
+ cleanVersion := filepath.Clean(explicit)
+ if strings.Contains(cleanVersion, string(filepath.Separator)) || cleanVersion == "." || cleanVersion == ".." {
+ return "", false, fmt.Errorf("invalid plugin version %q: pass a version directory name, not a path", explicit)
+ }
+
+ return cleanVersion, true, nil
+}
+
+func discoverPluginRoot(preferredVersion string, requirePreferred bool) (string, error) {
homeDir, err := os.UserHomeDir()
if err != nil {
return "", fmt.Errorf("resolve home directory: %w", err)
}
parent := filepath.Join(homeDir, defaultPluginVersionsDir)
+ if preferredVersion != "" {
+ legacyPath, ok, err := discoverLegacyPluginRoot(homeDir, preferredVersion)
+ if err != nil {
+ return "", err
+ }
+ if ok {
+ return legacyPath, nil
+ }
+
+ preferredPath := filepath.Join(parent, preferredVersion)
+ if _, err := os.Stat(filepath.Join(preferredPath, defaultServerRelativeBin)); err == nil {
+ return preferredPath, nil
+ } else if requirePreferred {
+ return "", fmt.Errorf(
+ "requested computer-use plugin version %q was not found under %q; pass --plugin-version latest to use newest installed",
+ preferredVersion,
+ parent,
+ )
+ }
+ }
+
entries, err := os.ReadDir(parent)
if err != nil {
return "", fmt.Errorf("read %q: %w", parent, err)
@@ -679,6 +733,47 @@ func discoverPluginRoot() (string, error) {
return candidates[0].path, nil
}
+func discoverLegacyPluginRoot(homeDir string, preferredVersion string) (string, bool, error) {
+ if preferredVersion == "" {
+ return "", false, nil
+ }
+
+ root := filepath.Join(homeDir, defaultLegacyPluginRoot)
+ if _, err := os.Stat(filepath.Join(root, defaultServerRelativeBin)); err != nil {
+ return "", false, nil
+ }
+
+ version, ok, err := readPluginManifestVersion(root)
+ if err != nil {
+ return "", false, err
+ }
+ if !ok || version != preferredVersion {
+ return "", false, nil
+ }
+
+ return root, true, nil
+}
+
+func readPluginManifestVersion(pluginRoot string) (string, bool, error) {
+ manifestPath := filepath.Join(pluginRoot, defaultPluginManifest)
+ data, err := os.ReadFile(manifestPath)
+ if err != nil {
+ if os.IsNotExist(err) {
+ return "", false, nil
+ }
+ return "", false, fmt.Errorf("read plugin manifest %q: %w", manifestPath, err)
+ }
+
+ var manifest pluginManifest
+ if err := json.Unmarshal(data, &manifest); err != nil {
+ return "", false, fmt.Errorf("decode plugin manifest %q: %w", manifestPath, err)
+ }
+ if strings.TrimSpace(manifest.Version) == "" {
+ return "", false, nil
+ }
+ return strings.TrimSpace(manifest.Version), true, nil
+}
+
func readToolArgs(argsJSON, argsFile string) (map[string]any, error) {
if argsFile != "" {
data, err := os.ReadFile(argsFile)
@@ -821,7 +916,8 @@ Examples:
Environment:
%s Override the installed plugin root.
+ %s Override the installed bundled plugin version; use "latest" for newest installed or "host" for app-server host config.
%s Override the SkyComputerUseClient executable path.
%s Override the Codex binary used for app-server mode.
-`, cliName, cliName, cliName, cliName, cliName, cliName, cliName, cliName, cliName, cliName, cliName, cliName, pluginRootEnvVar, serverBinEnvVar, appServerBinEnvVar)
+`, cliName, cliName, cliName, cliName, cliName, cliName, cliName, cliName, cliName, cliName, cliName, cliName, pluginRootEnvVar, pluginVersionEnvVar, serverBinEnvVar, appServerBinEnvVar)
}
diff --git a/scripts/computer-use-cli/main_test.go b/scripts/computer-use-cli/main_test.go
index 4bbe3bf..fd0f11f 100644
--- a/scripts/computer-use-cli/main_test.go
+++ b/scripts/computer-use-cli/main_test.go
@@ -4,6 +4,7 @@ import (
"encoding/json"
"os"
"path/filepath"
+ "strings"
"testing"
"time"
)
@@ -87,7 +88,7 @@ func TestDiscoverPluginRootChoosesNewestCandidate(t *testing.T) {
t.Fatalf("chtimes older: %v", err)
}
- root, err := discoverPluginRoot()
+ root, err := discoverPluginRoot("", false)
if err != nil {
t.Fatalf("discoverPluginRoot returned error: %v", err)
}
@@ -96,6 +97,145 @@ func TestDiscoverPluginRootChoosesNewestCandidate(t *testing.T) {
}
}
+func TestDiscoverPluginRootPrefersDefaultTestVersion(t *testing.T) {
+ tempHome := t.TempDir()
+ t.Setenv("HOME", tempHome)
+
+ parent := filepath.Join(tempHome, defaultPluginVersionsDir)
+ if err := os.MkdirAll(parent, 0o755); err != nil {
+ t.Fatalf("mkdir parent: %v", err)
+ }
+
+ legacy := filepath.Join(parent, defaultTestPluginVersion)
+ newer := filepath.Join(parent, "1.0.755")
+ createFakePluginRoot(t, legacy)
+ createFakePluginRoot(t, newer)
+
+ future := time.Now().Add(time.Hour)
+ if err := os.Chtimes(newer, future, future); err != nil {
+ t.Fatalf("chtimes newer: %v", err)
+ }
+
+ root, err := discoverPluginRoot(defaultTestPluginVersion, false)
+ if err != nil {
+ t.Fatalf("discoverPluginRoot returned error: %v", err)
+ }
+ if got, want := root, legacy; got != want {
+ t.Fatalf("discoverPluginRoot = %q, want %q", got, want)
+ }
+}
+
+func TestDiscoverPluginRootPrefersLegacyRootForDefaultTestVersion(t *testing.T) {
+ tempHome := t.TempDir()
+ t.Setenv("HOME", tempHome)
+
+ parent := filepath.Join(tempHome, defaultPluginVersionsDir)
+ cacheRoot := filepath.Join(parent, defaultTestPluginVersion)
+ legacyRoot := filepath.Join(tempHome, defaultLegacyPluginRoot)
+ createFakePluginRoot(t, cacheRoot)
+ createFakePluginRoot(t, legacyRoot)
+ writeFakePluginManifest(t, legacyRoot, defaultTestPluginVersion)
+
+ root, err := discoverPluginRoot(defaultTestPluginVersion, false)
+ if err != nil {
+ t.Fatalf("discoverPluginRoot returned error: %v", err)
+ }
+ if got, want := root, legacyRoot; got != want {
+ t.Fatalf("discoverPluginRoot = %q, want %q", got, want)
+ }
+}
+
+func TestDiscoverPluginRootSkipsLegacyRootForMismatchedVersion(t *testing.T) {
+ tempHome := t.TempDir()
+ t.Setenv("HOME", tempHome)
+
+ parent := filepath.Join(tempHome, defaultPluginVersionsDir)
+ cacheRoot := filepath.Join(parent, defaultTestPluginVersion)
+ legacyRoot := filepath.Join(tempHome, defaultLegacyPluginRoot)
+ createFakePluginRoot(t, cacheRoot)
+ createFakePluginRoot(t, legacyRoot)
+ writeFakePluginManifest(t, legacyRoot, "1.0.1")
+
+ root, err := discoverPluginRoot(defaultTestPluginVersion, false)
+ if err != nil {
+ t.Fatalf("discoverPluginRoot returned error: %v", err)
+ }
+ if got, want := root, cacheRoot; got != want {
+ t.Fatalf("discoverPluginRoot = %q, want %q", got, want)
+ }
+}
+
+func TestResolveTargetUsesExplicitPluginVersion(t *testing.T) {
+ tempHome := t.TempDir()
+ t.Setenv("HOME", tempHome)
+
+ parent := filepath.Join(tempHome, defaultPluginVersionsDir)
+ legacy := filepath.Join(parent, defaultTestPluginVersion)
+ newer := filepath.Join(parent, "1.0.755")
+ createFakePluginRoot(t, legacy)
+ createFakePluginRoot(t, newer)
+
+ target, err := resolveTarget(commonFlags{pluginVersion: "1.0.755"})
+ if err != nil {
+ t.Fatalf("resolveTarget returned error: %v", err)
+ }
+ if got, want := target.PluginRoot, newer; got != want {
+ t.Fatalf("PluginRoot = %q, want %q", got, want)
+ }
+}
+
+func TestResolveTargetLatestPluginVersionSelectorUsesNewest(t *testing.T) {
+ tempHome := t.TempDir()
+ t.Setenv("HOME", tempHome)
+
+ parent := filepath.Join(tempHome, defaultPluginVersionsDir)
+ legacy := filepath.Join(parent, defaultTestPluginVersion)
+ newer := filepath.Join(parent, "1.0.755")
+ createFakePluginRoot(t, legacy)
+ createFakePluginRoot(t, newer)
+
+ future := time.Now().Add(time.Hour)
+ if err := os.Chtimes(newer, future, future); err != nil {
+ t.Fatalf("chtimes newer: %v", err)
+ }
+
+ target, err := resolveTarget(commonFlags{pluginVersion: "latest"})
+ if err != nil {
+ t.Fatalf("resolveTarget returned error: %v", err)
+ }
+ if got, want := target.PluginRoot, newer; got != want {
+ t.Fatalf("PluginRoot = %q, want %q", got, want)
+ }
+}
+
+func TestResolveTargetRejectsMissingExplicitPluginVersion(t *testing.T) {
+ tempHome := t.TempDir()
+ t.Setenv("HOME", tempHome)
+
+ parent := filepath.Join(tempHome, defaultPluginVersionsDir)
+ createFakePluginRoot(t, filepath.Join(parent, defaultTestPluginVersion))
+
+ if _, err := resolveTarget(commonFlags{pluginVersion: "9.9.999"}); err == nil {
+ t.Fatal("resolveTarget should reject a missing explicit plugin version")
+ }
+}
+
+func TestResolveTargetExplicitServerBinTakesPrecedenceOverPluginVersionEnv(t *testing.T) {
+ t.Setenv(pluginVersionEnvVar, "../bad")
+
+ root := t.TempDir()
+ createFakePluginRoot(t, root)
+ serverBin := filepath.Join(root, defaultServerRelativeBin)
+
+ target, err := resolveTarget(commonFlags{serverBin: serverBin})
+ if err != nil {
+ t.Fatalf("resolveTarget returned error: %v", err)
+ }
+ if got, want := target.ServerBin, serverBin; got != want {
+ t.Fatalf("ServerBin = %q, want %q", got, want)
+ }
+}
+
func TestResolveTransportDefaultsToAppServer(t *testing.T) {
t.Parallel()
@@ -159,6 +299,43 @@ func TestResolveAppServerBinaryPrefersExplicitPath(t *testing.T) {
}
}
+func TestResolveAppServerArgsInjectsDefaultTestVersionConfig(t *testing.T) {
+ tempHome := t.TempDir()
+ t.Setenv("HOME", tempHome)
+
+ parent := filepath.Join(tempHome, defaultPluginVersionsDir)
+ legacy := filepath.Join(parent, defaultTestPluginVersion)
+ newer := filepath.Join(parent, "1.0.755")
+ createFakePluginRoot(t, legacy)
+ createFakePluginRoot(t, newer)
+
+ args, err := resolveAppServerArgs(commonFlags{serverName: defaultAppServerServerName})
+ if err != nil {
+ t.Fatalf("resolveAppServerArgs returned error: %v", err)
+ }
+
+ joined := strings.Join(args, "\n")
+ if !strings.Contains(joined, legacy) {
+ t.Fatalf("app-server args should point at %q, got %q", legacy, joined)
+ }
+ if !strings.Contains(joined, `mcp_servers.computer-use.command=`) {
+ t.Fatalf("app-server args should override computer-use command, got %q", joined)
+ }
+}
+
+func TestResolveAppServerArgsHostSelectorLeavesConfigUntouched(t *testing.T) {
+ args, err := resolveAppServerArgs(commonFlags{pluginVersion: "host"})
+ if err != nil {
+ t.Fatalf("resolveAppServerArgs returned error: %v", err)
+ }
+ if got, want := len(args), 1; got != want {
+ t.Fatalf("len(args) = %d, want %d: %v", got, want, args)
+ }
+ if got, want := args[0], "app-server"; got != want {
+ t.Fatalf("args[0] = %q, want %q", got, want)
+ }
+}
+
func createFakePluginRoot(t *testing.T, root string) {
t.Helper()
@@ -170,3 +347,16 @@ func createFakePluginRoot(t *testing.T, root string) {
t.Fatalf("write fake server bin: %v", err)
}
}
+
+func writeFakePluginManifest(t *testing.T, root string, version string) {
+ t.Helper()
+
+ manifestPath := filepath.Join(root, defaultPluginManifest)
+ if err := os.MkdirAll(filepath.Dir(manifestPath), 0o755); err != nil {
+ t.Fatalf("mkdir plugin manifest dir: %v", err)
+ }
+ data := []byte(`{"name":"computer-use","version":"` + version + `"}`)
+ if err := os.WriteFile(manifestPath, data, 0o644); err != nil {
+ t.Fatalf("write plugin manifest: %v", err)
+ }
+}