Launch permission onboarding after npm install by kbdevs · Pull Request #10 · iFurySt/open-computer-use

kbdevs · 2026-04-22T23:41:36Z

Summary

auto-launch the bundled permission onboarding from npm postinstall during interactive local global installs instead of only printing next steps
keep CI and non-interactive installs quiet by gating the launch behind TTY/global-install checks and an opt-out env var
sync the generated package README, root README docs, and history so the install flow matches the shipped behavior

Notes

this uses the repo's existing permiso-style onboarding flow rather than adding a direct Permiso package dependency, which currently declares macOS 26 while open-computer-use still targets macOS 14+

Validation

make check-docs
swift test
node ./scripts/npm/build-packages.mjs --skip-build --out-dir tmp/npm-stage
CI=1 node ./tmp/npm-stage/open-computer-use/scripts/postinstall.mjs

Open the bundled onboarding helper during interactive global installs so users hit permissions immediately instead of only reading postinstall text. Document the new auto-launch flow in the repo and generated package README.

Copilot

Pull request overview

Updates the npm package install experience to automatically launch the bundled macOS permission onboarding during interactive global installs, and aligns documentation/history with the new flow.

Changes:

Auto-launch bundled permission onboarding from the generated npm postinstall script when appropriate (TTY + global + non-CI).
Update generated package README text and root READMEs (EN/ZH) to describe the automatic onboarding and manual fallback commands.
Add a history entry documenting the task and scope.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
scripts/npm/build-packages.mjs	Generates a postinstall script that best-effort launches the bundled app onboarding and updates install messaging/docs in the generated README.
docs/histories/2026-04/20260422-1636-launch-npm-postinstall-onboarding.md	Adds a history record describing the onboarding-on-install change.
README.zh-CN.md	Documents automatic onboarding launch for interactive global installs (Chinese).
README.md	Documents automatic onboarding launch for interactive global installs (English).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-22T23:45:37Z

+        OPEN_COMPUTER_USE_LAUNCHED_FROM_POSTINSTALL: "1",
+      },
+    });
+    child.on("error", () => {});


launchOnboardingIfPossible() returns true immediately after spawn(), even if the spawn fails asynchronously (e.g., EACCES/ENOENT -> error event). This can make launchedOnboarding true and print the “launched automatically” message when nothing was actually started. Consider returning false when child.pid is undefined and/or only setting launchedOnboarding once you have a successful spawn signal; alternatively, make the user-facing message not depend on a best-effort spawn result.

Suggested change

child.on("error", () => {});

child.on("error", () => {});

if (child.pid === undefined) {

return false;

}

Copilot · 2026-04-22T23:45:38Z

 npm i -g open-computer-use
 ```

+On interactive local global installs, npm also tries to open the bundled permiso-style permission onboarding automatically. If nothing appears, run `open-computer-use` or `open-computer-use doctor`.


This section describes the automatic postinstall onboarding but doesn’t mention the new opt-out env var (OPEN_COMPUTER_USE_SKIP_POSTINSTALL_ONBOARDING=1). Since this is user-facing behavior (auto-launching a GUI app), consider documenting the opt-out here (and/or in a dedicated “Environment variables” section) so users can disable it predictably.

Suggested change

On interactive local global installs, npm also tries to open the bundled permiso-style permission onboarding automatically. If nothing appears, run `open-computer-use` or `open-computer-use doctor`.

On interactive local global installs, npm also tries to open the bundled permiso-style permission onboarding automatically. To disable that behavior, set `OPEN_COMPUTER_USE_SKIP_POSTINSTALL_ONBOARDING=1` during install. If nothing appears, run `open-computer-use` or `open-computer-use doctor`.

Copilot · 2026-04-22T23:45:38Z

 npm i -g open-computer-use
 ```

+在本机交互式的全局安装场景下，npm 也会尝试自动拉起内置的 permiso 风格权限引导；如果没有弹出来，手动运行 `open-computer-use` 或 `open-computer-use doctor` 即可。


