chore: add Amp orb setup script

RM
16d ago
+43-0

What

Adds .agents/setup, the script Amp runs on a fresh orb before it saves the snapshot (docs). It's an executable bash script with set -euo pipefail that runs from the repo root. It's idempotent: on a re-run, anything already installed is skipped. It installs only what this repo's CI and manifests need, and ends with a dependency fetch or prebuild, not a test run, so it stays well under the 20-minute setup limit.

What it installs

  • apt: build-essential, cmake (Debian 12: 3.25), shellcheck
  • CPU-only configure: cmake -S kernels -B build/kernels-cpu -DBKL_ENABLE_CUDA=OFF

Pins and notes

  • Pins: cmake_minimum_required(3.24) (Debian 12 has 3.25.1); CPU path -DBKL_ENABLE_CUDA=OFF and the python3 tools/check_*.py / test_*.py checks from ci-cpu.yml use only the orb's system python3.
  • GPU: everything with -DBKL_ENABLE_CUDA=ON (kernel builds, benches, compute-sanitizer) needs the self-hosted [self-hosted, Linux, X64, CUDA] runner. On an orb, only the CPU checks and docs/tools work.
  • Not installed: actionlint 1.7.12 (ci-lint.yml downloads it per run).

No GPU on orbs

Amp orbs are Debian 12 cloud VMs with no GPU. The GPU-gated parts of this repo can't run on an orb; the notes above give the CPU path.

Testing

  • bash -n and shellcheck 0.10.0: clean.
  • Not run end to end. Only five of the scripts in this batch were run in a Debian 12 chroot (Limen-Capital, SynapticDistill.jl, combine-for-AI, Dioscuri-Cloud, silicon-hdl). This one has only been syntax-checked and linted.
  • Not run on a real Amp orb.

Things to double-check

  • rustup, juliaup and uv install into ~/.cargo/bin, ~/.juliaup/bin and ~/.local/bin and add those to the login profile. The script exports them for its own run. In a non-login, non-interactive shell they weren't on PATH, so check that Amp's agent shell finds cargo/julia/uv.
  • apt-get uses Acquire::Retries=5, but a deb.debian.org 500 can still fail the setup. Amp doesn't save a snapshot from a failed setup, so a retry fixes it.
  • Editing this script later doesn't rebuild existing orb snapshots. Delete it with amp projects snapshots delete <project> to force a fresh setup, or wait for it to expire (Amp reuses a snapshot for up to 72 hours).

Propose-only: please review before merging.

Summary by cubic

Adds .agents/setup, the bash script Amp runs on a fresh orb before saving a snapshot (Debian 12, CPU only). It installs only the packages this repo's CI needs — build-essential, cmake, shellcheck — and ends with the CPU-only CMake configure (-DBKL_ENABLE_CUDA=OFF), which skips every kernel target so no nvcc is required.

  • Idempotent: packages already installed are skipped on re-runs.
  • GPU-gated targets can't run on orbs, so setup stays on the CPU path.
  • Only syntax-checked and shellcheck-linted so far, not run end to end.