Skip to content

Commit 9ba5ead

Browse files
TennyZhuangFerrymanclaude
authored
feat(runtime): installPlan() and install() run the vendor's own installer, judged by the probe (#275)
Closes #268. Adds the install members decided in #268, so a host can set up a machine from nothing (install, sign in, use): ```ts readonly installPlan?: InstallPlanner; // (options?: InstallOptions) => Promise<InstallPlan>; read only readonly install?: Installer; // (options?: InstallOptions) => Promise<InstallResult>; oar never calls it on its own readonly installLines?: readonly InstallLine[]; // { line, description }[]; only on a runtime with parallel release lines (opencode) // InstallOptions { timeoutMs?: number; line?: string } ``` - **`installPlan()`** returns `{ kind: "plan", steps: [{ command, display }], source, network: true, privileges: false }`, or the same `unsupported` that `install` would return. It looks up the installer's tools on PATH and checks that the directories it writes are writable. It runs, downloads and writes nothing. - **`install()`** probes first. If the probe finds an available installation, the result is `already_installed` and nothing runs. Otherwise it runs the plan's steps with stdin closed and no terminal (own session and process group), under `timeoutMs` (default 10 minutes; the timeout stops everything the installer started), in the host environment minus package-script markers, never with sudo. Afterwards it probes again with the runtime's own `installation()`, the discovery sessions use. The result is `installed { installation, line?, output }` only when that probe finds an available installation; otherwise it is `failed { exitCode, output }`. The exit code never decides. - **`unsupported { reason, detail? }`**: `platform` | `requires_privileges` | `requires_gui` | `missing_tool` | `bundled` | `line_required` | `unknown_line`. ### Why each method Each runtime uses its vendor's documented per-user script, chosen because the runtime's own updater recognizes the copy it makes. The source is cited in the adapter and on the runtime page. | Runtime | install runs (macOS, Linux) | Source | Why: what the updater says about the copy (sandbox) | | --- | --- | --- | --- | | claude | `curl -fsSL https://claude.ai/install.sh \| bash` | https://code.claude.com/docs/en/setup | native install that `claude update` updates: `installMethod: native`; `checkUpdate` reads `downloads.claude.ai/.../latest` | | codex | `curl -fsSL https://chatgpt.com/codex/install.sh \| CODEX_NON_INTERACTIVE=1 sh` | https://github.com/openai/codex#installing-and-running-codex-cli | `codex doctor` update action `standalone installer`, which `codex update` reruns | | grok | `curl -fsSL https://x.ai/cli/install.sh \| bash` | https://docs.x.ai/build/overview | `grok update --check --json` installer `internal` | | kimi | `curl -fsSL https://code.kimi.com/kimi-code/install.sh \| bash` | https://github.com/MoonshotAI/kimi-code#install | `kimi upgrade -y`: "Kimi Code is already up to date (v2.1.1)." (for an npm copy it prints the manual command instead) | | opencode `v1` | `curl -fsSL https://opencode.ai/install \| bash` | https://opencode.ai/docs/#install | `opencode upgrade`: "Using method: curl", stays on 1.x | | opencode `v2` | `curl -fsSL https://opencode.ai/v2/install \| bash` | https://opencode.ai/v2/docs/ | `opencode upgrade`: "Using method: curl", stays on 2.x | | antigravity | nothing: `requires_gui` (Google documents installing it from an editor's agent registry) | https://antigravity.google/docs/ide/extensions/zed | | | pi, cursor | no member (bundled) | | | On Windows, every script runtime answers `platform`, and `detail` gives the vendor's own Windows command. oar does not run an installer it has not verified there. ### opencode release lines OpenCode 1 (`opencode-ai` 1.x) and OpenCode 2 (`@opencode/cli` 2.x) install the same `~/.opencode/bin/opencode`. The v2 installer replaces a v1 binary (https://opencode.ai/v2/docs/migrate-v1), and the v1 script silently downgrades v2 (anomalyco/opencode#54084). - **No default line.** The runtime declares `installLines: [v1, v2]`, and the host passes `line`. Without one, the result is `line_required`. A line the runtime doesn't list, or any `line` passed to a single-line runtime, is `unknown_line`: refused, never ignored. - **No overwrites.** A copy of either line found by the probe is `already_installed` with its `line` (read from the version: `1.18.35` → `v1`, `opencode v2.0.26` → `v2`). The other line's script never runs over it. - **`upgrade()` is untouched.** oar has no opencode upgrade. - **Version parsing fix.** `releaseVersion()` now reads a `v`-prefixed version (`opencode v2.0.26`). It returned undefined before. ### Discovery fix The decision says an installer putting the binary where discovery doesn't look is a discovery bug. Two probes now look in more places: - claude also looks at the native launcher `~/.local/bin/claude` (`%USERPROFILE%\.local\bin\claude.exe` on Windows). - codex also looks at the standalone launcher: `$CODEX_INSTALL_DIR/codex`, or `~/.local/bin/codex`. Both installers add their folder to PATH only in shell profiles, which a running host never reads. In the sandbox runs (PATH `/usr/bin:/bin`), these paths are how the probe found both. ### npm prefix check No built-in method uses npm, because every vendor documents a per-user script first, so there is no npm prefix to check. Instead, `requires_privileges` comes from the directories the script writes, including the installers' own location variables. For example, `KIMI_INSTALL_DIR=/opt/kimi-code` returns `requires_privileges` before anything runs, rather than failing midway. ### Docs and tooling - Contract: `docs/spec/install.md`. - Evidence: `docs/runtimes/install.md`. - Also updated: each runtime page, both READMEs, `docs/design/capabilities.md` (`installLines` is listed as a declaration), and `docs/spec/update.md` (the "oar never runs an install script" principle now applies to `upgrade` only). - `oar list` shows `install`. - `experiments/runtime-install.ts [runtime[@line]...]` re-runs the sandbox checks and refuses to run outside a sandbox. ## Verification **Unit tests.** None of them touch the network. - `tests/install.test.ts` and `tests/install-runtimes.test.ts` use a fake installer with the real probe on its install path. They cover: - judgement: `installed` is judged by the probe; `already_installed` runs nothing; a copy of another line is `already_installed` with that line, and nothing runs; exit 0 with nothing found is `failed`; a non-zero exit with the runtime in place is `installed`. - running: an unsupported plan runs nothing; a prompting installer reads EOF; a timed-out installer is stopped along with its worker; package-script markers are scrubbed. - plan answers: `platform` (win32, freebsd, ia32), `missing_tool`, `requires_privileges` (including an install-location variable), and writability judged on the nearest existing parent directory. - per runtime: every method's documented line and source; `line_required` and `unknown_line`; opencode line detection; `install` and `installPlan` always come together, and only pi and cursor have neither; antigravity is `requires_gui`. - Discovery candidates for claude and codex: `tests/installation.test.ts`. - `releaseVersion()` with a `v` prefix: `tests/update-projections.test.ts`. **Repo checks.** Run on main 9edb34b; rebased onto v0.47.0 (fe4bac6, a version-only commit) and typechecked again. - `pnpm run build`, typecheck and lint: green. - Tests: 1275 passed. Each full run on this shared, heavily loaded box (load average 55–127) failed 1–3 timing tests, and a different set each time: ACP request deadlines, `session-dispose` grace periods, `executable-probe-pipes`. All of them pass when run alone, and none touches install code. - Sea trial: mock, 19/19. **Live, Linux arm64 only** (Debian 13, Node 24.18.1), 2026-10-09. Each runtime and each opencode line ran in its own bubblewrap sandbox: fresh empty writable `HOME`, rest of the system read only, PATH `/usr/bin:/bin`, no terminal, stdin closed. | Runtime | Result | Installed version | Time | | --- | --- | --- | --- | | claude | `installed` | 2.1.295 | 31–44 s | | codex | `installed` | 0.162.0 | 20–28 s | | grok | `installed` | 1.0.50 | 10–12 s | | kimi | `installed` | 2.1.1 | 32–46 s | | opencode `v1` | `installed` | 1.18.35 | 10–13 s | | opencode `v2` | `installed` | 2.0.26 | 15 s | | opencode, no line | `line_required` | (nothing ran) | | | antigravity | `requires_gui` | (nothing ran) | | For every installed runtime: - The probe found it off PATH. - `checkUpdate` was ok and current, wherever oar has a check. - The second `install()` was `already_installed`. For opencode, the second call asked for the other line and found the first line, unreplaced. Answers from the environment, with nothing installed: - No network: claude `failed` with `exitCode: 0` and `curl: (6) Could not resolve host`. This is why the exit code cannot decide. - `KIMI_INSTALL_DIR=/opt/kimi-code`: `requires_privileges`. - PATH without curl: `missing_tool curl`. **Not verified:** - macOS and Linux x64: the same scripts run there, through their own platform branches. - The maintainers' exe.dev VMs. - Windows: there is no install path by design. - `upgrade()` of an installed copy: every install was already the latest release, so the updater's recognition above is its own report. - Sessions on opencode 2.0.26: this PR verifies only install. ## Open question oar picks no opencode line, as asked. A host that wants a single Install button still has to show the choice. If that turns out to be friction, `installLines` could carry the vendor's own recommendation as data, without oar choosing. Not added here. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Ferryman <[email protected]> Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent 75afa0f commit 9ba5ead