这里说明了 postinstall 会自动拉起权限引导，但没有提到新增的 opt-out 环境变量（OPEN_COMPUTER_USE_SKIP_POSTINSTALL_ONBOARDING=1）。因为这是用户可感知的行为（安装时自动启动 GUI），建议在这里顺带写明如何关闭，方便用户可预期地禁用。

上一轮 iFurySt#10/iFurySt#11/iFurySt#12 的结论建立在只有 1 步元素定向的轨迹上，我自己标注了 "样本太薄"。这一轮补足到 13 步 / 9 步元素定向（含完整对话框链路），结论全变，并暴露出两个真实缺陷。缺陷 1（已修）：render_visible_cells() 渲染的 cell RnCn 不带 Frame，而它们恰恰是屏幕上真实可见的——就是坐标寻址取到的当前视口内容。后果是任何"只保留可见节点" 的裁剪会把整个下拉/表格判成不可见并全部丢掉。实测中行距下拉的 cell R3C0 Double 就这样被三种策略同时丢弃，而它正是任务必须点中的元素。补上 Frame 后 H1 与 H1+H2 的保留率从 88% 回到 100%。缺陷 2（已定位未修）：render_visible_cells() 把角色硬编码成 cell，而 AT-SPI 的真实角色是 table cell。OSWorld 官方白名单有 table-cell 却没有 cell，于是这些行被判为无关角色丢掉——这是我们的渲染保真度问题，不是官方策略的弱点。最终实测（48063 token 基线）： H1 只保留可见 41% 保留 100% H3 丢结构容器 72% 保留 100% OSWorld 官方 21% 保留 88% H2 扁平列表 81% 保留 100% H1 + H2 37% 保留 100% <- 推荐另修评测器两处会高估自己的错误：把官方的 endswith 后缀匹配写成精确集合；解析器把无名两词角色 toggle button 拆成 role=toggle + name=button。两次方向都是误伤官方——用更严的规则去比对手等于给自己放水。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

hyprcat

Does it still apply after #107 and #108? Mostly yes:

The npm package still ships the app at dist/Open Computer Use.app/Contents/MacOS/OpenComputerUse (build-packages.mjs:22-23, :34 on main), so bundledAppBinary still resolves after the rename.
#108 only changed docs (OIDC trusted publishing) and doesn't affect lifecycle scripts.
The conflicts come from main rewriting renderPostinstall into a plain list of lines and the READMEs moving on, so a port would be mechanical.
The postinstall now runs on Linux and Windows too, so the darwin guard is needed; it's already there.

The blocker is the TTY gate. With default npm (7 and later), lifecycle scripts run with piped stdio unless --foreground-scripts is passed. So process.stdout.isTTY is false during a normal npm i -g, even in an interactive terminal, and the onboarding never opens. I checked this under a real pty with npm 11.17. The READMEs promise behaviour that, for nearly everyone, won't happen. For the same reason, npm hides the postinstall's own output, so the new "launched automatically" line isn't seen either.

I see two ways forward:

Drop the TTY gate and rely on darwin + global + not CI + the opt-out variable. That accepts a GUI window opening during non-interactive global installs.
Keep onboarding on the first open-computer-use / doctor run, which is what main does today, and close this PR.

How I checked

Tests. No Swift changes, so swift test on the head just reflects its April base: Executed 79 tests, with 0 failures. make check-docs passes.

Conflicts. git merge-tree --write-tree origin/main review/pr-10 gives CONFLICT (content) in README.md, README.zh-CN.md and scripts/npm/build-packages.mjs.

TTY probe. A throwaway package whose postinstall logs its environment, installed with npm install -g --prefix <scratch> under a pty (os.openpty). The pty itself checked out: test -t 1 was true inside it.

npm 11.17.0
default:              {"stdoutTTY":false,"stdinTTY":false,"npm_config_global":"true"}
--foreground-scripts: {"stdoutTTY":true,"stdinTTY":true,"npm_config_global":"true","foreground":"true"}

