mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-08-27 14:17:10 -04:00
c482d75a73
Reproducibly exercises the multi-agent Codex reconnect/retry storm
(origin §"Latest Correction") against a local proxy: concurrent Codex WS
sessions + parallel Anthropic /v1/messages replays, with /livez probed
every 250ms to detect event-loop starvation. Exits non-zero if /livez
p99 exceeds the configured threshold.
- scripts/repro_codex_replay.py — CLI harness (asyncio + websockets +
httpx, no new pip deps).
- scripts/fixtures/{anthropic_replay_body,codex_response_create_frame}.json
— hand-crafted, fully synthetic fixtures shaped like real traffic.
- scripts/README.md — "Reproducing the reconnect storm" section.
- tests/test_scripts/test_repro_codex_replay_smoke.py — FastAPI/uvicorn
mock server; runs the harness end-to-end in < 3s.
- .gitignore — allowlist the new checked-in scripts (existing rule
previously ignored everything under scripts/ except install.sh/.ps1).
77 lines
2.9 KiB
Markdown
77 lines
2.9 KiB
Markdown
# 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`), as described
|
|
in `wiki/plans/2026-04-17-codex-proxy-runtime-analysis.md` under "Latest
|
|
Correction". 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.
|