43 files changed

Lines changed: 1497 additions & 45 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -201,6 +201,11 @@ for (const runtime of defaultRuntimes.list()) {
201201
- **Installation:** `installation()` finds the runtime on this machine and
202202
reports its version, with no account or network calls. When PATH found
203203
it, `shadowed` lists the other copies on PATH after it, which never run.
204+
- **Install:** `installPlan()` says what installing a runtime would run (the
205+
vendor's documented installer, with its source page) or why nothing would
206+
run, and `install()` runs it for a runtime not found, judged by
207+
`installation()` afterwards (claude, codex, grok, kimi, and opencode's
208+
`v1` or `v2` line as the host chooses; [reference](docs/spec/install.md)).
204209
- **Login:** `login()` signs a runtime in through its own login without a
205210
terminal: it relays the sign-in URL or device code, and a code the person
206211
pastes back goes to the runtime only. `authStatus()` says whether it is

‎docs/design/capabilities.md‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,10 @@ tools, each used only where the one before does not fit.
1717

1818
When a runtime either can or cannot do a whole thing, the thing is an
1919
optional member and its presence is the capability. `Runtime.accountUsage`,
20-
`listModels`, `checkUpdate`, `upgrade`, `login`, `logout` and `authStatus`
21-
already work this way (antigravity, whose terms rule out a sign-in through
22-
OAR, has no `login`, and only the runtimes OAR signs in have a `logout`);
20+
`listModels`, `installPlan`, `install`, `checkUpdate`, `upgrade`, `login`,
21+
`logout` and `authStatus` already work this way (antigravity, whose terms
22+
rule out a sign-in through OAR, has no `login`, only the runtimes OAR signs
23+
in have a `logout`, and bundled pi and cursor have no `install`);
2324
`Session` `steer`, `withdraw` and `resources` do too: a session that cannot
2425
steer has no `steer`, one whose queue OAR does not hold (codex) has no
2526
`withdraw`, and one whose runtime runs in the host process (pi, cursor) has
@@ -56,6 +57,10 @@ front:
5657

5758
- `Runtime.refusedSessionOptions`: the options a runtime refuses at open,
5859
each with its reason.
60+
- `Runtime.installLines`: the parallel release lines a runtime installs
61+
(opencode `v1`, `v2`), so a host offers the choice OAR does not make
62+
before it plans an install; `install` answers `line_required` from the
63+
same list.
5964
- `Session.capabilities`: per-session facts that are not operations
6065
(`images`, the `attribution` tier, whether held input is `durable`), some
6166
known only after the runtime's handshake.

‎docs/runtimes/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ Cross-runtime investigations:
4040
- [Native skills, MCP and tool inventories](inventory.md) (local probes, 2026-09-16): what each runtime's own discovery calls return.
4141
- [Live model and effort changes](live-configure.md) (local probes, 2026-09-29): native setters that change a running session without a restart, and the adapter queues they meet.
4242
- [Runtime updaters](update.md) (sandbox probes, 2026-10-01): how each runtime updates itself and how its updater can claim success without upgrading.
43+
- [Runtime installers](install.md) (sandbox runs, 2026-10-09): what each vendor installer put where, whether the runtime's own updater recognizes the copy, and an install that exits 0 having installed nothing.
4344
- [Crash and resume](crash-resume.md) (live probes, 2026-10-02): what claude, codex and pi keep when the process tree dies mid tool call, and what they do by themselves on reopen.
4445

4546
Live-probe investigations of runtimes without an adapter live under

‎docs/runtimes/antigravity.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -398,7 +398,11 @@ checks `OAR_ANTIGRAVITY_BIN` and PATH `agy_acp_server.par`
398398
(`agy_acp_server.exe` on Windows), reading `Build label: <version>` from
399399
`--version` with a 30 second timeout. The ACP registry ships a zip with no
400400
installer, so there is no fallback path: put the binary on PATH or name it in
401-
`OAR_ANTIGRAVITY_BIN`. `checkUpdate` compares the installed version with that
401+
`OAR_ANTIGRAVITY_BIN`. Google documents installing the agent only from an
402+
editor's agent registry
403+
([Zed](https://antigravity.google/docs/ide/extensions/zed): External
404+
Agents, Install from Registry), so `installPlan` and `install` answer
405+
`unsupported` `requires_gui` ([runtime install](../spec/install.md)). `checkUpdate` compares the installed version with that
402406
registry entry, the only release listing (it can trail Google's downloads),
403407
and counts only a newer registry version as an update; the server has no
404408
updater, so there is no `upgrade` ([runtime updates](update.md)).

‎docs/runtimes/claude.md‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -552,8 +552,17 @@ provider request and further Claude output after the recorded exit in the
552552
(Claude 2.1.292). The host-exit hook runs the same tree cleanup synchronously;
553553
see the [lifetime limits](../spec/record-stream.md#the-rules).
554554

555-
Installation checks `OAR_CLAUDE_BIN`/PATH; update checks and upgrades are
556-
covered in [runtime updaters](update.md). Account usage is separate from
555+
Installation checks `OAR_CLAUDE_BIN`, PATH, then the native installer's
556+
launcher `~/.local/bin/claude` (`%USERPROFILE%\.local\bin\claude.exe` on
557+
Windows), which a GUI or service process's PATH can miss. When none is
558+
found, `install` runs Anthropic's native installer,
559+
`curl -fsSL https://claude.ai/install.sh | bash`
560+
([setup docs](https://code.claude.com/docs/en/setup); macOS and Linux;
561+
[runtime install](../spec/install.md), [sandbox run](install.md)). That
562+
method because its copy is the native install `claude update` updates:
563+
claude records `installMethod: native`, and `checkUpdate` reads the release
564+
pointer for it. Update checks and upgrades are covered in
565+
[runtime updaters](update.md). Account usage is separate from
557566
session context: the reader runs claude with `--safe-mode` (no user hooks or
558567
MCP servers; a CLI without the flag is `unsupported/unsupported_installation`,
559568
and a `--help` probe that times out rejects)
@@ -569,7 +578,8 @@ experimental (verified on 2.1.273); older versions can lack it. Login is
569578
mapped [below](#login).
570579
[Installation](../../packages/oar/src/runtimes/claude/installation.ts),
571580
[account usage](../../packages/oar/src/runtimes/claude/account-usage.ts),
572-
[updater](../../packages/oar/src/runtimes/claude/update.ts).
581+
[updater](../../packages/oar/src/runtimes/claude/update.ts),
582+
[installer](../../packages/oar/src/runtimes/claude/install.ts).
573583

574584
### Login
575585

‎docs/runtimes/codex.md‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -784,8 +784,19 @@ retry decision
784784

785785
Installation checks `OAR_CODEX_BIN`, then `codex` on PATH, then the macOS
786786
desktop bundles (`ChatGPT.app` before the legacy `Codex.app`, system before
787-
per-user installs), and requires `codex app-server --help` to succeed; a
788-
codex without the app-server surface is unsupported. Account usage is a
787+
per-user installs), then the standalone installer's launcher
788+
(`$CODEX_INSTALL_DIR/codex`, `~/.local/bin/codex`), and requires
789+
`codex app-server --help` to succeed; a codex without the app-server surface
790+
is unsupported. When none is found, `install` runs OpenAI's standalone
791+
installer, `curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_NON_INTERACTIVE=1 sh`
792+
([README](https://github.com/openai/codex#installing-and-running-codex-cli);
793+
`CODEX_NON_INTERACTIVE=1` is the switch install.sh's own usage text
794+
(`install.sh --help`) declares for skipping its prompts, not in the README;
795+
macOS and Linux; [runtime install](../spec/install.md),
796+
[sandbox run](install.md)). That method because `codex update` reruns the
797+
standalone installer for its copy: `codex doctor` reports the update action
798+
`standalone installer`, so `checkUpdate` and `upgrade` work on it, where a
799+
copied binary would be `manual or unknown`. Account usage is a
789800
separate reader on its own app-server process (`initialize`, `account/read`,
790801
`account/rateLimits/read`, with `reauth_required` / `unsupported` outcomes and
791802
rate-limit buckets merged as the codex TUI does); neither it nor installation
@@ -798,7 +809,8 @@ the probe deadline is unchanged, and an ordinary nonzero readiness exit still
798809
classifies the installation as unsupported.
799810
[Installation](../../packages/oar/src/runtimes/codex/installation.ts),
800811
[account usage](../../packages/oar/src/runtimes/codex/account-usage.ts),
801-
[update](../../packages/oar/src/runtimes/codex/update.ts).
812+
[update](../../packages/oar/src/runtimes/codex/update.ts),
813+
[install](../../packages/oar/src/runtimes/codex/install.ts).
802814

803815
### Login
804816

‎docs/runtimes/grok.md‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -631,15 +631,22 @@ See [host-exit cleanup and limits](../spec/record-stream.md#the-rules).
631631

632632
Installation checks `OAR_GROK_BIN`, PATH, and the official script/npm layouts
633633
(`$GROK_BIN_DIR`, `$GROK_HOME/bin`, `~/.grok/bin`), probing with
634-
`grok agent stdio --help`. [Account usage](../../packages/oar/src/runtimes/grok/account-usage.ts)
634+
`grok agent stdio --help`. When none is found, `install` runs xAI's script,
635+
`curl -fsSL https://x.ai/cli/install.sh | bash`
636+
([Grok Build docs](https://docs.x.ai/build/overview); macOS and Linux;
637+
[runtime install](../spec/install.md), [sandbox run](install.md)). That
638+
method because its copy is the one `grok update` updates: `grok update
639+
--check --json` reports installer `internal`, where an npm install would be
640+
a second copy. [Account usage](../../packages/oar/src/runtimes/grok/account-usage.ts)
635641
separately opens a connection and queries `_x.ai/billing` (plus
636642
`_x.ai/auth/info` for the email). No billing `config` is `unsupported`
637643
`quota_unavailable`; a config that carries none of `creditUsagePercent`,
638644
`used` and `monthlyLimit` reads as zero usage, as grok's own `/usage` shows it
639645
(1.0.46, an unused account; [account usage](../spec/account-usage.md),
640646
[test](../../tests/grok/grok-account-usage-reader.test.ts)). Account quota,
641647
prompt billing, and context occupancy are distinct APIs and measurements.
642-
[Installation](../../packages/oar/src/runtimes/grok/installation.ts).
648+
[Installation](../../packages/oar/src/runtimes/grok/installation.ts),
649+
[install](../../packages/oar/src/runtimes/grok/install.ts).
643650

644651
Grok updates itself by default. Launched from `~/.grok/bin`, as the script
645652
install puts it, `grok agent stdio` (OAR's own launch) checks for a release

‎docs/runtimes/install.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Runtime installers
2+
3+
Run on 2026-10-09 (Linux arm64, Debian 13, Node 24.18.1) through
4+
[`experiments/runtime-install.ts`](../../experiments/runtime-install.ts) in a
5+
bubblewrap sandbox: an empty writable `HOME`, the rest of the system read
6+
only, PATH `/usr/bin:/bin` (no runtime on it, and not the folders the
7+
installers use), `TMPDIR=/tmp`, no terminal and stdin closed, each runtime
8+
(and each opencode line) in its own fresh `HOME`. Each run is the public
9+
`installPlan()`, `install()`, `installation()`, `install()` again (for
10+
opencode, asking for the other line) and `checkUpdate()`, then the runtime's
11+
own updater asked how it sees the copy. Versions installed: claude 2.1.295,
12+
codex 0.162.0, grok 1.0.50, kimi 2.1.1, opencode 1.18.35 (`v1`) and 2.0.26
13+
(`v2`). The contract built on these facts is
14+
[runtime install](../spec/install.md).
15+
16+
**Not run:** macOS and Linux x64 (the same scripts, with their own platform
17+
branches), and Windows, where oar runs no installer (`platform`).
18+
19+
## Per runtime
20+
21+
| Runtime | Result | Probe found | The updater afterwards |
22+
| --- | --- | --- | --- |
23+
| claude | installed (31 to 44 s, three runs) | `~/.local/bin/claude`, `2.1.295 (Claude Code)`, off PATH | `checkUpdate` ok from `downloads.claude.ai/claude-code-releases/latest` (channel latest, current); `.claude.json` `installMethod: native` |
24+
| codex | installed (20 to 28 s, three runs) | `~/.local/bin/codex`, `codex-cli 0.162.0`, off PATH | `checkUpdate` ok from `codex doctor --json` (current); doctor's update action `standalone installer` |
25+
| grok | installed (10 to 12 s, three runs) | `~/.grok/bin/grok`, `grok 1.0.50` | `checkUpdate` ok, channel stable (current); `grok update --check --json` installer `internal` |
26+
| kimi | installed (32 to 46 s, four runs) | `~/.kimi-code/bin/kimi`, `2.1.1` | `checkUpdate` ok from `code.kimi.com/kimi-code/latest` (current); `kimi upgrade -y`: "Kimi Code is already up to date (v2.1.1)." |
27+
| opencode `v1` | installed, `line: "v1"` (10 to 13 s, four runs) | `~/.opencode/bin/opencode`, `1.18.35` | no `checkUpdate` in oar; `opencode upgrade`: "Using method: curl", "skipped: 1.18.35 is already installed" |
28+
| opencode `v2` | installed, `line: "v2"` (15 s; the script also twice by hand) | `~/.opencode/bin/opencode`, `opencode v2.0.26` | `opencode upgrade`: "Using method: curl", "OpenCode upgrade skipped: 2.0.26 is already installed" |
29+
| opencode, no line | `line_required` ("choose a release line: v1, v2"), plan the same, nothing ran | not_found | |
30+
| antigravity | unsupported `requires_gui`, plan the same, nothing ran | not_found | |
31+
32+
In every installed run the second `install()` was `already_installed` and
33+
ran nothing. For opencode it asked for the other line: after `v2`,
34+
`install({ line: "v1" })` was `already_installed` with `line: "v2"` and the
35+
binary still `opencode v2.0.26` (the 1 script would have replaced it,
36+
[anomalyco/opencode#54084](https://github.com/anomalyco/opencode/issues/54084));
37+
after `v1`, `v2` likewise found `v1`. Each installer's own progress came
38+
back verbatim as `output`.
39+
40+
## What each installer did besides the binary
41+
42+
- **claude** wrote `~/.local`, `~/.claude`, `~/.claude.json` and
43+
`~/.cache/claude`, and no shell profile: for the missing PATH entry it
44+
printed `echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc` instead
45+
of running it.
46+
- **codex** (with `CODEX_NON_INTERACTIVE=1`) added its PATH block to
47+
`~/.bashrc` and asked nothing.
48+
- **grok** added `~/.grok/bin` to PATH in `~/.bashrc`; with neither
49+
`~/.local/bin` nor `/usr/local/bin` on PATH, it linked nowhere else.
50+
- **kimi** added `~/.kimi-code/bin` to PATH in `~/.bashrc` and wrote
51+
`~/.kimi-code/region` (`mainland-cn`).
52+
- **opencode** (both lines) found no shell profile and created none: it
53+
printed the `export PATH` line. The `v2` script also writes an
54+
`opencode2` shim beside `opencode`.
55+
56+
## A failed install
57+
58+
With the network cut (`--unshare-net`), claude's `install()` was `failed`
59+
with `exitCode: 0` and `output` `curl: (6) Could not resolve host:
60+
claude.ai`: `curl | bash` exits with bash's status, and bash ran an empty
61+
script. Only the probe afterwards (not_found) tells this apart from success.
62+
63+
The sandbox needs `TMPDIR` to exist: kimi's installer stops at
64+
`mktemp: too few X's in template 'kimi-install'` when it does not.
65+
66+
## Answers without running anything
67+
68+
| Environment | Answer |
69+
| --- | --- |
70+
| `KIMI_INSTALL_DIR=/opt/kimi-code` (`/opt` root-owned) | kimi `unsupported` `requires_privileges`: "the installer writes /opt/kimi-code, and /opt is not writable by this user" (kimi's own docs pipe this case to `sudo`) |
71+
| PATH holding only `sh` and `bash` | claude `unsupported` `missing_tool` `curl` |

‎docs/runtimes/kimi.md‎

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -527,7 +527,22 @@ descendants ([test](../../tests/session-dispose.test.ts)). See
527527
checks `OAR_KIMI_BIN`, PATH `kimi`, `$KIMI_INSTALL_DIR/bin/kimi`,
528528
`~/.kimi-code/bin/kimi`, and the legacy `kimi-code` name, probing
529529
`kimi acp --help` with 30-second timeouts; it does not prove compatibility
530-
with Python kimi-cli.
530+
with Python kimi-cli. When none is found,
531+
[`install`](../../packages/oar/src/runtimes/kimi/install.ts) runs Moonshot's
532+
native installer, `curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash`
533+
([README](https://github.com/MoonshotAI/kimi-code#install); macOS and Linux;
534+
[runtime install](../spec/install.md), [sandbox run](install.md)). That
535+
method because its copy is the native one `kimi upgrade -y` updates (it
536+
answered "already up to date" for it, where an npm copy gets the manual
537+
command); the installer records region `mainland-cn`, so `checkUpdate`
538+
reads `code.kimi.com`.
539+
540+
The region marker (`~/.kimi-code/region`) only seeds the first login: once
541+
signed in, the login's own host decides. So a copy from this installer signs
542+
in to Moonshot's mainland China service by default. People outside mainland
543+
China sign in with `kimi login --region global` (OAR has no kimi login yet,
544+
see [runtime login](../spec/login.md)). The installer never overwrites an
545+
existing marker.
531546

532547
`checkUpdate` reads the release pointer kimi's own updater installs from, and
533548
`upgrade` runs `kimi upgrade -y`; a kimi older than 0.43.0 has no
@@ -588,7 +603,12 @@ controllers and in-flight work across OAR subprocesses, and any child usage
588603
(the transport carries none). [Session MCP servers](#session-mcp-servers)
589604
ran against a scripted provider only, not on the real login and model, and
590605
their vendor test runs locally (`OAR_TEST=kimi-aimock`), not in CI; whether
591-
a hidden same-name user server still starts is unmeasured. Keep native API
606+
a hidden same-name user server still starts is unmeasured. Install by
607+
region is open too: the install script's comments name a global mirror
608+
(`code.kimi.ai/kimi-code/install.sh`, which records region `global`), but
609+
Moonshot's README documents only `code.kimi.com`, so `install` runs that one.
610+
Choose the source by region once kimi documents the mirror, or once OAR has a
611+
kimi login that needs a regional install. Keep native API
592612
capabilities, transport
593613
limitations, OAR omissions, and unexecuted checks separate when designing or
594614
claiming support.

‎docs/runtimes/opencode.md‎

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -341,8 +341,26 @@ no terminal and no file access. It inherits the session's environment, so a
341341
crew child's environment reaches its tools. Installation is the `opencode`
342342
executable on PATH (npm `opencode-ai`, Homebrew, Scoop) or the install
343343
script's `~/.opencode/bin/opencode`, pinned with `OAR_OPENCODE_BIN`.
344-
`opencode upgrade` exists but OAR does not drive it yet, and there is no
345-
account usage query.
344+
345+
OpenCode ships two major lines of that one command: OpenCode 1 (npm
346+
`opencode-ai`, 1.x; `--version` prints `1.18.35`) and OpenCode 2 (npm
347+
`@opencode/cli`, 2.x; `opencode v2.0.26`). They do not install side by side:
348+
both scripts write `~/.opencode/bin/opencode`, the 2 installer replaces a 1
349+
binary ([migrating from 1](https://opencode.ai/v2/docs/migrate-v1)) and the 1
350+
script silently replaces a 2 binary
351+
([anomalyco/opencode#54084](https://github.com/anomalyco/opencode/issues/54084)).
352+
So the runtime declares `installLines` `v1` and `v2`, and
353+
[`install`](../../packages/oar/src/runtimes/opencode/install.ts) takes the
354+
host's `line` (none is `line_required`: OAR does not choose) and runs that
355+
line's script when nothing is found: `curl -fsSL https://opencode.ai/install | bash`
356+
([docs](https://opencode.ai/docs/#install)) or
357+
`curl -fsSL https://opencode.ai/v2/install | bash`
358+
([v2 docs](https://opencode.ai/v2/docs/)), macOS and Linux. A copy of either
359+
line already found is `already_installed` with its `line`, never replaced.
360+
Those scripts because each line's `opencode upgrade` takes its script install
361+
as the `curl` method and stays on the line ([runtime install](../spec/install.md),
362+
[sandbox run](install.md)). `opencode upgrade` exists but OAR does not drive
363+
it yet, and there is no account usage query.
346364

347365
### Session MCP servers
348366

0 commit comments

Comments
 (0)