hyprcat · 2026-10-22T19:58:28Z

+    return false;
+  }
+
+  if (process.stdout.isTTY !== true) {


npm 7 and later run lifecycle scripts with piped stdio by default, so isTTY is false, this early return always fires, and shouldLaunchOnboarding() returns false. A probe postinstall saw stdoutTTY:false under npm install -g in a pty, and stdoutTTY:true only with --foreground-scripts.

hyprcat · 2026-10-22T19:58:29Z

+      stdio: "ignore",
+      env: {
+        ...process.env,
+        OPEN_COMPUTER_USE_LAUNCHED_FROM_POSTINSTALL: "1",


Nothing reads OPEN_COMPUTER_USE_LAUNCHED_FROM_POSTINSTALL. I found no other reference under apps/, packages/ or scripts/, on this head or on main. Drop it, or have the app use it.

hyprcat · 2026-10-22T19:58:29Z

+    });
+    child.on("error", () => {});
+    child.unref();
+    return true;


This is still open from Copilot's April review: it returns true right after spawn(), so an asynchronous error (ENOENT/EACCES) still prints "launched automatically".

hyprcat · 2026-10-22T19:58:29Z

 npm i -g open-computer-use
 ```

+On interactive local global installs, npm also tries to open the bundled permiso-style permission onboarding automatically. If nothing appears, run `open-computer-use` or `open-computer-use doctor`.


Also still open from Copilot: document OPEN_COMPUTER_USE_SKIP_POSTINSTALL_ONBOARDING=1 next to the behaviour it turns off. And if the TTY gate stays, "on interactive local global installs" describes a case that only happens with --foreground-scripts.

feat: launch onboarding after npm install

5d7fe19

Open the bundled onboarding helper during interactive global installs so users hit permissions immediately instead of only reading postinstall text. Document the new auto-launch flow in the repo and generated package README.

Copilot AI review requested due to automatic review settings April 22, 2026 23:41

Copilot started reviewing on behalf of kbdevs April 22, 2026 23:42

View session

Copilot AI reviewed Apr 22, 2026

View reviewed changes

vietairs referenced this pull request in vietairs/open-codex-computer-use Jul 20, 2026

docs(lock): record pre-merge review consolidation decision (#10)

cf5b510

hyprcat suggested changes Oct 22, 2026

View reviewed changes

Navigation Menu

Repository navigation

Launch permission onboarding after npm install - #10

Launch permission onboarding after npm install#10
kbdevs wants to merge 1 commit into
iFurySt:mainfrom
kbdevs:kb/postinstall-onboarding

kbdevs commented Apr 22, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 22, 2026

Uh oh!

Copilot AI Apr 22, 2026

Uh oh!

Copilot AI Apr 22, 2026

Uh oh!

hyprcat left a comment

Uh oh!

hyprcat Oct 22, 2026

Uh oh!

hyprcat Oct 22, 2026

Uh oh!

hyprcat Oct 22, 2026

Uh oh!

hyprcat Oct 22, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	On interactive local global installs, npm also tries to open the bundled permiso-style permission onboarding automatically. If nothing appears, run `open-computer-use` or `open-computer-use doctor`.
	On interactive local global installs, npm also tries to open the bundled permiso-style permission onboarding automatically. To disable that behavior, set `OPEN_COMPUTER_USE_SKIP_POSTINSTALL_ONBOARDING=1` during install. If nothing appears, run `open-computer-use` or `open-computer-use doctor`.

Conversation

kbdevs commented Apr 22, 2026

Summary

Notes

Validation

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

hyprcat left a comment

Choose a reason for hiding this comment

Uh oh!

hyprcat Oct 22, 2026

Choose a reason for hiding this comment

Uh oh!

hyprcat Oct 22, 2026

Choose a reason for hiding this comment

Uh oh!

hyprcat Oct 22, 2026

Choose a reason for hiding this comment

Uh oh!

hyprcat Oct 22, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants