2026-04-17 15:55:34 +07:00
|
|
|
# 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
|
chore: remove committed node_modules + stray/internal markdown (repo hygiene) (#1528)
## Description
Repo hygiene for a public OSS project: removes committed `node_modules`,
stray/internal/draft markdown, and commercial-surface references —
keeping every real doc (the published docs site, the wiki guides, and
all component READMEs) intact. Every file was content-audited before
removal, and load-bearing files were verified against the code/CI and
kept.
Net: **1,695 files changed, +23 / −266,409** (the deletions are
dominated by a committed `node_modules` tree).
Closes # (no tracking issue)
## Type of Change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [x] Code refactoring (no functional changes)
## Changes Made
**Removed (verified to have no code/CI dependencies):**
- `examples/vercel-ai-sdk-pr/` — 1,649 committed `node_modules` files
(zero example source); `node_modules/` added to `.gitignore`.
- `docs/spec/` (23 draft "Living Specification" files — orphaned,
`1.0.0-draft`, drifted from the code), `docs/superpowers/` (2 agent
plans), `docs/proposals/` (2 internal/commercial memos).
- 6 orphan `docs/*.md` (auth-modes, bedrock,
claude-code-vertex-headroom, cortex-code, output-token-reduction-guide,
rtk-loop-weighting).
- `PR.md` (committed PR draft), `ENTERPRISE.md`, `.github/FUNDING.yml`.
**Content scrubs:**
- Removed unreleased "Headroom Cloud" / `api.headroom.ai` / `hr_`
references from `configuration.mdx`, `wiki/configuration.md`,
`wiki/typescript-sdk.md`, `sdk/typescript/README.md` (reworded to
neutral, accurate phrasing).
- Dropped a stale "awaiting maintainer before merge" line from
`plugins/headroom-oauth2/SPEC.md`; tidied `.gitignore` comments (kept
the protective `headroom-managed/` ignore rule).
- Fixed the now-dangling links into removed files (README
nav/`output-token-reduction` link, `scripts/README`, `wiki/vertex`).
**Explicitly KEPT (load-bearing — would orphan in-code citations if
removed):**
- `.changelog.md` — consumed by `.github/workflows/release.yml` (read as
the release-notes file).
- `REALIGNMENT/`, `docs/observability.md`, `docs/rtk-architecture.md`,
`wiki/plans/`, `TESTING-copilot-subscription.md` — referenced by the
Rust core / Python / tests as design docs.
## Testing
- [ ] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check`)
- [ ] Type checking passes (`mypy`)
- [x] New tests added for new functionality
- [x] Manual testing performed
### Test Output
```text
# Docs/markdown + .gitignore only — no Python/Rust source changed, so the
# behavioral test suite is unaffected. Verified the cleanup did not orphan
# references or break the published docs site:
$ git ls-files 'docs/content/docs/*.mdx' | wc -l # published site intact
42
$ # meta.json nav unchanged; no published page removed.
$ grep -rnI "Headroom Cloud|api.headroom.ai|'hr_" $(git ls-files '*.md' '*.mdx')
>>> none
$ # dangling refs to removed files (excl pre-existing P0/P2 spec stubs that
$ # never existed in git): none remaining.
```
## Real Behavior Proof
- Environment: macOS, local git clone of the repo (markdown/.gitignore
changes only — no runtime).
- Exact command / steps: 4 read-only content-audit agents classified
every `.md`/`.mdx` file; each removal candidate was cross-checked
against the codebase (`grep` for citations in `.rs`/`.py`/tests,
workflows, and configs); only files with no dependents were removed; the
tree was re-grepped after removal to confirm no new dangling references;
verified the published docs site page count (`git ls-files
'docs/content/docs/*.mdx' | wc -l` = 42, unchanged).
- Observed result: the 42-page published docs site and all wiki guides
are untouched; no source or workflow references a removed file;
`.changelog.md` (consumed by release.yml) and the code-cited design docs
were detected as dependencies and kept; the committed `node_modules`
tree is removed and `node_modules/` is gitignored so it can't be
re-committed; zero "Headroom Cloud"/`headroom.dev` references remain.
- Not tested: N/A — no executable code changed (only markdown, `.mdx`,
and `.gitignore`), so the behavioral test suite is unaffected.
## Review Readiness
- [x] I have performed a self-review
- [x] This PR is ready for human review
## Checklist
- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [ ] I have updated the CHANGELOG.md if applicable
## Additional Notes
- This branch deletes `.github/FUNDING.yml` while PR #1526 edits it —
the two will be sequenced at merge (delete wins).
- A follow-up option (not in this PR): also remove the internal design
docs that are currently cited by the code (`REALIGNMENT/`,
`docs/observability.md`, `docs/rtk-architecture.md`, `wiki/plans/`) —
that requires scrubbing ~15–20 in-code citations so nothing dangles, so
it's deliberately deferred.
- Untracked local working files (`benchmarks/hf_pilot/`,
`tools/copilot-test/`) are intentionally left out of git (not
committed).
2026-06-27 23:32:54 -07:00
|
|
|
against a local Headroom proxy (default `http://127.0.0.1:8787`). Use it to:
|
2026-04-17 15:55:34 +07:00
|
|
|
|
|
|
|
|
- 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.
|