xithead 1.4.0 → 1.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (86) hide show
  1. package/README.md +108 -72
  2. package/app/api/config/route.ts +22 -0
  3. package/app/api/export/route.ts +83 -0
  4. package/app/api/models/route.ts +12 -0
  5. package/app/api/stats/route.ts +46 -0
  6. package/app/dashboard/page.tsx +445 -0
  7. package/app/globals.css +35 -0
  8. package/app/installation/page.tsx +293 -0
  9. package/app/layout.tsx +35 -0
  10. package/app/master-design-system.css +2076 -0
  11. package/app/master-design-system.source.css +8 -0
  12. package/app/page.tsx +187 -0
  13. package/app/rechtliches/agb/page.tsx +165 -0
  14. package/app/rechtliches/datenschutz/page.tsx +128 -0
  15. package/app/rechtliches/impressum/page.tsx +122 -0
  16. package/app/rechtliches/widerruf/page.tsx +185 -0
  17. package/bin/xithead.js +264 -0
  18. package/components/layout/AppShell.tsx +25 -0
  19. package/components/layout/Footer.tsx +120 -0
  20. package/components/layout/Header.tsx +145 -0
  21. package/components/marketing/LegalHighlights.tsx +45 -0
  22. package/components/marketing/LegalPageShell.tsx +49 -0
  23. package/components/marketing/LegalPanel.tsx +41 -0
  24. package/components/marketing/index.ts +3 -0
  25. package/design-system/README.md +80 -0
  26. package/design-system/base.css +127 -0
  27. package/design-system/components.css +1943 -0
  28. package/design-system/fonts.css +17 -0
  29. package/design-system/tailwind-preset.js +95 -0
  30. package/design-system/tokens.css +48 -0
  31. package/design-system/utilities.css +53 -0
  32. package/lib/config/index.ts +12 -0
  33. package/lib/hooks/index.ts +4 -0
  34. package/lib/hooks/use-mounted.ts +13 -0
  35. package/lib/hooks/use-session.ts +34 -0
  36. package/lib/hooks/use-settings.ts +49 -0
  37. package/lib/utils/index.ts +1 -0
  38. package/lib/utils/settings.ts +162 -0
  39. package/lib/utils/utils.ts +6 -0
  40. package/middleware.ts +26 -0
  41. package/next-env.d.ts +7 -0
  42. package/next.config.ts +12 -0
  43. package/package.json +77 -36
  44. package/postcss.config.mjs +7 -0
  45. package/public/apple-touch-icon.png +0 -0
  46. package/public/logo-transparent.png +0 -0
  47. package/public/xithead.ps1 +937 -0
  48. package/scripts/README.md +77 -0
  49. package/scripts/audit_wheel_glibc_symbols.py +217 -0
  50. package/scripts/build-master-design-system.cjs +33 -0
  51. package/scripts/build_rust_extension.sh +58 -0
  52. package/scripts/changelog-gen.py +203 -0
  53. package/scripts/eval_output_shaper.py +235 -0
  54. package/scripts/export_kompress_v2_onnx.py +267 -0
  55. package/scripts/fixtures/anthropic_replay_body.json +133 -0
  56. package/scripts/fixtures/codex_response_create_frame.json +52 -0
  57. package/scripts/install-git-hooks.sh +104 -0
  58. package/scripts/install.ps1 +1809 -0
  59. package/scripts/install.sh +1673 -0
  60. package/scripts/pr-governance.py +297 -0
  61. package/scripts/record_fixtures.py +59 -0
  62. package/scripts/refresh_model_limits.sh +48 -0
  63. package/scripts/replay_codex_ws_load.py +445 -0
  64. package/scripts/repro_codex_replay.py +699 -0
  65. package/scripts/smoke_issue_327.py +233 -0
  66. package/scripts/sync-plugin-versions.py +116 -0
  67. package/scripts/tests/test_changelog_gen.py +302 -0
  68. package/scripts/tests/test_pr_governance.py +163 -0
  69. package/scripts/tests/test_pr_health_labels.py +94 -0
  70. package/scripts/tests/test_pr_health_workflow.py +14 -0
  71. package/scripts/tests/test_sync_plugin_versions.py +131 -0
  72. package/scripts/tests/test_version_sync.py +291 -0
  73. package/scripts/validate-workflows.sh +39 -0
  74. package/scripts/verify-versions.py +106 -0
  75. package/scripts/version-sync.py +207 -0
  76. package/tailwind.config.js +31 -0
  77. package/tailwind.master.config.cjs +47 -0
  78. package/tsconfig.json +84 -0
  79. package/types/api.ts +12 -0
  80. package/types/config.ts +9 -0
  81. package/types/index.ts +2 -0
  82. package/npm/bin/xithead.js +0 -366
  83. package/npm/index.d.ts +0 -57
  84. package/npm/index.js +0 -139
  85. package/npm/package.json +0 -54
  86. package/npm/postinstall.js +0 -43
