xithead 1.2.2 → 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 (659) 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 +58 -137
  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 +2 -2
  551. package/npm/bin/xtream-head.js +366 -0
  552. package/npm/index.js +18 -91
  553. package/npm/package.json +55 -0
  554. package/package.json +47 -42
  555. package/plugins/headroom-agent-hooks/.claude-plugin/plugin.json +17 -0
  556. package/plugins/headroom-agent-hooks/hooks/hooks.json +29 -0
  557. package/plugins/headroom-oauth2/LICENSE +3 -0
  558. package/plugins/headroom-oauth2/SPEC.md +115 -0
  559. package/plugins/headroom-oauth2/pyproject.toml +48 -0
  560. package/plugins/hermes/headroom_retrieve/plugin.yaml +6 -0
  561. package/plugins/openclaw/hook-shim/HOOK.md +21 -0
  562. package/plugins/openclaw/hook-shim/handler.js +3 -0
  563. package/plugins/openclaw/openclaw.plugin.json +98 -0
  564. package/plugins/openclaw/package-lock.json +2692 -0
  565. package/plugins/openclaw/package.json +54 -0
  566. package/plugins/openclaw/prepare-dist.mjs +56 -0
  567. package/plugins/openclaw/src/convert.ts +418 -0
  568. package/plugins/openclaw/src/engine.ts +284 -0
  569. package/plugins/openclaw/src/gateway-config.ts +143 -0
  570. package/plugins/openclaw/src/index.ts +11 -0
  571. package/plugins/openclaw/src/plugin/index.ts +98 -0
  572. package/plugins/openclaw/src/proxy-manager.ts +477 -0
  573. package/plugins/openclaw/src/tools/headroom-retrieve.ts +76 -0
  574. package/plugins/openclaw/test/convert.test.ts +96 -0
  575. package/plugins/openclaw/test/engine-normalization.test.ts +21 -0
  576. package/plugins/openclaw/test/engine.test.ts +101 -0
  577. package/plugins/openclaw/test/gateway-config.test.ts +278 -0
  578. package/plugins/openclaw/test/plugin-runtime-routing.test.ts +141 -0
  579. package/plugins/openclaw/test/proxy-manager.test.ts +343 -0
  580. package/plugins/openclaw/tsup.config.ts +9 -0
  581. package/postcss.config.mjs +7 -0
  582. package/pyproject.toml +438 -0
  583. package/rust-toolchain.toml +16 -0
  584. package/sdk/typescript/examples/basic-compress.ts +64 -0
  585. package/sdk/typescript/examples/ccr-retrieve.ts +80 -0
  586. package/sdk/typescript/examples/hooks-custom-compression.ts +117 -0
  587. package/sdk/typescript/examples/middleware-composition.ts +59 -0
  588. package/sdk/typescript/examples/multi-provider.ts +53 -0
  589. package/sdk/typescript/examples/openai-anthropic-adapters.ts +73 -0
  590. package/sdk/typescript/examples/shared-context-multi-agent.ts +74 -0
  591. package/sdk/typescript/examples/simulation-dry-run.ts +80 -0
  592. package/sdk/typescript/examples/streaming-chat.ts +71 -0
  593. package/sdk/typescript/examples/structured-output.ts +99 -0
  594. package/sdk/typescript/examples/tool-calling-agent.ts +86 -0
  595. package/sdk/typescript/examples/with-headroom-vercel.ts +57 -0
  596. package/sdk/typescript/package-lock.json +3437 -0
  597. package/sdk/typescript/package.json +108 -0
  598. package/sdk/typescript/src/adapters/anthropic.ts +218 -0
  599. package/sdk/typescript/src/adapters/gemini.ts +83 -0
  600. package/sdk/typescript/src/adapters/openai.ts +77 -0
  601. package/sdk/typescript/src/adapters/vercel-ai.ts +131 -0
  602. package/sdk/typescript/src/client.ts +632 -0
  603. package/sdk/typescript/src/compress.ts +87 -0
  604. package/sdk/typescript/src/errors.ts +114 -0
  605. package/sdk/typescript/src/hooks.ts +113 -0
  606. package/sdk/typescript/src/index.ts +140 -0
  607. package/sdk/typescript/src/paths.ts +272 -0
  608. package/sdk/typescript/src/shared-context.ts +188 -0
  609. package/sdk/typescript/src/simulate.ts +52 -0
  610. package/sdk/typescript/src/types/config.ts +183 -0
  611. package/sdk/typescript/src/types/models.ts +314 -0
  612. package/sdk/typescript/src/types.ts +139 -0
  613. package/sdk/typescript/src/utils/case.ts +34 -0
  614. package/sdk/typescript/src/utils/format.ts +480 -0
  615. package/sdk/typescript/src/utils/stream.ts +50 -0
  616. package/sdk/typescript/test/adapters/anthropic.test.ts +217 -0
  617. package/sdk/typescript/test/adapters/gemini.test.ts +131 -0
  618. package/sdk/typescript/test/adapters/openai.test.ts +174 -0
  619. package/sdk/typescript/test/adapters/vercel-ai.test.ts +306 -0
  620. package/sdk/typescript/test/client-expanded.test.ts +333 -0
  621. package/sdk/typescript/test/client.test.ts +266 -0
  622. package/sdk/typescript/test/compress.test.ts +118 -0
  623. package/sdk/typescript/test/config.test.ts +275 -0
  624. package/sdk/typescript/test/errors.test.ts +169 -0
  625. package/sdk/typescript/test/format-integration.test.ts +252 -0
  626. package/sdk/typescript/test/hooks.test.ts +265 -0
  627. package/sdk/typescript/test/integration.test.ts +249 -0
  628. package/sdk/typescript/test/mdx-examples.test.ts +253 -0
  629. package/sdk/typescript/test/models.test.ts +318 -0
  630. package/sdk/typescript/test/parity.test.ts +337 -0
  631. package/sdk/typescript/test/paths.test.ts +447 -0
  632. package/sdk/typescript/test/shared-context.test.ts +245 -0
  633. package/sdk/typescript/test/simulate.test.ts +84 -0
  634. package/sdk/typescript/test/types.test.ts +244 -0
  635. package/sdk/typescript/test/utils/case.test.ts +129 -0
  636. package/sdk/typescript/test/utils/detect-format.test.ts +133 -0
  637. package/sdk/typescript/test/utils/format.test.ts +434 -0
  638. package/sdk/typescript/test/vercel-ai-e2e.test.ts +179 -0
  639. package/sdk/typescript/tsup.config.ts +17 -0
  640. package/tailwind.master.config.cjs +47 -0
  641. package/types/api.ts +12 -0
  642. package/types/config.ts +9 -0
  643. package/types/index.ts +2 -0
  644. package/uv.lock +6951 -0
  645. package/xithead.egg-info/PKG-INFO +22 -0
  646. package/xithead.egg-info/SOURCES.txt +16 -0
  647. package/xithead.egg-info/dependency_links.txt +1 -0
  648. package/xithead.egg-info/entry_points.txt +2 -0
  649. package/xithead.egg-info/requires.txt +10 -0
  650. package/xithead.egg-info/top_level.txt +2 -0
  651. package/xithead.ps1 +136 -0
  652. package/xithead.sh +129 -0
  653. package/xithead_dist/pyproject.toml +39 -0
  654. package/xithead_dist/xithead.egg-info/PKG-INFO +22 -0
  655. package/xithead_dist/xithead.egg-info/SOURCES.txt +16 -0
  656. package/xithead_dist/xithead.egg-info/dependency_links.txt +1 -0
  657. package/xithead_dist/xithead.egg-info/entry_points.txt +3 -0
  658. package/xithead_dist/xithead.egg-info/requires.txt +10 -0
  659. package/xithead_dist/xithead.egg-info/top_level.txt +2 -0
