headroom/scripts/README.md

# scripts/

Utility scripts bundled with the Headroom repo. Most are one-off operator
tools; a few are runnable as part of development workflows.

## Reproducing the reconnect storm

`repro_codex_replay.py` reproduces the multi-agent Codex reconnect/retry storm
against a local Headroom proxy (default `http://127.0.0.1:8787`). Use it to:

- Regression-check that `/livez` stays responsive under a cold-start storm.
- Empirically tune the Unit 4 pre-upstream semaphore default
  (`HEADROOM_ANTHROPIC_PRE_UPSTREAM_CONCURRENCY`).
- Exercise the Codex WS lifecycle + Anthropic HTTP path simultaneously
  without needing to replay captured production traffic.

### Run

```bash
# Default: 8 WS + 4 HTTP clients, 30s storm, p99 /livez must stay <= 500ms.
python scripts/repro_codex_replay.py

# Tighter budget, shorter run:
python scripts/repro_codex_replay.py \
    --url http://127.0.0.1:8787 \
    --ws-clients 16 \
    --anthropic-clients 8 \
    --duration 60 \
    --livez-threshold-ms 100

# Dump the full summary as JSON for downstream tooling:
python scripts/repro_codex_replay.py --json
```

Exit code:

- `0` — warmup succeeded (or was skipped), storm ran for the requested
  duration, and `/livez` p99 stayed under `--livez-threshold-ms`.
- `1` — soft assertion failed, proxy unreachable, or unhandled exception.
  Proxy-unreachable is detected and reported within ~5 seconds.

### Fixtures

The script loads two hand-crafted, fully synthetic JSON fixtures:

- `scripts/fixtures/anthropic_replay_body.json` — shape of a large agent
  reconnect replay `/v1/messages?beta=true` POST body.
- `scripts/fixtures/codex_response_create_frame.json` — first Codex WS frame
  with the `{"type": "response.create", "response": {...}}` envelope.

Override via `--ws-frame-fixture` / `--anthropic-body-fixture` if you have
captured traffic to replay instead.

### Interpretation

- `/livez p99` under threshold means the event loop is not starved during the
  storm. If it rises with the semaphore unbounded
  (`HEADROOM_ANTHROPIC_PRE_UPSTREAM_CONCURRENCY=10000`) and drops back under
  the default, Unit 4's backpressure is working.
- `Codex WS: opened` should equal `--ws-clients`. `response.completed`
  typically stays low when upstream auth isn't configured locally — the goal
  is handshake + relay wiring, not real upstream traffic.
- `Anthropic HTTP: ok_2xx + non_2xx + timed_out + errors` should roughly equal
  `attempted`. Sustained non-zero `timed_out` during the storm is the failure
  signal the plan targets.

A smoke test at `tests/test_scripts/test_repro_codex_replay_smoke.py`
exercises the script against a mock FastAPI server on every PR.

## Install scripts

- `install.sh` — POSIX installer.
- `install.ps1` — Windows PowerShell installer.

These are generated by the release pipeline; edit with care.

## Windows development bootstrap

`bootstrap-windows-dev.ps1` prepares a Windows development checkout. It resolves
or creates a repo-local Python virtual environment, checks for Rust, installs
Python build/test tooling, installs npm dependencies for the TypeScript SDK and
OpenClaw plugin, and runs a small smoke set.

```powershell
powershell -ExecutionPolicy Bypass -File scripts/bootstrap-windows-dev.ps1
```

Use `-CheckOnly` to print detected tool versions without installing packages.
Use `-SkipSmoke`, `-SkipDocs`, `-SkipNode`, or `-SkipRust` when intentionally
debugging one part of the environment.

## npm release asset smoke

`build_npm_release_assets.mjs` locally reproduces the release workflow's npm
asset build. It builds the TypeScript SDK tarball, installs that tarball into
OpenClaw, rewrites OpenClaw's release dependency to the same version,
regenerates `dist/package.json`, packs OpenClaw, and then runs
`verify_npm_release_assets.mjs`.

```bash
node scripts/build_npm_release_assets.mjs <version>
```

By default, output goes into a timestamped `release-assets-local/<version>-*`
directory. Pass an explicit empty directory when you want a predictable path:

```bash
node scripts/build_npm_release_assets.mjs <version> release-assets-local/smoke
```

Expected tarballs:

- `headroom-ai-<version>.tgz`
- `headroom-openclaw-<version>.tgz`

The script restores package metadata after it finishes so the source tree keeps
the registry-installable development dependency range.

## Python release artifact smoke

`build_python_release_smoke.py` locally reproduces the Python artifact smoke:
it builds a wheel with `maturin`, builds an sdist, verifies the sdist
`License-File` metadata against tarball contents, installs the wheel into a
fresh `python -m venv` environment, and imports the native `headroom._core`
extension from that installed wheel.

```bash
python scripts/build_python_release_smoke.py
```

By default, the wheel uses the faster Cargo `ci` profile and output goes into a
timestamped `release-assets-local/python-<version>-*` directory. Use `--release`
when you want the slower shipped-wheel profile:

```bash
python scripts/build_python_release_smoke.py --release --out release-assets-local/python-release-smoke
```

Expected artifacts:

- `headroom_ai-<version>-*.whl`
- `headroom_ai-<version>.tar.gz`

## Full local release smoke

`release_smoke_all.py` is the one-command local release gate. It first runs
`scripts/verify-versions.py`, then runs the npm release asset smoke and the
Python wheel/sdist smoke into sibling output directories.

```bash
python scripts/release_smoke_all.py
```

By default, output goes into `release-assets-local/all-<version>-*/npm` and
`release-assets-local/all-<version>-*/python`. Pass an explicit empty output
directory for a predictable evidence path:

```bash
python scripts/release_smoke_all.py --out release-assets-local/full-release-smoke
```

Use `--python-release` when the Python smoke should build with maturin's slower
release profile. Use `--skip-npm` or `--skip-python` only when intentionally
debugging one side of the artifact pipeline.