xithead 1.4.0 → 1.5.0

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 (661) hide show
  1. package/.actrc +14 -0
  2. package/.actrc.local.example +15 -0
  3. package/.changelog.md +2 -0
  4. package/.claude/agents/academic-anthropologist.md +125 -0
  5. package/.claude/agents/academic-geographer.md +127 -0
  6. package/.claude/agents/academic-historian.md +123 -0
  7. package/.claude/agents/academic-narratologist.md +118 -0
  8. package/.claude/agents/academic-psychologist.md +118 -0
  9. package/.claude/agents/academic-statistician.md +144 -0
  10. package/.claude/agents/accounts-payable-agent.md +205 -0
  11. package/.claude/agents/agentic-identity-trust.md +394 -0
  12. package/.claude/agents/agents-orchestrator.md +367 -0
  13. package/.claude/agents/automation-governance-architect.md +216 -0
  14. package/.claude/agents/blender-addon-engineer.md +243 -0
  15. package/.claude/agents/business-strategist.md +488 -0
  16. package/.claude/agents/change-management-consultant.md +497 -0
  17. package/.claude/agents/chief-financial-officer.md +388 -0
  18. package/.claude/agents/corporate-training-designer.md +192 -0
  19. package/.claude/agents/customer-service.md +398 -0
  20. package/.claude/agents/customer-success-manager.md +460 -0
  21. package/.claude/agents/data-consolidation-agent.md +60 -0
  22. package/.claude/agents/data-privacy-officer.md +412 -0
  23. package/.claude/agents/design-brand-guardian.md +322 -0
  24. package/.claude/agents/design-image-prompt-engineer.md +236 -0
  25. package/.claude/agents/design-inclusive-visuals-specialist.md +73 -0
  26. package/.claude/agents/design-persona-walkthrough.md +272 -0
  27. package/.claude/agents/design-ui-designer.md +386 -0
  28. package/.claude/agents/design-ui-finish-gate-reviewer.md +217 -0
  29. package/.claude/agents/design-ux-architect.md +482 -0
  30. package/.claude/agents/design-ux-researcher.md +329 -0
  31. package/.claude/agents/design-visual-storyteller.md +149 -0
  32. package/.claude/agents/design-whimsy-injector.md +460 -0
  33. package/.claude/agents/economy-designer.md +156 -0
  34. package/.claude/agents/engineering-ai-data-remediation-engineer.md +211 -0
  35. package/.claude/agents/engineering-ai-engineer.md +146 -0
  36. package/.claude/agents/engineering-api-platform-engineer.md +181 -0
  37. package/.claude/agents/engineering-ats-validator-architect.md +383 -0
  38. package/.claude/agents/engineering-autonomous-optimization-architect.md +121 -0
  39. package/.claude/agents/engineering-backend-architect.md +255 -0
  40. package/.claude/agents/engineering-china-network-engineer.md +252 -0
  41. package/.claude/agents/engineering-cms-developer.md +536 -0
  42. package/.claude/agents/engineering-code-reviewer.md +76 -0
  43. package/.claude/agents/engineering-codebase-onboarding-engineer.md +173 -0
  44. package/.claude/agents/engineering-data-engineer.md +349 -0
  45. package/.claude/agents/engineering-data-visualization-engineer.md +151 -0
  46. package/.claude/agents/engineering-database-optimizer.md +188 -0
  47. package/.claude/agents/engineering-database-reliability-engineer.md +201 -0
  48. package/.claude/agents/engineering-desktop-app-engineer.md +209 -0
  49. package/.claude/agents/engineering-developer-tooling-engineer.md +153 -0
  50. package/.claude/agents/engineering-devops-automator.md +385 -0
  51. package/.claude/agents/engineering-drupal-performance.md +347 -0
  52. package/.claude/agents/engineering-drupal-shopping-cart.md +360 -0
  53. package/.claude/agents/engineering-electrical-engineer.md +575 -0
  54. package/.claude/agents/engineering-email-intelligence-engineer.md +390 -0
  55. package/.claude/agents/engineering-embedded-firmware-engineer.md +196 -0
  56. package/.claude/agents/engineering-feishu-integration-developer.md +606 -0
  57. package/.claude/agents/engineering-filament-optimization-specialist.md +283 -0
  58. package/.claude/agents/engineering-finops-engineer.md +164 -0
  59. package/.claude/agents/engineering-frontend-developer.md +257 -0
  60. package/.claude/agents/engineering-gaussdb-expert.md +334 -0
  61. package/.claude/agents/engineering-git-workflow-master.md +98 -0
  62. package/.claude/agents/engineering-i18n-engineer.md +214 -0
  63. package/.claude/agents/engineering-identity-access-engineer.md +217 -0
  64. package/.claude/agents/engineering-incident-response-commander.md +444 -0
  65. package/.claude/agents/engineering-iot-fleet-engineer.md +148 -0
  66. package/.claude/agents/engineering-it-service-manager.md +561 -0
  67. package/.claude/agents/engineering-knowledge-graph-engineer.md +372 -0
  68. package/.claude/agents/engineering-llm-post-training-engineer.md +166 -0
  69. package/.claude/agents/engineering-minimal-change-engineer.md +207 -0
  70. package/.claude/agents/engineering-mobile-app-builder.md +493 -0
  71. package/.claude/agents/engineering-mobile-release-engineer.md +164 -0
  72. package/.claude/agents/engineering-multi-agent-systems-architect.md +600 -0
  73. package/.claude/agents/engineering-network-engineer.md +245 -0
  74. package/.claude/agents/engineering-orgscript-engineer.md +113 -0
  75. package/.claude/agents/engineering-payments-billing-engineer.md +228 -0
  76. package/.claude/agents/engineering-pdf-engine-architect.md +696 -0
  77. package/.claude/agents/engineering-platform-engineer.md +270 -0
  78. package/.claude/agents/engineering-privacy-engineer.md +152 -0
  79. package/.claude/agents/engineering-prompt-engineer.md +209 -0
  80. package/.claude/agents/engineering-rag-pipeline-engineer.md +450 -0
  81. package/.claude/agents/engineering-rapid-prototyper.md +466 -0
  82. package/.claude/agents/engineering-realtime-collaboration-engineer.md +200 -0
  83. package/.claude/agents/engineering-rust-refactoring-specialist.md +313 -0
  84. package/.claude/agents/engineering-search-relevance-engineer.md +237 -0
  85. package/.claude/agents/engineering-section-508-specialist.md +339 -0
  86. package/.claude/agents/engineering-senior-developer.md +176 -0
  87. package/.claude/agents/engineering-servicenow-developer-mentor.md +180 -0
  88. package/.claude/agents/engineering-software-architect.md +112 -0
  89. package/.claude/agents/engineering-solidity-smart-contract-engineer.md +522 -0
  90. package/.claude/agents/engineering-sre.md +90 -0
  91. package/.claude/agents/engineering-technical-writer.md +393 -0
  92. package/.claude/agents/engineering-universal-document-compiler.md +370 -0
  93. package/.claude/agents/engineering-uswds-developer.md +340 -0
  94. package/.claude/agents/engineering-video-streaming-engineer.md +151 -0
  95. package/.claude/agents/engineering-voice-ai-integration-engineer.md +584 -0
  96. package/.claude/agents/engineering-webassembly-engineer.md +153 -0
  97. package/.claude/agents/engineering-wechat-mini-program-developer.md +356 -0
  98. package/.claude/agents/engineering-wordpress-performance.md +346 -0
  99. package/.claude/agents/engineering-wordpress-shopping-cart.md +346 -0
  100. package/.claude/agents/esg-sustainability-officer.md +396 -0
  101. package/.claude/agents/finance-bookkeeper-controller.md +260 -0
  102. package/.claude/agents/finance-financial-analyst.md +234 -0
  103. package/.claude/agents/finance-fpa-analyst.md +263 -0
  104. package/.claude/agents/finance-investment-researcher.md +272 -0
  105. package/.claude/agents/finance-tax-strategist.md +239 -0
  106. package/.claude/agents/game-audio-engineer.md +264 -0
  107. package/.claude/agents/game-designer.md +167 -0
  108. package/.claude/agents/gis-3d-scene-developer.md +111 -0
  109. package/.claude/agents/gis-analyst.md +91 -0
  110. package/.claude/agents/gis-bim-specialist.md +108 -0
  111. package/.claude/agents/gis-cartography-designer.md +150 -0
  112. package/.claude/agents/gis-drone-reality-mapping.md +120 -0
  113. package/.claude/agents/gis-geoai-ml-engineer.md +105 -0
  114. package/.claude/agents/gis-geoprocessing-specialist.md +97 -0
  115. package/.claude/agents/gis-qa-engineer.md +133 -0
  116. package/.claude/agents/gis-solution-engineer.md +101 -0
  117. package/.claude/agents/gis-spatial-data-engineer.md +97 -0
  118. package/.claude/agents/gis-spatial-data-scientist.md +111 -0
  119. package/.claude/agents/gis-technical-consultant.md +86 -0
  120. package/.claude/agents/gis-web-gis-developer.md +108 -0
  121. package/.claude/agents/godot-gameplay-scripter.md +338 -0
  122. package/.claude/agents/godot-multiplayer-engineer.md +301 -0
  123. package/.claude/agents/godot-shader-developer.md +267 -0
  124. package/.claude/agents/government-digital-presales-consultant.md +363 -0
  125. package/.claude/agents/grant-writer.md +511 -0
  126. package/.claude/agents/healthcare-aging-parent-care-companion.md +414 -0
  127. package/.claude/agents/healthcare-clinical-evidence-agent.md +231 -0
  128. package/.claude/agents/healthcare-customer-service.md +389 -0
  129. package/.claude/agents/healthcare-innovation-strategist.md +433 -0
  130. package/.claude/agents/healthcare-marketing-compliance.md +395 -0
  131. package/.claude/agents/healthcare-sovereign-health-systems-agent.md +312 -0
  132. package/.claude/agents/hospitality-guest-services.md +603 -0
  133. package/.claude/agents/hr-onboarding.md +451 -0
  134. package/.claude/agents/identity-graph-operator.md +303 -0
  135. package/.claude/agents/language-translator.md +264 -0
  136. package/.claude/agents/legal-billing-time-tracking.md +569 -0
  137. package/.claude/agents/legal-client-intake.md +492 -0
  138. package/.claude/agents/legal-document-review.md +454 -0
  139. package/.claude/agents/level-designer.md +208 -0
  140. package/.claude/agents/loan-officer-assistant.md +555 -0
  141. package/.claude/agents/lsp-index-engineer.md +320 -0
  142. package/.claude/agents/ma-integration-manager.md +427 -0
  143. package/.claude/agents/macos-spatial-metal-engineer.md +337 -0
  144. package/.claude/agents/marketing-aeo-foundations.md +264 -0
  145. package/.claude/agents/marketing-agentic-search-optimizer.md +279 -0
  146. package/.claude/agents/marketing-ai-citation-strategist.md +172 -0
  147. package/.claude/agents/marketing-app-store-optimizer.md +321 -0
  148. package/.claude/agents/marketing-baidu-seo-specialist.md +226 -0
  149. package/.claude/agents/marketing-bilibili-content-strategist.md +199 -0
  150. package/.claude/agents/marketing-book-co-author.md +110 -0
  151. package/.claude/agents/marketing-carousel-growth-engine.md +204 -0
  152. package/.claude/agents/marketing-china-ecommerce-operator.md +283 -0
  153. package/.claude/agents/marketing-china-market-localization-strategist.md +283 -0
  154. package/.claude/agents/marketing-content-creator.md +54 -0
  155. package/.claude/agents/marketing-cross-border-ecommerce.md +259 -0
  156. package/.claude/agents/marketing-developer-community-builder.md +285 -0
  157. package/.claude/agents/marketing-douyin-strategist.md +149 -0
  158. package/.claude/agents/marketing-email-strategist.md +249 -0
  159. package/.claude/agents/marketing-global-podcast-strategist.md +206 -0
  160. package/.claude/agents/marketing-growth-hacker.md +54 -0
  161. package/.claude/agents/marketing-instagram-curator.md +113 -0
  162. package/.claude/agents/marketing-kuaishou-strategist.md +223 -0
  163. package/.claude/agents/marketing-linkedin-content-creator.md +214 -0
  164. package/.claude/agents/marketing-livestream-commerce-coach.md +305 -0
  165. package/.claude/agents/marketing-multi-platform-publisher.md +217 -0
  166. package/.claude/agents/marketing-podcast-strategist.md +277 -0
  167. package/.claude/agents/marketing-pr-communications-manager.md +473 -0
  168. package/.claude/agents/marketing-private-domain-operator.md +308 -0
  169. package/.claude/agents/marketing-reddit-community-builder.md +123 -0
  170. package/.claude/agents/marketing-seo-specialist.md +370 -0
  171. package/.claude/agents/marketing-short-video-editing-coach.md +412 -0
  172. package/.claude/agents/marketing-social-media-strategist.md +125 -0
  173. package/.claude/agents/marketing-tiktok-strategist.md +125 -0
  174. package/.claude/agents/marketing-twitter-engager.md +126 -0
  175. package/.claude/agents/marketing-video-optimization-specialist.md +119 -0
  176. package/.claude/agents/marketing-wechat-official-account.md +145 -0
  177. package/.claude/agents/marketing-weibo-strategist.md +240 -0
  178. package/.claude/agents/marketing-x-twitter-intelligence-analyst.md +161 -0
  179. package/.claude/agents/marketing-xiaohongshu-specialist.md +138 -0
  180. package/.claude/agents/marketing-zhihu-strategist.md +162 -0
  181. package/.claude/agents/medical-billing-coding-specialist.md +491 -0
  182. package/.claude/agents/narrative-designer.md +243 -0
  183. package/.claude/agents/operations-manager.md +399 -0
  184. package/.claude/agents/organizational-psychologist.md +391 -0
  185. package/.claude/agents/paid-media-auditor.md +71 -0
  186. package/.claude/agents/paid-media-creative-strategist.md +71 -0
  187. package/.claude/agents/paid-media-paid-social-strategist.md +71 -0
  188. package/.claude/agents/paid-media-ppc-strategist.md +71 -0
  189. package/.claude/agents/paid-media-programmatic-buyer.md +71 -0
  190. package/.claude/agents/paid-media-search-query-analyst.md +71 -0
  191. package/.claude/agents/paid-media-tracking-specialist.md +71 -0
  192. package/.claude/agents/personal-growth-mentor.md +159 -0
  193. package/.claude/agents/product-behavioral-nudge-engine.md +83 -0
  194. package/.claude/agents/product-dx-engineer.md +332 -0
  195. package/.claude/agents/product-feedback-synthesizer.md +119 -0
  196. package/.claude/agents/product-manager.md +469 -0
  197. package/.claude/agents/product-sprint-prioritizer.md +154 -0
  198. package/.claude/agents/product-trend-researcher.md +159 -0
  199. package/.claude/agents/project-management-experiment-tracker.md +198 -0
  200. package/.claude/agents/project-management-jira-workflow-steward.md +233 -0
  201. package/.claude/agents/project-management-meeting-notes-specialist.md +95 -0
  202. package/.claude/agents/project-management-project-shepherd.md +194 -0
  203. package/.claude/agents/project-management-studio-operations.md +200 -0
  204. package/.claude/agents/project-management-studio-producer.md +203 -0
  205. package/.claude/agents/project-manager-senior.md +135 -0
  206. package/.claude/agents/real-estate-buyer-seller.md +596 -0
  207. package/.claude/agents/recruitment-specialist.md +515 -0
  208. package/.claude/agents/report-distribution-agent.md +65 -0
  209. package/.claude/agents/research-synthesist.md +136 -0
  210. package/.claude/agents/resume-tailor.md +230 -0
  211. package/.claude/agents/retail-customer-returns.md +566 -0
  212. package/.claude/agents/roblox-avatar-creator.md +297 -0
  213. package/.claude/agents/roblox-experience-designer.md +306 -0
  214. package/.claude/agents/roblox-systems-scripter.md +332 -0
  215. package/.claude/agents/sales-account-strategist.md +227 -0
  216. package/.claude/agents/sales-coach.md +271 -0
  217. package/.claude/agents/sales-data-extraction-agent.md +67 -0
  218. package/.claude/agents/sales-deal-strategist.md +180 -0
  219. package/.claude/agents/sales-discovery-coach.md +225 -0
  220. package/.claude/agents/sales-engineer.md +182 -0
  221. package/.claude/agents/sales-offer-lead-gen-strategist.md +257 -0
  222. package/.claude/agents/sales-outbound-strategist.md +201 -0
  223. package/.claude/agents/sales-outreach.md +425 -0
  224. package/.claude/agents/sales-pipeline-analyst.md +267 -0
  225. package/.claude/agents/sales-proposal-strategist.md +217 -0
  226. package/.claude/agents/security-ai-generated-code-auditor.md +207 -0
  227. package/.claude/agents/security-appsec-engineer.md +536 -0
  228. package/.claude/agents/security-architect.md +307 -0
  229. package/.claude/agents/security-blockchain-security-auditor.md +482 -0
  230. package/.claude/agents/security-cloud-security-architect.md +576 -0
  231. package/.claude/agents/security-compliance-auditor.md +158 -0
  232. package/.claude/agents/security-incident-responder.md +450 -0
  233. package/.claude/agents/security-penetration-tester.md +399 -0
  234. package/.claude/agents/security-secrets-credential-engineer.md +189 -0
  235. package/.claude/agents/security-senior-secops.md +760 -0
  236. package/.claude/agents/security-threat-detection-engineer.md +553 -0
  237. package/.claude/agents/security-threat-intelligence-analyst.md +661 -0
  238. package/.claude/agents/specialized-chief-of-staff.md +279 -0
  239. package/.claude/agents/specialized-civil-engineer.md +356 -0
  240. package/.claude/agents/specialized-codebase-archaeologist.md +341 -0
  241. package/.claude/agents/specialized-cultural-intelligence-strategist.md +88 -0
  242. package/.claude/agents/specialized-developer-advocate.md +317 -0
  243. package/.claude/agents/specialized-document-generator.md +55 -0
  244. package/.claude/agents/specialized-fedramp-rmf-compliance.md +378 -0
  245. package/.claude/agents/specialized-focus-music-architect.md +175 -0
  246. package/.claude/agents/specialized-french-consulting-market.md +194 -0
  247. package/.claude/agents/specialized-korean-business-navigator.md +216 -0
  248. package/.claude/agents/specialized-master-plan-architect.md +157 -0
  249. package/.claude/agents/specialized-mcp-builder.md +260 -0
  250. package/.claude/agents/specialized-model-qa.md +528 -0
  251. package/.claude/agents/specialized-pricing-analyst.md +243 -0
  252. package/.claude/agents/specialized-salesforce-architect.md +182 -0
  253. package/.claude/agents/specialized-strategy-duel-agent.md +130 -0
  254. package/.claude/agents/specialized-workflow-architect.md +597 -0
  255. package/.claude/agents/study-abroad-advisor.md +282 -0
  256. package/.claude/agents/supply-chain-strategist.md +591 -0
  257. package/.claude/agents/support-analytics-reporter.md +387 -0
  258. package/.claude/agents/support-executive-summary-generator.md +212 -0
  259. package/.claude/agents/support-finance-tracker.md +480 -0
  260. package/.claude/agents/support-infrastructure-maintainer.md +628 -0
  261. package/.claude/agents/support-legal-compliance-checker.md +591 -0
  262. package/.claude/agents/support-support-responder.md +607 -0
  263. package/.claude/agents/technical-artist.md +233 -0
  264. package/.claude/agents/terminal-integration-specialist.md +70 -0
  265. package/.claude/agents/testing-accessibility-auditor.md +327 -0
  266. package/.claude/agents/testing-api-tester.md +334 -0
  267. package/.claude/agents/testing-evidence-collector.md +210 -0
  268. package/.claude/agents/testing-performance-benchmarker.md +283 -0
  269. package/.claude/agents/testing-reality-checker.md +249 -0
  270. package/.claude/agents/testing-test-automation-engineer.md +196 -0
  271. package/.claude/agents/testing-test-results-analyzer.md +330 -0
  272. package/.claude/agents/testing-tool-evaluator.md +416 -0
  273. package/.claude/agents/testing-workflow-optimizer.md +463 -0
  274. package/.claude/agents/unity-architect.md +271 -0
  275. package/.claude/agents/unity-editor-tool-developer.md +310 -0
  276. package/.claude/agents/unity-multiplayer-engineer.md +323 -0
  277. package/.claude/agents/unity-shader-graph-artist.md +269 -0
  278. package/.claude/agents/unreal-multiplayer-architect.md +364 -0
  279. package/.claude/agents/unreal-systems-engineer.md +322 -0
  280. package/.claude/agents/unreal-technical-artist.md +256 -0
  281. package/.claude/agents/unreal-world-builder.md +273 -0
  282. package/.claude/agents/visionos-spatial-engineer.md +54 -0
  283. package/.claude/agents/xr-cockpit-interaction-specialist.md +32 -0
  284. package/.claude/agents/xr-immersive-developer.md +32 -0
  285. package/.claude/agents/xr-interface-architect.md +32 -0
  286. package/.claude/agents/zk-steward.md +211 -0
  287. package/.claude-plugin/marketplace.json +30 -0
  288. package/.commitlintrc.json +26 -0
  289. package/.devcontainer/Dockerfile +24 -0
  290. package/.devcontainer/devcontainer.json +70 -0
  291. package/.devcontainer/docker-compose.memory.yml +42 -0
  292. package/.devcontainer/memory-stack/devcontainer.json +84 -0
  293. package/.devcontainer/post-create.sh +83 -0
  294. package/.dockerignore +23 -0
  295. package/.env.act.example +15 -0
  296. package/.env.example +171 -0
  297. package/.eslintrc.json +16 -0
  298. package/.git-blame-ignore-revs +10 -0
  299. package/.gitattributes +2 -0
  300. package/.gitguardian.yaml +50 -0
  301. package/.githooks/pre-commit +6 -0
  302. package/.pre-commit-config.yaml +30 -0
  303. package/.release-please-config-xithead.json +22 -0
  304. package/.release-please-config.json +44 -0
  305. package/.release-please-manifest-xithead.json +3 -0
  306. package/.release-please-manifest.json +3 -0
  307. package/CODE_OF_CONDUCT.md +133 -0
  308. package/CONTRIBUTING.md +133 -0
  309. package/Cargo.lock +5557 -0
  310. package/Cargo.toml +121 -0
  311. package/Dockerfile +38 -0
  312. package/Dockerfile.proxy +48 -0
  313. package/ENTERPRISE.md +5 -0
  314. package/FEATURES_ADVANCED.md +311 -0
  315. package/Headroom-2.gif +0 -0
  316. package/HeadroomDemo-Fast.gif +0 -0
  317. package/MANIFEST.in +4 -0
  318. package/MODERNIZATION_GUIDE.md +358 -0
  319. package/Makefile +140 -0
  320. package/NOTICE +43 -0
  321. package/NPM_TOKEN_SETUP.md +81 -0
  322. package/PR.md +170 -0
  323. package/PUBLISH.md +77 -0
  324. package/README.md +108 -72
  325. package/README_FRONTEND.md +196 -0
  326. package/REALIGNMENT/00-overview.md +53 -0
  327. package/REALIGNMENT/01-bug-list.md +421 -0
  328. package/REALIGNMENT/02-architecture.md +322 -0
  329. package/REALIGNMENT/03-phase-A-lockdown.md +420 -0
  330. package/REALIGNMENT/04-phase-B-live-zone.md +470 -0
  331. package/REALIGNMENT/05-phase-C-rust-proxy.md +329 -0
  332. package/REALIGNMENT/06-phase-D-bedrock-vertex.md +222 -0
  333. package/REALIGNMENT/07-phase-E-cache-stabilization.md +338 -0
  334. package/REALIGNMENT/08-phase-F-auth-mode.md +254 -0
  335. package/REALIGNMENT/09-phase-G-rtk-observability.md +194 -0
  336. package/REALIGNMENT/10-phase-H-python-retirement.md +214 -0
  337. package/REALIGNMENT/11-phase-I-test-infra.md +385 -0
  338. package/REALIGNMENT/12-decisions-needed.md +196 -0
  339. package/REALIGNMENT/INDEX.md +82 -0
  340. package/REFACTORING_CAMPAIGN.md +277 -0
  341. package/RESTRUCTURE_PLAN.md +100 -0
  342. package/RUST_DEV.md +361 -0
  343. package/SECURITY.md +65 -0
  344. package/SETUP_AUTO_PUBLISH.md +164 -0
  345. package/TESTING-copilot-subscription.md +153 -0
  346. package/app/api/config/route.ts +22 -0
  347. package/app/api/export/route.ts +83 -0
  348. package/app/api/models/route.ts +12 -0
  349. package/app/api/stats/route.ts +46 -0
  350. package/app/dashboard/page.tsx +445 -0
  351. package/app/globals.css +35 -0
  352. package/app/installation/page.tsx +293 -0
  353. package/app/layout.tsx +35 -0
  354. package/app/master-design-system.css +2076 -0
  355. package/app/master-design-system.source.css +8 -0
  356. package/app/page.tsx +187 -0
  357. package/app/rechtliches/agb/page.tsx +165 -0
  358. package/app/rechtliches/datenschutz/page.tsx +128 -0
  359. package/app/rechtliches/impressum/page.tsx +122 -0
  360. package/app/rechtliches/widerruf/page.tsx +185 -0
  361. package/bin/xithead.js +264 -0
  362. package/codecov.yml +34 -0
  363. package/components/layout/AppShell.tsx +25 -0
  364. package/components/layout/Footer.tsx +120 -0
  365. package/components/layout/Header.tsx +145 -0
  366. package/components/marketing/LegalHighlights.tsx +45 -0
  367. package/components/marketing/LegalPageShell.tsx +49 -0
  368. package/components/marketing/LegalPanel.tsx +41 -0
  369. package/components/marketing/index.ts +3 -0
  370. package/crates/headroom-core/Cargo.toml +165 -0
  371. package/crates/headroom-core/benches/auth_mode.rs +74 -0
  372. package/crates/headroom-core/benches/ccr_store.rs +224 -0
  373. package/crates/headroom-core/benches/tokenizer.rs +52 -0
  374. package/crates/headroom-core/config/pipeline.toml +151 -0
  375. package/crates/headroom-core/proptest-regressions/transforms/tag_protector.txt +9 -0
  376. package/crates/headroom-core/src/auth_mode.rs +250 -0
  377. package/crates/headroom-core/src/cache_control.rs +414 -0
  378. package/crates/headroom-core/src/ccr/backends/in_memory.rs +317 -0
  379. package/crates/headroom-core/src/ccr/backends/mod.rs +152 -0
  380. package/crates/headroom-core/src/ccr/backends/redis.rs +146 -0
  381. package/crates/headroom-core/src/ccr/backends/sqlite.rs +205 -0
  382. package/crates/headroom-core/src/ccr/mod.rs +119 -0
  383. package/crates/headroom-core/src/compression_policy.rs +505 -0
  384. package/crates/headroom-core/src/lib.rs +33 -0
  385. package/crates/headroom-core/src/relevance/base.rs +139 -0
  386. package/crates/headroom-core/src/relevance/bm25.rs +385 -0
  387. package/crates/headroom-core/src/relevance/embedding.rs +354 -0
  388. package/crates/headroom-core/src/relevance/hybrid.rs +364 -0
  389. package/crates/headroom-core/src/relevance/mod.rs +64 -0
  390. package/crates/headroom-core/src/signals/keyword_detector.rs +433 -0
  391. package/crates/headroom-core/src/signals/line_importance.rs +84 -0
  392. package/crates/headroom-core/src/signals/mod.rs +61 -0
  393. package/crates/headroom-core/src/signals/tiered.rs +141 -0
  394. package/crates/headroom-core/src/tokenizer/estimator.rs +152 -0
  395. package/crates/headroom-core/src/tokenizer/hf_impl.rs +314 -0
  396. package/crates/headroom-core/src/tokenizer/mod.rs +56 -0
  397. package/crates/headroom-core/src/tokenizer/registry.rs +342 -0
  398. package/crates/headroom-core/src/tokenizer/tiktoken_impl.rs +265 -0
  399. package/crates/headroom-core/src/transforms/adaptive_sizer.rs +610 -0
  400. package/crates/headroom-core/src/transforms/anchor_selector.rs +1189 -0
  401. package/crates/headroom-core/src/transforms/content_detector.rs +769 -0
  402. package/crates/headroom-core/src/transforms/detection.rs +222 -0
  403. package/crates/headroom-core/src/transforms/diff_compressor.rs +1685 -0
  404. package/crates/headroom-core/src/transforms/live_zone.rs +2967 -0
  405. package/crates/headroom-core/src/transforms/log_compressor.rs +1295 -0
  406. package/crates/headroom-core/src/transforms/magika_detector.rs +395 -0
  407. package/crates/headroom-core/src/transforms/mod.rs +64 -0
  408. package/crates/headroom-core/src/transforms/pipeline/config.rs +331 -0
  409. package/crates/headroom-core/src/transforms/pipeline/mod.rs +103 -0
  410. package/crates/headroom-core/src/transforms/pipeline/offloads/diff_noise.rs +524 -0
  411. package/crates/headroom-core/src/transforms/pipeline/offloads/diff_offload.rs +279 -0
  412. package/crates/headroom-core/src/transforms/pipeline/offloads/json_offload.rs +400 -0
  413. package/crates/headroom-core/src/transforms/pipeline/offloads/log_offload.rs +284 -0
  414. package/crates/headroom-core/src/transforms/pipeline/offloads/mod.rs +34 -0
  415. package/crates/headroom-core/src/transforms/pipeline/offloads/search_offload.rs +331 -0
  416. package/crates/headroom-core/src/transforms/pipeline/orchestrator.rs +848 -0
  417. package/crates/headroom-core/src/transforms/pipeline/reformats/json_minifier.rs +175 -0
  418. package/crates/headroom-core/src/transforms/pipeline/reformats/log_template.rs +545 -0
  419. package/crates/headroom-core/src/transforms/pipeline/reformats/mod.rs +12 -0
  420. package/crates/headroom-core/src/transforms/pipeline/traits.rs +338 -0
  421. package/crates/headroom-core/src/transforms/recommendations.rs +329 -0
  422. package/crates/headroom-core/src/transforms/safety.rs +215 -0
  423. package/crates/headroom-core/src/transforms/search_compressor.rs +902 -0
  424. package/crates/headroom-core/src/transforms/smart_crusher/analyzer.rs +1262 -0
  425. package/crates/headroom-core/src/transforms/smart_crusher/anchors.rs +407 -0
  426. package/crates/headroom-core/src/transforms/smart_crusher/builder.rs +263 -0
  427. package/crates/headroom-core/src/transforms/smart_crusher/classifier.rs +214 -0
  428. package/crates/headroom-core/src/transforms/smart_crusher/compaction/classifier.rs +283 -0
  429. package/crates/headroom-core/src/transforms/smart_crusher/compaction/compactor.rs +733 -0
  430. package/crates/headroom-core/src/transforms/smart_crusher/compaction/formatter.rs +961 -0
  431. package/crates/headroom-core/src/transforms/smart_crusher/compaction/ir.rs +252 -0
  432. package/crates/headroom-core/src/transforms/smart_crusher/compaction/mod.rs +127 -0
  433. package/crates/headroom-core/src/transforms/smart_crusher/compaction/walker.rs +397 -0
  434. package/crates/headroom-core/src/transforms/smart_crusher/config.rs +173 -0
  435. package/crates/headroom-core/src/transforms/smart_crusher/constraints.rs +159 -0
  436. package/crates/headroom-core/src/transforms/smart_crusher/crusher.rs +1665 -0
  437. package/crates/headroom-core/src/transforms/smart_crusher/crushers.rs +865 -0
  438. package/crates/headroom-core/src/transforms/smart_crusher/error_keywords.rs +77 -0
  439. package/crates/headroom-core/src/transforms/smart_crusher/field_detect.rs +393 -0
  440. package/crates/headroom-core/src/transforms/smart_crusher/hashing.rs +72 -0
  441. package/crates/headroom-core/src/transforms/smart_crusher/mod.rs +81 -0
  442. package/crates/headroom-core/src/transforms/smart_crusher/observer.rs +66 -0
  443. package/crates/headroom-core/src/transforms/smart_crusher/orchestration.rs +459 -0
  444. package/crates/headroom-core/src/transforms/smart_crusher/outliers.rs +507 -0
  445. package/crates/headroom-core/src/transforms/smart_crusher/planning.rs +904 -0
  446. package/crates/headroom-core/src/transforms/smart_crusher/statistics.rs +510 -0
  447. package/crates/headroom-core/src/transforms/smart_crusher/stats_math.rs +287 -0
  448. package/crates/headroom-core/src/transforms/smart_crusher/traits.rs +203 -0
  449. package/crates/headroom-core/src/transforms/smart_crusher/types.rs +263 -0
  450. package/crates/headroom-core/src/transforms/tag_protector.rs +1272 -0
  451. package/crates/headroom-core/src/transforms/unidiff_detector.rs +232 -0
  452. package/crates/headroom-parity/Cargo.toml +26 -0
  453. package/crates/headroom-parity/examples/diff_fixture.rs +66 -0
  454. package/crates/headroom-parity/src/bin/parity_run.rs +78 -0
  455. package/crates/headroom-parity/src/lib.rs +613 -0
  456. package/crates/headroom-proxy/Cargo.toml +119 -0
  457. package/crates/headroom-proxy/data/model_prices_and_context_window.json +39767 -0
  458. package/crates/headroom-proxy/src/bedrock/auth_mode_layer.rs +192 -0
  459. package/crates/headroom-proxy/src/bedrock/envelope.rs +239 -0
  460. package/crates/headroom-proxy/src/bedrock/eventstream.rs +769 -0
  461. package/crates/headroom-proxy/src/bedrock/eventstream_to_sse.rs +459 -0
  462. package/crates/headroom-proxy/src/bedrock/invoke.rs +735 -0
  463. package/crates/headroom-proxy/src/bedrock/invoke_streaming.rs +1098 -0
  464. package/crates/headroom-proxy/src/bedrock/mod.rs +66 -0
  465. package/crates/headroom-proxy/src/bedrock/sigv4.rs +324 -0
  466. package/crates/headroom-proxy/src/bedrock/vendor.rs +82 -0
  467. package/crates/headroom-proxy/src/cache_stabilization/anthropic_cache_control.rs +698 -0
  468. package/crates/headroom-proxy/src/cache_stabilization/drift_detector.rs +683 -0
  469. package/crates/headroom-proxy/src/cache_stabilization/mod.rs +61 -0
  470. package/crates/headroom-proxy/src/cache_stabilization/openai_cache_key.rs +600 -0
  471. package/crates/headroom-proxy/src/cache_stabilization/tool_def_normalize.rs +514 -0
  472. package/crates/headroom-proxy/src/cache_stabilization/volatile_detector.rs +720 -0
  473. package/crates/headroom-proxy/src/compression/anthropic.rs +92 -0
  474. package/crates/headroom-proxy/src/compression/live_zone_anthropic.rs +1311 -0
  475. package/crates/headroom-proxy/src/compression/live_zone_openai.rs +660 -0
  476. package/crates/headroom-proxy/src/compression/live_zone_responses.rs +678 -0
  477. package/crates/headroom-proxy/src/compression/mod.rs +127 -0
  478. package/crates/headroom-proxy/src/compression/model_limits.rs +211 -0
  479. package/crates/headroom-proxy/src/config.rs +646 -0
  480. package/crates/headroom-proxy/src/error.rs +69 -0
  481. package/crates/headroom-proxy/src/handlers/chat_completions.rs +100 -0
  482. package/crates/headroom-proxy/src/handlers/conversations.rs +241 -0
  483. package/crates/headroom-proxy/src/handlers/mod.rs +13 -0
  484. package/crates/headroom-proxy/src/handlers/responses.rs +256 -0
  485. package/crates/headroom-proxy/src/headers.rs +288 -0
  486. package/crates/headroom-proxy/src/health.rs +41 -0
  487. package/crates/headroom-proxy/src/lib.rs +21 -0
  488. package/crates/headroom-proxy/src/main.rs +141 -0
  489. package/crates/headroom-proxy/src/observability/cache_hit_rate.rs +340 -0
  490. package/crates/headroom-proxy/src/observability/compression_ratio.rs +158 -0
  491. package/crates/headroom-proxy/src/observability/metric_names.rs +174 -0
  492. package/crates/headroom-proxy/src/observability/mod.rs +68 -0
  493. package/crates/headroom-proxy/src/observability/prometheus.rs +394 -0
  494. package/crates/headroom-proxy/src/observability/proxy_metrics.rs +368 -0
  495. package/crates/headroom-proxy/src/proxy.rs +1619 -0
  496. package/crates/headroom-proxy/src/responses_items.rs +565 -0
  497. package/crates/headroom-proxy/src/sse/anthropic.rs +415 -0
  498. package/crates/headroom-proxy/src/sse/framing.rs +366 -0
  499. package/crates/headroom-proxy/src/sse/mod.rs +40 -0
  500. package/crates/headroom-proxy/src/sse/openai_chat.rs +231 -0
  501. package/crates/headroom-proxy/src/sse/openai_responses.rs +458 -0
  502. package/crates/headroom-proxy/src/vertex/adc.rs +315 -0
  503. package/crates/headroom-proxy/src/vertex/envelope.rs +167 -0
  504. package/crates/headroom-proxy/src/vertex/mod.rs +277 -0
  505. package/crates/headroom-proxy/src/vertex/raw_predict.rs +490 -0
  506. package/crates/headroom-proxy/src/vertex/stream_raw_predict.rs +49 -0
  507. package/crates/headroom-proxy/src/websocket.rs +246 -0
  508. package/crates/headroom-py/Cargo.toml +37 -0
  509. package/crates/headroom-py/build.rs +77 -0
  510. package/crates/headroom-py/glibc_compat.c +170 -0
  511. package/crates/headroom-py/src/lib.rs +1655 -0
  512. package/deny.toml +32 -0
  513. package/design-system/base.css +127 -0
  514. package/design-system/components.css +1943 -0
  515. package/design-system/fonts.css +17 -0
  516. package/design-system/tailwind-preset.js +95 -0
  517. package/design-system/tokens.css +48 -0
  518. package/design-system/utilities.css +53 -0
  519. package/docker/differential-network-capture/Dockerfile.runner +14 -0
  520. package/docker/differential-network-capture/docker-compose.yml +142 -0
  521. package/docker/differential-network-capture/run-claude-lane.sh +24 -0
  522. package/docker/docker-compose.native.yml +44 -0
  523. package/docker-bake.hcl +88 -0
  524. package/docker-compose.yml +80 -0
  525. package/e2e/_lib/make_shim.ps1 +24 -0
  526. package/e2e/_lib/make_shim.sh +28 -0
  527. package/e2e/docker-native-install.sh +120 -0
  528. package/e2e/init/Dockerfile +79 -0
  529. package/e2e/wrap/Dockerfile +115 -0
  530. package/examples/07-context-compression.ipynb +279 -0
  531. package/examples/deployment/macos-launchagent/com.headroom.proxy.plist.template +65 -0
  532. package/examples/deployment/macos-launchagent/install.sh +227 -0
  533. package/examples/deployment/macos-launchagent/shell-integration.sh +74 -0
  534. package/examples/deployment/macos-launchagent/uninstall.sh +145 -0
  535. package/headroom-savings.png +0 -0
  536. package/headroom_learn.gif +0 -0
  537. package/lib/config/index.ts +12 -0
  538. package/lib/hooks/index.ts +4 -0
  539. package/lib/hooks/use-mounted.ts +13 -0
  540. package/lib/hooks/use-session.ts +34 -0
  541. package/lib/hooks/use-settings.ts +49 -0
  542. package/lib/utils/index.ts +1 -0
  543. package/lib/utils/settings.ts +162 -0
  544. package/lib/utils/utils.ts +6 -0
  545. package/llms.txt +67 -0
  546. package/middleware.ts +26 -0
  547. package/mkdocs.yml +136 -0
  548. package/next-env.d.ts +7 -0
  549. package/next.config.ts +12 -0
  550. package/npm/bin/xithead.js +366 -366
  551. package/npm/bin/xtream-head.js +366 -0
  552. package/npm/index.d.ts +57 -57
  553. package/npm/index.js +139 -139
  554. package/npm/package.json +55 -54
  555. package/npm/postinstall.js +43 -43
  556. package/package.json +58 -36
  557. package/plugins/headroom-agent-hooks/.claude-plugin/plugin.json +17 -0
  558. package/plugins/headroom-agent-hooks/hooks/hooks.json +29 -0
  559. package/plugins/headroom-oauth2/LICENSE +3 -0
  560. package/plugins/headroom-oauth2/SPEC.md +115 -0
  561. package/plugins/headroom-oauth2/pyproject.toml +48 -0
  562. package/plugins/hermes/headroom_retrieve/plugin.yaml +6 -0
  563. package/plugins/openclaw/hook-shim/HOOK.md +21 -0
  564. package/plugins/openclaw/hook-shim/handler.js +3 -0
  565. package/plugins/openclaw/openclaw.plugin.json +98 -0
  566. package/plugins/openclaw/package-lock.json +2692 -0
  567. package/plugins/openclaw/package.json +54 -0
  568. package/plugins/openclaw/prepare-dist.mjs +56 -0
  569. package/plugins/openclaw/src/convert.ts +418 -0
  570. package/plugins/openclaw/src/engine.ts +284 -0
  571. package/plugins/openclaw/src/gateway-config.ts +143 -0
  572. package/plugins/openclaw/src/index.ts +11 -0
  573. package/plugins/openclaw/src/plugin/index.ts +98 -0
  574. package/plugins/openclaw/src/proxy-manager.ts +477 -0
  575. package/plugins/openclaw/src/tools/headroom-retrieve.ts +76 -0
  576. package/plugins/openclaw/test/convert.test.ts +96 -0
  577. package/plugins/openclaw/test/engine-normalization.test.ts +21 -0
  578. package/plugins/openclaw/test/engine.test.ts +101 -0
  579. package/plugins/openclaw/test/gateway-config.test.ts +278 -0
  580. package/plugins/openclaw/test/plugin-runtime-routing.test.ts +141 -0
  581. package/plugins/openclaw/test/proxy-manager.test.ts +343 -0
  582. package/plugins/openclaw/tsup.config.ts +9 -0
  583. package/postcss.config.mjs +7 -0
  584. package/pyproject.toml +438 -0
  585. package/rust-toolchain.toml +16 -0
  586. package/sdk/typescript/examples/basic-compress.ts +64 -0
  587. package/sdk/typescript/examples/ccr-retrieve.ts +80 -0
  588. package/sdk/typescript/examples/hooks-custom-compression.ts +117 -0
  589. package/sdk/typescript/examples/middleware-composition.ts +59 -0
  590. package/sdk/typescript/examples/multi-provider.ts +53 -0
  591. package/sdk/typescript/examples/openai-anthropic-adapters.ts +73 -0
  592. package/sdk/typescript/examples/shared-context-multi-agent.ts +74 -0
  593. package/sdk/typescript/examples/simulation-dry-run.ts +80 -0
  594. package/sdk/typescript/examples/streaming-chat.ts +71 -0
  595. package/sdk/typescript/examples/structured-output.ts +99 -0
  596. package/sdk/typescript/examples/tool-calling-agent.ts +86 -0
  597. package/sdk/typescript/examples/with-headroom-vercel.ts +57 -0
  598. package/sdk/typescript/package-lock.json +3437 -0
  599. package/sdk/typescript/package.json +108 -0
  600. package/sdk/typescript/src/adapters/anthropic.ts +218 -0
  601. package/sdk/typescript/src/adapters/gemini.ts +83 -0
  602. package/sdk/typescript/src/adapters/openai.ts +77 -0
  603. package/sdk/typescript/src/adapters/vercel-ai.ts +131 -0
  604. package/sdk/typescript/src/client.ts +632 -0
  605. package/sdk/typescript/src/compress.ts +87 -0
  606. package/sdk/typescript/src/errors.ts +114 -0
  607. package/sdk/typescript/src/hooks.ts +113 -0
  608. package/sdk/typescript/src/index.ts +140 -0
  609. package/sdk/typescript/src/paths.ts +272 -0
  610. package/sdk/typescript/src/shared-context.ts +188 -0
  611. package/sdk/typescript/src/simulate.ts +52 -0
  612. package/sdk/typescript/src/types/config.ts +183 -0
  613. package/sdk/typescript/src/types/models.ts +314 -0
  614. package/sdk/typescript/src/types.ts +139 -0
  615. package/sdk/typescript/src/utils/case.ts +34 -0
  616. package/sdk/typescript/src/utils/format.ts +480 -0
  617. package/sdk/typescript/src/utils/stream.ts +50 -0
  618. package/sdk/typescript/test/adapters/anthropic.test.ts +217 -0
  619. package/sdk/typescript/test/adapters/gemini.test.ts +131 -0
  620. package/sdk/typescript/test/adapters/openai.test.ts +174 -0
  621. package/sdk/typescript/test/adapters/vercel-ai.test.ts +306 -0
  622. package/sdk/typescript/test/client-expanded.test.ts +333 -0
  623. package/sdk/typescript/test/client.test.ts +266 -0
  624. package/sdk/typescript/test/compress.test.ts +118 -0
  625. package/sdk/typescript/test/config.test.ts +275 -0
  626. package/sdk/typescript/test/errors.test.ts +169 -0
  627. package/sdk/typescript/test/format-integration.test.ts +252 -0
  628. package/sdk/typescript/test/hooks.test.ts +265 -0
  629. package/sdk/typescript/test/integration.test.ts +249 -0
  630. package/sdk/typescript/test/mdx-examples.test.ts +253 -0
  631. package/sdk/typescript/test/models.test.ts +318 -0
  632. package/sdk/typescript/test/parity.test.ts +337 -0
  633. package/sdk/typescript/test/paths.test.ts +447 -0
  634. package/sdk/typescript/test/shared-context.test.ts +245 -0
  635. package/sdk/typescript/test/simulate.test.ts +84 -0
  636. package/sdk/typescript/test/types.test.ts +244 -0
  637. package/sdk/typescript/test/utils/case.test.ts +129 -0
  638. package/sdk/typescript/test/utils/detect-format.test.ts +133 -0
  639. package/sdk/typescript/test/utils/format.test.ts +434 -0
  640. package/sdk/typescript/test/vercel-ai-e2e.test.ts +179 -0
  641. package/sdk/typescript/tsup.config.ts +17 -0
  642. package/tailwind.master.config.cjs +47 -0
  643. package/types/api.ts +12 -0
  644. package/types/config.ts +9 -0
  645. package/types/index.ts +2 -0
  646. package/uv.lock +6951 -0
  647. package/xithead.egg-info/PKG-INFO +22 -0
  648. package/xithead.egg-info/SOURCES.txt +16 -0
  649. package/xithead.egg-info/dependency_links.txt +1 -0
  650. package/xithead.egg-info/entry_points.txt +2 -0
  651. package/xithead.egg-info/requires.txt +10 -0
  652. package/xithead.egg-info/top_level.txt +2 -0
  653. package/xithead.ps1 +136 -0
  654. package/xithead.sh +129 -0
  655. package/xithead_dist/pyproject.toml +39 -0
  656. package/xithead_dist/xithead.egg-info/PKG-INFO +22 -0
  657. package/xithead_dist/xithead.egg-info/SOURCES.txt +16 -0
  658. package/xithead_dist/xithead.egg-info/dependency_links.txt +1 -0
  659. package/xithead_dist/xithead.egg-info/entry_points.txt +3 -0
  660. package/xithead_dist/xithead.egg-info/requires.txt +10 -0
  661. package/xithead_dist/xithead.egg-info/top_level.txt +2 -0
