Skip to content

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

Add computer-use CLI probe docs

Leoa153d0e84e33
diff --git a/README.md b/README.md
index 55602ca..73178e6 100644
--- a/README.md
+++ b/README.md
@@ -67,6 +67,21 @@ swift test
./scripts/run-tool-smoke-tests.sh
```
+如果你需要从仓库里直接探测官方 Codex 桌面版自带的闭源 `computer-use` 插件,优先用:
+
+```bash
+cd scripts/computer-use-cli
+go run . list-tools
+go run . call list_apps
+```
+
+这不是仓库主产物,而是一个调试/探针 CLI。它会自动在两种模式间切换:
+
+- 对官方 bundled `computer-use`,走 `codex app-server` 代理调用。
+- 对显式传入的非 Sky stdio server,走 direct MCP 连接。
+
+详细背景、约束和用法见 [docs/references/codex-computer-use-cli.md](./docs/references/codex-computer-use-cli.md)。
+
如果你想单独看某个 app 当前会被如何序列化,可以直接跑:
```bash
@@ -135,6 +150,8 @@ https://chatgpt.com/backend-api/codex/responses
端到端 smoke runner,会真实拉起 fixture 和 MCP server,对 9 个 tools 做回归。
- `scripts/build-open-computer-use-app.sh`
生成最小可运行的 `.app` bundle,便于真实授权与本地 UI 验证。
+- `scripts/computer-use-cli`
+ 一个独立 Go 模块,用来探测官方 bundled `computer-use` 和普通 stdio MCP server;默认会对官方 Sky client 走 `codex app-server` 代理,避免 caller signing / launch constraint 问题。
- `plugins/open-computer-use`
repo-local Codex plugin 包装层,包含 plugin manifest、MCP 启动脚本和展示资源。
- `scripts/install-codex-plugin.sh`
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 5d1feed..fbd2554 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -18,7 +18,7 @@
- 键鼠输入模拟
- fixture test bridge
- `scripts/`
- 仓库级自动化命令,包括 smoke test 和 `.app` 打包入口。
+ 仓库级自动化命令,包括 smoke test、`.app` 打包入口,以及 `scripts/computer-use-cli/` 这个用于探测官方 bundled `computer-use` 的 Go helper。
- `docs/`
逆向分析、执行计划、history 和项目约束。
@@ -66,6 +66,7 @@
## 关键边界
- 开源版当前不复刻官方闭源实现里的 caller signing、私有 IPC、overlay UI 和 plugin 自安装逻辑。
+- 因为官方 `SkyComputerUseClient` 带有宿主侧 launch constraints,普通 stdio MCP client 在本机上可能被系统直接杀掉;如果要探测官方 bundled `computer-use`,默认应通过 `scripts/computer-use-cli` 的 app-server 模式走已签名的 Codex 宿主。
- 当前权限引导已经具备可运行 app、深链和拖拽辅助,但还没有完全复刻官方那套嵌入式 choreography / overlay 体验。
- screenshot 当前使用系统窗口截图 API,结果写入临时目录,不做长期持久化。
- 会话状态现在是进程内内存态,保存每个 app 最近一次 snapshot 和 element index 映射。
diff --git a/docs/histories/2026-04/20260417-1807-move-computer-use-cli-into-scripts.md b/docs/histories/2026-04/20260417-1807-move-computer-use-cli-into-scripts.md
new file mode 100644
index 0000000..9a2f323
--- /dev/null
+++ b/docs/histories/2026-04/20260417-1807-move-computer-use-cli-into-scripts.md
@@ -0,0 +1,33 @@
+## [2026-04-17 18:07] | Task: 移动 computer-use-cli 并补仓库文档
+
+### 🤖 Execution Context
+* **Agent ID**: `Codex`
+* **Base Model**: `gpt-5.4`
+* **Runtime**: `Codex CLI`
+
+### 📥 User Query
+> 把 `computer-use-cli/` 移动到 `open-codex-computer-use` 仓库里的合适位置,并根据该仓库 `AGENTS.md` 的约定补充文档,告诉后续 AI 这个工具怎么使用。
+
+### 🛠 Changes Overview
+**Scope:** `scripts/computer-use-cli`, `README`, `docs/ARCHITECTURE.md`, `docs/references`, `docs/histories`
+
+**Key Actions:**
+- **[Relocate helper CLI]**: 把独立 Go 调试工具移动到 `scripts/computer-use-cli/`,让它和仓库级自动化脚本放在同一层。
+- **[Document repo-level usage]**: 在仓库根 `README.md`、架构文档和 references 索引里补上入口,避免后续 Agent 只能靠聊天上下文知道这个工具存在。
+- **[Add durable reference]**: 新增 `docs/references/codex-computer-use-cli.md`,说明官方 bundled `computer-use` 为什么不能依赖普通 stdio client 直连,以及应该如何使用 app-server 模式探测它。
+
+### 🧠 Design Intent (Why)
+这个 CLI 的职责是调试和探测,不是仓库主产物,放在 `scripts/` 下比塞进 `apps/` 或 `packages/` 更符合边界。与此同时,`AGENTS.md` 明确要求把仓库级知识沉淀到 `docs/`,所以用一份独立 reference 文档承接“为什么存在”和“AI 应该怎么用”,再从 `README` 和 `ARCHITECTURE` 做导航,比把细节堆进 `AGENTS.md` 更符合这个仓库的文档纪律。
+
+### 📁 Files Modified
+- `scripts/computer-use-cli/README.md`
+- `scripts/computer-use-cli/app_server.go`
+- `scripts/computer-use-cli/go.mod`
+- `scripts/computer-use-cli/go.sum`
+- `scripts/computer-use-cli/main.go`
+- `scripts/computer-use-cli/main_test.go`
+- `README.md`
+- `docs/ARCHITECTURE.md`
+- `docs/references/README.md`
+- `docs/references/codex-computer-use-cli.md`
+- `docs/histories/2026-04/20260417-1807-move-computer-use-cli-into-scripts.md`
diff --git a/docs/references/README.md b/docs/references/README.md
index 53e3fa7..b5a28da 100644
--- a/docs/references/README.md
+++ b/docs/references/README.md
@@ -19,3 +19,5 @@
- 用 `mitmdump` + `scripts/codex_dump.py` 抓 Codex 上游 HTTP / WebSocket 流量,并把样本沉淀到 `artifacts/codex-dumps/` 做持续分析。
- `codex-local-runtime-logs.md`
- 当上游 LLM dump 不足以解释本地 tool / MCP 行为时,补查 Codex 本地 `logs_2.sqlite`;默认顺序仍然是先看上游抓包,再看本地日志。
+- `codex-computer-use-cli.md`
+ - 仓库内 `scripts/computer-use-cli/` 的用途、使用方法,以及为什么探测官方 bundled `computer-use` 时要优先走 `codex app-server` 代理而不是 direct stdio。
diff --git a/docs/references/codex-computer-use-cli.md b/docs/references/codex-computer-use-cli.md
new file mode 100644
index 0000000..9c9f9d5
--- /dev/null
+++ b/docs/references/codex-computer-use-cli.md
@@ -0,0 +1,106 @@
+# `scripts/computer-use-cli`
+
+这个目录下放的是一个独立 Go CLI,用来做两类事情:
+
+- 探测官方 Codex 桌面版自带的闭源 `computer-use`
+- 直接连接普通 stdio MCP server,例如本仓库产出的 `open-computer-use`
+
+它不是仓库主产物,而是调试/逆向分析辅助工具。
+
+## 为什么需要它
+
+在这台机器上,官方 bundled `computer-use` 的可执行文件 `SkyComputerUseClient` 不能被一个普通 unsigned MCP client 稳定直接拉起。
+
+已验证的现象是:
+
+- 标准 stdio MCP client 握手前就退出
+- 官方 Go MCP SDK 自带示例也会失败
+- crash report 指向 `Launch Constraint Violation` / `CODESIGNING`
+
+结论是:这不是单纯的 MCP 协议兼容问题,而是宿主签名/父进程约束。要探测官方 bundled `computer-use`,应优先借助已签名的 Codex 宿主,通过 `codex app-server` 走 `mcpServer/tool/call`。
+
+## 目录位置
+
+```text
+scripts/computer-use-cli/
+```
+
+目录本身是一个独立 Go module,内部自带 `go.mod`、单测和 README。
+
+## AI 默认用法
+
+如果任务目标是“验证官方 Codex 自带的 `computer-use` 能不能列工具、能不能调某个 tool”,优先这样跑:
+
+```bash
+cd scripts/computer-use-cli
+go run . list-tools
+go run . call list_apps
+go run . call get_app_state --args '{"app":"Feishu"}'
+```
+
+默认 `auto` 模式会自动选择:
+
+- 官方 bundled `computer-use` -> `app-server`
+- 显式传入的非 Sky server binary -> `direct`
+
+## 两种 transport
+
+### 1. `app-server`
+
+适用于官方 bundled `computer-use`。
+
+```bash
+cd scripts/computer-use-cli
+go run . list-tools --transport app-server
+go run . call list_apps --transport app-server
+```
+
+这个模式会:
+
+1. 启动 `codex app-server`
+2. 建一个 ephemeral thread
+3. 通过 `mcpServer/tool/call` 调目标 server
+
+如果本机 Codex 可执行不在默认位置,可以显式指定:
+
+```bash
+CODEX_APP_SERVER_BIN=/Applications/Codex.app/Contents/Resources/codex \
+go run . call list_apps --transport app-server
+```
+
+### 2. `direct`
+
+适用于普通 stdio MCP server,例如本仓库本地产出的 `open-computer-use`。
+
+```bash
+cd scripts/computer-use-cli
+go run . call list_apps \
+ --transport direct \
+ --server-bin ~/.codex/plugins/cache/open-computer-use-local/open-computer-use/0.1.0/scripts/launch-open-computer-use.sh
+```
+
+## 什么时候不要再重试 direct
+
+如果目标是官方 `SkyComputerUseClient`,而且你已经看到下面这类现象,就不要再浪费时间试“换一个通用 MCP client”:
+
+- `EOF`
+- `broken pipe`
+- 初始化前退出
+- crash report 里出现 `Launch Constraint Violation`
+
+这类情况下,优先切回 `app-server` 模式。
+
+## 本地验证
+
+```bash
+cd scripts/computer-use-cli
+go test ./...
+```
+
+如果只是想快速确认工具链没坏,最小正向验证通常是:
+
+```bash
+cd scripts/computer-use-cli
+go run . list-tools
+go run . call list_apps
+```
diff --git a/scripts/computer-use-cli/README.md b/scripts/computer-use-cli/README.md
new file mode 100644
index 0000000..c9edd70
--- /dev/null
+++ b/scripts/computer-use-cli/README.md
@@ -0,0 +1,95 @@
+# computer-use-cli
+
+Small Go CLI for probing Codex desktop-control tooling.
+
+This directory is intended to be run from `scripts/computer-use-cli/` inside the repo:
+
+```bash
+cd scripts/computer-use-cli
+go run . list-tools
+go run . call list_apps
+```
+
+It supports two transports:
+
+- `direct`: talk to a stdio MCP server directly with the official Go MCP SDK transport layer.
+- `app-server`: talk to `codex app-server`, create an ephemeral thread, then proxy `mcpServer/tool/call` through the signed Codex host.
+
+`auto` is the default:
+
+- for the official bundled proprietary `computer-use`, it uses `app-server`
+- 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"}'
+```
+
+Explicit transport examples:
+
+```bash
+go run . list-tools --transport app-server
+go run . call list_apps --transport app-server
+go run . call list_apps --transport direct --server-bin /path/to/open-computer-use
+```
+
+Flags can appear either before or after the tool name for `call`:
+
+```bash
+go run . call --server-bin /path/to/server list_apps
+go run . call list_apps --server-bin /path/to/server
+```
+
+## Default target
+
+By default, the CLI auto-discovers the official bundled `computer-use` plugin under:
+
+```text
+~/.codex/plugins/cache/openai-bundled/computer-use/<version>
+```
+
+You can override that with:
+
+```bash
+COMPUTER_USE_PLUGIN_ROOT=/path/to/plugin-root
+COMPUTER_USE_SERVER_BIN=/path/to/server-binary
+```
+
+or the equivalent flags:
+
+```bash
+--plugin-root /path/to/plugin-root
+--server-bin /path/to/server-binary
+```
+
+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
+```
+
+## Verified behavior in this workspace
+
+- 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.
+
+Example working invocation against `open-computer-use`:
+
+```bash
+go run . list-tools \
+ --transport direct \
+ --server-bin ~/.codex/plugins/cache/open-computer-use-local/open-computer-use/0.1.0/scripts/launch-open-computer-use.sh
+```
+
+Example working invocation against the official bundled `computer-use`:
+
+```bash
+go run . call list_apps --transport app-server
+```
diff --git a/scripts/computer-use-cli/app_server.go b/scripts/computer-use-cli/app_server.go
new file mode 100644
index 0000000..6ca55c1
--- /dev/null
+++ b/scripts/computer-use-cli/app_server.go
@@ -0,0 +1,446 @@
+package main
+
+import (
+ "bufio"
+ "bytes"
+ "context"
+ "encoding/json"
+ "fmt"
+ "io"
+ "os"
+ "os/exec"
+ "path/filepath"
+ "sort"
+ "strconv"
+ "strings"
+ "sync/atomic"
+
+ "github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+const (
+ transportAuto = "auto"
+ transportDirect = "direct"
+ transportAppServer = "app-server"
+ appServerBinEnvVar = "CODEX_APP_SERVER_BIN"
+ defaultAppServerServerName = "computer-use"
+ defaultAppServerApprovalPolicy = "never"
+ defaultAppServerSandbox = "danger-full-access"
+ defaultCodexAppBinary = "/Applications/Codex.app/Contents/Resources/codex"
+)
+
+type appServerSession struct {
+ cmd *exec.Cmd
+ stdin io.WriteCloser
+ messages chan appServerMessage
+ readErr chan error
+ nextID int64
+}
+
+type appServerInitializeParams struct {
+ ClientInfo *mcp.Implementation `json:"clientInfo"`
+}
+
+type appServerListMcpStatusParams struct {
+ Detail string `json:"detail,omitempty"`
+}
+
+type appServerListMcpStatusResult struct {
+ Data []*appServerMcpStatus `json:"data"`
+}
+
+type appServerMcpStatus struct {
+ Name string `json:"name"`
+ Tools map[string]*mcp.Tool `json:"tools"`
+ AuthStatus string `json:"authStatus"`
+}
+
+type appServerThreadStartParams struct {
+ ApprovalPolicy string `json:"approvalPolicy,omitempty"`
+ Cwd string `json:"cwd,omitempty"`
+ Ephemeral bool `json:"ephemeral"`
+ Sandbox string `json:"sandbox,omitempty"`
+}
+
+type appServerThreadStartResult struct {
+ Thread appServerThread `json:"thread"`
+}
+
+type appServerThread struct {
+ ID string `json:"id"`
+}
+
+type appServerToolCallParams struct {
+ ThreadID string `json:"threadId"`
+ Server string `json:"server"`
+ Tool string `json:"tool"`
+ Arguments map[string]any `json:"arguments,omitempty"`
+}
+
+type appServerMessage struct {
+ ID any `json:"id,omitempty"`
+ Method string `json:"method,omitempty"`
+ Params json.RawMessage `json:"params,omitempty"`
+ Result json.RawMessage `json:"result,omitempty"`
+ Error *appServerError `json:"error,omitempty"`
+}
+
+type appServerError struct {
+ Code int `json:"code"`
+ Message string `json:"message"`
+ Data json.RawMessage `json:"data,omitempty"`
+}
+
+func (e *appServerError) Error() string {
+ if e == nil {
+ return ""
+ }
+ return fmt.Sprintf("code %d: %s", e.Code, e.Message)
+}
+
+func resolveTransport(flags commonFlags) (string, error) {
+ switch flags.transport {
+ case "", transportAuto:
+ if flags.appServerBin != "" {
+ return transportAppServer, nil
+ }
+ if flags.serverBin == "" && flags.pluginRoot == "" {
+ return transportAppServer, nil
+ }
+
+ target, err := resolveTarget(flags)
+ if err != nil {
+ return "", err
+ }
+ if isSkyComputerUseBinary(target.ServerBin) {
+ return transportAppServer, nil
+ }
+ return transportDirect, nil
+ case transportDirect, transportAppServer:
+ return flags.transport, nil
+ default:
+ return "", fmt.Errorf("invalid --transport %q: want %q, %q, or %q", flags.transport, transportAuto, transportDirect, transportAppServer)
+ }
+}
+
+func connectAppServer(ctx context.Context, flags commonFlags) (*appServerSession, error) {
+ appServerBin, err := resolveAppServerBinary(flags)
+ if err != nil {
+ return nil, err
+ }
+
+ threadCwd, err := resolveThreadCwd(flags)
+ if err != nil {
+ return nil, err
+ }
+
+ cmd := exec.Command(appServerBin, "app-server")
+ cmd.Dir = threadCwd
+ cmd.Stderr = os.Stderr
+
+ stdin, err := cmd.StdinPipe()
+ if err != nil {
+ return nil, fmt.Errorf("open stdin for %q: %w", appServerBin, err)
+ }
+ stdout, err := cmd.StdoutPipe()
+ if err != nil {
+ return nil, fmt.Errorf("open stdout for %q: %w", appServerBin, err)
+ }
+ if err := cmd.Start(); err != nil {
+ return nil, fmt.Errorf("start %q: %w", appServerBin, err)
+ }
+
+ session := &appServerSession{
+ cmd: cmd,
+ stdin: stdin,
+ messages: make(chan appServerMessage, 32),
+ readErr: make(chan error, 1),
+ }
+ go session.readLoop(stdout)
+
+ connectCtx, cancel := context.WithTimeout(ctx, flags.timeout)
+ defer cancel()
+ if err := session.initialize(connectCtx); err != nil {
+ _ = session.Close()
+ return nil, fmt.Errorf("initialize app-server session: %w", err)
+ }
+ return session, nil
+}
+
+func (s *appServerSession) Close() error {
+ if s.stdin != nil {
+ _ = s.stdin.Close()
+ }
+ if s.cmd != nil && s.cmd.Process != nil {
+ _ = s.cmd.Process.Kill()
+ _ = s.cmd.Wait()
+ }
+ return nil
+}
+
+func (s *appServerSession) initialize(ctx context.Context) error {
+ var result map[string]any
+ if err := s.request(ctx, "initialize", appServerInitializeParams{
+ ClientInfo: &mcp.Implementation{
+ Name: cliName,
+ Version: cliVersion,
+ Title: cliName,
+ },
+ }, &result); err != nil {
+ return err
+ }
+
+ return s.notify("initialized", map[string]any{})
+}
+
+func (s *appServerSession) listToolsViaAppServer(ctx context.Context, serverName string) (*mcp.ListToolsResult, error) {
+ var result appServerListMcpStatusResult
+ if err := s.request(ctx, "mcpServerStatus/list", appServerListMcpStatusParams{
+ Detail: "toolsAndAuthOnly",
+ }, &result); err != nil {
+ return nil, err
+ }
+
+ status, err := findAppServerStatus(result.Data, serverName)
+ if err != nil {
+ return nil, err
+ }
+
+ return &mcp.ListToolsResult{Tools: sortToolMap(status.Tools)}, nil
+}
+
+func (s *appServerSession) callToolViaAppServer(
+ ctx context.Context,
+ flags commonFlags,
+ toolName string,
+ toolArgs map[string]any,
+) (*mcp.CallToolResult, error) {
+ threadCwd, err := resolveThreadCwd(flags)
+ if err != nil {
+ return nil, err
+ }
+
+ var thread appServerThreadStartResult
+ if err := s.request(ctx, "thread/start", appServerThreadStartParams{
+ ApprovalPolicy: flags.approvalPolicy,
+ Cwd: threadCwd,
+ Ephemeral: true,
+ Sandbox: flags.sandbox,
+ }, &thread); err != nil {
+ return nil, fmt.Errorf("start ephemeral thread: %w", err)
+ }
+ if thread.Thread.ID == "" {
+ return nil, fmt.Errorf("app-server returned an empty thread id")
+ }
+
+ var result mcp.CallToolResult
+ if err := s.request(ctx, "mcpServer/tool/call", appServerToolCallParams{
+ ThreadID: thread.Thread.ID,
+ Server: flags.serverName,
+ Tool: toolName,
+ Arguments: toolArgs,
+ }, &result); err != nil {
+ return nil, err
+ }
+ return &result, nil
+}
+
+func (s *appServerSession) request(ctx context.Context, method string, params any, out any) error {
+ requestID := atomic.AddInt64(&s.nextID, 1)
+
+ if err := s.sendMessage(map[string]any{
+ "id": requestID,
+ "method": method,
+ "params": params,
+ }); err != nil {
+ return fmt.Errorf("write %q request: %w", method, err)
+ }
+
+ for {
+ select {
+ case <-ctx.Done():
+ return ctx.Err()
+ case err := <-s.readErr:
+ return fmt.Errorf("read %q response: %w", method, err)
+ case message := <-s.messages:
+ if message.Method != "" {
+ if message.ID != nil {
+ return fmt.Errorf("server sent unexpected request %q while waiting for %q", message.Method, method)
+ }
+ continue
+ }
+
+ if !appServerMessageIDMatches(message.ID, requestID) {
+ continue
+ }
+ if message.Error != nil {
+ return fmt.Errorf("%q failed: %w", method, message.Error)
+ }
+ if out == nil || len(message.Result) == 0 {
+ return nil
+ }
+ if err := json.Unmarshal(message.Result, out); err != nil {
+ return fmt.Errorf("decode %q response: %w", method, err)
+ }
+ return nil
+ }
+ }
+}
+
+func (s *appServerSession) notify(method string, params any) error {
+ if err := s.sendMessage(map[string]any{
+ "method": method,
+ "params": params,
+ }); err != nil {
+ return fmt.Errorf("write %q notification: %w", method, err)
+ }
+ return nil
+}
+
+func (s *appServerSession) sendMessage(message any) error {
+ data, err := json.Marshal(message)
+ if err != nil {
+ return err
+ }
+ if _, err := s.stdin.Write(append(data, '\n')); err != nil {
+ return err
+ }
+ return nil
+}
+
+func (s *appServerSession) readLoop(stdout io.Reader) {
+ reader := bufio.NewReader(stdout)
+ for {
+ line, err := reader.ReadBytes('\n')
+ if len(bytes.TrimSpace(line)) > 0 {
+ var message appServerMessage
+ if unmarshalErr := json.Unmarshal(bytes.TrimSpace(line), &message); unmarshalErr != nil {
+ s.readErr <- fmt.Errorf("decode app-server message: %w", unmarshalErr)
+ return
+ }
+ s.messages <- message
+ }
+
+ if err != nil {
+ s.readErr <- err
+ return
+ }
+ }
+}
+
+func appServerMessageIDMatches(rawID any, want int64) bool {
+ switch value := rawID.(type) {
+ case nil:
+ return false
+ case float64:
+ return int64(value) == want
+ case json.Number:
+ got, err := value.Int64()
+ return err == nil && got == want
+ case string:
+ return value == strconv.FormatInt(want, 10)
+ default:
+ return fmt.Sprint(value) == strconv.FormatInt(want, 10)
+ }
+}
+
+func resolveAppServerBinary(flags commonFlags) (string, error) {
+ if path := firstNonEmpty(flags.appServerBin, os.Getenv(appServerBinEnvVar)); path != "" {
+ return validateAppServerBinary(path)
+ }
+
+ candidates := []string{defaultCodexAppBinary}
+ if path, err := exec.LookPath("codex"); err == nil {
+ candidates = append(candidates, path)
+ }
+
+ var checked []string
+ for _, candidate := range candidates {
+ if strings.TrimSpace(candidate) == "" {
+ continue
+ }
+ normalized, err := validateAppServerBinary(candidate)
+ if err == nil {
+ return normalized, nil
+ }
+ checked = append(checked, candidate)
+ }
+
+ return "", fmt.Errorf(
+ "could not find a usable Codex binary for app-server mode; checked %s; pass --app-server-bin or set %s",
+ strings.Join(checked, ", "),
+ appServerBinEnvVar,
+ )
+}
+
+func validateAppServerBinary(path string) (string, error) {
+ normalized, err := normalizePath(path)
+ if err != nil {
+ return "", err
+ }
+
+ info, err := os.Stat(normalized)
+ if err != nil {
+ return "", fmt.Errorf("stat app-server binary %q: %w", normalized, err)
+ }
+ if info.IsDir() {
+ return "", fmt.Errorf("app-server binary %q is a directory", normalized)
+ }
+ return normalized, nil
+}
+
+func resolveThreadCwd(flags commonFlags) (string, error) {
+ if flags.cwd != "" {
+ return normalizePath(flags.cwd)
+ }
+
+ wd, err := os.Getwd()
+ if err != nil {
+ return "", fmt.Errorf("resolve current working directory: %w", err)
+ }
+ return normalizePath(wd)
+}
+
+func isSkyComputerUseBinary(path string) bool {
+ cleanPath := filepath.Clean(path)
+ return filepath.Base(cleanPath) == "SkyComputerUseClient" && strings.HasSuffix(cleanPath, filepath.Clean(defaultServerRelativeBin))
+}
+
+func findAppServerStatus(statuses []*appServerMcpStatus, serverName string) (*appServerMcpStatus, error) {
+ available := make([]string, 0, len(statuses))
+ for _, status := range statuses {
+ if status == nil {
+ continue
+ }
+ available = append(available, status.Name)
+ if status.Name == serverName {
+ return status, nil
+ }
+ }
+ sort.Strings(available)
+ return nil, fmt.Errorf("server %q not found in app-server inventory; available servers: %s", serverName, strings.Join(available, ", "))
+}
+
+func sortToolMap(toolMap map[string]*mcp.Tool) []*mcp.Tool {
+ if len(toolMap) == 0 {
+ return nil
+ }
+
+ names := make([]string, 0, len(toolMap))
+ for name := range toolMap {
+ names = append(names, name)
+ }
+ sort.Strings(names)
+
+ tools := make([]*mcp.Tool, 0, len(names))
+ for _, name := range names {
+ tool := toolMap[name]
+ if tool == nil {
+ tool = &mcp.Tool{Name: name}
+ } else if tool.Name == "" {
+ tool.Name = name
+ }
+ tools = append(tools, tool)
+ }
+ return tools
+}
diff --git a/scripts/computer-use-cli/go.mod b/scripts/computer-use-cli/go.mod
new file mode 100644
index 0000000..7464c92
--- /dev/null
+++ b/scripts/computer-use-cli/go.mod
@@ -0,0 +1,11 @@
+module github.com/openai/codex/computer-use-cli
+
+go 1.26.0
+
+require github.com/modelcontextprotocol/go-sdk v1.1.0
+
+require (
+ github.com/google/jsonschema-go v0.4.2 // indirect
+ github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
+ golang.org/x/oauth2 v0.35.0 // indirect
+)
diff --git a/scripts/computer-use-cli/go.sum b/scripts/computer-use-cli/go.sum
new file mode 100644
index 0000000..076f4e8
--- /dev/null
+++ b/scripts/computer-use-cli/go.sum
@@ -0,0 +1,12 @@
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/jsonschema-go v0.4.2 h1:tmrUohrwoLZZS/P3x7ex0WAVknEkBZM46iALbcqoRA8=
+github.com/google/jsonschema-go v0.4.2/go.mod h1:r5quNTdLOYEz95Ru18zA0ydNbBuYoo9tgaYcxEYhJVE=
+github.com/modelcontextprotocol/go-sdk v1.1.0 h1:Qjayg53dnKC4UZ+792W21e4BpwEZBzwgRW6LrjLWSwA=
+github.com/modelcontextprotocol/go-sdk v1.1.0/go.mod h1:6fM3LCm3yV7pAs8isnKLn07oKtB0MP9LHd3DfAcKw10=
+github.com/yosida95/uritemplate/v3 v3.0.2 h1:Ed3Oyj9yrmi9087+NczuL5BwkIc4wvTb5zIM+UJPGz4=
+github.com/yosida95/uritemplate/v3 v3.0.2/go.mod h1:ILOh0sOhIJR3+L/8afwt/kE++YT040gmv5BQTMR2HP4=
+golang.org/x/oauth2 v0.35.0 h1:Mv2mzuHuZuY2+bkyWXIHMfhNdJAdwW3FuWeCPYN5GVQ=
+golang.org/x/oauth2 v0.35.0/go.mod h1:lzm5WQJQwKZ3nwavOZ3IS5Aulzxi68dUSgRHujetwEA=
+golang.org/x/tools v0.34.0 h1:qIpSLOxeCYGg9TrcJokLBG4KFA6d795g0xkBkiESGlo=
+golang.org/x/tools v0.34.0/go.mod h1:pAP9OwEaY1CAW3HOmg3hLZC5Z0CCmzjAF2UQMSqNARg=
diff --git a/scripts/computer-use-cli/main.go b/scripts/computer-use-cli/main.go
new file mode 100644
index 0000000..7ecf6a7
--- /dev/null
+++ b/scripts/computer-use-cli/main.go
@@ -0,0 +1,697 @@
+package main
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "flag"
+ "fmt"
+ "io"
+ "os"
+ "os/exec"
+ "path/filepath"
+ "sort"
+ "strings"
+ "sync/atomic"
+ "time"
+
+ "github.com/modelcontextprotocol/go-sdk/jsonrpc"
+ "github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+const (
+ cliName = "computer-use-cli"
+ cliVersion = "0.1.0"
+ defaultTimeout = 60 * time.Second
+ pluginRootEnvVar = "COMPUTER_USE_PLUGIN_ROOT"
+ serverBinEnvVar = "COMPUTER_USE_SERVER_BIN"
+ defaultPluginVersionsDir = ".codex/plugins/cache/openai-bundled/computer-use"
+ defaultServerRelativeBin = "Codex Computer Use.app/Contents/SharedSupport/SkyComputerUseClient.app/Contents/MacOS/SkyComputerUseClient"
+)
+
+type commonFlags struct {
+ transport string
+ pluginRoot string
+ serverBin string
+ appServerBin string
+ serverName string
+ cwd string
+ approvalPolicy string
+ sandbox string
+ timeout time.Duration
+ pretty bool
+}
+
+type resolvedTarget struct {
+ PluginRoot string `json:"pluginRoot"`
+ ServerBin string `json:"serverBin"`
+}
+
+type rpcSession struct {
+ conn mcp.Connection
+ nextID int64
+}
+
+type initializeParams struct {
+ Capabilities initializeClientCapabilities `json:"capabilities"`
+ ClientInfo *mcp.Implementation `json:"clientInfo"`
+ ProtocolVersion string `json:"protocolVersion"`
+}
+
+type initializeClientCapabilities struct {
+ Experimental map[string]any `json:"experimental,omitempty"`
+ Sampling *mcp.SamplingCapabilities `json:"sampling,omitempty"`
+ Elicitation *mcp.ElicitationCapabilities `json:"elicitation,omitempty"`
+}
+
+func main() {
+ if err := run(context.Background(), os.Args[1:], os.Stdout, os.Stderr); err != nil {
+ if !errors.Is(err, flag.ErrHelp) {
+ fmt.Fprintf(os.Stderr, "error: %v\n", err)
+ }
+ os.Exit(1)
+ }
+}
+
+func run(ctx context.Context, args []string, stdout io.Writer, stderr io.Writer) error {
+ if len(args) == 0 {
+ printRootUsage(stderr)
+ return flag.ErrHelp
+ }
+
+ switch args[0] {
+ case "resolve-server":
+ return runResolveServer(ctx, args[1:], stdout, stderr)
+ case "list-tools":
+ return runListTools(ctx, args[1:], stdout, stderr)
+ case "call":
+ return runCall(ctx, args[1:], stdout, stderr)
+ case "help", "-h", "--help":
+ printRootUsage(stderr)
+ return nil
+ default:
+ printRootUsage(stderr)
+ return fmt.Errorf("unknown subcommand %q", args[0])
+ }
+}
+
+func runResolveServer(_ context.Context, args []string, stdout io.Writer, stderr io.Writer) error {
+ var flags commonFlags
+
+ fs := flag.NewFlagSet("resolve-server", flag.ContinueOnError)
+ fs.SetOutput(stderr)
+ addCommonFlags(fs, &flags)
+ if err := fs.Parse(args); err != nil {
+ return err
+ }
+ if fs.NArg() != 0 {
+ return fmt.Errorf("resolve-server does not accept positional arguments")
+ }
+
+ target, err := resolveTarget(flags)
+ if err != nil {
+ return err
+ }
+ return writeJSON(stdout, target, flags.pretty)
+}
+
+func runListTools(ctx context.Context, args []string, stdout io.Writer, stderr io.Writer) error {
+ var flags commonFlags
+
+ fs := flag.NewFlagSet("list-tools", flag.ContinueOnError)
+ fs.SetOutput(stderr)
+ addCommonFlags(fs, &flags)
+ if err := fs.Parse(args); err != nil {
+ return err
+ }
+ if fs.NArg() != 0 {
+ return fmt.Errorf("list-tools does not accept positional arguments")
+ }
+
+ transport, err := resolveTransport(flags)
+ if err != nil {
+ return err
+ }
+
+ switch transport {
+ case transportDirect:
+ session, err := connect(ctx, flags)
+ if err != nil {
+ return err
+ }
+ defer session.Close()
+
+ opCtx, cancel := context.WithTimeout(ctx, flags.timeout)
+ defer cancel()
+
+ result, err := session.listTools(opCtx)
+ if err != nil {
+ return fmt.Errorf("list tools: %w", err)
+ }
+ return writeJSON(stdout, result, flags.pretty)
+ case transportAppServer:
+ session, err := connectAppServer(ctx, flags)
+ if err != nil {
+ return err
+ }
+ defer session.Close()
+
+ opCtx, cancel := context.WithTimeout(ctx, flags.timeout)
+ defer cancel()
+
+ result, err := session.listToolsViaAppServer(opCtx, flags.serverName)
+ if err != nil {
+ return fmt.Errorf("list tools via app-server: %w", err)
+ }
+ return writeJSON(stdout, result, flags.pretty)
+ default:
+ return fmt.Errorf("unsupported transport %q", transport)
+ }
+}
+
+func runCall(ctx context.Context, args []string, stdout io.Writer, stderr io.Writer) error {
+ var flags commonFlags
+ var argsJSON string
+ var argsFile string
+ var toolName string
+
+ parseArgs := args
+ if len(args) > 0 && !strings.HasPrefix(args[0], "-") {
+ toolName = args[0]
+ parseArgs = args[1:]
+ }
+
+ fs := flag.NewFlagSet("call", flag.ContinueOnError)
+ fs.SetOutput(stderr)
+ addCommonFlags(fs, &flags)
+ fs.StringVar(&argsJSON, "args", "", "JSON object arguments for tools/call")
+ fs.StringVar(&argsFile, "args-file", "", "Path to a file containing JSON object arguments")
+ if err := fs.Parse(parseArgs); err != nil {
+ return err
+ }
+
+ if argsJSON != "" && argsFile != "" {
+ return fmt.Errorf("use only one of --args or --args-file")
+ }
+ if toolName == "" {
+ if fs.NArg() != 1 {
+ return fmt.Errorf("usage: %s call [flags] <tool-name>", cliName)
+ }
+ toolName = fs.Arg(0)
+ } else if fs.NArg() != 0 {
+ return fmt.Errorf("usage: %s call [flags] <tool-name>", cliName)
+ }
+ toolArgs, err := readToolArgs(argsJSON, argsFile)
+ if err != nil {
+ return err
+ }
+
+ transport, err := resolveTransport(flags)
+ if err != nil {
+ return err
+ }
+
+ switch transport {
+ case transportDirect:
+ session, err := connect(ctx, flags)
+ if err != nil {
+ return err
+ }
+ defer session.Close()
+
+ opCtx, cancel := context.WithTimeout(ctx, flags.timeout)
+ defer cancel()
+
+ result, err := session.callTool(opCtx, toolName, toolArgs)
+ if err != nil {
+ return fmt.Errorf("call tool %q: %w", toolName, err)
+ }
+ return writeJSON(stdout, result, flags.pretty)
+ case transportAppServer:
+ session, err := connectAppServer(ctx, flags)
+ if err != nil {
+ return err
+ }
+ defer session.Close()
+
+ opCtx, cancel := context.WithTimeout(ctx, flags.timeout)
+ defer cancel()
+
+ result, err := session.callToolViaAppServer(opCtx, flags, toolName, toolArgs)
+ if err != nil {
+ return fmt.Errorf("call tool %q via app-server: %w", toolName, err)
+ }
+ return writeJSON(stdout, result, flags.pretty)
+ default:
+ return fmt.Errorf("unsupported transport %q", transport)
+ }
+}
+
+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.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")
+ fs.StringVar(&flags.cwd, "cwd", "", "Working directory used for the ephemeral thread in app-server mode")
+ fs.StringVar(&flags.approvalPolicy, "approval-policy", defaultAppServerApprovalPolicy, "Approval policy used in app-server mode")
+ fs.StringVar(&flags.sandbox, "sandbox", defaultAppServerSandbox, "Sandbox mode used in app-server mode")
+ fs.DurationVar(&flags.timeout, "timeout", defaultTimeout, "Timeout for connect and RPC operations")
+ fs.BoolVar(&flags.pretty, "pretty", true, "Pretty-print JSON output")
+}
+
+func connect(ctx context.Context, flags commonFlags) (*rpcSession, error) {
+ target, err := resolveTarget(flags)
+ if err != nil {
+ return nil, err
+ }
+
+ commandPath := target.ServerBin
+ if relativePath, err := filepath.Rel(target.PluginRoot, target.ServerBin); err == nil && !strings.HasPrefix(relativePath, "..") {
+ commandPath = relativePath
+ if !strings.HasPrefix(commandPath, ".") {
+ commandPath = "." + string(filepath.Separator) + commandPath
+ }
+ }
+
+ cmd := exec.Command(commandPath, "mcp")
+ cmd.Dir = target.PluginRoot
+ cmd.Env = mcpServerEnv()
+ cmd.Stderr = os.Stderr
+
+ transport := &mcp.CommandTransport{Command: cmd}
+ connectCtx, cancel := context.WithTimeout(ctx, flags.timeout)
+ defer cancel()
+
+ conn, err := transport.Connect(connectCtx)
+ if err != nil {
+ return nil, fmt.Errorf("connect to %q: %w", target.ServerBin, err)
+ }
+ session := &rpcSession{conn: conn}
+ if err := session.initialize(connectCtx); err != nil {
+ _ = conn.Close()
+ return nil, fmt.Errorf("initialize session: %w", err)
+ }
+ return session, nil
+}
+
+func (s *rpcSession) Close() error {
+ return s.conn.Close()
+}
+
+func (s *rpcSession) initialize(ctx context.Context) error {
+ var result mcp.InitializeResult
+ if err := s.request(ctx, "initialize", initializeParams{
+ Capabilities: initializeClientCapabilities{},
+ ClientInfo: &mcp.Implementation{
+ Name: cliName,
+ Version: cliVersion,
+ Title: cliName,
+ },
+ ProtocolVersion: "2025-06-18",
+ }, &result); err != nil {
+ return err
+ }
+
+ return s.notify(ctx, "notifications/initialized", &mcp.InitializedParams{})
+}
+
+func (s *rpcSession) listTools(ctx context.Context) (*mcp.ListToolsResult, error) {
+ var result mcp.ListToolsResult
+ if err := s.request(ctx, "tools/list", &mcp.ListToolsParams{}, &result); err != nil {
+ return nil, err
+ }
+ return &result, nil
+}
+
+func (s *rpcSession) callTool(
+ ctx context.Context,
+ toolName string,
+ toolArgs map[string]any,
+) (*mcp.CallToolResult, error) {
+ var result mcp.CallToolResult
+ if err := s.request(ctx, "tools/call", &mcp.CallToolParams{
+ Name: toolName,
+ Arguments: toolArgs,
+ }, &result); err != nil {
+ return nil, err
+ }
+ return &result, nil
+}
+
+func (s *rpcSession) request(ctx context.Context, method string, params any, out any) error {
+ requestID := fmt.Sprintf("req-%d", atomic.AddInt64(&s.nextID, 1))
+ id, err := jsonrpc.MakeID(requestID)
+ if err != nil {
+ return fmt.Errorf("build request id: %w", err)
+ }
+
+ paramsRaw, err := marshalParams(params)
+ if err != nil {
+ return fmt.Errorf("marshal params for %q: %w", method, err)
+ }
+
+ if err := s.conn.Write(ctx, &jsonrpc.Request{
+ ID: id,
+ Method: method,
+ Params: paramsRaw,
+ }); err != nil {
+ return fmt.Errorf("write %q request: %w", method, err)
+ }
+
+ for {
+ message, err := s.conn.Read(ctx)
+ if err != nil {
+ return fmt.Errorf("read %q response: %w", method, err)
+ }
+
+ switch message := message.(type) {
+ case *jsonrpc.Response:
+ if fmt.Sprint(message.ID.Raw()) != requestID {
+ continue
+ }
+ if message.Error != nil {
+ return fmt.Errorf("%q failed: %w", method, message.Error)
+ }
+ if out == nil || len(message.Result) == 0 {
+ return nil
+ }
+ if err := json.Unmarshal(message.Result, out); err != nil {
+ return fmt.Errorf("decode %q response: %w", method, err)
+ }
+ return nil
+ case *jsonrpc.Request:
+ if message.ID.IsValid() {
+ return fmt.Errorf("server sent unexpected request %q while waiting for %q", message.Method, method)
+ }
+ default:
+ return fmt.Errorf("received unexpected JSON-RPC message type %T while waiting for %q", message, method)
+ }
+ }
+}
+
+func (s *rpcSession) notify(ctx context.Context, method string, params any) error {
+ paramsRaw, err := marshalParams(params)
+ if err != nil {
+ return fmt.Errorf("marshal params for %q notification: %w", method, err)
+ }
+
+ if err := s.conn.Write(ctx, &jsonrpc.Request{
+ Method: method,
+ Params: paramsRaw,
+ }); err != nil {
+ return fmt.Errorf("write %q notification: %w", method, err)
+ }
+ return nil
+}
+
+func marshalParams(params any) (json.RawMessage, error) {
+ if params == nil {
+ return nil, nil
+ }
+ raw, err := json.Marshal(params)
+ if err != nil {
+ return nil, err
+ }
+ return raw, nil
+}
+
+func mcpServerEnv() []string {
+ allowed := []string{
+ "HOME",
+ "LOGNAME",
+ "PATH",
+ "SHELL",
+ "USER",
+ "__CF_USER_TEXT_ENCODING",
+ "LANG",
+ "LC_ALL",
+ "TERM",
+ "TMPDIR",
+ "TZ",
+ }
+
+ env := make([]string, 0, len(allowed))
+ for _, key := range allowed {
+ if value, ok := os.LookupEnv(key); ok {
+ env = append(env, key+"="+value)
+ }
+ }
+ return env
+}
+
+func resolveTarget(flags commonFlags) (resolvedTarget, error) {
+ serverBin := firstNonEmpty(flags.serverBin, os.Getenv(serverBinEnvVar))
+ pluginRoot := firstNonEmpty(flags.pluginRoot, os.Getenv(pluginRootEnvVar))
+
+ if serverBin != "" {
+ resolvedServerBin, err := normalizePath(serverBin)
+ if err != nil {
+ return resolvedTarget{}, err
+ }
+ resolvedPluginRoot, err := derivePluginRoot(pluginRoot, resolvedServerBin)
+ if err != nil {
+ return resolvedTarget{}, err
+ }
+ return validateTarget(resolvedTarget{
+ PluginRoot: resolvedPluginRoot,
+ ServerBin: resolvedServerBin,
+ })
+ }
+
+ if pluginRoot == "" {
+ var err error
+ pluginRoot, err = discoverPluginRoot()
+ if err != nil {
+ return resolvedTarget{}, err
+ }
+ }
+
+ resolvedPluginRoot, err := normalizePath(pluginRoot)
+ if err != nil {
+ return resolvedTarget{}, err
+ }
+
+ return validateTarget(resolvedTarget{
+ PluginRoot: resolvedPluginRoot,
+ ServerBin: filepath.Join(resolvedPluginRoot, defaultServerRelativeBin),
+ })
+}
+
+func derivePluginRoot(pluginRoot, serverBin string) (string, error) {
+ if pluginRoot != "" {
+ return normalizePath(pluginRoot)
+ }
+
+ parts := strings.Split(filepath.Clean(serverBin), string(filepath.Separator))
+ want := strings.Split(filepath.Clean(defaultServerRelativeBin), string(filepath.Separator))
+ if len(parts) <= len(want) {
+ return filepath.Dir(serverBin), nil
+ }
+
+ rootParts := parts[:len(parts)-len(want)]
+ root := filepath.Join(rootParts...)
+ if filepath.Join(root, defaultServerRelativeBin) == filepath.Clean(serverBin) {
+ return root, nil
+ }
+
+ return filepath.Dir(serverBin), nil
+}
+
+func validateTarget(target resolvedTarget) (resolvedTarget, error) {
+ if target.PluginRoot == "" {
+ return resolvedTarget{}, fmt.Errorf("plugin root is empty")
+ }
+ if target.ServerBin == "" {
+ return resolvedTarget{}, fmt.Errorf("server binary path is empty")
+ }
+
+ info, err := os.Stat(target.ServerBin)
+ if err != nil {
+ return resolvedTarget{}, fmt.Errorf("stat server binary %q: %w", target.ServerBin, err)
+ }
+ if info.IsDir() {
+ return resolvedTarget{}, fmt.Errorf("server binary %q is a directory", target.ServerBin)
+ }
+
+ rootInfo, err := os.Stat(target.PluginRoot)
+ if err != nil {
+ return resolvedTarget{}, fmt.Errorf("stat plugin root %q: %w", target.PluginRoot, err)
+ }
+ if !rootInfo.IsDir() {
+ return resolvedTarget{}, fmt.Errorf("plugin root %q is not a directory", target.PluginRoot)
+ }
+
+ return target, nil
+}
+
+func discoverPluginRoot() (string, error) {
+ homeDir, err := os.UserHomeDir()
+ if err != nil {
+ return "", fmt.Errorf("resolve home directory: %w", err)
+ }
+
+ parent := filepath.Join(homeDir, defaultPluginVersionsDir)
+ entries, err := os.ReadDir(parent)
+ if err != nil {
+ return "", fmt.Errorf("read %q: %w", parent, err)
+ }
+
+ type candidate struct {
+ path string
+ modTime time.Time
+ name string
+ }
+
+ var candidates []candidate
+ for _, entry := range entries {
+ if !entry.IsDir() {
+ continue
+ }
+
+ path := filepath.Join(parent, entry.Name())
+ serverBin := filepath.Join(path, defaultServerRelativeBin)
+ if _, err := os.Stat(serverBin); err != nil {
+ continue
+ }
+
+ info, err := entry.Info()
+ if err != nil {
+ return "", fmt.Errorf("stat plugin candidate %q: %w", path, err)
+ }
+
+ candidates = append(candidates, candidate{
+ path: path,
+ modTime: info.ModTime(),
+ name: entry.Name(),
+ })
+ }
+
+ if len(candidates) == 0 {
+ return "", fmt.Errorf(
+ "no installed computer-use plugin found under %q; set %s or pass --plugin-root/--server-bin",
+ parent,
+ pluginRootEnvVar,
+ )
+ }
+
+ sort.Slice(candidates, func(i, j int) bool {
+ if candidates[i].modTime.Equal(candidates[j].modTime) {
+ return candidates[i].name > candidates[j].name
+ }
+ return candidates[i].modTime.After(candidates[j].modTime)
+ })
+
+ return candidates[0].path, nil
+}
+
+func readToolArgs(argsJSON, argsFile string) (map[string]any, error) {
+ if argsFile != "" {
+ data, err := os.ReadFile(argsFile)
+ if err != nil {
+ return nil, fmt.Errorf("read args file %q: %w", argsFile, err)
+ }
+ argsJSON = string(data)
+ }
+
+ if strings.TrimSpace(argsJSON) == "" {
+ return nil, nil
+ }
+
+ decoder := json.NewDecoder(strings.NewReader(argsJSON))
+ decoder.UseNumber()
+
+ var value any
+ if err := decoder.Decode(&value); err != nil {
+ return nil, fmt.Errorf("decode tool args JSON: %w", err)
+ }
+ if decoder.More() {
+ return nil, fmt.Errorf("tool args JSON must contain exactly one object")
+ }
+
+ object, ok := value.(map[string]any)
+ if !ok {
+ return nil, fmt.Errorf("tool args must be a JSON object")
+ }
+ return object, nil
+}
+
+func writeJSON(w io.Writer, value any, pretty bool) error {
+ var (
+ data []byte
+ err error
+ )
+
+ if pretty {
+ data, err = json.MarshalIndent(value, "", " ")
+ } else {
+ data, err = json.Marshal(value)
+ }
+ if err != nil {
+ return fmt.Errorf("marshal JSON output: %w", err)
+ }
+
+ if _, err := fmt.Fprintln(w, string(data)); err != nil {
+ return fmt.Errorf("write output: %w", err)
+ }
+ return nil
+}
+
+func normalizePath(path string) (string, error) {
+ if path == "" {
+ return "", nil
+ }
+
+ if strings.HasPrefix(path, "~") {
+ homeDir, err := os.UserHomeDir()
+ if err != nil {
+ return "", fmt.Errorf("resolve home directory: %w", err)
+ }
+ switch path {
+ case "~":
+ path = homeDir
+ case "~/":
+ path = homeDir
+ default:
+ path = filepath.Join(homeDir, strings.TrimPrefix(path, "~/"))
+ }
+ }
+
+ absPath, err := filepath.Abs(path)
+ if err != nil {
+ return "", fmt.Errorf("resolve absolute path for %q: %w", path, err)
+ }
+ return absPath, nil
+}
+
+func firstNonEmpty(values ...string) string {
+ for _, value := range values {
+ if strings.TrimSpace(value) != "" {
+ return value
+ }
+ }
+ return ""
+}
+
+func printRootUsage(w io.Writer) {
+ fmt.Fprintf(w, `%s talks to local computer-use tooling either directly over stdio MCP or via Codex app-server proxy mode.
+
+Usage:
+ %s resolve-server [flags]
+ %s list-tools [flags]
+ %s call [flags] <tool-name>
+
+Examples:
+ %s resolve-server
+ %s list-tools
+ %s call list_apps
+ %s call list_apps --transport app-server
+ %s call list_apps --transport direct --server-bin /path/to/open-computer-use
+ %s call get_app_state --args '{"app":"Feishu"}'
+
+Environment:
+ %s Override the installed plugin root.
+ %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, pluginRootEnvVar, serverBinEnvVar, appServerBinEnvVar)
+}
diff --git a/scripts/computer-use-cli/main_test.go b/scripts/computer-use-cli/main_test.go
new file mode 100644
index 0000000..0c61cfc
--- /dev/null
+++ b/scripts/computer-use-cli/main_test.go
@@ -0,0 +1,141 @@
+package main
+
+import (
+ "encoding/json"
+ "os"
+ "path/filepath"
+ "testing"
+ "time"
+)
+
+func TestReadToolArgsAcceptsJSONObject(t *testing.T) {
+ t.Parallel()
+
+ args, err := readToolArgs(`{"app":"Feishu","clicks":2}`, "")
+ if err != nil {
+ t.Fatalf("readToolArgs returned error: %v", err)
+ }
+
+ if got, want := args["app"], "Feishu"; got != want {
+ t.Fatalf("app = %#v, want %#v", got, want)
+ }
+
+ number, ok := args["clicks"].(json.Number)
+ if !ok {
+ t.Fatalf("clicks type = %T, want json.Number", args["clicks"])
+ }
+ if got, want := number.String(), "2"; got != want {
+ t.Fatalf("clicks = %q, want %q", got, want)
+ }
+}
+
+func TestReadToolArgsRejectsNonObject(t *testing.T) {
+ t.Parallel()
+
+ if _, err := readToolArgs(`["not","an","object"]`, ""); err == nil {
+ t.Fatal("readToolArgs should reject non-object JSON")
+ }
+}
+
+func TestDiscoverPluginRootChoosesNewestCandidate(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)
+ }
+
+ older := filepath.Join(parent, "1.0.0")
+ newer := filepath.Join(parent, "1.0.1")
+ createFakePluginRoot(t, older)
+ createFakePluginRoot(t, newer)
+
+ past := time.Now().Add(-time.Hour)
+ if err := os.Chtimes(older, past, past); err != nil {
+ t.Fatalf("chtimes older: %v", err)
+ }
+
+ root, err := discoverPluginRoot()
+ if err != nil {
+ t.Fatalf("discoverPluginRoot returned error: %v", err)
+ }
+ if got, want := root, newer; got != want {
+ t.Fatalf("discoverPluginRoot = %q, want %q", got, want)
+ }
+}
+
+func TestResolveTransportDefaultsToAppServer(t *testing.T) {
+ t.Parallel()
+
+ transport, err := resolveTransport(commonFlags{})
+ if err != nil {
+ t.Fatalf("resolveTransport returned error: %v", err)
+ }
+ if got, want := transport, transportAppServer; got != want {
+ t.Fatalf("transport = %q, want %q", got, want)
+ }
+}
+
+func TestResolveTransportUsesAppServerForBundledSkyBinary(t *testing.T) {
+ t.Parallel()
+
+ root := t.TempDir()
+ createFakePluginRoot(t, root)
+
+ transport, err := resolveTransport(commonFlags{pluginRoot: root})
+ if err != nil {
+ t.Fatalf("resolveTransport returned error: %v", err)
+ }
+ if got, want := transport, transportAppServer; got != want {
+ t.Fatalf("transport = %q, want %q", got, want)
+ }
+}
+
+func TestResolveTransportUsesDirectForExplicitNonSkyBinary(t *testing.T) {
+ t.Parallel()
+
+ root := t.TempDir()
+ serverBin := filepath.Join(root, "open-computer-use.sh")
+ if err := os.WriteFile(serverBin, []byte("#!/bin/sh\n"), 0o755); err != nil {
+ t.Fatalf("write server bin: %v", err)
+ }
+
+ transport, err := resolveTransport(commonFlags{serverBin: serverBin})
+ if err != nil {
+ t.Fatalf("resolveTransport returned error: %v", err)
+ }
+ if got, want := transport, transportDirect; got != want {
+ t.Fatalf("transport = %q, want %q", got, want)
+ }
+}
+
+func TestResolveAppServerBinaryPrefersExplicitPath(t *testing.T) {
+ t.Parallel()
+
+ root := t.TempDir()
+ appServerBin := filepath.Join(root, "codex")
+ if err := os.WriteFile(appServerBin, []byte("#!/bin/sh\n"), 0o755); err != nil {
+ t.Fatalf("write app-server bin: %v", err)
+ }
+
+ resolved, err := resolveAppServerBinary(commonFlags{appServerBin: appServerBin})
+ if err != nil {
+ t.Fatalf("resolveAppServerBinary returned error: %v", err)
+ }
+ if got, want := resolved, appServerBin; got != want {
+ t.Fatalf("resolved binary = %q, want %q", got, want)
+ }
+}
+
+func createFakePluginRoot(t *testing.T, root string) {
+ t.Helper()
+
+ serverBin := filepath.Join(root, defaultServerRelativeBin)
+ if err := os.MkdirAll(filepath.Dir(serverBin), 0o755); err != nil {
+ t.Fatalf("mkdir plugin root: %v", err)
+ }
+ if err := os.WriteFile(serverBin, []byte("stub"), 0o755); err != nil {
+ t.Fatalf("write fake server bin: %v", err)
+ }
+}