Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion .github/workflows/build-native-android.yml
Original file line number Diff line number Diff line change
Expand Up @@ -115,12 +115,19 @@ jobs:
echo "LLVM_STRIP=$LLVM_STRIP" >> "$GITHUB_ENV"
mkdir -p work artifacts/transplant/opentui-bionic
{
# Zig 0.17.0 requires every libc field, including the new
# `cc_dir` and `darwin_sdk_dir`, and rejects an empty `cc_dir` for
# linux targets. `gcc_dir` is the 0.16 field name and a 0.17 alias
# for `cc_dir`, so emitting that spelling keeps one file valid on
# either toolchain. cc_dir holds crtbegin_so.o, which for the NDK
# is the same API-level lib dir as crt_dir.
echo "include_dir=$SYSROOT/usr/include/aarch64-linux-android"
echo "sys_include_dir=$SYSROOT/usr/include"
echo "crt_dir=$LIBDIR"
echo "msvc_lib_dir="
echo "kernel32_lib_dir="
echo "gcc_dir="
echo "gcc_dir=$LIBDIR"
echo "darwin_sdk_dir="
} > work/android-libc.txt
sh work/opentui/packages/native/scripts/prepare-zig-deps.sh
(
Expand Down
7 changes: 4 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,11 @@

## ACTIVE NATIVE V2 WORK (2026-10-31)

- Release candidate: OpenCode `2.2.5` on Android/Bionic Bun `1.4.4` with OpenTUI `0.8.0` (Zig `0.16.0`). Pins live in `tools/supply-chain-lock.json`; `tools/ocver.py` is the only reader, and `current` drives CI, publishing and `install.sh`.
- `2.2.5` release candidate builds and runs on-device (version, server, TUI); not yet published.
- Release candidate: OpenCode `2.2.6` on Android/Bionic Bun `1.4.4` with OpenTUI `0.8.1` (Zig `0.17.0`). Pins live in `tools/supply-chain-lock.json`; `tools/ocver.py` is the only reader, and `current` drives CI, publishing and `install.sh`.
- `2.2.5` is published and runs on-device (version, server, TUI). `2.2.6` is the current candidate and is not yet released.
- Publish only from a CI candidate artifact via `publish-native-android.yml` (it re-checks provenance and checksums); never upload a binary built on a device.
- Android bionic tags heap pointers in the top byte; OpenTUI's `toSafeNumberPointer()` rejects them, so `tools/patch-opentui-ffi.py` must run before `Bun.build` (`bytecode:true` makes binary-level JS edits dead).
- Android bionic tags heap pointers in the top byte; OpenTUI's `toSafeNumberPointer()` rejects them, so `tools/patch-opentui-ffi.py` passes the tagged BigInt straight to Bun's FFI (masking the tag makes Scudo abort at `free()` with "Pointer tag … was truncated"). It must run before `Bun.build` (`bytecode:true` makes binary-level JS edits dead); CI greps the built ELF for the `BigInt.asUintN` marker.
- Zig `0.17.0` needs every field in the `--libc` file (`cc_dir` is mandatory for linux/Android) and its `translate-c` also searches the host `/usr/include`, which bionic's `#include_next <limits.h>` then follows into glibc. `tools/patch-opentui-android.py` injects an empty `src/bionic-include-next/limits.h` to stop that inside the sysroot.
- Build guide: `docs/guides/native-v2-build.md`; transplant details: `docs/reference/transplant.md`. Release builds run in GitHub Actions for reproducibility. On-device local builds are allowed; Termux already is Bionic so no NDK. Needs Termux `python3`, `npm`, `clang`, `make` (`zig` only to rebuild OpenTUI) and network.
- History: native v2 `2.0.26`/`2.0.28` on Bun `1.4.0`/`1.4.2` were the previous user-facing line. The Bun 1.4.0 candidate from Actions run 38142306988 passed on-device TUI, API, session and real-prompt checks.
- Pin current native workflow actions to immutable commit SHAs, with the version in a comment. Use v6 where available.
Expand Down
62 changes: 62 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# Contributing

## Branching

The default branch is **`native-android`**. It is the only branch that ships, and it is what `origin/HEAD` points at. Open every pull request against it.

```
native-android <- default, release line, protected in practice
feat/<thing> <- your work
```

- Branch off `native-android`, keep the branch focused, and open the PR back into `native-android`.
- Prefix names with `feat/`, `fix/`, `docs/` or `chore/`. Longer-lived trains use `rc*/` or `archive/` as the existing branches do.
- Do not force-push `native-android`; rewrite your own branch instead.
- The `archive/`, `glibc`, `rc6-*` and `test-*` branches are historical. Leave them alone; do not base new work on them.

## What this project ships

One Android/aarch64 Bionic ELF for Termux. No PRoot, no glibc, no wrapper in the runtime path. The wrapper line exists as `opencode-wrapper` appendix packaging only, and it stays out of the mainline.

## Ground rules

- **aarch64 only.** Do not add a 32-bit (armv7/arm32) target or re-introduce its scripts; that track failed and was removed.
- **Pinned inputs.** Versions, commits and hashes live in [`tools/supply-chain-lock.json`](tools/supply-chain-lock.json), read through [`tools/ocver.py`](tools/ocver.py). Never hardcode a version in a script, workflow or installer — read it from the lock. A version bump means a new lock entry, not an edit to existing pins.
- **Do not edit generated output.** `artifacts/`, `packing/dpkg/work/`, `packing/pacman/pkg/` and versioned packages are build products.
- **Actions are pinned** to immutable commit SHAs with the version in a trailing comment. Use the v6 line where it exists.
- **Shell scripts** use `set -euo pipefail` and fail fast on missing binaries or files.

## Testing

```sh
make selfcheck # local consistency checks
```

The **Unit Tests** workflow runs the `bats` suite on every push and pull request. Release builds are not part of PR CI: they are dispatched by hand through `build-native-android.yml`, which compiles the pinned source, builds the Bionic OpenTUI library, verifies the FFI guard *before* stripping, and produces an unsigned candidate artifact.

A change to the build pipeline is not done until that workflow is green. A change to the runtime is not done until the candidate runs on a real device: `--version`, TUI, auth, one real prompt, clean exit.

## Releases

Releases are published from CI, never from a maintainer machine:

1. `build-native-android.yml` produces the candidate plus checksums.
2. The candidate is smoke-tested on a device.
3. `publish-native-android.yml` is dispatched with that run ID; it re-checks provenance and checksums, then publishes [`RELEASE_NOTES.md`](RELEASE_NOTES.md) verbatim.

Do not upload a locally built binary. Do not tag a release that has no verified CI artifact behind it.

## Documentation

Docs are grouped by purpose under [`docs/`](docs/):

| Folder | Contents |
|---|---|
| `guides/` | How to build, install, migrate, manage plugins |
| `reference/` | How the pipeline works, contracts, design notes |
| `ops/` | Runbooks and maintainer operations |
| `history/` | Superseded material, kept for archaeology |

When behaviour and docs disagree, fix the doc in the same change as the code. When you add or move a workflow-critical document, update the [`docs/README.md`](docs/README.md) index and the root [`AGENTS.md`](AGENTS.md) map.

Documents written in Chinese are kept as-is because their evidence trails are still cited.
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,9 @@ curl -fsSL https://github.com/Spectra010s/opencode-termux/raw/native-android/ins
opencode
```

The installer downloads the [GitHub release](https://github.com/Spectra010s/opencode-termux/releases) binary, checks its SHA-256 against the release checksum file, and installs it as `~/.local/bin/opencode`. If `~/.local/bin` is not on `PATH`, it prints the direct command and the exact PATH line to add; it does not silently edit your shell startup files.
The installer downloads the [GitHub release](https://github.com/Spectra010s/opencode-termux/releases) binary, checks its SHA-256 against the release checksum file, and installs it as `~/.local/bin/opencode`, keeping your chats, sign-ins, and configuration. If `~/.local/bin` is not on `PATH`, it prints the direct command and the exact PATH line to add; it does not silently edit your shell startup files.

Once installed this way, `opencode upgrade`, its `opencode update` alias, and the TUI's `/update` use this repository's latest published release and verified installer. To update an APT installation, use `apt update && apt install --only-upgrade opencode`.
Already on an earlier build? Run `opencode upgrade`; its `opencode update` alias and the TUI's `/update` do the same. They point at this repository's verified installer. To update an APT installation, use `apt update && apt install --only-upgrade opencode`.

OpenCode is also available from this project's APT source. Follow the
[APT setup and install instructions](docs/guides/apt-repository.md).
Expand Down
46 changes: 12 additions & 34 deletions RELEASE_NOTES.md
Original file line number Diff line number Diff line change
@@ -1,39 +1,17 @@
# OpenCode 2.2.5 for Termux
## What changed upstream (2.2.5 → 2.2.6)

OpenCode v2 as a native Android/aarch64 Bionic binary for Termux: no PRoot, no glibc. This release moves the Android build from 2.0.28 to 2.2.5, and fixes the reason the previous 2.2.x candidates died before drawing a single frame.
- **Shared MCP connections**: `pool: true` on an MCP server shares one connection across projects with the same setup, so you run fewer processes and start faster.
- **Scripted runs in worktrees**: `opencode run -w` (or `--worktree=<name>`) starts the session in a new git worktree, and `--archived` keeps CI and scripted sessions out of the inbox, home, and session lists.
- **Session warming**: provider- and model-specific warming settings, including an `interval: "auto"` mode based on cache TTL.
- **`opencode run` waits for its background work**: background shells, subagents, and image jobs finish first (it prints `waiting for N background job(s)`) and the model answers their results before the run exits. There is no time limit, so set a timeout on CI jobs.
- **TUI fixes**: Ctrl+Z suspends while a form or dialog is open, session titles containing newlines no longer crash the TUI, focus stays on an open dialog when a question arrives, and **Scroll on send** keeps your reading position after you submit a prompt.
- **Security**: file reads and media are served as sandboxed downloads, `/api/*` refuses cross-site navigations and requests from disallowed origins, and webfetch/Code Mode URLs that contain credentials are rejected.
- **Also**: MCP servers that are still connecting get up to 2 seconds before a model call, OpenCode Console config requests time out after 5 seconds instead of hanging startup, and `opencode acp` no longer leaves empty IDE sessions behind.

## Install

```sh
curl -fsSL https://github.com/Spectra010s/opencode-termux/raw/v2.2.5/install.sh | sh
```

Then run `opencode`. The installer checks the compressed download and the executable against the release checksums before replacing `~/.local/bin/opencode`, and keeps your chats, sign-ins, and configuration.

Already on 2.0.28? Run `opencode upgrade`. It points at this verified installer.

Requires Android 9 (API 28) or newer, aarch64, and about 700 MiB free.

## What changed upstream (2.2.0 → 2.2.5)

- **`/goal`**: keep a session working toward an objective until a reviewer confirms it is met (`/goal pause`, `/goal resume`, `/goal clear`).
- **Image generation**: agents can create or edit images through `experimental_image_generate`, enabled automatically when a connected provider has image models.
- **Claude Agent**: sign in with Claude Code (`claude auth login`) and select it in `/connect` to use those models.
- **OpenTUI 0.8**: TUI plugins now require `@opentui/core` and `@opentui/solid` 0.8 or newer; scroll and render-context APIs changed accordingly.
- **Compaction buffer as a percentage**: `"compaction": { "buffer": "20%" }` keeps part of any model's context window free.
- **Fixes**: MCP servers sending messages over 10 MiB no longer get disconnected, calls to a tool named `bash` run as `shell` instead of failing, and `read`/`edit` errors now point at the missing folder or the closest matching lines.

Desktop-only changes in these versions (persistent desktop terminals, artifacts, the desktop model picker) do not apply to this Termux build.
Desktop-only changes in 2.2.6 (mobile composer dock, GUI plugin themes and slots, tab menu actions) do not apply to this Termux build.

## What changed in this Android build

- Built from pinned OpenCode source with Bun 1.4.4 and OpenTUI 0.8.0 (Zig 0.16.0); versions, hashes, and commits live in [`tools/supply-chain-lock.json`](https://github.com/Spectra010s/opencode-termux/blob/native-android/tools/supply-chain-lock.json).
- The candidate now compiles directly against the pinned Android Bun base and grafts the bionic OpenTUI library onto it. Re-running the old post-compile transplant on a 1.4.4 base produced a binary that died with SIGILL on the first instruction.
- **TUI fix**: Android bionic tags heap pointers in the top byte, and OpenTUI's FFI shim rejected those as unsafe (`Pointer exceeds safe integer range`) before the first frame. The build now masks that tag before the check, so the renderer starts normally.
- `opencode upgrade` still points at this verified installer instead of an incompatible upstream download. `opencode uninstall --dry-run` previews removal; `opencode uninstall` removes the binary and shared cache but keeps user data.

## Verified build

The candidate came from [Actions run 41906034445](https://github.com/Spectra010s/opencode-termux/actions/runs/41906034445), built and checked by CI, with `sha256 24e9600d80752a31c052135a75677495fcb0ee694580216aa9dc37a89a75d657`. It was tested: `--version` passed, providers and models listed through the server, and the TUI started. Wider device testing is welcome; report problems at [issues](https://github.com/Spectra010s/opencode-termux/issues).

Checksums and build inputs are attached to this release. The [source-build guide](https://github.com/Spectra010s/opencode-termux/blob/native-android/docs/guides/native-v2-build.md) shows how to reproduce the build.
- Built from pinned OpenCode source with Bun 1.4.4 and OpenTUI 0.8.1 (Zig 0.17.0); versions, hashes, and commits live in [`tools/supply-chain-lock.json`](https://github.com/Spectra010s/opencode-termux/blob/native-android/tools/supply-chain-lock.json).
- **Quiet shutdown**: 2.2.5 cleared the ARM top-byte tag that bionic puts on heap pointers so the renderer would start, but Scudo re-checks that tag when the memory is freed, so quitting printed a pointer-tag message. Pointers are now handed to Bun's FFI unchanged (Bun 1.4 keeps all 64 bits for `ptr` arguments), so nothing is truncated and shutdown prints nothing. Untagged platforms and small allocations still take the plain-number path upstream uses.
- **OpenTUI 0.8.1 build**: Zig 0.17.0 requires every field in the `--libc` file and its `translate-c` also searches the host include directories. The build now writes the full schema and shadows bionic `limits.h` inside the sysroot, so the Android OpenTUI library builds the same way in CI and on a Termux device.
12 changes: 6 additions & 6 deletions docs/guides/native-v2-build.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,14 +19,14 @@ tag so a tagged copy cannot silently install a later release.
`tools/ocver.py` is the only reader. Use it instead of hardcoding:

```sh
python3 tools/ocver.py current # 2.2.5
python3 tools/ocver.py tag # v2.2.5
python3 tools/ocver.py current # 2.2.6
python3 tools/ocver.py tag # v2.2.6
python3 tools/ocver.py field bun_version # 1.4.4
python3 tools/ocver.py asset source # opencode-2.2.5-android-aarch64-source
python3 tools/ocver.py asset source # opencode-2.2.6-android-aarch64-source
```

Current release record: OpenCode `2.2.5` (commit `9bbb8ce1…`) on Bun `1.4.4`,
OpenTUI `0.8.0` (commit `738067f4…`), Zig `0.16.0`, `ANDROID_API=28`. Bun `1.4.4`
Current release record: OpenCode `2.2.6` (commit `dc2ffcf8…`) on Bun `1.4.4`,
OpenTUI `0.8.1` (commit `9a09079c…`), Zig `0.17.0`, `ANDROID_API=28`. Bun `1.4.4`
is the only supported host and base — upstream `package.json` declares
`packageManager: bun@1.4.4`, and there is no 1.4.2 fallback.

Expand Down Expand Up @@ -82,7 +82,7 @@ explicit gap, never a silent skip.

## Why the transplant tools remain

For 2.2.5, CI compiles directly against the Android Bun ELF and uses only
For 2.2.x, CI compiles directly against the Android Bun ELF and uses only
`swap_tui.py` from the transplant tools. The older `transplant.py all` path
remains for supported transplant builds; running it on this already compiled
1.4.4 ELF produced a binary that failed on device.
2 changes: 1 addition & 1 deletion install.sh
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
set -eu

repo=Spectra010s/opencode-termux
release_tag=v2.2.5
release_tag=v2.2.6
if [ "$#" -gt 0 ]; then
[ "$#" -eq 2 ] && [ "$1" = --version ] || { echo 'Usage: install.sh [--version X.Y.Z]' >&2; exit 2; }
case "$2" in
Expand Down
19 changes: 11 additions & 8 deletions scripts/ci/build-opencode-source.sh
Original file line number Diff line number Diff line change
Expand Up @@ -68,11 +68,13 @@ OPENCODE_BUN_VERSION="$BUN_VERSION" python3 tools/patch-opencode-source.py "$src

cd "$src"
"$host_bun" install --frozen-lockfile --ignore-scripts --os=linux --cpu='*'
# bionic tags heap pointers in the top byte; OpenTUI 0.8.0's FFI shim treats
# bionic tags heap pointers in the top byte; OpenTUI's FFI shim treats
# them as "Pointer exceeds safe integer range" and the TUI refuses to start.
# Patch the installed shim before Bun builds, because build.ts sets
# bytecode:true -- editing the JS inside the compiled ELF afterwards does
# nothing.
# The tag must survive to native free() as well -- Scudo aborts with
# "Pointer tag ... was truncated" when it does not -- so the shim hands the
# tagged BigInt to Bun's FFI instead of masking it. Patch the installed shim
# before Bun builds, because build.ts sets bytecode:true -- editing the JS
# inside the compiled ELF afterwards does nothing.
python3 "$ROOT/tools/patch-opentui-ffi.py" "$src"
cd "$src/packages/cli"
# Upstream 2.2.x selects the compile target from OPENCODE_TARGET (env), not
Expand All @@ -88,10 +90,11 @@ BUN_SOURCE_TARGET_ELF="$target_bun" \
compiled="$src/packages/cli/dist/cli-linux-arm64/bin/opencode"
test -s "$compiled"
# source maps keep the bundled JS readable in the ELF, so this proves the
# pointer mask survived into the build (bytecode:true makes it unpatched at
# runtime otherwise).
grep -aq '0x00ffffffffffffffn' "$compiled" || {
echo "opentui top-byte pointer mask missing from the compiled ELF" >&2
# tagged-pointer passthrough survived into the build (bytecode:true makes it
# unpatched at runtime otherwise). The marker is the u64 clamp the patched
# shim returns: minification drops comments but never a global property access.
grep -aq 'BigInt.asUintN' "$compiled" || {
echo "opentui tagged-pointer passthrough missing from the compiled ELF" >&2
exit 1
}
cd "$ROOT"
Expand Down
Loading
Loading