@@ -0,0 +1,340 @@
1
+ //! Per-session cache-hit-rate observability — Phase G PR-G3.
2
+ //!
3
+ //! # The H-blocker metric
4
+ //!
5
+ //! Phase H ("retire the Python proxy") depends on this metric to
6
+ //! confirm parity between the Rust proxy and the soon-to-retire
7
+ //! Python proxy during canary. The acceptance gate in
8
+ //! `REALIGNMENT/10-phase-H-python-retirement.md:11-12` reads
9
+ //! `cache_hit_rate ≥ Python baseline; no 5xx regressions in 24h`.
10
+ //! That assertion is meaningless without this histogram.
11
+ //!
12
+ //! # Definition
13
+ //!
14
+ //! For every completed request session we observe one sample on the
15
+ //! `proxy_cache_hit_rate_per_session` histogram whose value is:
16
+ //!
17
+ //! ```text
18
+ //! cache_read_input_tokens
19
+ //! ───────────────────────
20
+ //! total_input_tokens
21
+ //! ```
22
+ //!
23
+ //! `total_input_tokens` is the full denominator each provider
24
+ //! exposes on the `usage` payload (input + cache_read +
25
+ //! cache_creation), NOT the "billable" input that excludes cache
26
+ //! hits. Defining the denominator this way means the metric stays
27
+ //! meaningful across providers and stays in [0, 1].
28
+ //!
29
+ //! # When called
30
+ //!
31
+ //! - Anthropic: at `message_delta` (which carries the final `usage`).
32
+ //! - OpenAI Chat: on the final usage chunk (when
33
+ //! `stream_options.include_usage = true`; otherwise no sample is
34
+ //! emitted — the absence is itself a signal).
35
+ //! - OpenAI Responses: at `response.completed`.
36
+ //!
37
+ //! # Cardinality
38
+ //!
39
+ //! One label only: `provider ∈ {anthropic, openai_chat, openai_responses}`.
40
+ //! The metric is *intentionally* low-cardinality — the H1 canary
41
+ //! looks at fleet-wide hit rate, not per-model. Per-model breakdown
42
+ //! lives in the per-provider info logs we already emit.
43
+ //!
44
+ //! # Bucket selection
45
+ //!
46
+ //! Bucket boundaries are picked so the histogram discriminates the
47
+ //! "no cache" → "cache landed" transition with high resolution near
48
+ //! 0 and the "high-hit-rate" regime (where cache is paying for
49
+ //! itself) with high resolution near 1. The middle is coarser because
50
+ //! ~50% hit-rate is operationally uninteresting — either the cache
51
+ //! is working or it isn't.
52
+
53
+ use std::sync::OnceLock;
54
+
55
+ use prometheus::{HistogramOpts, HistogramVec, Registry};
56
+
57
+ use super::metric_names::{
58
+ LABEL_PROVIDER, METRIC_PROXY_CACHE_HIT_RATE_PER_SESSION,
59
+ METRIC_PROXY_CACHE_HIT_RATE_PER_SESSION_HELP,
60
+ };
61
+
62
+ /// Histogram buckets in [0, 1]. Tighter near 0 (so a "barely any
63
+ /// cache hit" stays distinguishable from a true zero) and near 1
64
+ /// (so a "near-perfect cache" stays distinguishable from a real
65
+ /// 100% hit). The middle band is intentionally coarser.
66
+ pub(super) const CACHE_HIT_RATE_BUCKETS: &[f64] =
67
+ &[0.0, 0.01, 0.05, 0.1, 0.25, 0.5, 0.75, 0.9, 0.95, 0.99, 1.0];
68
+
69
+ /// Provider label vocabulary. Kept here (rather than scattered
70
+ /// across emit sites) so the cardinality budget is reviewable in one
71
+ /// place per realignment build-constraint "configurable + scalable".
72
+ pub mod provider {
73
+ pub const ANTHROPIC: &str = "anthropic";
74
+ pub const OPENAI_CHAT: &str = "openai_chat";
75
+ pub const OPENAI_RESPONSES: &str = "openai_responses";
76
+ }
77
+
78
+ /// `proxy_cache_hit_rate_per_session{provider}` — initialised on
79
+ /// first call from `register_in`.
80
+ pub fn histogram(registry: &Registry) -> &'static HistogramVec {
81
+ static HIST: OnceLock<HistogramVec> = OnceLock::new();
82
+ HIST.get_or_init(|| {
83
+ let opts = HistogramOpts::new(
84
+ METRIC_PROXY_CACHE_HIT_RATE_PER_SESSION,
85
+ METRIC_PROXY_CACHE_HIT_RATE_PER_SESSION_HELP,
86
+ )
87
+ .buckets(CACHE_HIT_RATE_BUCKETS.to_vec());
88
+ let hist = HistogramVec::new(opts, &[LABEL_PROVIDER])
89
+ .expect("proxy_cache_hit_rate_per_session descriptor is well-formed");
90
+ registry
91
+ .register(Box::new(hist.clone()))
92
+ .expect("proxy_cache_hit_rate_per_session registers exactly once");
93
+ hist
94
+ })
95
+ }
96
+
97
+ /// Compute the per-session cache hit rate given the three counters
98
+ /// most providers expose on `usage`. Returns `None` when the
99
+ /// denominator is zero (no input tokens at all — typically a
100
+ /// degenerate request such as an empty messages array), so callers
101
+ /// can choose to skip the observation rather than divide-by-zero.
102
+ ///
103
+ /// Per realignment build-constraint "no silent fallbacks", a
104
+ /// zero-denominator request is *NOT* coerced to `0.0`; it returns
105
+ /// `None` so the emit-site can log + skip instead of polluting the
106
+ /// histogram with synthesised samples.
107
+ pub fn compute_hit_rate(
108
+ input_tokens: u64,
109
+ cache_read_input_tokens: u64,
110
+ cache_creation_input_tokens: u64,
111
+ ) -> Option<f64> {
112
+ let denom = input_tokens
113
+ .saturating_add(cache_read_input_tokens)
114
+ .saturating_add(cache_creation_input_tokens);
115
+ if denom == 0 {
116
+ return None;
117
+ }
118
+ Some(cache_read_input_tokens as f64 / denom as f64)
119
+ }
120
+
121
+ /// H2 gate: should we observe a cache-hit-rate sample for this
122
+ /// Anthropic session?
123
+ ///
124
+ /// Returns `Some(rate)` ONLY when the stream completed cleanly
125
+ /// (`state.status == MessageStop`) AND the denominator is non-zero.
126
+ /// A client disconnect mid-stream closes the channel too — without
127
+ /// this gate we'd observe a half-finished session that has only
128
+ /// `message_start` usage and pollute the histogram with garbage.
129
+ ///
130
+ /// Extracted from `proxy.rs::run_sse_state_machine` so the H2
131
+ /// contract is unit-testable independent of the global Prometheus
132
+ /// registry (which parallel tests share).
133
+ pub fn compute_anthropic_session_hit_rate(
134
+ state: &crate::sse::anthropic::AnthropicStreamState,
135
+ ) -> Option<f64> {
136
+ if state.status != crate::sse::anthropic::StreamStatus::MessageStop {
137
+ return None;
138
+ }
139
+ compute_hit_rate(
140
+ state.usage.input_tokens,
141
+ state.usage.cache_read_input_tokens,
142
+ state.usage.cache_creation_input_tokens,
143
+ )
144
+ }
145
+
146
+ /// Observe one per-session sample.
147
+ ///
148
+ /// `provider` MUST be one of the [`provider`] constants — callers
149
+ /// from the SSE state machine pass the matching string verbatim. We
150
+ /// do not validate the label here because the cardinality is bounded
151
+ /// by the static call sites; an invalid label would be a bug, not a
152
+ /// runtime mismatch.
153
+ ///
154
+ /// M3 fix: NaN / non-finite inputs are loud-skipped instead of
155
+ /// silently observed. `f64::clamp(0.0, 1.0)` returns NaN when the
156
+ /// input is NaN, so the prior implementation could pollute the
157
+ /// histogram with NaN samples in release builds (the debug_assert
158
+ /// was compiled out). Per "no silent fallbacks", an unexpected NaN
159
+ /// surfaces in the logs rather than getting eaten.
160
+ pub fn observe(provider: &'static str, request_id: &str, hit_rate: f64) {
161
+ if !hit_rate.is_finite() {
162
+ tracing::warn!(
163
+ event = "cache_hit_rate_non_finite",
164
+ metric = METRIC_PROXY_CACHE_HIT_RATE_PER_SESSION,
165
+ provider = provider,
166
+ request_id = %request_id,
167
+ hit_rate = hit_rate,
168
+ "refusing to observe a non-finite cache hit rate; this is a caller bug"
169
+ );
170
+ return;
171
+ }
172
+ debug_assert!(
173
+ (0.0..=1.0).contains(&hit_rate),
174
+ "cache hit rate must be in [0.0, 1.0]; got {hit_rate}"
175
+ );
176
+ // After the is_finite guard, clamp can only normalise legitimate
177
+ // edge-of-range floats (1.0 + epsilon etc.) and never produces NaN.
178
+ let clamped = hit_rate.clamp(0.0, 1.0);
179
+ histogram(super::prometheus::registry())
180
+ .with_label_values(&[provider])
181
+ .observe(clamped);
182
+ tracing::debug!(
183
+ event = "metric_recorded",
184
+ metric = METRIC_PROXY_CACHE_HIT_RATE_PER_SESSION,
185
+ provider = provider,
186
+ request_id = %request_id,
187
+ hit_rate = clamped,
188
+ "observed proxy_cache_hit_rate_per_session"
189
+ );
190
+ }
191
+
192
+ #[cfg(test)]
193
+ mod tests {
194
+ use super::*;
195
+
196
+ #[test]
197
+ fn hit_rate_zero_when_no_cache_reads() {
198
+ let r = compute_hit_rate(100, 0, 0).unwrap();
199
+ assert!((r - 0.0).abs() < f64::EPSILON);
200
+ }
201
+
202
+ #[test]
203
+ fn hit_rate_one_when_all_reads_are_cache_hits() {
204
+ // Edge case: input_tokens == 0 means upstream charged us
205
+ // nothing new — every input came from cache.
206
+ let r = compute_hit_rate(0, 1000, 0).unwrap();
207
+ assert!((r - 1.0).abs() < f64::EPSILON);
208
+ }
209
+
210
+ #[test]
211
+ fn hit_rate_split_three_ways() {
212
+ // 50 fresh input, 50 cache_read, 50 cache_creation → 50/150.
213
+ let r = compute_hit_rate(50, 50, 50).unwrap();
214
+ assert!((r - (1.0 / 3.0)).abs() < 1e-9);
215
+ }
216
+
217
+ #[test]
218
+ fn hit_rate_none_on_empty_request() {
219
+ // Degenerate: no tokens at all. Caller should skip the
220
+ // observation, not coerce to 0.0.
221
+ assert!(compute_hit_rate(0, 0, 0).is_none());
222
+ }
223
+
224
+ #[test]
225
+ fn observe_nan_skipped_loudly() {
226
+ // M3: a NaN input must NOT reach the histogram. The
227
+ // pre-fix code clamped via `f64::clamp(0.0, 1.0)` which
228
+ // returns NaN for NaN input — a NaN sample in release
229
+ // builds was the bug. After the fix we log + skip.
230
+ // The histogram count for this synthetic provider stays
231
+ // at whatever it was before the call.
232
+ let label = "test_nan_provider_v1";
233
+ // Drive a guaranteed-clean session count via a real
234
+ // observation, then push a NaN and assert no count move.
235
+ observe(label, "req-nan-baseline", 0.5);
236
+ let before = histogram(super::super::prometheus::registry())
237
+ .with_label_values(&[label])
238
+ .get_sample_count();
239
+ observe(label, "req-nan-attempt", f64::NAN);
240
+ let after = histogram(super::super::prometheus::registry())
241
+ .with_label_values(&[label])
242
+ .get_sample_count();
243
+ assert_eq!(
244
+ before, after,
245
+ "NaN must not be observed; expected count unchanged from {before} to {after}"
246
+ );
247
+ }
248
+
249
+ #[test]
250
+ fn h2_aborted_anthropic_stream_returns_none() {
251
+ // H2: a stream that closes without `message_stop` (Open
252
+ // state) MUST NOT produce a sample, regardless of usage
253
+ // values.
254
+ use crate::sse::anthropic::{AnthropicStreamState, StreamStatus, UsageBuilder};
255
+ let state = AnthropicStreamState {
256
+ status: StreamStatus::Open,
257
+ usage: UsageBuilder {
258
+ input_tokens: 800,
259
+ cache_read_input_tokens: 200,
260
+ output_tokens: 50,
261
+ cache_creation_input_tokens: 0,
262
+ },
263
+ ..Default::default()
264
+ };
265
+ assert!(
266
+ compute_anthropic_session_hit_rate(&state).is_none(),
267
+ "H2 gate must skip emission for non-completed stream"
268
+ );
269
+ }
270
+
271
+ #[test]
272
+ fn h2_errored_anthropic_stream_returns_none() {
273
+ // H2: an Errored stream is also not "completed cleanly" —
274
+ // skip the observation.
275
+ use crate::sse::anthropic::{AnthropicStreamState, StreamStatus, UsageBuilder};
276
+ let state = AnthropicStreamState {
277
+ status: StreamStatus::Errored,
278
+ usage: UsageBuilder {
279
+ input_tokens: 800,
280
+ cache_read_input_tokens: 200,
281
+ output_tokens: 50,
282
+ cache_creation_input_tokens: 0,
283
+ },
284
+ ..Default::default()
285
+ };
286
+ assert!(
287
+ compute_anthropic_session_hit_rate(&state).is_none(),
288
+ "H2 gate must skip emission for errored stream"
289
+ );
290
+ }
291
+
292
+ #[test]
293
+ fn h2_completed_anthropic_stream_returns_rate() {
294
+ // H2 positive case: MessageStop + non-zero usage → return
295
+ // the rate so the caller can observe it.
296
+ use crate::sse::anthropic::{AnthropicStreamState, StreamStatus, UsageBuilder};
297
+ let state = AnthropicStreamState {
298
+ status: StreamStatus::MessageStop,
299
+ usage: UsageBuilder {
300
+ input_tokens: 800,
301
+ cache_read_input_tokens: 200,
302
+ output_tokens: 50,
303
+ cache_creation_input_tokens: 0,
304
+ },
305
+ ..Default::default()
306
+ };
307
+ let rate = compute_anthropic_session_hit_rate(&state).expect("completed stream emits");
308
+ // 200 / (800 + 200 + 0) = 0.2
309
+ assert!((rate - 0.2).abs() < 1e-9);
310
+ }
311
+
312
+ #[test]
313
+ fn h2_completed_but_zero_denominator_returns_none() {
314
+ // Even on a completed stream, a zero-token request returns
315
+ // None — per "no silent fallbacks", no synthesised 0.0.
316
+ use crate::sse::anthropic::{AnthropicStreamState, StreamStatus, UsageBuilder};
317
+ let state = AnthropicStreamState {
318
+ status: StreamStatus::MessageStop,
319
+ usage: UsageBuilder::default(),
320
+ ..Default::default()
321
+ };
322
+ assert!(compute_anthropic_session_hit_rate(&state).is_none());
323
+ }
324
+
325
+ #[test]
326
+ fn observe_infinity_skipped_loudly() {
327
+ // Same contract for +/- infinity.
328
+ let label = "test_inf_provider_v1";
329
+ observe(label, "req-inf-baseline", 0.5);
330
+ let before = histogram(super::super::prometheus::registry())
331
+ .with_label_values(&[label])
332
+ .get_sample_count();
333
+ observe(label, "req-pos-inf", f64::INFINITY);
334
+ observe(label, "req-neg-inf", f64::NEG_INFINITY);
335
+ let after = histogram(super::super::prometheus::registry())
336
+ .with_label_values(&[label])
337
+ .get_sample_count();
338
+ assert_eq!(before, after);
339
+ }
340
+ }
@@ -0,0 +1,158 @@
1
+ //! Per-block compression-ratio observability — Phase G PR-G3.
2
+ //!
3
+ //! # Definition
4
+ //!
5
+ //! For every block the live-zone dispatcher successfully shrinks, we
6
+ //! observe one sample on the `proxy_compression_ratio_by_strategy`
7
+ //! histogram. The sample value is the ratio
8
+ //! `compressed_tokens / original_tokens` (in [0, 1)), so smaller =
9
+ //! better. The metric is labelled by:
10
+ //!
11
+ //! - `strategy` — the compressor identifier (`smart_crusher`,
12
+ //! `log_compressor`, `search_compressor`, `diff_compressor`,
13
+ //! `e3_anthropic_cache_control`, `e1_tool_array_sort`, …). The
14
+ //! label vocabulary is bounded by the static `&'static str` set
15
+ //! the compressors return on their `BlockAction::Compressed`
16
+ //! manifests — never a customer-controlled value.
17
+ //! - `content_type` — the detection-tier output for the block
18
+ //! (`source_code`, `log`, `search_output`, `diff`, `text`, …).
19
+ //! Cardinality bounded by `headroom_core::transforms::ContentType`.
20
+ //!
21
+ //! Counter twin: `proxy_compression_rejected_by_token_check_total{strategy}`
22
+ //! captures the "compressor ran but didn't shrink the token count"
23
+ //! case so dashboards can attribute the absence of histogram samples
24
+ //! to legitimate rejection rather than to a missing call site.
25
+ //!
26
+ //! # Bucket selection
27
+ //!
28
+ //! Buckets are tighter near 0 (the "aggressive shrink" tail dashboard
29
+ //! operators care about), wider in the middle. Anything above 1 would
30
+ //! be a tokenizer regression — `BlockAction::Compressed` enforces
31
+ //! `compressed_tokens < original_tokens`, so the histogram should
32
+ //! never see a sample > 0.99 in practice.
33
+
34
+ use std::sync::OnceLock;
35
+
36
+ use prometheus::{HistogramOpts, HistogramVec, IntCounterVec, Opts, Registry};
37
+
38
+ use super::metric_names::{
39
+ LABEL_CONTENT_TYPE, LABEL_STRATEGY, METRIC_PROXY_COMPRESSION_RATIO_BY_STRATEGY,
40
+ METRIC_PROXY_COMPRESSION_RATIO_BY_STRATEGY_HELP,
41
+ METRIC_PROXY_COMPRESSION_REJECTED_BY_TOKEN_CHECK_TOTAL,
42
+ METRIC_PROXY_COMPRESSION_REJECTED_BY_TOKEN_CHECK_TOTAL_HELP,
43
+ };
44
+
45
+ /// Histogram buckets in [0, 1). Tight at the aggressive end (≤0.25
46
+ /// means we kept ≤25% of the original tokens), coarser at the upper
47
+ /// end where a measurement is operationally indistinguishable from
48
+ /// "barely any shrink".
49
+ pub(super) const COMPRESSION_RATIO_BUCKETS: &[f64] =
50
+ &[0.05, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.75, 0.9, 0.99];
51
+
52
+ /// `proxy_compression_ratio_by_strategy{strategy, content_type}`.
53
+ pub fn ratio_histogram(registry: &Registry) -> &'static HistogramVec {
54
+ static HIST: OnceLock<HistogramVec> = OnceLock::new();
55
+ HIST.get_or_init(|| {
56
+ let opts = HistogramOpts::new(
57
+ METRIC_PROXY_COMPRESSION_RATIO_BY_STRATEGY,
58
+ METRIC_PROXY_COMPRESSION_RATIO_BY_STRATEGY_HELP,
59
+ )
60
+ .buckets(COMPRESSION_RATIO_BUCKETS.to_vec());
61
+ let hist = HistogramVec::new(opts, &[LABEL_STRATEGY, LABEL_CONTENT_TYPE])
62
+ .expect("proxy_compression_ratio_by_strategy descriptor is well-formed");
63
+ registry
64
+ .register(Box::new(hist.clone()))
65
+ .expect("proxy_compression_ratio_by_strategy registers exactly once");
66
+ hist
67
+ })
68
+ }
69
+
70
+ /// `proxy_compression_rejected_by_token_check_total{strategy}`.
71
+ pub fn rejected_counter(registry: &Registry) -> &'static IntCounterVec {
72
+ static COUNTER: OnceLock<IntCounterVec> = OnceLock::new();
73
+ COUNTER.get_or_init(|| {
74
+ let opts = Opts::new(
75
+ METRIC_PROXY_COMPRESSION_REJECTED_BY_TOKEN_CHECK_TOTAL,
76
+ METRIC_PROXY_COMPRESSION_REJECTED_BY_TOKEN_CHECK_TOTAL_HELP,
77
+ );
78
+ let counter = IntCounterVec::new(opts, &[LABEL_STRATEGY])
79
+ .expect("proxy_compression_rejected_by_token_check_total descriptor is well-formed");
80
+ registry
81
+ .register(Box::new(counter.clone()))
82
+ .expect("proxy_compression_rejected_by_token_check_total registers exactly once");
83
+ counter
84
+ })
85
+ }
86
+
87
+ /// Observe one compression-ratio sample. `strategy` and `content_type`
88
+ /// must be `&'static str` (bounded by compiler-known compressor +
89
+ /// content-type enum sets).
90
+ pub fn observe_ratio(
91
+ strategy: &'static str,
92
+ content_type: &str,
93
+ original_tokens: usize,
94
+ compressed_tokens: usize,
95
+ ) {
96
+ if original_tokens == 0 {
97
+ // Per realignment build-constraint "no silent fallbacks": a
98
+ // zero-denominator block would synthesise a `NaN` sample we
99
+ // can't observe meaningfully. Loud-log and skip.
100
+ tracing::warn!(
101
+ event = "compression_ratio_zero_denominator",
102
+ strategy = strategy,
103
+ content_type = %content_type,
104
+ compressed_tokens = compressed_tokens,
105
+ "skipping proxy_compression_ratio_by_strategy observation: \
106
+ original_tokens == 0 (would divide by zero)"
107
+ );
108
+ return;
109
+ }
110
+ let ratio = (compressed_tokens as f64) / (original_tokens as f64);
111
+ ratio_histogram(super::prometheus::registry())
112
+ .with_label_values(&[strategy, content_type])
113
+ .observe(ratio);
114
+ tracing::debug!(
115
+ event = "metric_recorded",
116
+ metric = METRIC_PROXY_COMPRESSION_RATIO_BY_STRATEGY,
117
+ strategy = strategy,
118
+ content_type = %content_type,
119
+ original_tokens = original_tokens,
120
+ compressed_tokens = compressed_tokens,
121
+ ratio = ratio,
122
+ "observed proxy_compression_ratio_by_strategy"
123
+ );
124
+ }
125
+
126
+ /// Increment the rejection counter for a compressor that ran but did
127
+ /// not produce a token-smaller output.
128
+ pub fn record_rejected_by_token_check(strategy: &'static str) {
129
+ rejected_counter(super::prometheus::registry())
130
+ .with_label_values(&[strategy])
131
+ .inc();
132
+ tracing::debug!(
133
+ event = "metric_recorded",
134
+ metric = METRIC_PROXY_COMPRESSION_REJECTED_BY_TOKEN_CHECK_TOTAL,
135
+ strategy = strategy,
136
+ "incremented proxy_compression_rejected_by_token_check_total"
137
+ );
138
+ }
139
+
140
+ #[cfg(test)]
141
+ mod tests {
142
+ use super::*;
143
+
144
+ #[test]
145
+ fn zero_original_tokens_skips_observation() {
146
+ // Calling observe with original_tokens=0 must not panic and
147
+ // must not divide-by-zero; the warn log is sufficient.
148
+ observe_ratio("smart_crusher", "text", 0, 0);
149
+ }
150
+
151
+ #[test]
152
+ fn ratio_50_percent_recorded() {
153
+ // Drive the metric so the family appears in scrapes; we
154
+ // exercise the path here, not the value (which is asserted
155
+ // via integration tests).
156
+ observe_ratio("test_strategy_50pct", "text", 200, 100);
157
+ }
158
+ }
@@ -0,0 +1,174 @@
1
+ //! Centralised metric-name + label-key constants — Phase G PR-G3.
2
+ //!
3
+ //! Realignment build-constraint "configurable: every metric name + label
4
+ //! vocabulary defined in one place" applies here. The Bedrock D3
5
+ //! metrics in [`super::prometheus`] predate this module; they keep
6
+ //! their inline literals (a churn-cost decision documented in the
7
+ //! PR-G3 commit) but every PR-G3 metric and its labels live here.
8
+ //!
9
+ //! # Naming convention
10
+ //!
11
+ //! - `METRIC_*` — the wire-name string. Prometheus convention:
12
+ //! `_total` for counters, `_seconds` / no suffix for histograms.
13
+ //! - `METRIC_*_HELP` — the HELP-line text used at registration. Kept
14
+ //! alongside the wire name so a rename catches both in one diff.
15
+ //! - `LABEL_*` — the label-key string. Reuse across metrics where
16
+ //! the dimension is the same (`provider`, `strategy`, …).
17
+
18
+ // ---------- proxy_cache_hit_rate_per_session ----------
19
+
20
+ pub const METRIC_PROXY_CACHE_HIT_RATE_PER_SESSION: &str = "proxy_cache_hit_rate_per_session";
21
+ pub const METRIC_PROXY_CACHE_HIT_RATE_PER_SESSION_HELP: &str =
22
+ "Per-session cache hit rate observed at the Rust proxy from \
23
+ usage.cache_read_input_tokens / (input + cache_read + cache_creation). \
24
+ Phase H canary gate: parity with the Python proxy baseline.";
25
+
26
+ // ---------- proxy_compression_ratio_by_strategy ----------
27
+
28
+ pub const METRIC_PROXY_COMPRESSION_RATIO_BY_STRATEGY: &str = "proxy_compression_ratio_by_strategy";
29
+ pub const METRIC_PROXY_COMPRESSION_RATIO_BY_STRATEGY_HELP: &str =
30
+ "Compression ratio (compressed_tokens / original_tokens) observed \
31
+ per block that was actually shrunk by the live-zone dispatcher. \
32
+ Labelled by strategy (smart_crusher/log_compressor/…) and \
33
+ detected content_type.";
34
+
35
+ // ---------- proxy_compression_rejected_by_token_check_total ----------
36
+
37
+ pub const METRIC_PROXY_COMPRESSION_REJECTED_BY_TOKEN_CHECK_TOTAL: &str =
38
+ "proxy_compression_rejected_by_token_check_total";
39
+ pub const METRIC_PROXY_COMPRESSION_REJECTED_BY_TOKEN_CHECK_TOTAL_HELP: &str =
40
+ "Count of compressor runs whose output failed the tokenizer-validated \
41
+ shrink check (compressed_tokens >= original_tokens). Surfaces 'we ran \
42
+ but kept the original' cases that would otherwise be invisible.";
43
+
44
+ // ---------- proxy_passthrough_bytes_modified_total ----------
45
+
46
+ pub const METRIC_PROXY_PASSTHROUGH_BYTES_MODIFIED_TOTAL: &str =
47
+ "proxy_passthrough_bytes_modified_total";
48
+ pub const METRIC_PROXY_PASSTHROUGH_BYTES_MODIFIED_TOTAL_HELP: &str =
49
+ "Bytes modified on a path that is supposed to passthrough verbatim. \
50
+ MUST stay 0 outside the compression-on hot path. Any non-zero rate \
51
+ fires the cache-safety alarm.";
52
+
53
+ // ---------- proxy_rate_limit_remaining_* ----------
54
+
55
+ pub const METRIC_PROXY_RATE_LIMIT_REMAINING_REQUESTS: &str = "proxy_rate_limit_remaining_requests";
56
+ pub const METRIC_PROXY_RATE_LIMIT_REMAINING_REQUESTS_HELP: &str =
57
+ "Upstream-reported remaining requests for the current window, \
58
+ extracted from rate-limit response headers (anthropic-ratelimit-* \
59
+ or x-ratelimit-*). Per-provider, per-window-bucket gauge.";
60
+
61
+ pub const METRIC_PROXY_RATE_LIMIT_REMAINING_TOKENS: &str = "proxy_rate_limit_remaining_tokens";
62
+ pub const METRIC_PROXY_RATE_LIMIT_REMAINING_TOKENS_HELP: &str =
63
+ "Upstream-reported remaining tokens for the current window, extracted \
64
+ from rate-limit response headers (anthropic-ratelimit-*-tokens or \
65
+ x-ratelimit-remaining-tokens).";
66
+
67
+ pub const METRIC_PROXY_RATE_LIMIT_REMAINING_INPUT_TOKENS: &str =
68
+ "proxy_rate_limit_remaining_input_tokens";
69
+ pub const METRIC_PROXY_RATE_LIMIT_REMAINING_INPUT_TOKENS_HELP: &str =
70
+ "Upstream-reported remaining INPUT tokens for the current window. \
71
+ Anthropic separates input and output token budgets in its \
72
+ ratelimit headers; this gauge tracks the input bucket.";
73
+
74
+ pub const METRIC_PROXY_RATE_LIMIT_REMAINING_OUTPUT_TOKENS: &str =
75
+ "proxy_rate_limit_remaining_output_tokens";
76
+ pub const METRIC_PROXY_RATE_LIMIT_REMAINING_OUTPUT_TOKENS_HELP: &str =
77
+ "Upstream-reported remaining OUTPUT tokens for the current window. \
78
+ Anthropic-only header on present providers.";
79
+
80
+ // ---------- proxy_service_tier_count_total ----------
81
+
82
+ pub const METRIC_PROXY_SERVICE_TIER_COUNT_TOTAL: &str = "proxy_service_tier_count_total";
83
+ pub const METRIC_PROXY_SERVICE_TIER_COUNT_TOTAL_HELP: &str =
84
+ "Count of requests/responses observed at the proxy, labelled by the \
85
+ OpenAI Responses service_tier the request resolved into (auto, \
86
+ default, flex, on_demand, priority).";
87
+
88
+ // ---------- proxy_response_status_count_total ----------
89
+
90
+ pub const METRIC_PROXY_RESPONSE_STATUS_COUNT_TOTAL: &str = "proxy_response_status_count_total";
91
+ pub const METRIC_PROXY_RESPONSE_STATUS_COUNT_TOTAL_HELP: &str =
92
+ "Count of OpenAI Responses outcomes labelled by terminal status \
93
+ (completed, incomplete, failed, cancelled, in_progress). \
94
+ 'incomplete' detail lands in the structured log paired with each \
95
+ increment.";
96
+
97
+ // Phase G PR-G3 remediation (C3 + C4): the metric-name constants
98
+ // for `proxy_image_generation_call_log_redacted_total`,
99
+ // `wrap_rtk_invocations_total`, and `wrap_rtk_tokens_saved_per_session`
100
+ // were removed because the underlying counters had no production
101
+ // emit site on the Rust side. The same metrics are exported by the
102
+ // Python proxy (`headroom/proxy/prometheus_metrics.py`) which is the
103
+ // natural owner: image redaction is a Python-proxy operation and RTK
104
+ // invocation tracking lives in the wrap CLI, both Python-side
105
+ // surfaces. See `docs/observability.md`.
106
+
107
+ // ---------- shared label keys ----------
108
+
109
+ pub const LABEL_PROVIDER: &str = "provider";
110
+ pub const LABEL_STRATEGY: &str = "strategy";
111
+ pub const LABEL_CONTENT_TYPE: &str = "content_type";
112
+ pub const LABEL_PATH: &str = "path";
113
+ pub const LABEL_TIER: &str = "tier";
114
+ pub const LABEL_STATUS: &str = "status";
115
+
116
+ // ---------- bounded label vocabularies ----------
117
+
118
+ /// OpenAI service-tier values per the Responses API spec
119
+ /// (`service_tier` field on the response object). The metric label
120
+ /// vocabulary is **strictly** this set plus a `"scale"` value
121
+ /// (documented in OpenAI's tier-pricing page) and a sentinel
122
+ /// `"other"` bucket for anything else, so a malicious client posting
123
+ /// `{"service_tier":"<random>"}` per request cannot blow up
124
+ /// cardinality.
125
+ pub mod service_tier {
126
+ pub const AUTO: &str = "auto";
127
+ pub const DEFAULT: &str = "default";
128
+ pub const FLEX: &str = "flex";
129
+ pub const ON_DEMAND: &str = "on_demand";
130
+ pub const PRIORITY: &str = "priority";
131
+ pub const SCALE: &str = "scale";
132
+ /// Sentinel for any unknown / unrecognised tier value. Prevents
133
+ /// label-cardinality DoS from arbitrary inbound JSON.
134
+ pub const OTHER: &str = "other";
135
+
136
+ /// Validate an inbound `service_tier` string against the bounded
137
+ /// vocabulary. Returns the matching `&'static` constant or
138
+ /// [`OTHER`] for any unrecognised value (with a tracing::warn so
139
+ /// wire-format drift is loud rather than silently bucketed).
140
+ ///
141
+ /// The matching is case-sensitive — the OpenAI spec is
142
+ /// case-sensitive on these strings; a case-different value is
143
+ /// treated as drift, not as the same tier.
144
+ pub fn validate(raw: &str) -> &'static str {
145
+ match raw {
146
+ AUTO => AUTO,
147
+ DEFAULT => DEFAULT,
148
+ FLEX => FLEX,
149
+ ON_DEMAND => ON_DEMAND,
150
+ PRIORITY => PRIORITY,
151
+ SCALE => SCALE,
152
+ _ => {
153
+ tracing::warn!(
154
+ event = "service_tier_unknown",
155
+ raw = %raw,
156
+ bucket = OTHER,
157
+ "unknown service_tier value bucketed to 'other' to bound cardinality"
158
+ );
159
+ OTHER
160
+ }
161
+ }
162
+ }
163
+ }
164
+
165
+ /// OpenAI Responses terminal-status vocabulary. `in_progress` is the
166
+ /// non-terminal entry — included so observers see a request that
167
+ /// closed mid-stream (we increment on the last status seen).
168
+ pub mod response_status {
169
+ pub const COMPLETED: &str = "completed";
170
+ pub const INCOMPLETE: &str = "incomplete";
171
+ pub const FAILED: &str = "failed";
172
+ pub const CANCELLED: &str = "cancelled";
173
+ pub const IN_PROGRESS: &str = "in_progress";
174
+ }