@@ -0,0 +1,699 @@
1
+ #!/usr/bin/env python3
2
+ """Repro harness: multi-agent Codex reconnect storm against a local proxy.
3
+
4
+ This script reproduces the failure class described in
5
+ ``wiki/plans/2026-04-17-codex-proxy-runtime-analysis.md`` ("Latest Correction"):
6
+ a burst of concurrent Codex WebSocket sessions plus a parallel burst of large
7
+ Anthropic ``/v1/messages`` replays immediately after a fresh proxy restart, with
8
+ ``/livez`` probed continuously to detect event-loop starvation.
9
+
10
+ Usage::
11
+
12
+ python scripts/repro_codex_replay.py \\
13
+ --url http://127.0.0.1:8787 \\
14
+ --ws-clients 8 \\
15
+ --anthropic-clients 4 \\
16
+ --duration 30
17
+
18
+ Exit code is ``0`` iff the warmup phase succeeded (or was skipped), the storm
19
+ phase ran for the requested duration, and ``/livez`` p99 stayed at or below the
20
+ configured threshold (``--livez-threshold-ms``, default 500ms).
21
+
22
+ The harness adds no new pip dependencies: it uses ``asyncio`` + ``websockets``
23
+ + ``httpx`` only, all already available in the Headroom dev environment.
24
+ """
25
+
26
+ from __future__ import annotations
27
+
28
+ import argparse
29
+ import asyncio
30
+ import json
31
+ import random
32
+ import statistics
33
+ import sys
34
+ import time
35
+ from contextlib import asynccontextmanager, suppress
36
+ from dataclasses import dataclass, field
37
+ from pathlib import Path
38
+ from typing import Any
39
+ from urllib.parse import urlparse, urlunparse
40
+
41
+ import httpx
42
+
43
+ try:
44
+ from websockets.asyncio.client import connect as ws_connect
45
+ except ImportError: # pragma: no cover - older websockets fallback
46
+ from websockets.client import connect as ws_connect # type: ignore[no-redef]
47
+
48
+ # asyncio.timeout was added in Python 3.11; provide a thin shim for 3.10.
49
+ if sys.version_info >= (3, 11):
50
+ _asyncio_timeout = asyncio.timeout
51
+ else:
52
+
53
+ @asynccontextmanager
54
+ async def _asyncio_timeout(delay: float | None): # type: ignore[no-redef]
55
+ """Minimal shim that mimics ``asyncio.timeout`` using ``wait_for``."""
56
+ # For the single call-site we have, wrapping the entire body in a task
57
+ # and cancelling it on timeout is sufficient. We yield control, and if
58
+ # the caller's block exceeds *delay* seconds the enclosing task is
59
+ # cancelled.
60
+ loop = asyncio.get_running_loop()
61
+ deadline = loop.time() + delay if delay is not None else None
62
+ task = asyncio.current_task()
63
+ handle = None
64
+ if deadline is not None and task is not None:
65
+ handle = loop.call_at(deadline, task.cancel)
66
+ try:
67
+ yield
68
+ except asyncio.CancelledError:
69
+ raise asyncio.TimeoutError() from None
70
+ finally:
71
+ if handle is not None:
72
+ handle.cancel()
73
+
74
+
75
+ from websockets.exceptions import ConnectionClosed, InvalidStatus, WebSocketException
76
+
77
+ # ---------------------------------------------------------------------------
78
+ # Fixtures
79
+ # ---------------------------------------------------------------------------
80
+
81
+ SCRIPT_DIR = Path(__file__).resolve().parent
82
+ DEFAULT_WS_FRAME_FIXTURE = SCRIPT_DIR / "fixtures" / "codex_response_create_frame.json"
83
+ DEFAULT_ANTHROPIC_BODY_FIXTURE = SCRIPT_DIR / "fixtures" / "anthropic_replay_body.json"
84
+
85
+
86
+ def _load_json(path: Path) -> dict[str, Any]:
87
+ with path.open("r", encoding="utf-8") as f:
88
+ return json.load(f)
89
+
90
+
91
+ # ---------------------------------------------------------------------------
92
+ # Stats
93
+ # ---------------------------------------------------------------------------
94
+
95
+
96
+ @dataclass
97
+ class LatencyHistogram:
98
+ """Minimal fixed-list histogram with p50/p95/p99/max computation."""
99
+
100
+ samples_ms: list[float] = field(default_factory=list)
101
+
102
+ def record(self, value_ms: float) -> None:
103
+ self.samples_ms.append(value_ms)
104
+
105
+ @property
106
+ def count(self) -> int:
107
+ return len(self.samples_ms)
108
+
109
+ def percentile(self, p: float) -> float:
110
+ if not self.samples_ms:
111
+ return 0.0
112
+ ordered = sorted(self.samples_ms)
113
+ if p <= 0:
114
+ return ordered[0]
115
+ if p >= 100:
116
+ return ordered[-1]
117
+ idx = max(0, min(len(ordered) - 1, int(round((p / 100.0) * (len(ordered) - 1)))))
118
+ return ordered[idx]
119
+
120
+ def as_summary(self) -> dict[str, float]:
121
+ if not self.samples_ms:
122
+ return {"count": 0, "p50": 0.0, "p95": 0.0, "p99": 0.0, "max": 0.0}
123
+ return {
124
+ "count": self.count,
125
+ "p50": self.percentile(50),
126
+ "p95": self.percentile(95),
127
+ "p99": self.percentile(99),
128
+ "max": max(self.samples_ms),
129
+ }
130
+
131
+
132
+ @dataclass
133
+ class CodexWsStats:
134
+ opened: int = 0
135
+ response_completed: int = 0
136
+ errors: dict[str, int] = field(default_factory=dict)
137
+
138
+ def record_error(self, kind: str) -> None:
139
+ self.errors[kind] = self.errors.get(kind, 0) + 1
140
+
141
+
142
+ @dataclass
143
+ class AnthropicHttpStats:
144
+ attempted: int = 0
145
+ ok_2xx: int = 0
146
+ non_2xx: int = 0
147
+ timed_out: int = 0
148
+ errors: int = 0
149
+ first_byte_latency_ms: list[float] = field(default_factory=list)
150
+
151
+ @property
152
+ def avg_first_byte_ms(self) -> float:
153
+ if not self.first_byte_latency_ms:
154
+ return 0.0
155
+ return statistics.mean(self.first_byte_latency_ms)
156
+
157
+
158
+ # ---------------------------------------------------------------------------
159
+ # URL helpers
160
+ # ---------------------------------------------------------------------------
161
+
162
+
163
+ def _http_to_ws_url(http_url: str, path: str) -> str:
164
+ parsed = urlparse(http_url)
165
+ scheme = "wss" if parsed.scheme == "https" else "ws"
166
+ # Preserve host:port; override scheme + path. Ensure path starts with a single "/".
167
+ normalized_path = "/" + path.lstrip("/") if path else ""
168
+ return urlunparse((scheme, parsed.netloc, normalized_path, "", "", ""))
169
+
170
+
171
+ # ---------------------------------------------------------------------------
172
+ # Warmup phase
173
+ # ---------------------------------------------------------------------------
174
+
175
+
176
+ async def warmup_probe(
177
+ url: str,
178
+ ws_frame: dict[str, Any],
179
+ timeout_s: float = 10.0,
180
+ ) -> tuple[bool, float, str]:
181
+ """Open one WS, send the response.create frame, wait briefly.
182
+
183
+ Returns ``(success, elapsed_ms, note)``. Success is true if the proxy
184
+ accepts the WebSocket handshake and the initial frame is sent without
185
+ error. We do not require ``response.completed`` — upstream auth will
186
+ often fail locally and the proxy will send an error frame; the important
187
+ signal is that the handshake + relay wiring worked.
188
+ """
189
+ ws_url = _http_to_ws_url(url, "/v1/responses")
190
+ start = time.perf_counter()
191
+ handshake_ok = False
192
+ frame_sent = False
193
+ note = "unknown"
194
+ try:
195
+ async with _asyncio_timeout(timeout_s):
196
+ async with ws_connect(
197
+ ws_url,
198
+ additional_headers={"Authorization": "Bearer repro-harness"},
199
+ ) as ws:
200
+ handshake_ok = True
201
+ try:
202
+ await ws.send(json.dumps(ws_frame))
203
+ frame_sent = True
204
+ except (ConnectionClosed, WebSocketException) as exc:
205
+ note = f"send_failed:{type(exc).__name__}"
206
+ return False, (time.perf_counter() - start) * 1000.0, note
207
+ # Drain until terminal event, close, or deadline.
208
+ deadline_local = time.perf_counter() + timeout_s
209
+ while time.perf_counter() < deadline_local:
210
+ remaining = deadline_local - time.perf_counter()
211
+ if remaining <= 0:
212
+ break
213
+ try:
214
+ raw = await asyncio.wait_for(ws.recv(), timeout=remaining)
215
+ except asyncio.TimeoutError:
216
+ note = "timeout_waiting_for_completion"
217
+ break
218
+ except ConnectionClosed:
219
+ # Upstream (or mock) closed cleanly after accepting our
220
+ # frame — this still counts as a working pre-upstream
221
+ # path; the warmup's purpose is handshake + send, not
222
+ # demanding real upstream output.
223
+ note = "upstream_closed_after_send"
224
+ break
225
+ try:
226
+ evt = json.loads(raw) if isinstance(raw, str) else {}
227
+ except json.JSONDecodeError:
228
+ continue
229
+ etype = evt.get("type", "")
230
+ if etype == "response.completed":
231
+ note = "response.completed"
232
+ break
233
+ if etype in {"error", "response.failed"}:
234
+ note = f"terminal:{etype}"
235
+ break
236
+ elapsed_ms = (time.perf_counter() - start) * 1000.0
237
+ return frame_sent, elapsed_ms, note
238
+ except (OSError, WebSocketException, InvalidStatus, asyncio.TimeoutError) as exc:
239
+ elapsed_ms = (time.perf_counter() - start) * 1000.0
240
+ # If the handshake completed and we sent the frame, a subsequent close
241
+ # error from the context manager is not a warmup failure.
242
+ if frame_sent:
243
+ return True, elapsed_ms, f"post_send_close:{type(exc).__name__}"
244
+ if handshake_ok:
245
+ return False, elapsed_ms, f"post_handshake_error:{type(exc).__name__}: {exc}"
246
+ return False, elapsed_ms, f"{type(exc).__name__}: {exc}"
247
+
248
+
249
+ # ---------------------------------------------------------------------------
250
+ # Storm phase
251
+ # ---------------------------------------------------------------------------
252
+
253
+
254
+ async def _ws_client(
255
+ idx: int,
256
+ url: str,
257
+ ws_frame: dict[str, Any],
258
+ deadline: float,
259
+ stats: CodexWsStats,
260
+ ) -> None:
261
+ ws_url = _http_to_ws_url(url, "/v1/responses")
262
+ try:
263
+ async with ws_connect(
264
+ ws_url,
265
+ additional_headers={"Authorization": f"Bearer repro-harness-ws-{idx}"},
266
+ open_timeout=10,
267
+ ) as ws:
268
+ stats.opened += 1
269
+ try:
270
+ await ws.send(json.dumps(ws_frame))
271
+ except (ConnectionClosed, WebSocketException) as exc:
272
+ stats.record_error(f"send:{type(exc).__name__}")
273
+ return
274
+ # Hold the session open, draining events until deadline or close.
275
+ while True:
276
+ remaining = deadline - time.perf_counter()
277
+ if remaining <= 0:
278
+ break
279
+ try:
280
+ raw = await asyncio.wait_for(ws.recv(), timeout=min(remaining, 5.0))
281
+ except asyncio.TimeoutError:
282
+ continue
283
+ except ConnectionClosed:
284
+ break
285
+ try:
286
+ evt = json.loads(raw) if isinstance(raw, str) else {}
287
+ except json.JSONDecodeError:
288
+ continue
289
+ etype = evt.get("type", "")
290
+ if etype == "response.completed":
291
+ stats.response_completed += 1
292
+ break
293
+ if etype in {"error", "response.failed"}:
294
+ stats.record_error(f"upstream:{etype}")
295
+ break
296
+ except (OSError, InvalidStatus) as exc:
297
+ stats.record_error(f"connect:{type(exc).__name__}")
298
+ except WebSocketException as exc:
299
+ stats.record_error(f"ws:{type(exc).__name__}")
300
+ except Exception as exc: # pragma: no cover - defensive
301
+ stats.record_error(f"unexpected:{type(exc).__name__}")
302
+
303
+
304
+ async def _anthropic_client(
305
+ idx: int,
306
+ url: str,
307
+ body: dict[str, Any],
308
+ deadline: float,
309
+ stats: AnthropicHttpStats,
310
+ ) -> None:
311
+ endpoint = url.rstrip("/") + "/v1/messages?beta=true"
312
+ headers = {
313
+ "Content-Type": "application/json",
314
+ "Authorization": f"Bearer repro-harness-anthropic-{idx}",
315
+ "anthropic-version": "2023-06-01",
316
+ "x-api-key": f"repro-harness-anthropic-{idx}",
317
+ }
318
+ retry_cutoff = min(deadline, time.perf_counter() + 60.0)
319
+ attempt = 0
320
+ async with httpx.AsyncClient(timeout=httpx.Timeout(30.0, connect=5.0)) as client:
321
+ while time.perf_counter() < deadline:
322
+ attempt += 1
323
+ stats.attempted += 1
324
+ start = time.perf_counter()
325
+ try:
326
+ resp = await client.post(endpoint, headers=headers, json=body)
327
+ first_byte_ms = (time.perf_counter() - start) * 1000.0
328
+ stats.first_byte_latency_ms.append(first_byte_ms)
329
+ # Drain body so the connection is released.
330
+ with suppress(Exception):
331
+ _ = resp.content
332
+ if 200 <= resp.status_code < 300:
333
+ stats.ok_2xx += 1
334
+ return
335
+ stats.non_2xx += 1
336
+ if resp.status_code < 500:
337
+ # Client error — no retry, agent would surface this.
338
+ return
339
+ except httpx.TimeoutException:
340
+ stats.timed_out += 1
341
+ except (httpx.HTTPError, OSError):
342
+ stats.errors += 1
343
+ # Retry loop — mimic agent behavior with bounded wall clock.
344
+ if time.perf_counter() >= retry_cutoff:
345
+ return
346
+ # Exponential backoff with 50-150% jitter, mirroring the
347
+ # ``jitter_delay_ms(base_ms=250, max_ms=5000, attempt=n)``
348
+ # helper used inside the proxy. Keeping the formula inline
349
+ # so this script stays dependency-free of the proxy package.
350
+ _base_ms = 250
351
+ _max_ms = 5000
352
+ _delay_ms = min(_base_ms * (2 ** (attempt - 1)), _max_ms) * (0.5 + random.random())
353
+ await asyncio.sleep(_delay_ms / 1000.0)
354
+
355
+
356
+ async def _livez_prober(
357
+ url: str,
358
+ histogram: LatencyHistogram,
359
+ deadline: float,
360
+ interval_ms: int = 250,
361
+ ) -> None:
362
+ endpoint = url.rstrip("/") + "/livez"
363
+ async with httpx.AsyncClient(timeout=httpx.Timeout(5.0, connect=2.0)) as client:
364
+ while time.perf_counter() < deadline:
365
+ start = time.perf_counter()
366
+ try:
367
+ resp = await client.get(endpoint)
368
+ elapsed_ms = (time.perf_counter() - start) * 1000.0
369
+ if resp.status_code == 200:
370
+ histogram.record(elapsed_ms)
371
+ else:
372
+ # Treat non-200 as worst-case for our threshold.
373
+ histogram.record(max(elapsed_ms, 5000.0))
374
+ except (httpx.HTTPError, OSError):
375
+ histogram.record(5000.0)
376
+ # Tick every interval_ms regardless of probe latency.
377
+ sleep_for = interval_ms / 1000.0
378
+ next_wake = time.perf_counter() + sleep_for
379
+ remaining = max(0.0, next_wake - time.perf_counter())
380
+ if remaining > 0:
381
+ await asyncio.sleep(remaining)
382
+
383
+
384
+ # ---------------------------------------------------------------------------
385
+ # Orchestration
386
+ # ---------------------------------------------------------------------------
387
+
388
+
389
+ async def _check_reachable(url: str, timeout_s: float = 5.0) -> tuple[bool, str]:
390
+ endpoint = url.rstrip("/") + "/livez"
391
+ try:
392
+ async with httpx.AsyncClient(timeout=httpx.Timeout(timeout_s, connect=timeout_s)) as client:
393
+ resp = await client.get(endpoint)
394
+ return (True, f"HTTP {resp.status_code}")
395
+ except (httpx.ConnectError, ConnectionRefusedError, OSError) as exc:
396
+ return (False, f"{type(exc).__name__}: {exc}")
397
+ except httpx.HTTPError as exc:
398
+ return (True, f"reachable-but-error: {type(exc).__name__}: {exc}")
399
+
400
+
401
+ async def run_harness(args: argparse.Namespace) -> dict[str, Any]:
402
+ ws_frame = _load_json(Path(args.ws_frame_fixture))
403
+ anthropic_body = _load_json(Path(args.anthropic_body_fixture))
404
+
405
+ # Reachability gate — quick, clear failure if the proxy is not up.
406
+ reachable, reach_note = await _check_reachable(args.url, timeout_s=5.0)
407
+ if not reachable:
408
+ return {
409
+ "ok": False,
410
+ "reason": "proxy_unreachable",
411
+ "detail": reach_note,
412
+ "url": args.url,
413
+ }
414
+
415
+ # Phase 1: warmup
416
+ warmup_result: dict[str, Any]
417
+ if args.no_warmup:
418
+ warmup_result = {"skipped": True}
419
+ else:
420
+ success, elapsed_ms, note = await warmup_probe(
421
+ args.url, ws_frame, timeout_s=args.warmup_timeout
422
+ )
423
+ warmup_result = {
424
+ "skipped": False,
425
+ "success": success,
426
+ "elapsed_ms": round(elapsed_ms, 2),
427
+ "note": note,
428
+ }
429
+
430
+ # Phase 2: storm
431
+ livez_hist = LatencyHistogram()
432
+ ws_stats = CodexWsStats()
433
+ http_stats = AnthropicHttpStats()
434
+
435
+ storm_start = time.perf_counter()
436
+ deadline = storm_start + args.duration
437
+
438
+ livez_task = asyncio.create_task(
439
+ _livez_prober(args.url, livez_hist, deadline, interval_ms=args.livez_interval_ms),
440
+ name="repro-livez-prober",
441
+ )
442
+ ws_tasks = [
443
+ asyncio.create_task(
444
+ _ws_client(i, args.url, ws_frame, deadline, ws_stats),
445
+ name=f"repro-ws-{i}",
446
+ )
447
+ for i in range(args.ws_clients)
448
+ ]
449
+ http_tasks = [
450
+ asyncio.create_task(
451
+ _anthropic_client(i, args.url, anthropic_body, deadline, http_stats),
452
+ name=f"repro-http-{i}",
453
+ )
454
+ for i in range(args.anthropic_clients)
455
+ ]
456
+
457
+ # Let the storm run. Gather storm tasks but keep probing /livez for the
458
+ # full requested duration regardless of when the clients exit — the whole
459
+ # point is to observe event-loop health across the window.
460
+ storm_tasks = ws_tasks + http_tasks
461
+ try:
462
+ await asyncio.wait_for(
463
+ asyncio.gather(*storm_tasks, return_exceptions=True),
464
+ timeout=args.duration + 10.0,
465
+ )
466
+ except asyncio.TimeoutError:
467
+ for t in storm_tasks:
468
+ if not t.done():
469
+ t.cancel()
470
+ await asyncio.gather(*storm_tasks, return_exceptions=True)
471
+
472
+ # Let the /livez prober run to its own deadline so the histogram covers
473
+ # the full window, not just the interval where storm tasks were alive.
474
+ remaining = deadline - time.perf_counter()
475
+ if remaining > 0:
476
+ with suppress(asyncio.TimeoutError):
477
+ await asyncio.wait_for(asyncio.shield(livez_task), timeout=remaining + 2.0)
478
+ if not livez_task.done():
479
+ livez_task.cancel()
480
+ with suppress(asyncio.CancelledError, Exception):
481
+ await livez_task
482
+
483
+ storm_duration_s = time.perf_counter() - storm_start
484
+ livez_summary = livez_hist.as_summary()
485
+
486
+ # Soft assertion: livez p99 under threshold.
487
+ threshold_ms = args.livez_threshold_ms
488
+ livez_ok = livez_summary["p99"] <= threshold_ms
489
+
490
+ return {
491
+ "ok": (warmup_result.get("skipped", False) or warmup_result.get("success", False))
492
+ and livez_ok,
493
+ "warmup": warmup_result,
494
+ "storm": {
495
+ "ws_clients": args.ws_clients,
496
+ "anthropic_clients": args.anthropic_clients,
497
+ "requested_duration_s": args.duration,
498
+ "actual_duration_s": round(storm_duration_s, 3),
499
+ },
500
+ "livez": {
501
+ **livez_summary,
502
+ "threshold_ms": threshold_ms,
503
+ "threshold_ok": livez_ok,
504
+ },
505
+ "codex_ws": {
506
+ "opened": ws_stats.opened,
507
+ "response_completed": ws_stats.response_completed,
508
+ "errors": dict(ws_stats.errors),
509
+ },
510
+ "anthropic_http": {
511
+ "attempted": http_stats.attempted,
512
+ "ok_2xx": http_stats.ok_2xx,
513
+ "non_2xx": http_stats.non_2xx,
514
+ "timed_out": http_stats.timed_out,
515
+ "errors": http_stats.errors,
516
+ "avg_first_byte_ms": round(http_stats.avg_first_byte_ms, 2),
517
+ },
518
+ }
519
+
520
+
521
+ # ---------------------------------------------------------------------------
522
+ # Printing
523
+ # ---------------------------------------------------------------------------
524
+
525
+
526
+ def format_summary(result: dict[str, Any]) -> str:
527
+ if result.get("reason") == "proxy_unreachable":
528
+ return (
529
+ "Proxy unreachable at {url}.\n"
530
+ " {detail}\n"
531
+ " Hint: start the proxy with `xtream-head proxy` and retry."
532
+ ).format(**result)
533
+
534
+ lines: list[str] = []
535
+ lines.append("=" * 72)
536
+ lines.append("Codex proxy reconnect-storm repro harness — summary")
537
+ lines.append("=" * 72)
538
+ warm = result.get("warmup", {})
539
+ if warm.get("skipped"):
540
+ lines.append("Warmup: skipped")
541
+ else:
542
+ lines.append(
543
+ "Warmup: success={success} elapsed_ms={elapsed_ms} note={note}".format(**warm)
544
+ )
545
+ storm = result.get("storm", {})
546
+ lines.append(
547
+ "Storm: ws_clients={ws_clients} anthropic_clients={anthropic_clients} "
548
+ "requested={requested_duration_s}s actual={actual_duration_s}s".format(**storm)
549
+ )
550
+ livez = result.get("livez", {})
551
+ lines.append(
552
+ "/livez: count={count} p50={p50:.2f}ms p95={p95:.2f}ms "
553
+ "p99={p99:.2f}ms max={max:.2f}ms (threshold={threshold_ms}ms, "
554
+ "ok={threshold_ok})".format(**livez)
555
+ )
556
+ ws = result.get("codex_ws", {})
557
+ lines.append(
558
+ "Codex WS: opened={opened} response.completed={response_completed} "
559
+ "errors={errors}".format(**ws)
560
+ )
561
+ http = result.get("anthropic_http", {})
562
+ lines.append(
563
+ "Anthropic HTTP: attempted={attempted} ok_2xx={ok_2xx} non_2xx={non_2xx} "
564
+ "timed_out={timed_out} errors={errors} avg_first_byte_ms={avg_first_byte_ms}".format(**http)
565
+ )
566
+ lines.append("=" * 72)
567
+ lines.append("RESULT: {}".format("OK" if result.get("ok") else "FAIL"))
568
+ lines.append("=" * 72)
569
+ return "\n".join(lines)
570
+
571
+
572
+ # ---------------------------------------------------------------------------
573
+ # CLI
574
+ # ---------------------------------------------------------------------------
575
+
576
+
577
+ def build_parser() -> argparse.ArgumentParser:
578
+ parser = argparse.ArgumentParser(
579
+ description="Reproducibly exercise the multi-agent Codex reconnect/retry "
580
+ "storm against a local Xtream Head proxy.",
581
+ formatter_class=argparse.ArgumentDefaultsHelpFormatter,
582
+ )
583
+ parser.add_argument(
584
+ "--url",
585
+ default="http://127.0.0.1:8787",
586
+ help="Base URL of the running proxy.",
587
+ )
588
+ parser.add_argument(
589
+ "--ws-clients",
590
+ type=int,
591
+ default=8,
592
+ help="Number of concurrent Codex WS connections to open during the storm.",
593
+ )
594
+ parser.add_argument(
595
+ "--anthropic-clients",
596
+ type=int,
597
+ default=4,
598
+ help="Number of concurrent Anthropic /v1/messages POST clients.",
599
+ )
600
+ parser.add_argument(
601
+ "--duration",
602
+ type=float,
603
+ default=30.0,
604
+ help="Total storm phase length, in seconds.",
605
+ )
606
+ parser.add_argument(
607
+ "--livez-threshold-ms",
608
+ type=float,
609
+ default=500.0,
610
+ help="Soft assertion threshold for /livez p99 (ms). Exit non-zero if exceeded.",
611
+ )
612
+ parser.add_argument(
613
+ "--livez-interval-ms",
614
+ type=int,
615
+ default=250,
616
+ help="Interval between /livez probes, in milliseconds.",
617
+ )
618
+ parser.add_argument(
619
+ "--warmup-timeout",
620
+ type=float,
621
+ default=10.0,
622
+ help="Max seconds to wait for the warmup WS session to complete.",
623
+ )
624
+ parser.add_argument(
625
+ "--no-warmup",
626
+ action="store_true",
627
+ help="Skip the warmup probe phase.",
628
+ )
629
+ parser.add_argument(
630
+ "--ws-frame-fixture",
631
+ default=str(DEFAULT_WS_FRAME_FIXTURE),
632
+ help="Path to the Codex response.create frame JSON fixture.",
633
+ )
634
+ parser.add_argument(
635
+ "--anthropic-body-fixture",
636
+ default=str(DEFAULT_ANTHROPIC_BODY_FIXTURE),
637
+ help="Path to the Anthropic /v1/messages request body JSON fixture.",
638
+ )
639
+ parser.add_argument(
640
+ "--json",
641
+ action="store_true",
642
+ help=(
643
+ "Emit the full summary as JSON on stdout; the human-readable "
644
+ "summary is routed to stderr. Without --json, the human summary "
645
+ "is on stdout and nothing goes to JSON."
646
+ ),
647
+ )
648
+ return parser
649
+
650
+
651
+ # Exit codes. Keep POSIX-style — 0 means success, non-zero categorises
652
+ # the failure so callers (CI, smoke tests, shell wrappers) can branch.
653
+ EXIT_OK = 0
654
+ EXIT_CRASH = 1
655
+ EXIT_PROXY_UNREACHABLE = 2
656
+ EXIT_LIVEZ_THRESHOLD = 3
657
+ EXIT_WARMUP_FAILED = 4
658
+ EXIT_SIGINT = 130
659
+
660
+
661
+ def _classify_exit(result: dict[str, Any]) -> int:
662
+ """Map a harness result dict onto one of the exit constants above."""
663
+ if result.get("reason") == "proxy_unreachable":
664
+ return EXIT_PROXY_UNREACHABLE
665
+ warm = result.get("warmup", {})
666
+ if not warm.get("skipped", False) and not warm.get("success", True):
667
+ return EXIT_WARMUP_FAILED
668
+ livez = result.get("livez", {})
669
+ if livez and not livez.get("threshold_ok", True):
670
+ return EXIT_LIVEZ_THRESHOLD
671
+ return EXIT_OK if result.get("ok") else EXIT_CRASH
672
+
673
+
674
+ def main(argv: list[str] | None = None) -> int:
675
+ parser = build_parser()
676
+ args = parser.parse_args(argv)
677
+ try:
678
+ result = asyncio.run(run_harness(args))
679
+ except KeyboardInterrupt:
680
+ print("\nInterrupted by user.", file=sys.stderr)
681
+ return EXIT_SIGINT
682
+ except Exception as exc: # noqa: BLE001 - top-level guard
683
+ print(f"Harness crashed: {type(exc).__name__}: {exc}", file=sys.stderr)
684
+ return EXIT_CRASH
685
+
686
+ # Output routing: when --json is set, JSON on stdout (machine-readable)
687
+ # and human summary on stderr (so operators still see what happened
688
+ # without polluting stdout). Without --json, human summary on stdout.
689
+ if args.json:
690
+ print(format_summary(result), file=sys.stderr)
691
+ print(json.dumps(result, indent=2, sort_keys=True))
692
+ else:
693
+ print(format_summary(result))
694
+
695
+ return _classify_exit(result)
696
+
697
+
698
+ if __name__ == "__main__":
699
+ sys.exit(main())