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
package/PR.md ADDED
@@ -0,0 +1,170 @@
1
+ ## Description
2
+
3
+ Implement unified CI/CD release automation with semantic versioning across all three packages:
4
+ - **Python (xtream-head)** β€” pip package on PyPI
5
+ - **TypeScript SDK (xtream-head)** β€” npm package on npmjs.org
6
+ - **OpenClaw plugin (xtream-head-openclaw)** β€” npm package on npmjs.org and GitHub Package Registry
7
+
8
+ Currently the three packages are independently versioned (0.5.25 / 0.1.0 / 0.1.0). This PR introduces a single-source-of-truth version in `pyproject.toml` that propagates to all packages on every release, driven by conventional commit messages.
9
+
10
+ Fixes #(issue number)
11
+
12
+ ## Type of Change
13
+
14
+ - [ ] Bug fix (non-breaking change that fixes an issue)
15
+ - [x] New feature (non-breaking change that adds functionality)
16
+ - [ ] Breaking change (fix or feature that would cause existing functionality to change)
17
+ - [x] Documentation update
18
+ - [ ] Performance improvement
19
+ - [x] Code refactoring (no functional changes)
20
+
21
+ ## Changes Made
22
+
23
+ ### New Files
24
+
25
+ **Scripts:**
26
+ - `scripts/version-sync.py` β€” Reads version from `pyproject.toml`, updates all 4 version files. Supports `--version X.Y.Z` and `--bump {major,minor,patch}`.
27
+ - `scripts/changelog-gen.py` β€” Parses conventional commits since last tag, groups by type, generates markdown changelog with breaking change detection.
28
+ - `scripts/verify-versions.py` β€” Pre-release sanity check that all 4 version files are in sync.
29
+ - `scripts/tests/test_version_sync.py` β€” 5 tests for version-sync.py
30
+ - `scripts/tests/test_changelog_gen.py` β€” 23 tests for changelog-gen.py
31
+
32
+ **Workflows:**
33
+ - `.github/workflows/release.yml` β€” Unified release pipeline: detect β†’ build β†’ publish-pypi β†’ publish-npm β†’ publish-github-packages β†’ create-release
34
+ - `.commitlintrc.json` β€” Conventional commit enforcement via `@commitlint/config-conventional`
35
+
36
+ **Local Testing (act):**
37
+ - `.actrc` β€” Default `act` flags (Ubuntu runner, reuse, quiet)
38
+ - `.github/act/dry-run.json` β€” `act` event file for dry-run testing
39
+ - `.github/act/push-feat.json` β€” `act` event file for simulating a feat commit
40
+ - `.actrc.local.example` β€” Local override template for `act`
41
+ - `.env.act.example` β€” Secrets documentation template for `act` local testing
42
+
43
+ **Documentation:**
44
+ - `docs/content/docs/releases.mdx` β€” Full documentation for the release pipeline, testing guide, and configuration reference
45
+
46
+ ### Modified Files
47
+
48
+ - `.github/workflows/ci.yml` β€” Added `commitlint` job to enforce conventional commits
49
+ - `.github/workflows/publish.yml` β€” Changed from `release` trigger to `workflow_dispatch` only (superseded by `release.yml`)
50
+ - `.github/workflows/release.yml` β€” **Rewritten** with canonical+commit-height algorithm (no more commit loop)
51
+ - `.gitignore` β€” Added `!scripts/version-sync.py`, `!scripts/changelog-gen.py`, `!scripts/verify-versions.py`, `!scripts/tests/`, `.env.act`, `.actrc.local`
52
+
53
+ ## Testing
54
+
55
+ - [x] Unit tests pass (`pytest`)
56
+ - `scripts/tests/test_version_sync.py` β€” 5/5 passing
57
+ - `scripts/tests/test_changelog_gen.py` β€” 23/23 passing
58
+ - [x] Linting passes (`ruff check .`)
59
+ - [ ] Type checking passes (`mypy headroom`) β€” pre-existing issue in `headroom/cli/wrap.py:487` (unrelated)
60
+ - [x] New tests added for new functionality
61
+ - [x] Workflow tested with `act` (dry-run passes all jobs through build step β€” no infinite loop)
62
+
63
+ ## Algorithm Validation
64
+
65
+ The canonical+commit-height algorithm was validated with test cases:
66
+ - Canonical `0.5.25`, no prior tag, `feat:` commit β†’ git tag `v0.6.0.0`, npm `0.6.0` βœ…
67
+ - Canonical `0.5.25`, tag `v0.5.25.2`, `fix:` commit β†’ git tag `v0.5.25.3`, npm `0.5.26` βœ…
68
+ - Canonical `0.5.25`, no prior tag, `fix:` commit β†’ git tag `v0.5.25.0`, npm `0.5.25` βœ…
69
+ - Manual override `1.2.3` β†’ git tag `v1.2.3`, npm `1.2.3` βœ…
70
+
71
+ ## Test Output
72
+
73
+ ```
74
+ scripts/tests/test_version_sync.py .....
75
+ scripts/tests/test_changelog_gen.py .......................
76
+ ```
77
+
78
+ ## Checklist
79
+
80
+ - [x] My code follows the project's style guidelines
81
+ - [x] I have performed a self-review of my code
82
+ - [x] I have commented my code, particularly in hard-to-understand areas
83
+ - [x] My changes generate no new warnings
84
+ - [x] I have added tests that prove my fix is effective or that my feature works
85
+ - [x] New and existing unit tests pass locally with my changes
86
+ - [x] I have made corresponding changes to the documentation
87
+ - [ ] I have updated the CHANGELOG.md if applicable
88
+
89
+ ## Additional Notes
90
+
91
+ ### Version Bump Logic
92
+
93
+ **Canonical + Commit Height Algorithm** β€” The workflow NEVER commits back to the repo. `pyproject.toml` is the canonical source of truth, updated manually before merging.
94
+
95
+ | Commit | Bump | Git Tag | npm Version |
96
+ |--------|------|---------|-------------|
97
+ | `fix:`, `ci:`, `chore:`, `perf:`, `refactor:` | patch | `v0.5.25.3` | `0.5.26` |
98
+ | `feat:` | minor | `v0.6.0.0` | `0.6.0` |
99
+ | `feat!:` or `feat:` + `BREAKING CHANGE` body | major | `v1.0.0.0` | `1.0.0` |
100
+
101
+ The git tag uses `v{canonical}.{height}` (e.g., `v0.5.25.3` = 3 commits since canonical `0.5.25`). npm versions use 3-part semver, bumped from canonical.
102
+
103
+ ### Package Publishing Targets
104
+
105
+ | Package | Target | Status |
106
+ |---------|--------|--------|
107
+ | `xtream-head` (Python) | PyPI | βœ… via `pypa/gh-action-pypi-publish` |
108
+ | `xtream-head` (TypeScript SDK) | npmjs.org | βœ… via `npm publish` |
109
+ | `xtream-head-openclaw` | npmjs.org | βœ… via `npm publish` |
110
+ | `xtream-head-openclaw` | GitHub Package Registry | βœ… via `npm publish --registry npm.pkg.github.com` |
111
+
112
+ ### Safety Gates
113
+
114
+ Each publish job requires both `dry_run != 'true'` **and** the corresponding skip variable not set:
115
+
116
+ | Variable | Effect |
117
+ |----------|--------|
118
+ | `PYPI_SKIP=true` | Skip PyPI publish |
119
+ | `NPM_SKIP=true` | Skip both npm publishes |
120
+ | `GH_PACKAGES_SKIP=true` | Skip GitHub Package Registry publish |
121
+
122
+ Set in: **GitHub repo β†’ Settings β†’ Variables β†’ Actions Variables**.
123
+
124
+ ### Workflow Triggers
125
+
126
+ - **Auto:** On push to `main` β€” analyzes latest commit, bumps version, builds, publishes, creates GitHub Release
127
+ - **Manual:** `workflow_dispatch` with optional `version` override and `dry_run` flag
128
+ - **Paths ignore:** Skips runs when only `docs/`, `.github/workflows/ci.yml`, `.github/workflows/publish.yml`, `scripts/`, `.commitlintrc.json`, `.actrc`, `.github/act/`, or `.env.act.example` change
129
+
130
+ ### Local Testing
131
+
132
+ ```bash
133
+ # Install act
134
+ winget install act
135
+
136
+ # Dry-run (no publishes)
137
+ act -W .github/workflows/release.yml -e .github/act/dry-run.json
138
+
139
+ # Test feat: commit (minor bump)
140
+ act -W .github/workflows/release.yml -e .github/act/push-feat.json
141
+ ```
142
+
143
+ ### Required GitHub Secrets
144
+
145
+ | Secret | Purpose |
146
+ |--------|---------|
147
+ | `NPM_TOKEN` | Publishing to npmjs.org |
148
+ | `GITHUB_TOKEN` | GitHub Package Registry (auto-provided by GitHub Actions) |
149
+
150
+ PyPI uses trusted publisher OIDC β€” no secret required, only the `pypi` GitHub Environment must be configured.
151
+
152
+ ### First Release Note
153
+
154
+ The TypeScript packages are currently at `0.1.0` while Python is at `0.5.25`. The first release will align all three to the same version. Update `pyproject.toml` to the desired canonical version before merging, then use `workflow_dispatch` with a manual `version` input to set the target explicitly.
155
+
156
+ After each release, update `pyproject.toml` to match the published version to keep the canonical current and ensure unique git tags.
157
+
158
+ ### Parameterized Configuration
159
+
160
+ All package names and registries are top-level `env` constants in `release.yml`:
161
+
162
+ ```yaml
163
+ env:
164
+ PYPI_PACKAGE: xtream-head
165
+ PYPI_ENVIRONMENT: pypi
166
+ NPM_REGISTRY_URL: https://registry.npmjs.org
167
+ NPM_SDK_PACKAGE: xtream-head
168
+ NPM_OPENCLAW_PACKAGE: xtream-head-openclaw
169
+ GITHUB_PACKAGES_REGISTRY_URL: https://npm.pkg.github.com
170
+ ```
package/PUBLISH.md ADDED
@@ -0,0 +1,77 @@
1
+ # Publishing Guide
2
+
3
+ ## npm Registry (npmjs.com)
4
+
5
+ ### Prerequisites
6
+ - npm account at https://www.npmjs.com
7
+ - Logged in: `npm login`
8
+
9
+ ### Publish Steps
10
+
11
+ ```bash
12
+ # 1. Verify version in package.json is updated
13
+ npm version patch # or 'minor' / 'major'
14
+
15
+ # 2. Build and test
16
+ npm run build
17
+ npm test # if tests exist
18
+
19
+ # 3. Publish to npm
20
+ npm publish
21
+
22
+ # 4. Verify on https://www.npmjs.com/package/xithead
23
+ ```
24
+
25
+ ### Current Version
26
+ - **Version**: 1.5.0
27
+ - **Package Name**: `xithead`
28
+ - **Registry**: https://registry.npmjs.org/
29
+ - **Access**: public
30
+
31
+ ### Install via npm
32
+ ```bash
33
+ npm install -g xithead
34
+ # or
35
+ npm install -g github:xtream-itsolutions/xithead
36
+ ```
37
+
38
+ ## GitHub Release
39
+
40
+ After publishing to npm, create a GitHub release:
41
+
42
+ ```bash
43
+ git tag v1.5.0
44
+ git push origin v1.5.0
45
+ # Then create release on GitHub with changelog
46
+ ```
47
+
48
+ ## PyPI (Python Package Index)
49
+
50
+ Current setup:
51
+ - xithead is a **Node.js CLI** application, not a Python package
52
+ - PyPI is for Python packages only
53
+ - If Python wrapper is needed in future, create separate `xithead-py` package
54
+
55
+ For now:
56
+ - Distribution via npm (JavaScript)
57
+ - No PyPI package needed
58
+
59
+ ## Troubleshooting
60
+
61
+ **Not authenticated to npm?**
62
+ ```bash
63
+ npm login
64
+ # Enter credentials from npm account
65
+ ```
66
+
67
+ **Package already exists?**
68
+ ```bash
69
+ npm unpublish xithead@1.5.0 # Remove old version if needed
70
+ npm publish # Publish new version
71
+ ```
72
+
73
+ **View published packages:**
74
+ ```bash
75
+ npm view xithead versions # Show all versions
76
+ npm info xithead # Show package info
77
+ ```
package/README.md CHANGED
@@ -1,72 +1,108 @@
1
- # xtream-head
2
-
3
- **Lokaler Claude Code Proxy** von [Xtream-ITSolutions UG](https://xtream-itsolutions.com) β€” setzt sich zwischen Claude Code und die Anthropic API, maximiert den Prompt Cache und reduziert Token-Kosten bis zu **88%**.
4
-
5
- Dashboard lΓ€uft lokal auf `localhost:8787/dashboard` β€” deine Stats, deine Daten.
6
-
7
- ---
8
-
9
- ## Installation
10
-
11
- ### Option 1: Von GitHub (EMPFOHLEN) ⭐
12
-
13
- Immer die neueste Version mit allen Features:
14
-
15
- ```bash
16
- npm install github:xtream-itsolutions/xithead
17
- ```
18
-
19
- Dann starten:
20
- ```bash
21
- xithead
22
- ```
23
-
24
- ### Option 2: Skript-Installation (Windows)
25
-
26
- ```powershell
27
- iex (irm https://raw.githubusercontent.com/xtream-itsolutions/xithead/main/xithead.ps1)
28
- xithead
29
- ```
30
-
31
- ### Option 3: npm (Stable Release)
32
-
33
- ```bash
34
- npm install xithead@latest
35
- xithead
36
- ```
37
-
38
- VollstΓ€ndige Anleitung fΓΌr Windows, macOS und Linux: **[xtream-head.com/installation](https://xtream-head.com/installation)**
39
-
40
- ---
41
-
42
- ## Befehle
43
-
44
- | Befehl | Funktion |
45
- |--------|----------|
46
- | `xithead` | Proxy + Claude Code starten |
47
- | `xithead-dashboard` | Dashboard im Browser ΓΆffnen |
48
- | `xithead-stats` | Einsparungen in der Konsole anzeigen |
49
- | `xithead-update` | Alles aktualisieren |
50
- | `xithead-doctor` | System-Diagnose |
51
-
52
- ---
53
-
54
- ## Was es macht
55
-
56
- - **Cache-Control Normalisierung** β€” Verhindert HTTP 400 Fehler
57
- - **Lossless Compression** β€” ANSI-Strip, Run-Collapse, Diff-Strip, Line-Truncation
58
- - **Message Dedup** β€” Identische Nachrichten werden eliminiert
59
- - **Context Trim** β€” Automatische KΓΌrzung bei Token-Overflow
60
- - **Lokales Dashboard** β€” Echtzeit-Stats auf `localhost:8787/dashboard`
61
-
62
- ---
63
-
64
- ## Links
65
-
66
- - Website: [xtream-head.com](https://xtream-head.com)
67
- - Discord: [discord.gg/xtream-itsolutions](https://discord.gg/xtream-itsolutions)
68
- - Unternehmen: [xtream-itsolutions.com](https://xtream-itsolutions.com)
69
-
70
- ---
71
-
72
- Apache 2.0 License Β· Β© 2026 Xtream-ITSolutions UG
1
+ # xtream-head
2
+
3
+ **Lokaler Claude Code Proxy** von [Xtream-ITSolutions UG](https://xtream-itsolutions.com) β€” setzt sich zwischen Claude Code und die Anthropic API, maximiert den Prompt Cache und reduziert Token-Kosten bis zu **88%**.
4
+
5
+ Dashboard lΓ€uft lokal auf `localhost:8787/dashboard` β€” deine Stats, deine Daten.
6
+
7
+ ---
8
+
9
+ ## Installation
10
+
11
+ ### Option 1: Proxy (Python, empfohlen fΓΌr Claude Code)
12
+
13
+ Der Proxy ist das Python-Paket. Er startet auf `http://127.0.0.1:8787` und leitet Anfragen an `https://api.anthropic.com` weiter.
14
+
15
+ ```bash
16
+ pip install "xtream-head[proxy]" # aus PyPI, sobald verΓΆffentlicht
17
+ # oder aus dem Repo:
18
+ pip install -e ".[proxy]"
19
+ ```
20
+
21
+ Proxy starten und Claude Code direkt darΓΌber laufen lassen:
22
+ ```bash
23
+ xithead wrap claude
24
+ ```
25
+
26
+ Oder den Proxy separat starten und die Umgebungsvariable selbst setzen:
27
+ ```bash
28
+ xithead proxy --port 8787
29
+ export ANTHROPIC_BASE_URL=http://127.0.0.1:8787 # Windows PowerShell: $env:ANTHROPIC_BASE_URL='http://127.0.0.1:8787'
30
+ claude
31
+ ```
32
+
33
+ ### Option 2: Dashboard (npm)
34
+
35
+ Das npm-Paket startet nur das Next.js-Dashboard. Es startet keinen Proxy.
36
+
37
+ ```bash
38
+ npm install -g github:xtream-itsolutions/xithead
39
+ xithead # Dashboard auf http://localhost:8787/dashboard
40
+ ```
41
+
42
+ > **Hinweis:** Beide Pakete stellen einen Befehl `xithead` bereit. Nicht beide gleichzeitig installieren, und beide Dienste nicht gleichzeitig auf Port 8787 starten.
43
+
44
+ ### Option 3: Skript-Installation (Windows)
45
+
46
+ ```powershell
47
+ iex (irm https://raw.githubusercontent.com/xtream-itsolutions/xithead/main/xithead.ps1)
48
+ xithead
49
+ ```
50
+
51
+ ### VS Code: Claude Code Extension ΓΌber den Proxy betreiben
52
+
53
+ Die Extension liest dieselbe Claude-Code-Konfiguration wie die CLI. Die Umgebungsvariable deshalb in `~/.claude/settings.json` eintragen, nicht nur in der Shell:
54
+
55
+ ```json
56
+ {
57
+ "env": {
58
+ "ANTHROPIC_BASE_URL": "http://127.0.0.1:8787"
59
+ }
60
+ }
61
+ ```
62
+
63
+ Danach:
64
+ 1. Proxy starten: `xithead proxy --port 8787`.
65
+ 2. VS Code komplett neu starten, damit die Extension die Einstellung ΓΌbernimmt.
66
+ 3. Im Claude-Code-Panel eine Nachricht senden.
67
+
68
+ Ist der Proxy nicht gestartet, schlagen Anfragen fehl. Dann den `env`-Eintrag entfernen, damit Claude Code wieder direkt mit der Anthropic-API spricht.
69
+
70
+ VollstΓ€ndige Anleitung fΓΌr Windows, macOS und Linux: **[xtream-head.com/installation](https://xtream-head.com/installation)**
71
+
72
+ ---
73
+
74
+ ## Befehle
75
+
76
+ | Befehl | Funktion |
77
+ |--------|----------|
78
+ | `xtream-head` | Proxy + Claude Code starten |
79
+ | `xtream-head-dashboard` | Dashboard im Browser ΓΆffnen |
80
+ | `xtream-head-stats` | Einsparungen in der Konsole anzeigen |
81
+ | `xtream-head-update` | Alles aktualisieren |
82
+ | `xtream-head-doctor` | System-Diagnose |
83
+ | `headroom privacy doctor` | Datenschutz- und Deployment-Sicherheit prΓΌfen |
84
+
85
+ ---
86
+
87
+ ## Was es macht
88
+
89
+ - **Cache-Control Normalisierung** β€” Verhindert HTTP 400 Fehler
90
+ - **Lossless Compression** β€” ANSI-Strip, Run-Collapse, Diff-Strip, Line-Truncation
91
+ - **Message Dedup** β€” Identische Nachrichten werden eliminiert
92
+ - **Context Trim** β€” Automatische KΓΌrzung bei Token-Overflow
93
+ - **Lokales Dashboard** β€” Echtzeit-Stats auf `localhost:8787/dashboard`
94
+ - **Policy Engine** β€” Provider-, Modell- und Projektregeln fΓΌr sichere Kompression
95
+ - **Replay-Fixtures** β€” anonymisierte Requests reproduzierbar analysieren
96
+ - **Quality Score** β€” Einsparung, Latenz, Struktur und ZuverlΓ€ssigkeit gemeinsam bewerten
97
+
98
+ ---
99
+
100
+ ## Links
101
+
102
+ - Website: [xtream-head.com](https://xtream-head.com)
103
+ - Discord: [discord.gg/xtream-itsolutions](https://discord.gg/xtream-itsolutions)
104
+ - Unternehmen: [xtream-itsolutions.com](https://xtream-itsolutions.com)
105
+
106
+ ---
107
+
108
+ Apache 2.0 License Β· Β© 2026 Xtream-ITSolutions UG
@@ -0,0 +1,196 @@
1
+ # XIT Head β€” Frontend
2
+
3
+ Modern Next.js-basiertes Frontend fΓΌr Claude Code Proxy mit professioneller Projektstruktur.
4
+
5
+ ## πŸ“ Projektstruktur
6
+
7
+ ```
8
+ .
9
+ β”œβ”€β”€ app/ # Next.js App Router (Pages & Routes)
10
+ β”‚ β”œβ”€β”€ layout.tsx # Root Layout
11
+ β”‚ β”œβ”€β”€ page.tsx # Homepage
12
+ β”‚ β”œβ”€β”€ dashboard/ # Dashboard Routes
13
+ β”‚ β”œβ”€β”€ installation/ # Installation Guide
14
+ β”‚ β”œβ”€β”€ api/ # API Routes
15
+ β”‚ └── rechtliches/ # Legal Pages
16
+ β”œβ”€β”€ components/ # React Components
17
+ β”‚ β”œβ”€β”€ layout/ # Layout Components (Header, Footer, AppShell)
18
+ β”‚ β”œβ”€β”€ dashboard/ # Dashboard-specific Components
19
+ β”‚ β”œβ”€β”€ pages/ # Page Components
20
+ β”‚ β”œβ”€β”€ shared/ # Reusable Components
21
+ β”‚ β”œβ”€β”€ marketing/ # Marketing Components
22
+ β”‚ └── ui/ # UI Library Components
23
+ β”œβ”€β”€ lib/ # Utilities & Business Logic
24
+ β”‚ β”œβ”€β”€ config/ # Configuration
25
+ β”‚ β”œβ”€β”€ utils/ # Utility Functions
26
+ β”‚ β”œβ”€β”€ hooks/ # Custom React Hooks (exported to lib/hooks)
27
+ β”‚ β”œβ”€β”€ schemas/ # Zod/Validation Schemas
28
+ β”‚ β”œβ”€β”€ middleware/ # Middleware Utilities
29
+ β”‚ β”œβ”€β”€ api/ # API Client Helpers
30
+ β”‚ └── __tests__/ # Unit Tests
31
+ β”œβ”€β”€ hooks/ # Custom React Hooks (aliased to lib/hooks)
32
+ β”œβ”€β”€ types/ # TypeScript Type Definitions
33
+ β”œβ”€β”€ public/ # Static Assets (images, icons, etc)
34
+ β”œβ”€β”€ scripts/ # Build & Utility Scripts
35
+ β”œβ”€β”€ design-system/ # Design Tokens & System
36
+ β”œβ”€β”€ __tests__/ # Integration Tests
37
+ β”œβ”€β”€ middleware.ts # Next.js Middleware
38
+ β”œβ”€β”€ next.config.ts # Next.js Configuration
39
+ β”œβ”€β”€ tailwind.config.ts # Tailwind CSS Configuration
40
+ β”œβ”€β”€ tsconfig.json # TypeScript Configuration
41
+ β”œβ”€β”€ package.json # NPM Configuration
42
+ └── README.md # Documentation
43
+ ```
44
+
45
+ ## πŸš€ Quick Start
46
+
47
+ ### Installation
48
+ ```bash
49
+ npm install
50
+ ```
51
+
52
+ ### Development
53
+ ```bash
54
+ npm run dev
55
+ # App lΓ€uft auf http://localhost:3000
56
+ ```
57
+
58
+ ### Build
59
+ ```bash
60
+ npm run build
61
+ npm run start
62
+ ```
63
+
64
+ ### Testing
65
+ ```bash
66
+ npm run test # Alle Tests laufen
67
+ npm run test:ui # Test UI ΓΆffnen
68
+ npm run test:coverage # Coverage Report
69
+ ```
70
+
71
+ ### Code Quality
72
+ ```bash
73
+ npm run lint # ESLint
74
+ npm run type-check # TypeScript Check
75
+ npm run format # Code Formatierung
76
+ npm run verify # Alle Checks
77
+ ```
78
+
79
+ ## πŸ“¦ Scripts
80
+
81
+ | Script | Beschreibung |
82
+ |--------|-------------|
83
+ | `dev` | Starts dev server |
84
+ | `build` | Build fΓΌr production |
85
+ | `start` | Start production server |
86
+ | `lint` | ESLint check |
87
+ | `type-check` | TypeScript type checking |
88
+ | `format` | Prettier formatting |
89
+ | `test` | Vitest runner |
90
+ | `clean` | Delete build artifacts |
91
+ | `clean:cache` | Clear Next.js cache |
92
+ | `analyze` | Build bundle analysis |
93
+
94
+ ## 🎨 Design System
95
+
96
+ - **Color Scheme**: Schwarz/Weiß mit #BE3455 als Brand-Akzent
97
+ - **Framework**: Tailwind CSS v4
98
+ - **Icons**: Lucide React
99
+ - **Typography**: System Fonts mit Fallbacks
100
+
101
+ ## πŸ”— Path Aliases
102
+
103
+ ```json
104
+ {
105
+ "@/*": "./*",
106
+ "@/app/*": "./app/*",
107
+ "@/components/*": "./components/*",
108
+ "@/lib/*": "./lib/*",
109
+ "@/types/*": "./types/*",
110
+ "@/hooks/*": "./lib/hooks/*",
111
+ "@/utils/*": "./lib/utils/*",
112
+ "@/schemas/*": "./lib/schemas/*"
113
+ }
114
+ ```
115
+
116
+ ## πŸ“Š Pages
117
+
118
+ - **Homepage**: `/`
119
+ - **Dashboard**: `/dashboard`
120
+ - **Dashboard Analytics**: `/dashboard/analytics`
121
+ - **Dashboard Settings**: `/dashboard/settings`
122
+ - **Installation**: `/installation`
123
+ - **Legal**: `/rechtliches/*`
124
+
125
+ ## πŸ”§ Configuration
126
+
127
+ ### Environment Variables
128
+ Kopiere `.env.example` zu `.env.local` und passe an:
129
+
130
+ ```bash
131
+ cp .env.example .env.local
132
+ ```
133
+
134
+ ## πŸ§ͺ Testing
135
+
136
+ Das Projekt nutzt **Vitest** fΓΌr Unit Tests:
137
+
138
+ ```bash
139
+ npm run test # Run all tests
140
+ npm run test:ui # Open Vitest UI
141
+ npm run test:coverage # Generate coverage report
142
+ ```
143
+
144
+ ## πŸ“ Dependencies
145
+
146
+ **Main Dependencies:**
147
+ - Next.js 15.3.4
148
+ - React 19.0.0
149
+ - Tailwind CSS 4
150
+ - Lucide React 0.454
151
+ - Recharts 2.15
152
+
153
+ **Dev Dependencies:**
154
+ - TypeScript 5
155
+ - ESLint + TypeScript Support
156
+ - Prettier
157
+ - Vitest
158
+ - PostCSS
159
+
160
+ ## πŸš€ Deployment
161
+
162
+ ### Production Build
163
+ ```bash
164
+ npm run build
165
+ npm run start
166
+ ```
167
+
168
+ ### Docker
169
+ ```bash
170
+ docker build -t xtream-head .
171
+ docker run -p 3000:3000 xtream-head
172
+ ```
173
+
174
+ ## πŸ“š Best Practices
175
+
176
+ 1. **Components**: Nutze funktionale Komponenten mit Hooks
177
+ 2. **Styling**: Tailwind CSS fΓΌr alle Styles
178
+ 3. **Types**: Immer vollstΓ€ndige TypeScript Types
179
+ 4. **Hooks**: Custom Hooks in `lib/hooks/`
180
+ 5. **Utils**: Business Logic in `lib/utils/`
181
+ 6. **Tests**: Unit Tests in `lib/__tests__/`
182
+
183
+ ## πŸ” Security
184
+
185
+ - Alle API-Requests sind authentifiziert
186
+ - CORS-Headers sind konfiguriert
187
+ - CSP-Headers zur XSS-Prevention
188
+ - Sensitive Data ist environment-protected
189
+
190
+ ## πŸ“ž Support
191
+
192
+ FΓΌr Issues und Fragen: https://github.com/Xtream-ITSolutions/xithead
193
+
194
+ ## πŸ“„ Lizenz
195
+
196
+ Apache 2.0 β€” Siehe LICENSE datei
@@ -0,0 +1,53 @@
1
+ # 00 β€” Overview & Wrong Mental Model
2
+
3
+ ## Executive summary
4
+
5
+ Headroom is built on the wrong mental model: **"compression means choosing what to drop from conversation history."** The flagship `IntelligentContextManager` (ICM) tokenizes the entire `messages` array, scores each message for importance, and removes old messages until the budget is hit. It has been wired into the Rust proxy on `/v1/messages` with `frozen_message_count: 0` hardcoded β€” so every compression event drops messages from index 0, busting the Anthropic prompt cache for every customer that triggers it.
6
+
7
+ The correct mental model β€” confirmed by an authoritative engineering guide and ten parallel deep-audit subagents β€” is the opposite: **"passthrough is sacred; compress only the live zone, type-aware, hash-keyed, position-preserving, with side-channel metadata."** The cache hot zone (system prompt, tools, old turns, reasoning/thinking/redacted/compaction items) is **never** touched.
8
+
9
+ The audit found:
10
+
11
+ - **5 top-tier cache-killer bugs** all stemming from the wrong model
12
+ - **~10 K LOC of architectural over-build** (ICM + scoring + relevance + rolling-window + progressive-summarizer + tool-crusher + cache-aligner rewrite path + most of `crates/headroom-core/src/{context,scoring,relevance}/`)
13
+ - **Wire-format gaps** in the streaming SSE parser (missing `thinking_delta`, `signature_delta`, `citations_delta`; UTF-8-split corruption; single-`\n` SSE split bugs in fallback paths)
14
+ - **Bedrock/Vertex parity is fake** β€” a lossy LiteLLM Anthropic-to-OpenAI conversion drops `thinking`, `redacted_thinking`, `document`, `search_result`, `image`, `server_tool_use`, `mcp_tool_use` blocks
15
+ - **No tool-definition normalization** anywhere
16
+ - **No auth-mode awareness** β€” PAYG, OAuth, and subscription CLIs all get the same policy and the same fingerprint-leaking re-serialization
17
+ - **`X-Headroom-*` request headers leak upstream**, plus `anthropic-beta` mutation and `OpenAI-Beta` auto-injection β€” fingerprint-class subscription-revocation risks
18
+ - **CCR markers** are computed but never injected into the outgoing request body in the Rust path; the `ccr_retrieve` tool flips on/off per request β€” busts the tools array on every state change
19
+
20
+ ## What changes
21
+
22
+ The realignment is structured in 9 phases, 40 PRs, ~13 weeks sequential or ~8 weeks with parallel work:
23
+
24
+ - **Phase A β€” Lockdown (1 week):** stop the cache bleeding immediately. Make `/v1/messages` compression a passthrough; stop mutating the system prompt; switch Python forwarders from `httpx ... json=body` (re-serializes) to `httpx ... content=raw_bytes`; honor customer-set `cache_control` markers in Rust; strip `x-headroom-*` from upstream-bound headers; pin `anthropic-beta` order and make it session-sticky; add a SHA-256 byte-faithful round-trip test.
25
+ - **Phase B β€” Live-zone engine (2 weeks):** delete ICM, scoring, relevance, rolling-window, progressive-summarizer, tool-crusher (~10 K LOC). Build a live-zone-only block dispatcher in Rust that runs SmartCrusher / LogCompressor / DiffCompressor / SearchCompressor / KompressCompressor on the latest user message content + latest tool_result + latest function_call_output + latest local_shell_call_output. Token-validate every compression with fallback. CCR hardens: persistent backend + always-on `ccr_retrieve` tool registration.
26
+ - **Phase C β€” Rust proxy paths (3 weeks):** byte-level SSE parser with full state machine; `/v1/chat/completions`, `/v1/responses` (HTTP and streaming) handlers; per-item-type passthrough preservation (V4A patches, `local_shell_call.action.command` argv, Codex `phase` field, MCP items, `compaction`).
27
+ - **Phase D β€” Bedrock/Vertex native (2 weeks):** delete the LiteLLM lossy converter; build native `/model/.../invoke` (AWS) and `/v1beta1/projects/.../publishers/anthropic/.../streamRawPredict` (GCP) routes with SigV4 + ADC signing. Cache fidelity restored on Bedrock/Vertex traffic.
28
+ - **Phase E β€” Phase 3 cache stabilization (1 week):** sort tool array deterministically; sort JSON Schema keys recursively; auto-place up to 4 `cache_control` breakpoints (Anthropic); auto-inject `prompt_cache_key` (OpenAI); volatile-content detector with customer warning (no rewrite); cache-bust drift telemetry.
29
+ - **Phase F β€” Auth-mode policy (1 week):** `classify_auth_mode(headers)` helper returning `payg | oauth | subscription`; per-mode compression policy gates; TOIN aggregation key extended to `(auth_mode, model_family, structure_hash)`; conditional `X-Forwarded-*` headers in Rust.
30
+ - **Phase G β€” RTK + observability (1 week):** extend wrap CLIs (cline, continue, goose, openhands); wire the dead `tokens_saved_rtk` field; per-invocation RTK Prometheus metrics.
31
+ - **Phase H β€” Python retirement (2 weeks):** delete `headroom/proxy/server.py`, all handlers, `responses_converter.py`, `memory_handler.py`, `memory_tool_adapter.py`, `batch.py`, `semantic_cache.py`, all of `headroom/transforms/*` Python (per Phase B); keep CLI wrappers, RTK installer, evals, learn, memory writers, tokenizers, TOIN.
32
+ - **Phase I β€” Test infra (continuous, parallel):** SHA-256 round-trip tests; SSE corner-case fixtures (UTF-8 split, ping, all delta types, `[DONE]`, mid-stream error); property tests (no-panic SSE parser, tokens-non-increasing compression); cache-hit-rate continuous metric; promote `ccr` / `log_compressor` / `cache_aligner` parity comparators from `Skipped` stubs to real; make `make test-parity` a per-PR gate.
33
+
34
+ ## Top 5 wrong assumptions
35
+
36
+ 1. **"Compression means choosing what to drop from history."** Implemented as ICM + DropByScoreStrategy + MessageScorer + relevance + scoring + rolling-window + progressive-summarizer. Fix: retire entirely; compress live-zone content only.
37
+ 2. **"TOIN can influence per-request compression decisions."** `headroom/telemetry/toin.py:853-927` mutates pattern state during a call and returns hints that bias the same-input-bytes decision. Fix: strict observation-only; recommendations published between deploys.
38
+ 3. **"CCR can mutate the cache hot zone (tools array, system prompt) on demand."** `headroom/ccr/tool_injection.py:302-328` only adds `ccr_retrieve` when content was compressed β€” tools list flips between requests. `cache_aligner.py:160-262` and `headroom/proxy/server.py:1051` rewrite the system prompt. Fix: register `ccr_retrieve` on every request; route memory injection to the live zone tail; delete the cache_aligner rewrite path.
39
+ 4. **"Summarizing past turns is a strategy."** `intelligent_context.py:316-353` SUMMARIZE replaces messages with a single summary at the same position β€” head modification. Fix: delete; offer compaction only as an explicit customer-initiated action.
40
+ 5. **"ToolCrusher operates on every tool message in history without a frozen check."** `headroom/transforms/tool_crusher.py:106` iterates all tool messages. Fix: delete; ContentRouter covers the use case correctly.
41
+
42
+ ## What's preserved
43
+
44
+ Per your direction:
45
+ - **TOIN** (Tool Output Intelligence Network) β€” observation-only refactor; per-tenant key
46
+ - **CCR** (Compress-Cache-Retrieve) β€” persistent backend + always-on tool
47
+ - **Kompress-base** β€” plain-text Β§8.6 compressor; stays in Python now, Rust port via `ort` crate later
48
+ - **ContentRouter** β€” Python ~2150 LOC, the architecturally correct piece (NOTE: earlier project memory said 53 K lines β€” that was wrong by 25Γ—; the file is fine)
49
+ - All per-type compressors: SmartCrusher (Rust 25 files), CodeCompressor, LogCompressor, SearchCompressor, DiffCompressor
50
+
51
+ ## What's deleted
52
+
53
+ ~25 K LOC across two languages. See [01-bug-list.md](./01-bug-list.md) Β§6 for the full retirement list with file:line evidence.