@@ -0,0 +1,338 @@
1
+ # Phase E — Phase 3 Cache Stabilization
2
+
3
+ **Goal:** Add the cache-stabilization surface that today is **completely missing**: tool array deterministic sort, recursive JSON Schema key sort, auto `cache_control` placement (Anthropic), `prompt_cache_key` auto-injection (OpenAI), volatile-content detector with customer warning (no rewrite), cache-bust drift telemetry. These are guide §8.5, §9.11, §6.2, §4.17 implementations and the "Phase 3" of the guide's implementation checklist.
4
+
5
+ **Calendar:** 1 week.
6
+
7
+ **Shape:** 6 PRs. Mostly parallel; E3 + E4 should land paired (per-mode policy).
8
+
9
+ ---
10
+
11
+ ## PR-E1 — Tool array deterministic sort (Rust)
12
+
13
+ **Branch:** `realign-E1-tool-array-sort`
14
+ **Worktree:** `~/claude-projects/headroom-worktrees/realign-E1-tool-array-sort`
15
+ **Risk:** **LOW**
16
+ **LOC:** +200
17
+
18
+ ### Scope
19
+ Eliminate P3-28. Sort `tools[]` alphabetically by name on the way out. Idempotent: re-sorting an already-sorted array is a no-op. Implementation matches Python's existing `_sort_tools_deterministically` (`headroom/proxy/handlers/anthropic.py:34-58`) — same sort key, same output bytes (modulo serialization).
20
+
21
+ ### Files
22
+
23
+ **Add:**
24
+ - `crates/headroom-proxy/src/compression/tool_def_normalize.rs`:
25
+ ```rust
26
+ pub fn sort_tools_deterministically(tools: &mut Vec<&RawValue>) -> Result<()> {
27
+ // Sort key: tool["name"] string, fallback to MD5(serialized) for unnamed tools.
28
+ tools.sort_by_key(|t| {
29
+ let parsed: serde_json::Value = serde_json::from_str(t.get()).unwrap_or_default();
30
+ parsed.get("name").and_then(|v| v.as_str()).unwrap_or("").to_string()
31
+ });
32
+ Ok(())
33
+ }
34
+ ```
35
+
36
+ **Modify:**
37
+ - `crates/headroom-proxy/src/compression/live_zone_anthropic.rs` — call `sort_tools_deterministically` on the request body's `tools` array before forwarding (only on PAYG; gated by Phase F PR-F2).
38
+ - `crates/headroom-proxy/src/compression/live_zone_openai.rs` — same.
39
+ - `crates/headroom-proxy/src/compression/live_zone_responses.rs` — same.
40
+
41
+ **Tests added:**
42
+ - `crates/headroom-proxy/tests/integration_tool_sort.rs::sort_alphabetic_by_name`
43
+ - `crates/headroom-proxy/tests/integration_tool_sort.rs::idempotent_resort_no_change`
44
+ - `crates/headroom-proxy/tests/integration_tool_sort.rs::byte_stable_across_runs`
45
+
46
+ ### Acceptance criteria
47
+
48
+ - Tests pass.
49
+ - Output `tools[]` byte-equal between Rust and Python sort implementations.
50
+
51
+ ### Blocked by
52
+
53
+ PR-B2.
54
+
55
+ ### Blocks
56
+
57
+ PR-E2.
58
+
59
+ ### Rollback
60
+
61
+ `git revert`. Rust path matches client's tool order (subject to the cache-bust risk).
62
+
63
+ ---
64
+
65
+ ## PR-E2 — Recursive JSON Schema key sort
66
+
67
+ **Branch:** `realign-E2-schema-key-sort`
68
+ **Worktree:** `~/claude-projects/headroom-worktrees/realign-E2-schema-key-sort`
69
+ **Risk:** **MEDIUM** (recursive sort over tool schemas; risk of breaking schema semantics if there's an `if`/`then`/`else` or `oneOf` ordering invariant — there isn't, but verify)
70
+ **LOC:** +300
71
+
72
+ ### Scope
73
+ Eliminate P3-29. Recursively sort JSON Schema object keys in every tool's `input_schema`. This includes nested `properties`, `definitions`, `oneOf`, `anyOf`, `allOf`, `if/then/else`, `additionalProperties`, etc.
74
+
75
+ ### Files
76
+
77
+ **Modify:**
78
+ - `crates/headroom-proxy/src/compression/tool_def_normalize.rs` — add `sort_schema_keys_recursive`. Walks every Object node; replaces with `IndexMap` rebuilt in alphabetic key order. Preserves Array order (JSON Schema arrays are ordered: `prefixItems`, `oneOf` alternatives, etc.).
79
+
80
+ **Tests added:**
81
+ - `crates/headroom-proxy/tests/integration_schema_sort.rs::flat_schema_keys_sorted`
82
+ - `crates/headroom-proxy/tests/integration_schema_sort.rs::nested_properties_sorted`
83
+ - `crates/headroom-proxy/tests/integration_schema_sort.rs::oneof_array_order_preserved`
84
+ - `crates/headroom-proxy/tests/integration_schema_sort.rs::definitions_keys_sorted`
85
+ - `crates/headroom-proxy/tests/integration_schema_sort.rs::idempotent_resort`
86
+
87
+ ### Acceptance criteria
88
+
89
+ - Tests pass.
90
+ - Snapshot test on a real production tool schema (e.g., Claude Code's `Read` tool) — pin the sorted bytes.
91
+
92
+ ### Blocked by
93
+
94
+ PR-E1.
95
+
96
+ ### Blocks
97
+
98
+ PR-E5.
99
+
100
+ ### Rollback
101
+
102
+ `git revert`. Schema keys reflect customer ordering.
103
+
104
+ ---
105
+
106
+ ## PR-E3 — Auto `cache_control` breakpoint placement (Anthropic)
107
+
108
+ **Branch:** `realign-E3-cache-control-auto-place`
109
+ **Worktree:** `~/claude-projects/headroom-worktrees/realign-E3-cache-control-auto-place`
110
+ **Risk:** **MEDIUM-HIGH** (auto-adds bytes to client request — only on PAYG)
111
+ **LOC:** +400
112
+
113
+ ### Scope
114
+ Eliminate P3-31. When PAYG mode is detected (Phase F PR-F1) and the customer has not set any `cache_control` markers, auto-place up to 4 ephemeral markers at:
115
+ 1. End of system prompt (1 marker)
116
+ 2. End of `tools[]` (1 marker)
117
+ 3. After the last stable conversation history boundary (1 marker; configurable threshold for "stable")
118
+ 4. Before the latest user message (1 marker)
119
+
120
+ OAuth and subscription modes: never auto-place (could void scope).
121
+
122
+ ### Files
123
+
124
+ **Add:**
125
+ - `crates/headroom-proxy/src/compression/cache_control.rs` — `pub fn auto_place_breakpoints(body: &mut serde_json::Value, auth_mode: AuthMode)`. Walks the structure; appends `cache_control: {type: "ephemeral"}` to the trailing block of system, tools, history, and current user message.
126
+
127
+ **Modify:**
128
+ - `crates/headroom-proxy/src/compression/live_zone_anthropic.rs` — call `auto_place_breakpoints` on PAYG only.
129
+
130
+ **Tests added:**
131
+ - `crates/headroom-proxy/tests/integration_cache_control_auto.rs::payg_auto_places_4_markers`
132
+ - `crates/headroom-proxy/tests/integration_cache_control_auto.rs::oauth_no_auto_placement`
133
+ - `crates/headroom-proxy/tests/integration_cache_control_auto.rs::subscription_no_auto_placement`
134
+ - `crates/headroom-proxy/tests/integration_cache_control_auto.rs::customer_set_markers_respected_no_addition`
135
+ - `crates/headroom-proxy/tests/integration_cache_control_auto.rs::ttl_ordering_correct_1h_before_5m`
136
+
137
+ ### Acceptance criteria
138
+
139
+ - Tests pass.
140
+ - Customer requests with existing markers are unmodified.
141
+ - A representative PAYG request gets 4 markers in the right positions.
142
+
143
+ ### Blocked by
144
+
145
+ PR-A4, PR-F1, PR-F2.
146
+
147
+ ### Blocks
148
+
149
+ None.
150
+
151
+ ### Rollback
152
+
153
+ `git revert`. Customers without their own `cache_control` markers don't get auto-placement; cache benefit smaller but correct.
154
+
155
+ ---
156
+
157
+ ## PR-E4 — `prompt_cache_key` auto-injection (OpenAI)
158
+
159
+ **Branch:** `realign-E4-prompt-cache-key-inject`
160
+ **Worktree:** `~/claude-projects/headroom-worktrees/realign-E4-prompt-cache-key-inject`
161
+ **Risk:** **MEDIUM**
162
+ **LOC:** +250
163
+
164
+ ### Scope
165
+ Eliminate P3-30. For OpenAI Chat Completions and Responses requests on PAYG mode where the customer has not set `prompt_cache_key`, auto-inject one derived from a stable session hash. OAuth/subscription modes: never inject (the CLI may already populate this and Headroom must preserve byte-for-byte).
166
+
167
+ ### Files
168
+
169
+ **Modify:**
170
+ - `crates/headroom-proxy/src/compression/live_zone_openai.rs` — add `inject_prompt_cache_key` step.
171
+ - `crates/headroom-proxy/src/compression/live_zone_responses.rs` — same.
172
+
173
+ **Add:**
174
+ - `crates/headroom-proxy/src/session.rs` — `pub fn derive_prompt_cache_key(session_id: &str, model: &str) -> String` — returns `{session_id}_{model_family}` (deterministic per session+model).
175
+
176
+ **Tests added:**
177
+ - `crates/headroom-proxy/tests/integration_prompt_cache_key.rs::payg_auto_injects_when_absent`
178
+ - `crates/headroom-proxy/tests/integration_prompt_cache_key.rs::customer_value_preserved`
179
+ - `crates/headroom-proxy/tests/integration_prompt_cache_key.rs::oauth_no_injection`
180
+ - `crates/headroom-proxy/tests/integration_prompt_cache_key.rs::subscription_no_injection`
181
+ - `crates/headroom-proxy/tests/integration_prompt_cache_key.rs::same_session_same_key_deterministic`
182
+
183
+ ### Acceptance criteria
184
+
185
+ - Tests pass.
186
+
187
+ ### Blocked by
188
+
189
+ PR-F1, PR-F2.
190
+
191
+ ### Blocks
192
+
193
+ None.
194
+
195
+ ### Rollback
196
+
197
+ `git revert`. OpenAI cache routing less sticky on PAYG; functional.
198
+
199
+ ---
200
+
201
+ ## PR-E5 — Volatile-content detector with customer warning (no rewrite)
202
+
203
+ **Branch:** `realign-E5-volatile-detector`
204
+ **Worktree:** `~/claude-projects/headroom-worktrees/realign-E5-volatile-detector`
205
+ **Risk:** **LOW**
206
+ **LOC:** +400
207
+
208
+ ### Scope
209
+ Eliminate P3-32. Detect dynamic content in the early prompt (timestamps, UUIDs, JWT tokens, build hashes, randomized IDs) and surface to the customer via a log line and a Prometheus metric. **Do not rewrite.** This is what Python's `cache_aligner.py` was *trying* to do correctly (the rewrite path is gone in Phase A PR-A2).
210
+
211
+ ### Files
212
+
213
+ **Add:**
214
+ - `crates/headroom-core/src/transforms/volatile_detector.rs`:
215
+ ```rust
216
+ pub struct VolatileDetector { /* compiled regex set */ }
217
+
218
+ impl VolatileDetector {
219
+ pub fn scan(&self, content: &str) -> Vec<VolatileFinding>;
220
+ }
221
+
222
+ pub struct VolatileFinding {
223
+ pub kind: VolatileKind, // Timestamp | Uuid | Jwt | BuildHash | ...
224
+ pub byte_offset: usize,
225
+ pub matched: String,
226
+ pub recommendation: String, // "Move to metadata"
227
+ }
228
+ ```
229
+ Patterns:
230
+ - ISO 8601 timestamp regex
231
+ - UUID v4 regex
232
+ - JWT shape (`eyJ...`)
233
+ - Long hex strings >=32 chars (build hashes)
234
+ - Unix epoch timestamps within an order of magnitude of `now`
235
+
236
+ **Modify:**
237
+ - `crates/headroom-proxy/src/compression/live_zone_anthropic.rs` — run scanner on system prompt; if findings, log warning and increment metric.
238
+ - `crates/headroom-proxy/src/compression/live_zone_openai.rs` — same on `instructions` field.
239
+ - `crates/headroom-proxy/src/compression/live_zone_responses.rs` — same.
240
+
241
+ **Tests added:**
242
+ - `crates/headroom-core/tests/volatile_detector.rs::detects_iso_8601_timestamp`
243
+ - `crates/headroom-core/tests/volatile_detector.rs::detects_uuid_v4`
244
+ - `crates/headroom-core/tests/volatile_detector.rs::detects_jwt_shape`
245
+ - `crates/headroom-core/tests/volatile_detector.rs::detects_build_hash`
246
+ - `crates/headroom-core/tests/volatile_detector.rs::no_false_positives_on_normal_prose`
247
+ - `crates/headroom-proxy/tests/integration_volatile.rs::warning_logged_on_volatile_system_prompt`
248
+ - `crates/headroom-proxy/tests/integration_volatile.rs::system_prompt_bytes_unchanged`
249
+
250
+ ### Acceptance criteria
251
+
252
+ - Tests pass.
253
+ - Detector runs in <1ms on a 4KB system prompt (don't slow the request path).
254
+
255
+ ### Blocked by
256
+
257
+ PR-E2.
258
+
259
+ ### Blocks
260
+
261
+ None.
262
+
263
+ ### Rollback
264
+
265
+ `git revert`. Detector loses; no functional regression.
266
+
267
+ ---
268
+
269
+ ## PR-E6 — Cache-bust drift detector telemetry
270
+
271
+ **Branch:** `realign-E6-cache-bust-detector`
272
+ **Worktree:** `~/claude-projects/headroom-worktrees/realign-E6-cache-bust-detector`
273
+ **Risk:** **LOW**
274
+ **LOC:** +500
275
+
276
+ ### Scope
277
+ Eliminate P3-35. Hash the prefix (system + tools + first N stable messages) of every request. Track per-session prefix hashes. When the prefix hash changes between turns, increment a counter and log a `prefix_drift` event with which subsystem mutated (likely none after Phase A — but if it happens, we want to know).
278
+
279
+ ### Files
280
+
281
+ **Add:**
282
+ - `crates/headroom-proxy/src/observability/prefix_drift.rs`:
283
+ ```rust
284
+ pub struct PrefixDriftDetector {
285
+ // Keyed by session_id; stores last-seen prefix hash + timestamp.
286
+ cache: Cache<SessionId, (PrefixHash, Instant)>,
287
+ }
288
+
289
+ impl PrefixDriftDetector {
290
+ pub fn check(&self, session_id: &str, body: &serde_json::Value) -> DriftCheck;
291
+ }
292
+
293
+ pub enum DriftCheck {
294
+ FirstSeen,
295
+ Stable,
296
+ Drifted { previous_hash: PrefixHash, new_hash: PrefixHash, age: Duration },
297
+ }
298
+ ```
299
+
300
+ **Modify:**
301
+ - `crates/headroom-proxy/src/observability/prometheus.rs` — add `prefix_drift_detected_total{provider, model}` counter.
302
+
303
+ **Tests added:**
304
+ - `crates/headroom-proxy/tests/integration_prefix_drift.rs::stable_prefix_no_drift`
305
+ - `crates/headroom-proxy/tests/integration_prefix_drift.rs::system_change_detected_as_drift`
306
+ - `crates/headroom-proxy/tests/integration_prefix_drift.rs::tools_reorder_detected`
307
+
308
+ ### Acceptance criteria
309
+
310
+ - Tests pass.
311
+ - A canary request that mutates the system prompt mid-session triggers the counter.
312
+
313
+ ### Blocked by
314
+
315
+ PR-B2.
316
+
317
+ ### Blocks
318
+
319
+ None.
320
+
321
+ ### Rollback
322
+
323
+ `git revert`. Loses observability; no functional regression.
324
+
325
+ ---
326
+
327
+ ## Phase E acceptance summary
328
+
329
+ After all 6 PRs land:
330
+
331
+ - ✅ Tools alphabetically sorted (deterministic, idempotent)
332
+ - ✅ JSON Schema keys recursively sorted
333
+ - ✅ `cache_control` auto-placement on PAYG (4 markers)
334
+ - ✅ `prompt_cache_key` auto-injection on PAYG (OpenAI)
335
+ - ✅ Volatile-content detector + customer warning (no rewrite)
336
+ - ✅ Cache-bust drift telemetry per session
337
+
338
+ **Phase E retires P3-28 through P3-32, P3-35.**
@@ -0,0 +1,254 @@
1
+ # Phase F — Auth-Mode Policy Gates
2
+
3
+ **Goal:** Make auth mode a first-class policy axis. Detect (PAYG / OAuth / subscription) at request entry; gate compression behavior, header injection, and TOIN aggregation per mode. Stealth mode for subscription CLIs.
4
+
5
+ **Calendar:** 1 week.
6
+
7
+ **Shape:** 4 PRs. F1 first; F2 + F3 + F4 parallel after.
8
+
9
+ Reference: `~/.claude/projects/-Users-tchopra-claude-projects-headroom/memory/project_auth_mode_compression_nuances.md`.
10
+
11
+ ---
12
+
13
+ ## PR-F1 — `classify_auth_mode` helper
14
+
15
+ **Branch:** `realign-F1-classify-auth-mode`
16
+ **Worktree:** `~/claude-projects/headroom-worktrees/realign-F1-classify-auth-mode`
17
+ **Risk:** **LOW**
18
+ **LOC:** +500
19
+
20
+ ### Scope
21
+ Single helper called at request entry returning `AuthMode = Payg | OAuth | Subscription`. Pure-function classification from headers (Authorization shape, OpenAI-Beta, anthropic-beta) and User-Agent prefix.
22
+
23
+ ### Files
24
+
25
+ **Add:**
26
+ - `crates/headroom-core/src/auth_mode.rs`:
27
+ ```rust
28
+ #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
29
+ pub enum AuthMode { Payg, OAuth, Subscription }
30
+
31
+ pub fn classify(headers: &http::HeaderMap) -> AuthMode {
32
+ let ua = headers.get("user-agent").and_then(|h| h.to_str().ok()).unwrap_or("").to_lowercase();
33
+ const SUBSCRIPTION_UA_PREFIXES: &[&str] = &[
34
+ "claude-cli/", "claude-code/", "codex-cli/", "cursor/",
35
+ "claude-vscode/", "github-copilot/", "anthropic-cli/", "antigravity/",
36
+ ];
37
+ if SUBSCRIPTION_UA_PREFIXES.iter().any(|p| ua.contains(p)) {
38
+ return AuthMode::Subscription;
39
+ }
40
+
41
+ let auth = headers.get("authorization").and_then(|h| h.to_str().ok()).unwrap_or("");
42
+ if auth.starts_with("Bearer ") {
43
+ let token = &auth[7..];
44
+ if token.starts_with("sk-ant-api") || token.starts_with("sk-") {
45
+ return AuthMode::Payg;
46
+ }
47
+ if token.starts_with("sk-ant-oat-") || token.split('.').count() >= 3 {
48
+ // sk-ant-oat-* (Claude Pro OAuth) or JWT (Codex/Cursor OAuth)
49
+ return AuthMode::OAuth;
50
+ }
51
+ }
52
+
53
+ // Bedrock / Vertex (no Authorization header from client; signed downstream)
54
+ if !auth.is_empty() == false
55
+ && headers.get("x-api-key").is_none()
56
+ && headers.get("x-goog-api-key").is_none()
57
+ {
58
+ return AuthMode::OAuth;
59
+ }
60
+
61
+ // x-api-key present (Anthropic API key style)
62
+ if headers.contains_key("x-api-key") {
63
+ return AuthMode::Payg;
64
+ }
65
+
66
+ AuthMode::Payg // default
67
+ }
68
+ ```
69
+
70
+ **Add (Python):**
71
+ - `headroom/proxy/auth_mode.py` — Python port of the same logic. Used in Python paths until Phase H deletes them.
72
+
73
+ **Modify:**
74
+ - `crates/headroom-core/src/lib.rs` — `pub mod auth_mode;`.
75
+ - `crates/headroom-proxy/src/proxy.rs` — call `classify` at request entry; store in request extensions for downstream handlers.
76
+ - `headroom/proxy/handlers/anthropic.py` — call Python `classify_auth_mode(headers)` at request entry.
77
+ - `headroom/proxy/handlers/openai.py` — same.
78
+
79
+ **Tests added:**
80
+ - `crates/headroom-core/tests/auth_mode.rs::api_key_classified_payg`
81
+ - `crates/headroom-core/tests/auth_mode.rs::oauth_jwt_classified_oauth`
82
+ - `crates/headroom-core/tests/auth_mode.rs::oauth_sk_ant_oat_classified_oauth`
83
+ - `crates/headroom-core/tests/auth_mode.rs::claude_code_ua_classified_subscription`
84
+ - `crates/headroom-core/tests/auth_mode.rs::cursor_ua_classified_subscription`
85
+ - `crates/headroom-core/tests/auth_mode.rs::no_auth_no_user_agent_default_payg`
86
+ - `crates/headroom-core/tests/auth_mode.rs::bedrock_no_auth_classified_oauth`
87
+ - Python equivalents in `tests/test_auth_mode.py`.
88
+
89
+ ### Acceptance criteria
90
+
91
+ - Tests pass.
92
+ - Detection runs in <10us per call.
93
+ - Documented in `docs/auth-modes.md` with the detection rules and how to extend.
94
+
95
+ ### Blocked by
96
+
97
+ None.
98
+
99
+ ### Blocks
100
+
101
+ PR-F2, PR-F3, PR-F4.
102
+
103
+ ### Rollback
104
+
105
+ `git revert`. All requests treated as PAYG (current behavior).
106
+
107
+ ---
108
+
109
+ ## PR-F2 — Per-mode compression policy gates
110
+
111
+ **Branch:** `realign-F2-per-mode-policy`
112
+ **Worktree:** `~/claude-projects/headroom-worktrees/realign-F2-per-mode-policy`
113
+ **Risk:** **MEDIUM-HIGH** (changes compression behavior per request)
114
+ **LOC:** +600
115
+
116
+ ### Scope
117
+ Wire `AuthMode` into every compression decision per the policy matrix in `02-architecture.md §2.4`. PAYG = aggressive (current default). OAuth = passthrough-prefer (no auto-`cache_control`, no auto-`prompt_cache_key`, no lossy compressors). Subscription = stealth (everything OAuth does + preserve `accept-encoding`, never strip; never inject `X-Headroom-*`; never mutate User-Agent).
118
+
119
+ ### Files
120
+
121
+ **Modify:**
122
+ - `crates/headroom-proxy/src/compression/live_zone_anthropic.rs` — gate `auto_place_breakpoints` on `auth_mode == Payg`.
123
+ - `crates/headroom-proxy/src/compression/live_zone_openai.rs` — gate `inject_prompt_cache_key` on `auth_mode == Payg`.
124
+ - `crates/headroom-proxy/src/compression/live_zone.rs` — gate lossy compressors (Kompress text) on `auth_mode == Payg`. OAuth and Subscription get lossless-only compression.
125
+ - `crates/headroom-proxy/src/headers.rs:103-117` — `add_x_forwarded_headers` becomes `add_x_forwarded_headers_if(auth_mode)`. Skip on Subscription.
126
+ - `crates/headroom-proxy/src/proxy.rs` — `accept-encoding` strip becomes conditional on `auth_mode != Subscription`.
127
+ - `headroom/proxy/handlers/anthropic.py` — gate Python compression decisions identically.
128
+ - `headroom/proxy/handlers/openai.py` — same.
129
+
130
+ **Tests added:**
131
+ - `crates/headroom-proxy/tests/integration_authmode_policy.rs::payg_aggressive_compression`
132
+ - `crates/headroom-proxy/tests/integration_authmode_policy.rs::oauth_no_auto_cache_control`
133
+ - `crates/headroom-proxy/tests/integration_authmode_policy.rs::oauth_no_auto_prompt_cache_key`
134
+ - `crates/headroom-proxy/tests/integration_authmode_policy.rs::oauth_lossless_only`
135
+ - `crates/headroom-proxy/tests/integration_authmode_policy.rs::subscription_no_x_forwarded`
136
+ - `crates/headroom-proxy/tests/integration_authmode_policy.rs::subscription_preserves_accept_encoding`
137
+ - `crates/headroom-proxy/tests/integration_authmode_policy.rs::subscription_lossless_only`
138
+
139
+ ### Acceptance criteria
140
+
141
+ - Tests pass.
142
+ - Manual smoke test: a real Claude Code session through the proxy produces no `X-Forwarded-*` upstream and preserves `accept-encoding`.
143
+
144
+ ### Blocked by
145
+
146
+ PR-F1, PR-E3, PR-E4.
147
+
148
+ ### Blocks
149
+
150
+ None.
151
+
152
+ ### Rollback
153
+
154
+ `git revert`. All requests treated as PAYG. No functional regression for PAYG users; OAuth/Subscription users may see scope-rejection or revocation increase.
155
+
156
+ ---
157
+
158
+ ## PR-F3 — TOIN per-tenant aggregation key
159
+
160
+ **Branch:** `realign-F3-toin-per-tenant`
161
+ **Worktree:** `~/claude-projects/headroom-worktrees/realign-F3-toin-per-tenant`
162
+ **Risk:** **MEDIUM**
163
+ **LOC:** -200 / +400
164
+
165
+ ### Scope
166
+ Eliminate P5-56. Extend TOIN's aggregation key from `structure_hash` to `(auth_mode, model_family, structure_hash)`. Storage key prefix updated; in-memory dicts re-keyed. Existing observations from before this PR are preserved under a `legacy/` prefix and deprecated over the next 30 days.
167
+
168
+ ### Files
169
+
170
+ **Modify:**
171
+ - `headroom/telemetry/toin.py:103` — `Pattern` adds `auth_mode: str = "unknown"`, `model_family: str = "unknown"`. (Already covered by Phase B PR-B5; this PR ensures the wiring lands.)
172
+ - `headroom/telemetry/toin.py:477, 496, 727, 729, 1248, 1256` — change aggregation key to tuple.
173
+ - `headroom/telemetry/toin.py` — migration helper that walks the legacy `structure_hash`-only store and copies entries under `("unknown", "unknown", structure_hash)` for graceful degrade.
174
+ - `headroom/telemetry/toin.py` — bumping aggregation key invalidates earlier recommendations; re-publish via the deploy CLI.
175
+ - `headroom/subscription/tracker.py:166` — replace `_current_token: str` (raw OAuth bearer storage) with `_current_token_id: str` (a one-way hash + last-4 chars for debugging). Polling code adapts to use the actual `Authorization` header per request rather than the stored copy.
176
+
177
+ **Tests added:**
178
+ - `tests/test_toin_per_tenant.py::test_aggregation_key_includes_auth_mode_model`
179
+ - `tests/test_toin_per_tenant.py::test_legacy_observations_preserved_under_unknown`
180
+ - `tests/test_toin_per_tenant.py::test_publish_per_auth_mode_writes_separate_recommendations`
181
+ - `tests/test_subscription_tracker_token_hardening.py::test_raw_token_not_stored_in_memory`
182
+
183
+ ### Acceptance criteria
184
+
185
+ - Tests pass.
186
+ - Recommendations file becomes structured `recommendations.toml` with sections per `(auth_mode, model_family)`.
187
+ - The subscription tracker token-leak risk closed.
188
+
189
+ ### Blocked by
190
+
191
+ PR-B5, PR-F1.
192
+
193
+ ### Blocks
194
+
195
+ None.
196
+
197
+ ### Rollback
198
+
199
+ `git revert`. TOIN reverts to global aggregation. No functional break.
200
+
201
+ ---
202
+
203
+ ## PR-F4 — `X-Forwarded-*` conditional in Rust path
204
+
205
+ **Branch:** `realign-F4-x-forwarded-conditional`
206
+ **Worktree:** `~/claude-projects/headroom-worktrees/realign-F4-x-forwarded-conditional`
207
+ **Risk:** **LOW**
208
+ **LOC:** +100
209
+
210
+ ### Scope
211
+ Eliminate P5-53. The Rust proxy currently always adds `X-Forwarded-For`, `X-Forwarded-Proto`, `X-Forwarded-Host`, `X-Request-Id` to upstream-bound requests. Make this conditional: PAYG → add; OAuth → add; Subscription → skip (fingerprint risk).
212
+
213
+ ### Files
214
+
215
+ **Modify:**
216
+ - `crates/headroom-proxy/src/headers.rs:103-117` — `add_x_forwarded_headers` takes an `AuthMode` parameter; no-ops on Subscription.
217
+
218
+ **Tests added:**
219
+ - `crates/headroom-proxy/tests/integration_x_forwarded_authmode.rs::payg_adds_xfwd`
220
+ - `crates/headroom-proxy/tests/integration_x_forwarded_authmode.rs::oauth_adds_xfwd`
221
+ - `crates/headroom-proxy/tests/integration_x_forwarded_authmode.rs::subscription_no_xfwd`
222
+
223
+ ### Acceptance criteria
224
+
225
+ - Tests pass.
226
+
227
+ ### Blocked by
228
+
229
+ PR-F1.
230
+
231
+ ### Blocks
232
+
233
+ None.
234
+
235
+ ### Rollback
236
+
237
+ `git revert`. Headers always added. Mild fingerprint regression for Subscription users.
238
+
239
+ ---
240
+
241
+ ## Phase F acceptance summary
242
+
243
+ After all 4 PRs land:
244
+
245
+ - ✅ `classify_auth_mode` helper detects PAYG / OAuth / Subscription
246
+ - ✅ Per-mode compression policy gates (auto-cache_control, prompt_cache_key, lossy compressors)
247
+ - ✅ TOIN aggregation key per `(auth_mode, model_family, structure_hash)`
248
+ - ✅ Subscription tracker doesn't store raw OAuth bearer
249
+ - ✅ `X-Forwarded-*` skipped on Subscription mode
250
+ - ✅ `accept-encoding` preserved on Subscription mode
251
+
252
+ **Phase F retires P5-52, P5-53, P5-54, P5-55, P5-56.**
253
+
254
+ After Phase F, fingerprint risk for Subscription CLI users is dramatically reduced.