Repository navigation
Commit 9ba5ead
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
File tree
- docs
- design
- runtimes
- spec
- experiments
- packages
- cli/src
- oar
- src
- contracts
- runtimes
- antigravity
- claude
- codex
- grok
- kimi
- opencode
- tests
- fixtures
Some content is hidden
Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
201 | 201 | | |
202 | 202 | | |
203 | 203 | | |
| 204 | + | |
| 205 | + | |
| 206 | + | |
| 207 | + | |
| 208 | + | |
204 | 209 | | |
205 | 210 | | |
206 | 211 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
17 | 17 | | |
18 | 18 | | |
19 | 19 | | |
20 | | - | |
21 | | - | |
22 | | - | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
23 | 24 | | |
24 | 25 | | |
25 | 26 | | |
| |||
56 | 57 | | |
57 | 58 | | |
58 | 59 | | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
59 | 64 | | |
60 | 65 | | |
61 | 66 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
40 | 40 | | |
41 | 41 | | |
42 | 42 | | |
| 43 | + | |
43 | 44 | | |
44 | 45 | | |
45 | 46 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
398 | 398 | | |
399 | 399 | | |
400 | 400 | | |
401 | | - | |
| 401 | + | |
| 402 | + | |
| 403 | + | |
| 404 | + | |
| 405 | + | |
402 | 406 | | |
403 | 407 | | |
404 | 408 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
552 | 552 | | |
553 | 553 | | |
554 | 554 | | |
555 | | - | |
556 | | - | |
| 555 | + | |
| 556 | + | |
| 557 | + | |
| 558 | + | |
| 559 | + | |
| 560 | + | |
| 561 | + | |
| 562 | + | |
| 563 | + | |
| 564 | + | |
| 565 | + | |
557 | 566 | | |
558 | 567 | | |
559 | 568 | | |
| |||
569 | 578 | | |
570 | 579 | | |
571 | 580 | | |
572 | | - | |
| 581 | + | |
| 582 | + | |
573 | 583 | | |
574 | 584 | | |
575 | 585 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
784 | 784 | | |
785 | 785 | | |
786 | 786 | | |
787 | | - | |
788 | | - | |
| 787 | + | |
| 788 | + | |
| 789 | + | |
| 790 | + | |
| 791 | + | |
| 792 | + | |
| 793 | + | |
| 794 | + | |
| 795 | + | |
| 796 | + | |
| 797 | + | |
| 798 | + | |
| 799 | + | |
789 | 800 | | |
790 | 801 | | |
791 | 802 | | |
| |||
798 | 809 | | |
799 | 810 | | |
800 | 811 | | |
801 | | - | |
| 812 | + | |
| 813 | + | |
802 | 814 | | |
803 | 815 | | |
804 | 816 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
631 | 631 | | |
632 | 632 | | |
633 | 633 | | |
634 | | - | |
| 634 | + | |
| 635 | + | |
| 636 | + | |
| 637 | + | |
| 638 | + | |
| 639 | + | |
| 640 | + | |
635 | 641 | | |
636 | 642 | | |
637 | 643 | | |
638 | 644 | | |
639 | 645 | | |
640 | 646 | | |
641 | 647 | | |
642 | | - | |
| 648 | + | |
| 649 | + | |
643 | 650 | | |
644 | 651 | | |
645 | 652 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
527 | 527 | | |
528 | 528 | | |
529 | 529 | | |
530 | | - | |
| 530 | + | |
| 531 | + | |
| 532 | + | |
| 533 | + | |
| 534 | + | |
| 535 | + | |
| 536 | + | |
| 537 | + | |
| 538 | + | |
| 539 | + | |
| 540 | + | |
| 541 | + | |
| 542 | + | |
| 543 | + | |
| 544 | + | |
| 545 | + | |
531 | 546 | | |
532 | 547 | | |
533 | 548 | | |
| |||
588 | 603 | | |
589 | 604 | | |
590 | 605 | | |
591 | | - | |
| 606 | + | |
| 607 | + | |
| 608 | + | |
| 609 | + | |
| 610 | + | |
| 611 | + | |
592 | 612 | | |
593 | 613 | | |
594 | 614 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
341 | 341 | | |
342 | 342 | | |
343 | 343 | | |
344 | | - | |
345 | | - | |
| 344 | + | |
| 345 | + | |
| 346 | + | |
| 347 | + | |
| 348 | + | |
| 349 | + | |
| 350 | + | |
| 351 | + | |
| 352 | + | |
| 353 | + | |
| 354 | + | |
| 355 | + | |
| 356 | + | |
| 357 | + | |
| 358 | + | |
| 359 | + | |
| 360 | + | |
| 361 | + | |
| 362 | + | |
| 363 | + | |
346 | 364 | | |
347 | 365 | | |
348 | 366 | | |
| |||
0 commit comments