xithead 1.4.0 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (661) hide show
  1. package/.actrc +14 -0
  2. package/.actrc.local.example +15 -0
  3. package/.changelog.md +2 -0
  4. package/.claude/agents/academic-anthropologist.md +125 -0
  5. package/.claude/agents/academic-geographer.md +127 -0
  6. package/.claude/agents/academic-historian.md +123 -0
  7. package/.claude/agents/academic-narratologist.md +118 -0
  8. package/.claude/agents/academic-psychologist.md +118 -0
  9. package/.claude/agents/academic-statistician.md +144 -0
  10. package/.claude/agents/accounts-payable-agent.md +205 -0
  11. package/.claude/agents/agentic-identity-trust.md +394 -0
  12. package/.claude/agents/agents-orchestrator.md +367 -0
  13. package/.claude/agents/automation-governance-architect.md +216 -0
  14. package/.claude/agents/blender-addon-engineer.md +243 -0
  15. package/.claude/agents/business-strategist.md +488 -0
  16. package/.claude/agents/change-management-consultant.md +497 -0
  17. package/.claude/agents/chief-financial-officer.md +388 -0
  18. package/.claude/agents/corporate-training-designer.md +192 -0
  19. package/.claude/agents/customer-service.md +398 -0
  20. package/.claude/agents/customer-success-manager.md +460 -0
  21. package/.claude/agents/data-consolidation-agent.md +60 -0
  22. package/.claude/agents/data-privacy-officer.md +412 -0
  23. package/.claude/agents/design-brand-guardian.md +322 -0
  24. package/.claude/agents/design-image-prompt-engineer.md +236 -0
  25. package/.claude/agents/design-inclusive-visuals-specialist.md +73 -0
  26. package/.claude/agents/design-persona-walkthrough.md +272 -0
  27. package/.claude/agents/design-ui-designer.md +386 -0
  28. package/.claude/agents/design-ui-finish-gate-reviewer.md +217 -0
  29. package/.claude/agents/design-ux-architect.md +482 -0
  30. package/.claude/agents/design-ux-researcher.md +329 -0
  31. package/.claude/agents/design-visual-storyteller.md +149 -0
  32. package/.claude/agents/design-whimsy-injector.md +460 -0
  33. package/.claude/agents/economy-designer.md +156 -0
  34. package/.claude/agents/engineering-ai-data-remediation-engineer.md +211 -0
  35. package/.claude/agents/engineering-ai-engineer.md +146 -0
  36. package/.claude/agents/engineering-api-platform-engineer.md +181 -0
  37. package/.claude/agents/engineering-ats-validator-architect.md +383 -0
  38. package/.claude/agents/engineering-autonomous-optimization-architect.md +121 -0
  39. package/.claude/agents/engineering-backend-architect.md +255 -0
  40. package/.claude/agents/engineering-china-network-engineer.md +252 -0
  41. package/.claude/agents/engineering-cms-developer.md +536 -0
  42. package/.claude/agents/engineering-code-reviewer.md +76 -0
  43. package/.claude/agents/engineering-codebase-onboarding-engineer.md +173 -0
  44. package/.claude/agents/engineering-data-engineer.md +349 -0
  45. package/.claude/agents/engineering-data-visualization-engineer.md +151 -0
  46. package/.claude/agents/engineering-database-optimizer.md +188 -0
  47. package/.claude/agents/engineering-database-reliability-engineer.md +201 -0
  48. package/.claude/agents/engineering-desktop-app-engineer.md +209 -0
  49. package/.claude/agents/engineering-developer-tooling-engineer.md +153 -0
  50. package/.claude/agents/engineering-devops-automator.md +385 -0
  51. package/.claude/agents/engineering-drupal-performance.md +347 -0
  52. package/.claude/agents/engineering-drupal-shopping-cart.md +360 -0
  53. package/.claude/agents/engineering-electrical-engineer.md +575 -0
  54. package/.claude/agents/engineering-email-intelligence-engineer.md +390 -0
  55. package/.claude/agents/engineering-embedded-firmware-engineer.md +196 -0
  56. package/.claude/agents/engineering-feishu-integration-developer.md +606 -0
  57. package/.claude/agents/engineering-filament-optimization-specialist.md +283 -0
  58. package/.claude/agents/engineering-finops-engineer.md +164 -0
  59. package/.claude/agents/engineering-frontend-developer.md +257 -0
  60. package/.claude/agents/engineering-gaussdb-expert.md +334 -0
  61. package/.claude/agents/engineering-git-workflow-master.md +98 -0
  62. package/.claude/agents/engineering-i18n-engineer.md +214 -0
  63. package/.claude/agents/engineering-identity-access-engineer.md +217 -0
  64. package/.claude/agents/engineering-incident-response-commander.md +444 -0
  65. package/.claude/agents/engineering-iot-fleet-engineer.md +148 -0
  66. package/.claude/agents/engineering-it-service-manager.md +561 -0
  67. package/.claude/agents/engineering-knowledge-graph-engineer.md +372 -0
  68. package/.claude/agents/engineering-llm-post-training-engineer.md +166 -0
  69. package/.claude/agents/engineering-minimal-change-engineer.md +207 -0
  70. package/.claude/agents/engineering-mobile-app-builder.md +493 -0
  71. package/.claude/agents/engineering-mobile-release-engineer.md +164 -0
  72. package/.claude/agents/engineering-multi-agent-systems-architect.md +600 -0
  73. package/.claude/agents/engineering-network-engineer.md +245 -0
  74. package/.claude/agents/engineering-orgscript-engineer.md +113 -0
  75. package/.claude/agents/engineering-payments-billing-engineer.md +228 -0
  76. package/.claude/agents/engineering-pdf-engine-architect.md +696 -0
  77. package/.claude/agents/engineering-platform-engineer.md +270 -0
  78. package/.claude/agents/engineering-privacy-engineer.md +152 -0
  79. package/.claude/agents/engineering-prompt-engineer.md +209 -0
  80. package/.claude/agents/engineering-rag-pipeline-engineer.md +450 -0
  81. package/.claude/agents/engineering-rapid-prototyper.md +466 -0
  82. package/.claude/agents/engineering-realtime-collaboration-engineer.md +200 -0
  83. package/.claude/agents/engineering-rust-refactoring-specialist.md +313 -0
  84. package/.claude/agents/engineering-search-relevance-engineer.md +237 -0
  85. package/.claude/agents/engineering-section-508-specialist.md +339 -0
  86. package/.claude/agents/engineering-senior-developer.md +176 -0
  87. package/.claude/agents/engineering-servicenow-developer-mentor.md +180 -0
  88. package/.claude/agents/engineering-software-architect.md +112 -0
  89. package/.claude/agents/engineering-solidity-smart-contract-engineer.md +522 -0
  90. package/.claude/agents/engineering-sre.md +90 -0
  91. package/.claude/agents/engineering-technical-writer.md +393 -0
  92. package/.claude/agents/engineering-universal-document-compiler.md +370 -0
  93. package/.claude/agents/engineering-uswds-developer.md +340 -0
  94. package/.claude/agents/engineering-video-streaming-engineer.md +151 -0
  95. package/.claude/agents/engineering-voice-ai-integration-engineer.md +584 -0
  96. package/.claude/agents/engineering-webassembly-engineer.md +153 -0
  97. package/.claude/agents/engineering-wechat-mini-program-developer.md +356 -0
  98. package/.claude/agents/engineering-wordpress-performance.md +346 -0
  99. package/.claude/agents/engineering-wordpress-shopping-cart.md +346 -0
  100. package/.claude/agents/esg-sustainability-officer.md +396 -0
  101. package/.claude/agents/finance-bookkeeper-controller.md +260 -0
  102. package/.claude/agents/finance-financial-analyst.md +234 -0
  103. package/.claude/agents/finance-fpa-analyst.md +263 -0
  104. package/.claude/agents/finance-investment-researcher.md +272 -0
  105. package/.claude/agents/finance-tax-strategist.md +239 -0
  106. package/.claude/agents/game-audio-engineer.md +264 -0
  107. package/.claude/agents/game-designer.md +167 -0
  108. package/.claude/agents/gis-3d-scene-developer.md +111 -0
  109. package/.claude/agents/gis-analyst.md +91 -0
  110. package/.claude/agents/gis-bim-specialist.md +108 -0
  111. package/.claude/agents/gis-cartography-designer.md +150 -0
  112. package/.claude/agents/gis-drone-reality-mapping.md +120 -0
  113. package/.claude/agents/gis-geoai-ml-engineer.md +105 -0
  114. package/.claude/agents/gis-geoprocessing-specialist.md +97 -0
  115. package/.claude/agents/gis-qa-engineer.md +133 -0
  116. package/.claude/agents/gis-solution-engineer.md +101 -0
  117. package/.claude/agents/gis-spatial-data-engineer.md +97 -0
  118. package/.claude/agents/gis-spatial-data-scientist.md +111 -0
  119. package/.claude/agents/gis-technical-consultant.md +86 -0
  120. package/.claude/agents/gis-web-gis-developer.md +108 -0
  121. package/.claude/agents/godot-gameplay-scripter.md +338 -0
  122. package/.claude/agents/godot-multiplayer-engineer.md +301 -0
  123. package/.claude/agents/godot-shader-developer.md +267 -0
  124. package/.claude/agents/government-digital-presales-consultant.md +363 -0
  125. package/.claude/agents/grant-writer.md +511 -0
  126. package/.claude/agents/healthcare-aging-parent-care-companion.md +414 -0
  127. package/.claude/agents/healthcare-clinical-evidence-agent.md +231 -0
  128. package/.claude/agents/healthcare-customer-service.md +389 -0
  129. package/.claude/agents/healthcare-innovation-strategist.md +433 -0
  130. package/.claude/agents/healthcare-marketing-compliance.md +395 -0
  131. package/.claude/agents/healthcare-sovereign-health-systems-agent.md +312 -0
  132. package/.claude/agents/hospitality-guest-services.md +603 -0
  133. package/.claude/agents/hr-onboarding.md +451 -0
  134. package/.claude/agents/identity-graph-operator.md +303 -0
  135. package/.claude/agents/language-translator.md +264 -0
  136. package/.claude/agents/legal-billing-time-tracking.md +569 -0
  137. package/.claude/agents/legal-client-intake.md +492 -0
  138. package/.claude/agents/legal-document-review.md +454 -0
  139. package/.claude/agents/level-designer.md +208 -0
  140. package/.claude/agents/loan-officer-assistant.md +555 -0
  141. package/.claude/agents/lsp-index-engineer.md +320 -0
  142. package/.claude/agents/ma-integration-manager.md +427 -0
  143. package/.claude/agents/macos-spatial-metal-engineer.md +337 -0
  144. package/.claude/agents/marketing-aeo-foundations.md +264 -0
  145. package/.claude/agents/marketing-agentic-search-optimizer.md +279 -0
  146. package/.claude/agents/marketing-ai-citation-strategist.md +172 -0
  147. package/.claude/agents/marketing-app-store-optimizer.md +321 -0
  148. package/.claude/agents/marketing-baidu-seo-specialist.md +226 -0
  149. package/.claude/agents/marketing-bilibili-content-strategist.md +199 -0
  150. package/.claude/agents/marketing-book-co-author.md +110 -0
  151. package/.claude/agents/marketing-carousel-growth-engine.md +204 -0
  152. package/.claude/agents/marketing-china-ecommerce-operator.md +283 -0
  153. package/.claude/agents/marketing-china-market-localization-strategist.md +283 -0
  154. package/.claude/agents/marketing-content-creator.md +54 -0
  155. package/.claude/agents/marketing-cross-border-ecommerce.md +259 -0
  156. package/.claude/agents/marketing-developer-community-builder.md +285 -0
  157. package/.claude/agents/marketing-douyin-strategist.md +149 -0
  158. package/.claude/agents/marketing-email-strategist.md +249 -0
  159. package/.claude/agents/marketing-global-podcast-strategist.md +206 -0
  160. package/.claude/agents/marketing-growth-hacker.md +54 -0
  161. package/.claude/agents/marketing-instagram-curator.md +113 -0
  162. package/.claude/agents/marketing-kuaishou-strategist.md +223 -0
  163. package/.claude/agents/marketing-linkedin-content-creator.md +214 -0
  164. package/.claude/agents/marketing-livestream-commerce-coach.md +305 -0
  165. package/.claude/agents/marketing-multi-platform-publisher.md +217 -0
  166. package/.claude/agents/marketing-podcast-strategist.md +277 -0
  167. package/.claude/agents/marketing-pr-communications-manager.md +473 -0
  168. package/.claude/agents/marketing-private-domain-operator.md +308 -0
  169. package/.claude/agents/marketing-reddit-community-builder.md +123 -0
  170. package/.claude/agents/marketing-seo-specialist.md +370 -0
  171. package/.claude/agents/marketing-short-video-editing-coach.md +412 -0
  172. package/.claude/agents/marketing-social-media-strategist.md +125 -0
  173. package/.claude/agents/marketing-tiktok-strategist.md +125 -0
  174. package/.claude/agents/marketing-twitter-engager.md +126 -0
  175. package/.claude/agents/marketing-video-optimization-specialist.md +119 -0
  176. package/.claude/agents/marketing-wechat-official-account.md +145 -0
  177. package/.claude/agents/marketing-weibo-strategist.md +240 -0
  178. package/.claude/agents/marketing-x-twitter-intelligence-analyst.md +161 -0
  179. package/.claude/agents/marketing-xiaohongshu-specialist.md +138 -0
  180. package/.claude/agents/marketing-zhihu-strategist.md +162 -0
  181. package/.claude/agents/medical-billing-coding-specialist.md +491 -0
  182. package/.claude/agents/narrative-designer.md +243 -0
  183. package/.claude/agents/operations-manager.md +399 -0
  184. package/.claude/agents/organizational-psychologist.md +391 -0
  185. package/.claude/agents/paid-media-auditor.md +71 -0
  186. package/.claude/agents/paid-media-creative-strategist.md +71 -0
  187. package/.claude/agents/paid-media-paid-social-strategist.md +71 -0
  188. package/.claude/agents/paid-media-ppc-strategist.md +71 -0
  189. package/.claude/agents/paid-media-programmatic-buyer.md +71 -0
  190. package/.claude/agents/paid-media-search-query-analyst.md +71 -0
  191. package/.claude/agents/paid-media-tracking-specialist.md +71 -0
  192. package/.claude/agents/personal-growth-mentor.md +159 -0
  193. package/.claude/agents/product-behavioral-nudge-engine.md +83 -0
  194. package/.claude/agents/product-dx-engineer.md +332 -0
  195. package/.claude/agents/product-feedback-synthesizer.md +119 -0
  196. package/.claude/agents/product-manager.md +469 -0
  197. package/.claude/agents/product-sprint-prioritizer.md +154 -0
  198. package/.claude/agents/product-trend-researcher.md +159 -0
  199. package/.claude/agents/project-management-experiment-tracker.md +198 -0
  200. package/.claude/agents/project-management-jira-workflow-steward.md +233 -0
  201. package/.claude/agents/project-management-meeting-notes-specialist.md +95 -0
  202. package/.claude/agents/project-management-project-shepherd.md +194 -0
  203. package/.claude/agents/project-management-studio-operations.md +200 -0
  204. package/.claude/agents/project-management-studio-producer.md +203 -0
  205. package/.claude/agents/project-manager-senior.md +135 -0
  206. package/.claude/agents/real-estate-buyer-seller.md +596 -0
  207. package/.claude/agents/recruitment-specialist.md +515 -0
  208. package/.claude/agents/report-distribution-agent.md +65 -0
  209. package/.claude/agents/research-synthesist.md +136 -0
  210. package/.claude/agents/resume-tailor.md +230 -0
  211. package/.claude/agents/retail-customer-returns.md +566 -0
  212. package/.claude/agents/roblox-avatar-creator.md +297 -0
  213. package/.claude/agents/roblox-experience-designer.md +306 -0
  214. package/.claude/agents/roblox-systems-scripter.md +332 -0
  215. package/.claude/agents/sales-account-strategist.md +227 -0
  216. package/.claude/agents/sales-coach.md +271 -0
  217. package/.claude/agents/sales-data-extraction-agent.md +67 -0
  218. package/.claude/agents/sales-deal-strategist.md +180 -0
  219. package/.claude/agents/sales-discovery-coach.md +225 -0
  220. package/.claude/agents/sales-engineer.md +182 -0
  221. package/.claude/agents/sales-offer-lead-gen-strategist.md +257 -0
  222. package/.claude/agents/sales-outbound-strategist.md +201 -0
  223. package/.claude/agents/sales-outreach.md +425 -0
  224. package/.claude/agents/sales-pipeline-analyst.md +267 -0
  225. package/.claude/agents/sales-proposal-strategist.md +217 -0
  226. package/.claude/agents/security-ai-generated-code-auditor.md +207 -0
  227. package/.claude/agents/security-appsec-engineer.md +536 -0
  228. package/.claude/agents/security-architect.md +307 -0
  229. package/.claude/agents/security-blockchain-security-auditor.md +482 -0
  230. package/.claude/agents/security-cloud-security-architect.md +576 -0
  231. package/.claude/agents/security-compliance-auditor.md +158 -0
  232. package/.claude/agents/security-incident-responder.md +450 -0
  233. package/.claude/agents/security-penetration-tester.md +399 -0
  234. package/.claude/agents/security-secrets-credential-engineer.md +189 -0
  235. package/.claude/agents/security-senior-secops.md +760 -0
  236. package/.claude/agents/security-threat-detection-engineer.md +553 -0
  237. package/.claude/agents/security-threat-intelligence-analyst.md +661 -0
  238. package/.claude/agents/specialized-chief-of-staff.md +279 -0
  239. package/.claude/agents/specialized-civil-engineer.md +356 -0
  240. package/.claude/agents/specialized-codebase-archaeologist.md +341 -0
  241. package/.claude/agents/specialized-cultural-intelligence-strategist.md +88 -0
  242. package/.claude/agents/specialized-developer-advocate.md +317 -0
  243. package/.claude/agents/specialized-document-generator.md +55 -0
  244. package/.claude/agents/specialized-fedramp-rmf-compliance.md +378 -0
  245. package/.claude/agents/specialized-focus-music-architect.md +175 -0
  246. package/.claude/agents/specialized-french-consulting-market.md +194 -0
  247. package/.claude/agents/specialized-korean-business-navigator.md +216 -0
  248. package/.claude/agents/specialized-master-plan-architect.md +157 -0
  249. package/.claude/agents/specialized-mcp-builder.md +260 -0
  250. package/.claude/agents/specialized-model-qa.md +528 -0
  251. package/.claude/agents/specialized-pricing-analyst.md +243 -0
  252. package/.claude/agents/specialized-salesforce-architect.md +182 -0
  253. package/.claude/agents/specialized-strategy-duel-agent.md +130 -0
  254. package/.claude/agents/specialized-workflow-architect.md +597 -0
  255. package/.claude/agents/study-abroad-advisor.md +282 -0
  256. package/.claude/agents/supply-chain-strategist.md +591 -0
  257. package/.claude/agents/support-analytics-reporter.md +387 -0
  258. package/.claude/agents/support-executive-summary-generator.md +212 -0
  259. package/.claude/agents/support-finance-tracker.md +480 -0
  260. package/.claude/agents/support-infrastructure-maintainer.md +628 -0
  261. package/.claude/agents/support-legal-compliance-checker.md +591 -0
  262. package/.claude/agents/support-support-responder.md +607 -0
  263. package/.claude/agents/technical-artist.md +233 -0
  264. package/.claude/agents/terminal-integration-specialist.md +70 -0
  265. package/.claude/agents/testing-accessibility-auditor.md +327 -0
  266. package/.claude/agents/testing-api-tester.md +334 -0
  267. package/.claude/agents/testing-evidence-collector.md +210 -0
  268. package/.claude/agents/testing-performance-benchmarker.md +283 -0
  269. package/.claude/agents/testing-reality-checker.md +249 -0
  270. package/.claude/agents/testing-test-automation-engineer.md +196 -0
  271. package/.claude/agents/testing-test-results-analyzer.md +330 -0
  272. package/.claude/agents/testing-tool-evaluator.md +416 -0
  273. package/.claude/agents/testing-workflow-optimizer.md +463 -0
  274. package/.claude/agents/unity-architect.md +271 -0
  275. package/.claude/agents/unity-editor-tool-developer.md +310 -0
  276. package/.claude/agents/unity-multiplayer-engineer.md +323 -0
  277. package/.claude/agents/unity-shader-graph-artist.md +269 -0
  278. package/.claude/agents/unreal-multiplayer-architect.md +364 -0
  279. package/.claude/agents/unreal-systems-engineer.md +322 -0
  280. package/.claude/agents/unreal-technical-artist.md +256 -0
  281. package/.claude/agents/unreal-world-builder.md +273 -0
  282. package/.claude/agents/visionos-spatial-engineer.md +54 -0
  283. package/.claude/agents/xr-cockpit-interaction-specialist.md +32 -0
  284. package/.claude/agents/xr-immersive-developer.md +32 -0
  285. package/.claude/agents/xr-interface-architect.md +32 -0
  286. package/.claude/agents/zk-steward.md +211 -0
  287. package/.claude-plugin/marketplace.json +30 -0
  288. package/.commitlintrc.json +26 -0
  289. package/.devcontainer/Dockerfile +24 -0
  290. package/.devcontainer/devcontainer.json +70 -0
  291. package/.devcontainer/docker-compose.memory.yml +42 -0
  292. package/.devcontainer/memory-stack/devcontainer.json +84 -0
  293. package/.devcontainer/post-create.sh +83 -0
  294. package/.dockerignore +23 -0
  295. package/.env.act.example +15 -0
  296. package/.env.example +171 -0
  297. package/.eslintrc.json +16 -0
  298. package/.git-blame-ignore-revs +10 -0
  299. package/.gitattributes +2 -0
  300. package/.gitguardian.yaml +50 -0
  301. package/.githooks/pre-commit +6 -0
  302. package/.pre-commit-config.yaml +30 -0
  303. package/.release-please-config-xithead.json +22 -0
  304. package/.release-please-config.json +44 -0
  305. package/.release-please-manifest-xithead.json +3 -0
  306. package/.release-please-manifest.json +3 -0
  307. package/CODE_OF_CONDUCT.md +133 -0
  308. package/CONTRIBUTING.md +133 -0
  309. package/Cargo.lock +5557 -0
  310. package/Cargo.toml +121 -0
  311. package/Dockerfile +38 -0
  312. package/Dockerfile.proxy +48 -0
  313. package/ENTERPRISE.md +5 -0
  314. package/FEATURES_ADVANCED.md +311 -0
  315. package/Headroom-2.gif +0 -0
  316. package/HeadroomDemo-Fast.gif +0 -0
  317. package/MANIFEST.in +4 -0
  318. package/MODERNIZATION_GUIDE.md +358 -0
  319. package/Makefile +140 -0
  320. package/NOTICE +43 -0
  321. package/NPM_TOKEN_SETUP.md +81 -0
  322. package/PR.md +170 -0
  323. package/PUBLISH.md +77 -0
  324. package/README.md +108 -72
  325. package/README_FRONTEND.md +196 -0
  326. package/REALIGNMENT/00-overview.md +53 -0
  327. package/REALIGNMENT/01-bug-list.md +421 -0
  328. package/REALIGNMENT/02-architecture.md +322 -0
  329. package/REALIGNMENT/03-phase-A-lockdown.md +420 -0
  330. package/REALIGNMENT/04-phase-B-live-zone.md +470 -0
  331. package/REALIGNMENT/05-phase-C-rust-proxy.md +329 -0
  332. package/REALIGNMENT/06-phase-D-bedrock-vertex.md +222 -0
  333. package/REALIGNMENT/07-phase-E-cache-stabilization.md +338 -0
  334. package/REALIGNMENT/08-phase-F-auth-mode.md +254 -0
  335. package/REALIGNMENT/09-phase-G-rtk-observability.md +194 -0
  336. package/REALIGNMENT/10-phase-H-python-retirement.md +214 -0
  337. package/REALIGNMENT/11-phase-I-test-infra.md +385 -0
  338. package/REALIGNMENT/12-decisions-needed.md +196 -0
  339. package/REALIGNMENT/INDEX.md +82 -0
  340. package/REFACTORING_CAMPAIGN.md +277 -0
  341. package/RESTRUCTURE_PLAN.md +100 -0
  342. package/RUST_DEV.md +361 -0
  343. package/SECURITY.md +65 -0
  344. package/SETUP_AUTO_PUBLISH.md +164 -0
  345. package/TESTING-copilot-subscription.md +153 -0
  346. package/app/api/config/route.ts +22 -0
  347. package/app/api/export/route.ts +83 -0
  348. package/app/api/models/route.ts +12 -0
  349. package/app/api/stats/route.ts +46 -0
  350. package/app/dashboard/page.tsx +445 -0
  351. package/app/globals.css +35 -0
  352. package/app/installation/page.tsx +293 -0
  353. package/app/layout.tsx +35 -0
  354. package/app/master-design-system.css +2076 -0
  355. package/app/master-design-system.source.css +8 -0
  356. package/app/page.tsx +187 -0
  357. package/app/rechtliches/agb/page.tsx +165 -0
  358. package/app/rechtliches/datenschutz/page.tsx +128 -0
  359. package/app/rechtliches/impressum/page.tsx +122 -0
  360. package/app/rechtliches/widerruf/page.tsx +185 -0
  361. package/bin/xithead.js +264 -0
  362. package/codecov.yml +34 -0
  363. package/components/layout/AppShell.tsx +25 -0
  364. package/components/layout/Footer.tsx +120 -0
  365. package/components/layout/Header.tsx +145 -0
  366. package/components/marketing/LegalHighlights.tsx +45 -0
  367. package/components/marketing/LegalPageShell.tsx +49 -0
  368. package/components/marketing/LegalPanel.tsx +41 -0
  369. package/components/marketing/index.ts +3 -0
  370. package/crates/headroom-core/Cargo.toml +165 -0
  371. package/crates/headroom-core/benches/auth_mode.rs +74 -0
  372. package/crates/headroom-core/benches/ccr_store.rs +224 -0
  373. package/crates/headroom-core/benches/tokenizer.rs +52 -0
  374. package/crates/headroom-core/config/pipeline.toml +151 -0
  375. package/crates/headroom-core/proptest-regressions/transforms/tag_protector.txt +9 -0
  376. package/crates/headroom-core/src/auth_mode.rs +250 -0
  377. package/crates/headroom-core/src/cache_control.rs +414 -0
  378. package/crates/headroom-core/src/ccr/backends/in_memory.rs +317 -0
  379. package/crates/headroom-core/src/ccr/backends/mod.rs +152 -0
  380. package/crates/headroom-core/src/ccr/backends/redis.rs +146 -0
  381. package/crates/headroom-core/src/ccr/backends/sqlite.rs +205 -0
  382. package/crates/headroom-core/src/ccr/mod.rs +119 -0
  383. package/crates/headroom-core/src/compression_policy.rs +505 -0
  384. package/crates/headroom-core/src/lib.rs +33 -0
  385. package/crates/headroom-core/src/relevance/base.rs +139 -0
  386. package/crates/headroom-core/src/relevance/bm25.rs +385 -0
  387. package/crates/headroom-core/src/relevance/embedding.rs +354 -0
  388. package/crates/headroom-core/src/relevance/hybrid.rs +364 -0
  389. package/crates/headroom-core/src/relevance/mod.rs +64 -0
  390. package/crates/headroom-core/src/signals/keyword_detector.rs +433 -0
  391. package/crates/headroom-core/src/signals/line_importance.rs +84 -0
  392. package/crates/headroom-core/src/signals/mod.rs +61 -0
  393. package/crates/headroom-core/src/signals/tiered.rs +141 -0
  394. package/crates/headroom-core/src/tokenizer/estimator.rs +152 -0
  395. package/crates/headroom-core/src/tokenizer/hf_impl.rs +314 -0
  396. package/crates/headroom-core/src/tokenizer/mod.rs +56 -0
  397. package/crates/headroom-core/src/tokenizer/registry.rs +342 -0
  398. package/crates/headroom-core/src/tokenizer/tiktoken_impl.rs +265 -0
  399. package/crates/headroom-core/src/transforms/adaptive_sizer.rs +610 -0
  400. package/crates/headroom-core/src/transforms/anchor_selector.rs +1189 -0
  401. package/crates/headroom-core/src/transforms/content_detector.rs +769 -0
  402. package/crates/headroom-core/src/transforms/detection.rs +222 -0
  403. package/crates/headroom-core/src/transforms/diff_compressor.rs +1685 -0
  404. package/crates/headroom-core/src/transforms/live_zone.rs +2967 -0
  405. package/crates/headroom-core/src/transforms/log_compressor.rs +1295 -0
  406. package/crates/headroom-core/src/transforms/magika_detector.rs +395 -0
  407. package/crates/headroom-core/src/transforms/mod.rs +64 -0
  408. package/crates/headroom-core/src/transforms/pipeline/config.rs +331 -0
  409. package/crates/headroom-core/src/transforms/pipeline/mod.rs +103 -0
  410. package/crates/headroom-core/src/transforms/pipeline/offloads/diff_noise.rs +524 -0
  411. package/crates/headroom-core/src/transforms/pipeline/offloads/diff_offload.rs +279 -0
  412. package/crates/headroom-core/src/transforms/pipeline/offloads/json_offload.rs +400 -0
  413. package/crates/headroom-core/src/transforms/pipeline/offloads/log_offload.rs +284 -0
  414. package/crates/headroom-core/src/transforms/pipeline/offloads/mod.rs +34 -0
  415. package/crates/headroom-core/src/transforms/pipeline/offloads/search_offload.rs +331 -0
  416. package/crates/headroom-core/src/transforms/pipeline/orchestrator.rs +848 -0
  417. package/crates/headroom-core/src/transforms/pipeline/reformats/json_minifier.rs +175 -0
  418. package/crates/headroom-core/src/transforms/pipeline/reformats/log_template.rs +545 -0
  419. package/crates/headroom-core/src/transforms/pipeline/reformats/mod.rs +12 -0
  420. package/crates/headroom-core/src/transforms/pipeline/traits.rs +338 -0
  421. package/crates/headroom-core/src/transforms/recommendations.rs +329 -0
  422. package/crates/headroom-core/src/transforms/safety.rs +215 -0
  423. package/crates/headroom-core/src/transforms/search_compressor.rs +902 -0
  424. package/crates/headroom-core/src/transforms/smart_crusher/analyzer.rs +1262 -0
  425. package/crates/headroom-core/src/transforms/smart_crusher/anchors.rs +407 -0
  426. package/crates/headroom-core/src/transforms/smart_crusher/builder.rs +263 -0
  427. package/crates/headroom-core/src/transforms/smart_crusher/classifier.rs +214 -0
  428. package/crates/headroom-core/src/transforms/smart_crusher/compaction/classifier.rs +283 -0
  429. package/crates/headroom-core/src/transforms/smart_crusher/compaction/compactor.rs +733 -0
  430. package/crates/headroom-core/src/transforms/smart_crusher/compaction/formatter.rs +961 -0
  431. package/crates/headroom-core/src/transforms/smart_crusher/compaction/ir.rs +252 -0
  432. package/crates/headroom-core/src/transforms/smart_crusher/compaction/mod.rs +127 -0
  433. package/crates/headroom-core/src/transforms/smart_crusher/compaction/walker.rs +397 -0
  434. package/crates/headroom-core/src/transforms/smart_crusher/config.rs +173 -0
  435. package/crates/headroom-core/src/transforms/smart_crusher/constraints.rs +159 -0
  436. package/crates/headroom-core/src/transforms/smart_crusher/crusher.rs +1665 -0
  437. package/crates/headroom-core/src/transforms/smart_crusher/crushers.rs +865 -0
  438. package/crates/headroom-core/src/transforms/smart_crusher/error_keywords.rs +77 -0
  439. package/crates/headroom-core/src/transforms/smart_crusher/field_detect.rs +393 -0
  440. package/crates/headroom-core/src/transforms/smart_crusher/hashing.rs +72 -0
  441. package/crates/headroom-core/src/transforms/smart_crusher/mod.rs +81 -0
  442. package/crates/headroom-core/src/transforms/smart_crusher/observer.rs +66 -0
  443. package/crates/headroom-core/src/transforms/smart_crusher/orchestration.rs +459 -0
  444. package/crates/headroom-core/src/transforms/smart_crusher/outliers.rs +507 -0
  445. package/crates/headroom-core/src/transforms/smart_crusher/planning.rs +904 -0
  446. package/crates/headroom-core/src/transforms/smart_crusher/statistics.rs +510 -0
  447. package/crates/headroom-core/src/transforms/smart_crusher/stats_math.rs +287 -0
  448. package/crates/headroom-core/src/transforms/smart_crusher/traits.rs +203 -0
  449. package/crates/headroom-core/src/transforms/smart_crusher/types.rs +263 -0
  450. package/crates/headroom-core/src/transforms/tag_protector.rs +1272 -0
  451. package/crates/headroom-core/src/transforms/unidiff_detector.rs +232 -0
  452. package/crates/headroom-parity/Cargo.toml +26 -0
  453. package/crates/headroom-parity/examples/diff_fixture.rs +66 -0
  454. package/crates/headroom-parity/src/bin/parity_run.rs +78 -0
  455. package/crates/headroom-parity/src/lib.rs +613 -0
  456. package/crates/headroom-proxy/Cargo.toml +119 -0
  457. package/crates/headroom-proxy/data/model_prices_and_context_window.json +39767 -0
  458. package/crates/headroom-proxy/src/bedrock/auth_mode_layer.rs +192 -0
  459. package/crates/headroom-proxy/src/bedrock/envelope.rs +239 -0
  460. package/crates/headroom-proxy/src/bedrock/eventstream.rs +769 -0
  461. package/crates/headroom-proxy/src/bedrock/eventstream_to_sse.rs +459 -0
  462. package/crates/headroom-proxy/src/bedrock/invoke.rs +735 -0
  463. package/crates/headroom-proxy/src/bedrock/invoke_streaming.rs +1098 -0
  464. package/crates/headroom-proxy/src/bedrock/mod.rs +66 -0
  465. package/crates/headroom-proxy/src/bedrock/sigv4.rs +324 -0
  466. package/crates/headroom-proxy/src/bedrock/vendor.rs +82 -0
  467. package/crates/headroom-proxy/src/cache_stabilization/anthropic_cache_control.rs +698 -0
  468. package/crates/headroom-proxy/src/cache_stabilization/drift_detector.rs +683 -0
  469. package/crates/headroom-proxy/src/cache_stabilization/mod.rs +61 -0
  470. package/crates/headroom-proxy/src/cache_stabilization/openai_cache_key.rs +600 -0
  471. package/crates/headroom-proxy/src/cache_stabilization/tool_def_normalize.rs +514 -0
  472. package/crates/headroom-proxy/src/cache_stabilization/volatile_detector.rs +720 -0
  473. package/crates/headroom-proxy/src/compression/anthropic.rs +92 -0
  474. package/crates/headroom-proxy/src/compression/live_zone_anthropic.rs +1311 -0
  475. package/crates/headroom-proxy/src/compression/live_zone_openai.rs +660 -0
  476. package/crates/headroom-proxy/src/compression/live_zone_responses.rs +678 -0
  477. package/crates/headroom-proxy/src/compression/mod.rs +127 -0
  478. package/crates/headroom-proxy/src/compression/model_limits.rs +211 -0
  479. package/crates/headroom-proxy/src/config.rs +646 -0
  480. package/crates/headroom-proxy/src/error.rs +69 -0
  481. package/crates/headroom-proxy/src/handlers/chat_completions.rs +100 -0
  482. package/crates/headroom-proxy/src/handlers/conversations.rs +241 -0
  483. package/crates/headroom-proxy/src/handlers/mod.rs +13 -0
  484. package/crates/headroom-proxy/src/handlers/responses.rs +256 -0
  485. package/crates/headroom-proxy/src/headers.rs +288 -0
  486. package/crates/headroom-proxy/src/health.rs +41 -0
  487. package/crates/headroom-proxy/src/lib.rs +21 -0
  488. package/crates/headroom-proxy/src/main.rs +141 -0
  489. package/crates/headroom-proxy/src/observability/cache_hit_rate.rs +340 -0
  490. package/crates/headroom-proxy/src/observability/compression_ratio.rs +158 -0
  491. package/crates/headroom-proxy/src/observability/metric_names.rs +174 -0
  492. package/crates/headroom-proxy/src/observability/mod.rs +68 -0
  493. package/crates/headroom-proxy/src/observability/prometheus.rs +394 -0
  494. package/crates/headroom-proxy/src/observability/proxy_metrics.rs +368 -0
  495. package/crates/headroom-proxy/src/proxy.rs +1619 -0
  496. package/crates/headroom-proxy/src/responses_items.rs +565 -0
  497. package/crates/headroom-proxy/src/sse/anthropic.rs +415 -0
  498. package/crates/headroom-proxy/src/sse/framing.rs +366 -0
  499. package/crates/headroom-proxy/src/sse/mod.rs +40 -0
  500. package/crates/headroom-proxy/src/sse/openai_chat.rs +231 -0
  501. package/crates/headroom-proxy/src/sse/openai_responses.rs +458 -0
  502. package/crates/headroom-proxy/src/vertex/adc.rs +315 -0
  503. package/crates/headroom-proxy/src/vertex/envelope.rs +167 -0
  504. package/crates/headroom-proxy/src/vertex/mod.rs +277 -0
  505. package/crates/headroom-proxy/src/vertex/raw_predict.rs +490 -0
  506. package/crates/headroom-proxy/src/vertex/stream_raw_predict.rs +49 -0
  507. package/crates/headroom-proxy/src/websocket.rs +246 -0
  508. package/crates/headroom-py/Cargo.toml +37 -0
  509. package/crates/headroom-py/build.rs +77 -0
  510. package/crates/headroom-py/glibc_compat.c +170 -0
  511. package/crates/headroom-py/src/lib.rs +1655 -0
  512. package/deny.toml +32 -0
  513. package/design-system/base.css +127 -0
  514. package/design-system/components.css +1943 -0
  515. package/design-system/fonts.css +17 -0
  516. package/design-system/tailwind-preset.js +95 -0
  517. package/design-system/tokens.css +48 -0
  518. package/design-system/utilities.css +53 -0
  519. package/docker/differential-network-capture/Dockerfile.runner +14 -0
  520. package/docker/differential-network-capture/docker-compose.yml +142 -0
  521. package/docker/differential-network-capture/run-claude-lane.sh +24 -0
  522. package/docker/docker-compose.native.yml +44 -0
  523. package/docker-bake.hcl +88 -0
  524. package/docker-compose.yml +80 -0
  525. package/e2e/_lib/make_shim.ps1 +24 -0
  526. package/e2e/_lib/make_shim.sh +28 -0
  527. package/e2e/docker-native-install.sh +120 -0
  528. package/e2e/init/Dockerfile +79 -0
  529. package/e2e/wrap/Dockerfile +115 -0
  530. package/examples/07-context-compression.ipynb +279 -0
  531. package/examples/deployment/macos-launchagent/com.headroom.proxy.plist.template +65 -0
  532. package/examples/deployment/macos-launchagent/install.sh +227 -0
  533. package/examples/deployment/macos-launchagent/shell-integration.sh +74 -0
  534. package/examples/deployment/macos-launchagent/uninstall.sh +145 -0
  535. package/headroom-savings.png +0 -0
  536. package/headroom_learn.gif +0 -0
  537. package/lib/config/index.ts +12 -0
  538. package/lib/hooks/index.ts +4 -0
  539. package/lib/hooks/use-mounted.ts +13 -0
  540. package/lib/hooks/use-session.ts +34 -0
  541. package/lib/hooks/use-settings.ts +49 -0
  542. package/lib/utils/index.ts +1 -0
  543. package/lib/utils/settings.ts +162 -0
  544. package/lib/utils/utils.ts +6 -0
  545. package/llms.txt +67 -0
  546. package/middleware.ts +26 -0
  547. package/mkdocs.yml +136 -0
  548. package/next-env.d.ts +7 -0
  549. package/next.config.ts +12 -0
  550. package/npm/bin/xithead.js +366 -366
  551. package/npm/bin/xtream-head.js +366 -0
  552. package/npm/index.d.ts +57 -57
  553. package/npm/index.js +139 -139
  554. package/npm/package.json +55 -54
  555. package/npm/postinstall.js +43 -43
  556. package/package.json +58 -36
  557. package/plugins/headroom-agent-hooks/.claude-plugin/plugin.json +17 -0
  558. package/plugins/headroom-agent-hooks/hooks/hooks.json +29 -0
  559. package/plugins/headroom-oauth2/LICENSE +3 -0
  560. package/plugins/headroom-oauth2/SPEC.md +115 -0
  561. package/plugins/headroom-oauth2/pyproject.toml +48 -0
  562. package/plugins/hermes/headroom_retrieve/plugin.yaml +6 -0
  563. package/plugins/openclaw/hook-shim/HOOK.md +21 -0
  564. package/plugins/openclaw/hook-shim/handler.js +3 -0
  565. package/plugins/openclaw/openclaw.plugin.json +98 -0
  566. package/plugins/openclaw/package-lock.json +2692 -0
  567. package/plugins/openclaw/package.json +54 -0
  568. package/plugins/openclaw/prepare-dist.mjs +56 -0
  569. package/plugins/openclaw/src/convert.ts +418 -0
  570. package/plugins/openclaw/src/engine.ts +284 -0
  571. package/plugins/openclaw/src/gateway-config.ts +143 -0
  572. package/plugins/openclaw/src/index.ts +11 -0
  573. package/plugins/openclaw/src/plugin/index.ts +98 -0
  574. package/plugins/openclaw/src/proxy-manager.ts +477 -0
  575. package/plugins/openclaw/src/tools/headroom-retrieve.ts +76 -0
  576. package/plugins/openclaw/test/convert.test.ts +96 -0
  577. package/plugins/openclaw/test/engine-normalization.test.ts +21 -0
  578. package/plugins/openclaw/test/engine.test.ts +101 -0
  579. package/plugins/openclaw/test/gateway-config.test.ts +278 -0
  580. package/plugins/openclaw/test/plugin-runtime-routing.test.ts +141 -0
  581. package/plugins/openclaw/test/proxy-manager.test.ts +343 -0
  582. package/plugins/openclaw/tsup.config.ts +9 -0
  583. package/postcss.config.mjs +7 -0
  584. package/pyproject.toml +438 -0
  585. package/rust-toolchain.toml +16 -0
  586. package/sdk/typescript/examples/basic-compress.ts +64 -0
  587. package/sdk/typescript/examples/ccr-retrieve.ts +80 -0
  588. package/sdk/typescript/examples/hooks-custom-compression.ts +117 -0
  589. package/sdk/typescript/examples/middleware-composition.ts +59 -0
  590. package/sdk/typescript/examples/multi-provider.ts +53 -0
  591. package/sdk/typescript/examples/openai-anthropic-adapters.ts +73 -0
  592. package/sdk/typescript/examples/shared-context-multi-agent.ts +74 -0
  593. package/sdk/typescript/examples/simulation-dry-run.ts +80 -0
  594. package/sdk/typescript/examples/streaming-chat.ts +71 -0
  595. package/sdk/typescript/examples/structured-output.ts +99 -0
  596. package/sdk/typescript/examples/tool-calling-agent.ts +86 -0
  597. package/sdk/typescript/examples/with-headroom-vercel.ts +57 -0
  598. package/sdk/typescript/package-lock.json +3437 -0
  599. package/sdk/typescript/package.json +108 -0
  600. package/sdk/typescript/src/adapters/anthropic.ts +218 -0
  601. package/sdk/typescript/src/adapters/gemini.ts +83 -0
  602. package/sdk/typescript/src/adapters/openai.ts +77 -0
  603. package/sdk/typescript/src/adapters/vercel-ai.ts +131 -0
  604. package/sdk/typescript/src/client.ts +632 -0
  605. package/sdk/typescript/src/compress.ts +87 -0
  606. package/sdk/typescript/src/errors.ts +114 -0
  607. package/sdk/typescript/src/hooks.ts +113 -0
  608. package/sdk/typescript/src/index.ts +140 -0
  609. package/sdk/typescript/src/paths.ts +272 -0
  610. package/sdk/typescript/src/shared-context.ts +188 -0
  611. package/sdk/typescript/src/simulate.ts +52 -0
  612. package/sdk/typescript/src/types/config.ts +183 -0
  613. package/sdk/typescript/src/types/models.ts +314 -0
  614. package/sdk/typescript/src/types.ts +139 -0
  615. package/sdk/typescript/src/utils/case.ts +34 -0
  616. package/sdk/typescript/src/utils/format.ts +480 -0
  617. package/sdk/typescript/src/utils/stream.ts +50 -0
  618. package/sdk/typescript/test/adapters/anthropic.test.ts +217 -0
  619. package/sdk/typescript/test/adapters/gemini.test.ts +131 -0
  620. package/sdk/typescript/test/adapters/openai.test.ts +174 -0
  621. package/sdk/typescript/test/adapters/vercel-ai.test.ts +306 -0
  622. package/sdk/typescript/test/client-expanded.test.ts +333 -0
  623. package/sdk/typescript/test/client.test.ts +266 -0
  624. package/sdk/typescript/test/compress.test.ts +118 -0
  625. package/sdk/typescript/test/config.test.ts +275 -0
  626. package/sdk/typescript/test/errors.test.ts +169 -0
  627. package/sdk/typescript/test/format-integration.test.ts +252 -0
  628. package/sdk/typescript/test/hooks.test.ts +265 -0
  629. package/sdk/typescript/test/integration.test.ts +249 -0
  630. package/sdk/typescript/test/mdx-examples.test.ts +253 -0
  631. package/sdk/typescript/test/models.test.ts +318 -0
  632. package/sdk/typescript/test/parity.test.ts +337 -0
  633. package/sdk/typescript/test/paths.test.ts +447 -0
  634. package/sdk/typescript/test/shared-context.test.ts +245 -0
  635. package/sdk/typescript/test/simulate.test.ts +84 -0
  636. package/sdk/typescript/test/types.test.ts +244 -0
  637. package/sdk/typescript/test/utils/case.test.ts +129 -0
  638. package/sdk/typescript/test/utils/detect-format.test.ts +133 -0
  639. package/sdk/typescript/test/utils/format.test.ts +434 -0
  640. package/sdk/typescript/test/vercel-ai-e2e.test.ts +179 -0
  641. package/sdk/typescript/tsup.config.ts +17 -0
  642. package/tailwind.master.config.cjs +47 -0
  643. package/types/api.ts +12 -0
  644. package/types/config.ts +9 -0
  645. package/types/index.ts +2 -0
  646. package/uv.lock +6951 -0
  647. package/xithead.egg-info/PKG-INFO +22 -0
  648. package/xithead.egg-info/SOURCES.txt +16 -0
  649. package/xithead.egg-info/dependency_links.txt +1 -0
  650. package/xithead.egg-info/entry_points.txt +2 -0
  651. package/xithead.egg-info/requires.txt +10 -0
  652. package/xithead.egg-info/top_level.txt +2 -0
  653. package/xithead.ps1 +136 -0
  654. package/xithead.sh +129 -0
  655. package/xithead_dist/pyproject.toml +39 -0
  656. package/xithead_dist/xithead.egg-info/PKG-INFO +22 -0
  657. package/xithead_dist/xithead.egg-info/SOURCES.txt +16 -0
  658. package/xithead_dist/xithead.egg-info/dependency_links.txt +1 -0
  659. package/xithead_dist/xithead.egg-info/entry_points.txt +3 -0
  660. package/xithead_dist/xithead.egg-info/requires.txt +10 -0
  661. package/xithead_dist/xithead.egg-info/top_level.txt +2 -0
@@ -0,0 +1,120 @@
1
+ #!/usr/bin/env bash
2
+
3
+ set -euo pipefail
4
+
5
+ ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
6
+ IMAGE="${HEADROOM_DOCKER_IMAGE:?set HEADROOM_DOCKER_IMAGE to a built test image}"
7
+ PROFILE="ci-smoke"
8
+ TMP_HOME="$(mktemp -d)"
9
+ PORT="$(python3 - <<'PY'
10
+ import socket
11
+
12
+ with socket.socket() as sock:
13
+ sock.bind(("127.0.0.1", 0))
14
+ print(sock.getsockname()[1])
15
+ PY
16
+ )"
17
+
18
+ cleanup() {
19
+ docker rm -f "headroom-${PROFILE}" >/dev/null 2>&1 || true
20
+ rm -rf "${TMP_HOME}"
21
+ }
22
+ trap cleanup EXIT
23
+
24
+ mkdir -p "${TMP_HOME}/.local"
25
+ export HOME="${TMP_HOME}"
26
+ export PATH="${HOME}/.local/bin:${PATH}"
27
+ export HEADROOM_DOCKER_IMAGE="${IMAGE}"
28
+
29
+ bash "${ROOT_DIR}/scripts/install.sh"
30
+
31
+ WRAPPER="${HOME}/.local/bin/headroom"
32
+ [[ -x "${WRAPPER}" ]]
33
+
34
+ "${WRAPPER}" install -? | grep -Fq "persistent-docker preset only"
35
+
36
+ "${WRAPPER}" install apply \
37
+ --profile "${PROFILE}" \
38
+ --port "${PORT}" \
39
+ --image "${IMAGE}" \
40
+ --no-telemetry
41
+
42
+ status_output="$("${WRAPPER}" install status --profile "${PROFILE}")"
43
+ printf '%s\n' "${status_output}"
44
+ grep -Fq "Status: running" <<<"${status_output}"
45
+ curl --fail --silent "http://127.0.0.1:${PORT}/readyz" >/dev/null
46
+ health_output="$(curl --fail --silent "http://127.0.0.1:${PORT}/health")"
47
+
48
+ python3 - <<'PY' "${HOME}" "${PROFILE}" "${PORT}" "${health_output}"
49
+ import json
50
+ import sys
51
+ from pathlib import Path
52
+
53
+ home = Path(sys.argv[1])
54
+ profile = sys.argv[2]
55
+ port = int(sys.argv[3])
56
+ health = json.loads(sys.argv[4])
57
+ manifest = json.loads((home / ".headroom" / "deploy" / profile / "manifest.json").read_text())
58
+ assert manifest["preset"] == "persistent-docker"
59
+ assert manifest["port"] == port
60
+ assert manifest["telemetry_enabled"] is False
61
+ assert health["deployment"]["profile"] == profile
62
+ assert health["deployment"]["preset"] == "persistent-docker"
63
+ assert health["deployment"]["runtime"] == "docker"
64
+ PY
65
+
66
+ if apply_error="$("${WRAPPER}" install apply --scope user 2>&1)"; then
67
+ echo "expected docker-native install apply --scope user to fail" >&2
68
+ exit 1
69
+ fi
70
+ grep -Fq "does not support provider/user/system mutation flags" <<<"${apply_error}"
71
+
72
+ # issue-175: prove the canonical filesystem-contract env vars reached the
73
+ # running container. Unit tests lock install-time forwarding; this asserts
74
+ # the runtime view. We inspect before stopping because `install stop` tears
75
+ # the container down.
76
+ CONTAINER_NAME="headroom-${PROFILE}"
77
+ expected_workspace_dir="/tmp/headroom-home/.headroom"
78
+ expected_config_dir="/tmp/headroom-home/.headroom/config"
79
+
80
+ container_env="$(docker inspect --format '{{range .Config.Env}}{{println .}}{{end}}' "${CONTAINER_NAME}")"
81
+ printf '%s\n' "${container_env}"
82
+
83
+ if ! grep -Fxq "HEADROOM_WORKSPACE_DIR=${expected_workspace_dir}" <<<"${container_env}"; then
84
+ echo "HEADROOM_WORKSPACE_DIR missing from ${CONTAINER_NAME} env (expected=${expected_workspace_dir})" >&2
85
+ exit 1
86
+ fi
87
+ if ! grep -Fxq "HEADROOM_CONFIG_DIR=${expected_config_dir}" <<<"${container_env}"; then
88
+ echo "HEADROOM_CONFIG_DIR missing from ${CONTAINER_NAME} env (expected=${expected_config_dir})" >&2
89
+ exit 1
90
+ fi
91
+
92
+ # Belt-and-suspenders: also assert via `docker exec` so we prove the vars are
93
+ # visible to a process running inside the container (not just in the static
94
+ # Config.Env snapshot).
95
+ exec_env="$(docker exec "${CONTAINER_NAME}" env)"
96
+ if ! grep -Fxq "HEADROOM_WORKSPACE_DIR=${expected_workspace_dir}" <<<"${exec_env}"; then
97
+ echo "HEADROOM_WORKSPACE_DIR not visible to docker exec in ${CONTAINER_NAME}" >&2
98
+ exit 1
99
+ fi
100
+ if ! grep -Fxq "HEADROOM_CONFIG_DIR=${expected_config_dir}" <<<"${exec_env}"; then
101
+ echo "HEADROOM_CONFIG_DIR not visible to docker exec in ${CONTAINER_NAME}" >&2
102
+ exit 1
103
+ fi
104
+
105
+ "${WRAPPER}" install stop --profile "${PROFILE}"
106
+ stopped_output="$("${WRAPPER}" install status --profile "${PROFILE}")"
107
+ printf '%s\n' "${stopped_output}"
108
+ grep -Fq "Status: stopped" <<<"${stopped_output}"
109
+
110
+ "${WRAPPER}" install start --profile "${PROFILE}"
111
+ started_output="$("${WRAPPER}" install status --profile "${PROFILE}")"
112
+ printf '%s\n' "${started_output}"
113
+ grep -Fq "Status: running" <<<"${started_output}"
114
+ curl --fail --silent "http://127.0.0.1:${PORT}/readyz" >/dev/null
115
+
116
+ "${WRAPPER}" install restart --profile "${PROFILE}"
117
+ curl --fail --silent "http://127.0.0.1:${PORT}/readyz" >/dev/null
118
+
119
+ "${WRAPPER}" install remove --profile "${PROFILE}"
120
+ [[ ! -e "${HOME}/.headroom/deploy/${PROFILE}" ]]
@@ -0,0 +1,79 @@
1
+ # ─── Stage 1: build the xtream-head wheel in manylinux ─────────────────────
2
+ # See e2e/wrap/Dockerfile for the full rationale. tl;dr: building from
3
+ # source inside `node:22-bookworm` produced a `_core.so` referencing
4
+ # `__isoc23_strtoll` (glibc 2.38+) that the same image's runtime libc
5
+ # couldn't resolve. Building inside manylinux_2_28 (AlmaLinux 8, glibc
6
+ # 2.28 baseline) yields a wheel portable to any glibc 2.28+ runtime.
7
+ FROM quay.io/pypa/manylinux_2_28_x86_64 AS builder
8
+
9
+ # No OpenSSL system deps required (rustls-everywhere refactor). See
10
+ # e2e/wrap/Dockerfile for the full rationale.
11
+
12
+ ENV CARGO_HOME=/usr/local/cargo \
13
+ RUSTUP_HOME=/usr/local/rustup \
14
+ PATH=/usr/local/cargo/bin:/opt/python/cp311-cp311/bin:${PATH}
15
+ RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
16
+ | sh -s -- -y --no-modify-path --profile minimal -c rustfmt -c clippy --default-toolchain 1.95.0
17
+
18
+ WORKDIR /build
19
+
20
+ COPY pyproject.toml uv.lock README.md ./
21
+ COPY Cargo.toml Cargo.lock rust-toolchain.toml ./
22
+ COPY crates/ crates/
23
+ COPY headroom/ headroom/
24
+
25
+ ENV PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1
26
+ # Build for Python 3.11 to match Stage 2's `python:3.11-slim` runtime.
27
+ RUN /opt/python/cp311-cp311/bin/pip install 'maturin>=1.5,<2.0' && \
28
+ /opt/python/cp311-cp311/bin/maturin build --release --out /dist --interpreter python3.11
29
+
30
+ # ─── Stage 2: python runtime ───────────────────────────────────────────────
31
+ # `python:3.11-slim` (now trixie, glibc 2.41) — see e2e/wrap/Dockerfile
32
+ # for why we need glibc ≥ 2.38 (the wheel's `_core.so` references C23
33
+ # symbols that bookworm's 2.36 doesn't export). The init e2e harness
34
+ # only needs python (no node) — `headroom init -g <target>` is Python.
35
+ FROM python:3.11-slim
36
+
37
+ ENV DEBIAN_FRONTEND=noninteractive \
38
+ PATH="/opt/headroom-venv/bin:${PATH}" \
39
+ PIP_DISABLE_PIP_VERSION_CHECK=1 \
40
+ PIP_NO_CACHE_DIR=1 \
41
+ PYTHONUNBUFFERED=1 \
42
+ PYTHONDONTWRITEBYTECODE=1 \
43
+ # Single-wheel refactor side effect: `headroom` is now installed
44
+ # from a wheel into site-packages, so `__file__.parents[2]` no
45
+ # longer points at the repo root (it points at site-packages).
46
+ # `_marketplace_source()` falls back to `chopratejas/headroom`
47
+ # (the GitHub remote) instead of the local `/workspace` path the
48
+ # `seq_claude_local` e2e assertion expects. Pin the source via
49
+ # the existing override env var so the local `/workspace`
50
+ # marketplace.json (COPY'd below) is used.
51
+ HEADROOM_MARKETPLACE_SOURCE=/workspace
52
+
53
+ RUN apt-get update && \
54
+ apt-get install -y --no-install-recommends \
55
+ ca-certificates \
56
+ git && \
57
+ rm -rf /var/lib/apt/lists/*
58
+
59
+ WORKDIR /workspace
60
+
61
+ COPY --from=builder /dist/*.whl /tmp/wheels/
62
+
63
+ # Init e2e harness imports from e2e._lib + .claude-plugin assets.
64
+ # DO NOT copy `headroom/` or `pyproject.toml` from the workspace —
65
+ # the installed wheel must be authoritative. The harness packages
66
+ # (e2e/_lib/, .claude-plugin/, plugins/) don't shadow `headroom`.
67
+ COPY .claude-plugin ./.claude-plugin
68
+ COPY .github/plugin ./.github/plugin
69
+ COPY plugins/headroom-agent-hooks ./plugins/headroom-agent-hooks
70
+ COPY e2e/__init__.py ./e2e/__init__.py
71
+ COPY e2e/_lib ./e2e/_lib
72
+ COPY e2e/init ./e2e/init
73
+
74
+ RUN python -m venv /opt/headroom-venv && \
75
+ /opt/headroom-venv/bin/python -m pip install --upgrade pip && \
76
+ /opt/headroom-venv/bin/python -m pip install "$(ls /tmp/wheels/headroom_ai-*.whl)[proxy]" && \
77
+ /opt/headroom-venv/bin/python -c "from headroom._core import DiffCompressor; print('headroom._core OK')"
78
+
79
+ CMD ["python", "e2e/init/run.py"]
@@ -0,0 +1,115 @@
1
+ # ─── Stage 1: build the xtream-head wheel in manylinux ─────────────────────
2
+ # Building from source inside `node:22-bookworm` produced a `_core.so` that
3
+ # referenced `__isoc23_strtoll` (a glibc 2.38+ symbol). The runtime in the
4
+ # same image couldn't resolve it at import time because something in the
5
+ # build chain — gcc version, libc6-dev backport, or cc-rs compiling
6
+ # transitive C deps against newer headers — emitted C23-era symbols that
7
+ # the runtime libc.so.6 doesn't have. Building inside the manylinux_2_28
8
+ # container (AlmaLinux 8, glibc 2.28 baseline) guarantees the wheel works
9
+ # on any glibc 2.28+ runtime, including bookworm.
10
+ FROM quay.io/pypa/manylinux_2_28_x86_64 AS builder
11
+
12
+ # No OpenSSL system deps required. As of the rustls-everywhere refactor,
13
+ # all HTTP+TLS in our Rust crates goes through `rustls`. fastembed's
14
+ # `hf-hub-rustls-tls` + `ort-download-binaries-rustls-tls` features
15
+ # replace the default native-tls path; `cargo tree -p headroom-py -i
16
+ # openssl-sys` returns "not found", confirming this Dockerfile no
17
+ # longer needs `openssl-devel`, `pkgconfig`, or any perl modules
18
+ # (Time::Piece, IPC::Cmd) for the openssl-src vendored Configure
19
+ # script. The historical `yum install openssl-devel pkgconfig
20
+ # perl-IPC-Cmd` line is intentionally absent.
21
+
22
+ # Install rust toolchain into the manylinux container. Match the
23
+ # rust-toolchain.toml at repo root (1.95.0 + rustfmt + clippy) so cargo
24
+ # doesn't try to mutate the toolchain on first invocation.
25
+ ENV CARGO_HOME=/usr/local/cargo \
26
+ RUSTUP_HOME=/usr/local/rustup \
27
+ PATH=/usr/local/cargo/bin:/opt/python/cp311-cp311/bin:${PATH}
28
+ RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
29
+ | sh -s -- -y --no-modify-path --profile minimal -c rustfmt -c clippy --default-toolchain 1.95.0
30
+
31
+ WORKDIR /build
32
+
33
+ COPY pyproject.toml uv.lock README.md ./
34
+ COPY Cargo.toml Cargo.lock rust-toolchain.toml ./
35
+ COPY crates/ crates/
36
+ COPY headroom/ headroom/
37
+
38
+ # Build the wheel with maturin. PYO3_USE_ABI3_FORWARD_COMPATIBILITY allows
39
+ # building against Python 3.14+ until we bump pyo3 past 0.22.
40
+ ENV PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1
41
+ # Build for Python 3.11 — aider-chat==0.86.2 requires Python <3.12, and
42
+ # trixie's default python3.13 is too new for aider. The manylinux image
43
+ # has python interpreters for every version at /opt/python/cpXY-cpXY/.
44
+ # Stage 2 uses `python:3.11-slim` (now trixie-based, glibc 2.41).
45
+ RUN /opt/python/cp311-cp311/bin/pip install 'maturin>=1.5,<2.0' && \
46
+ /opt/python/cp311-cp311/bin/maturin build --release --out /dist --interpreter python3.11
47
+
48
+ # ─── Stage 2: python+node runtime ───────────────────────────────────────────
49
+ # Base on `python:3.11-slim` (now trixie, glibc 2.41) instead of
50
+ # `node:22-bookworm` (glibc 2.36): the wheel's `_core.so` references
51
+ # three glibc 2.38+ C23 wrappers (`__isoc23_strtol{,l,ul}`) that one of
52
+ # our transitive C/C++ deps emits during cc-rs compilation even when
53
+ # built inside manylinux_2_28 (probably libstdc++'s `<cstdlib>` resolving
54
+ # `std::strtoll` to the C23 variant when the toolchain has newer
55
+ # headers). Bookworm's libc.so.6 doesn't export these wrappers, so
56
+ # `import headroom._core` fails at runtime. Trixie's glibc 2.41 does.
57
+ #
58
+ # We need Python 3.11 here (aider-chat==0.86.2 requires Python <3.12).
59
+ # Trixie's default `python3` is 3.13 — too new for aider. python:3.11-slim
60
+ # gives us Python 3.11 + trixie glibc + apt access for installing Node.
61
+ FROM python:3.11-slim
62
+
63
+ ENV DEBIAN_FRONTEND=noninteractive \
64
+ AIDER_CHAT_VERSION=0.86.2 \
65
+ CODEX_VERSION=0.118.0 \
66
+ OPENCLAW_VERSION=2026.4.7 \
67
+ PATH="/opt/headroom-venv/bin:/opt/aider-venv/bin:${PATH}" \
68
+ PIP_DISABLE_PIP_VERSION_CHECK=1 \
69
+ PIP_NO_CACHE_DIR=1 \
70
+ PYTHONUNBUFFERED=1 \
71
+ PYTHONDONTWRITEBYTECODE=1
72
+
73
+ # Install Node.js 22 from NodeSource (matches what node:22-trixie gives,
74
+ # but layered onto python:3.11-slim so we get py3.11 + node22 + glibc 2.41
75
+ # in one image). Also install git for any package that clones at install.
76
+ RUN apt-get update && \
77
+ apt-get install -y --no-install-recommends \
78
+ ca-certificates \
79
+ curl \
80
+ git \
81
+ gnupg && \
82
+ curl -fsSL https://deb.nodesource.com/setup_22.x | bash - && \
83
+ apt-get install -y --no-install-recommends nodejs && \
84
+ rm -rf /var/lib/apt/lists/*
85
+
86
+ WORKDIR /workspace
87
+
88
+ # Bring in the prebuilt manylinux wheel from stage 1.
89
+ COPY --from=builder /dist/*.whl /tmp/wheels/
90
+
91
+ # `sdk/typescript` and `plugins/openclaw` are wired into the wrap-e2e
92
+ # harness (e2e/wrap/run.py invokes `npx openclaw`). DO NOT copy
93
+ # `headroom/` or `pyproject.toml` from the workspace — they would shadow
94
+ # the installed wheel's `headroom/` package via cwd and Python would
95
+ # import the source-only `headroom/` (which has no `_core.so`),
96
+ # triggering the same `ModuleNotFoundError` the wheel install fixes.
97
+ COPY sdk/typescript ./sdk/typescript
98
+ COPY plugins/openclaw ./plugins/openclaw
99
+
100
+ # Install the prebuilt manylinux wheel with [proxy] extras. Pip resolves
101
+ # extras from the wheel's metadata and pulls deps from public PyPI. The
102
+ # wheel's `_core.so` was compiled against glibc 2.28, so it loads cleanly
103
+ # against bookworm's glibc 2.36 at runtime.
104
+ RUN python -m venv /opt/headroom-venv && \
105
+ /opt/headroom-venv/bin/python -m pip install --upgrade pip && \
106
+ /opt/headroom-venv/bin/python -m pip install "$(ls /tmp/wheels/headroom_ai-*.whl)[proxy]" && \
107
+ /opt/headroom-venv/bin/python -c "from headroom._core import DiffCompressor; print('headroom._core OK')" && \
108
+ python -m venv /opt/aider-venv && \
109
+ /opt/aider-venv/bin/python -m pip install --upgrade pip && \
110
+ /opt/aider-venv/bin/python -m pip install "aider-chat==${AIDER_CHAT_VERSION}" && \
111
+ npm install -g --no-fund --no-audit "@openai/codex@${CODEX_VERSION}" "openclaw@${OPENCLAW_VERSION}"
112
+
113
+ COPY e2e/wrap ./e2e/wrap
114
+
115
+ CMD ["python", "e2e/wrap/run.py"]
@@ -0,0 +1,279 @@
1
+ {
2
+ "cells": [
3
+ {
4
+ "cell_type": "markdown",
5
+ "metadata": {},
6
+ "source": [
7
+ "# Context Compression\n",
8
+ "\n",
9
+ "## What is it\n",
10
+ "\n",
11
+ "*Context Compression is the act of statistically reducing tool output size while preserving the information the LLM needs to answer the user's question.*\n",
12
+ "\n",
13
+ "## Why it helps\n",
14
+ "\n",
15
+ "* Avoids [Context Distraction](https://www.dbreunig.com/2025/06/22/how-contexts-fail-and-how-to-fix-them.html): Verbose tool outputs dilute the signal. Compression removes filler words and redundant phrasing while keeping key facts, errors, and anomalies.\n",
16
+ "* **No extra LLM call required**: Unlike pruning (notebook 04) and summarization (notebook 05) which call GPT-4o-mini per tool result, compression runs locally using statistical and ML-based token analysis. Zero additional cost, lower latency.\n",
17
+ "\n",
18
+ "## Context Compression in Practice\n",
19
+ "\n",
20
+ "[Xtream Head](https://github.com/Xtream-ITSolutions/xithead) is an open-source context optimization library that provides multi-algorithm compression. It auto-detects content type (JSON, code, logs, text) and routes to the optimal compressor:\n",
21
+ "\n",
22
+ "- **SmartCrusher**: Statistically analyzes JSON arrays \u2014 keeps errors, anomalies, and query-relevant items\n",
23
+ "- **Kompress**: ModernBERT token classifier \u2014 removes redundant tokens from text while preserving meaning\n",
24
+ "- **CodeCompressor**: AST-aware compression for source code\n",
25
+ "\n",
26
+ "When items are highly diverse (like RAG retriever chunks), Headroom keeps all items and compresses the text *within* each one \u2014 no information is dropped.\n",
27
+ "\n",
28
+ "## Context Compression in LangGraph\n",
29
+ "\n",
30
+ "We'll replace the LLM-based pruning/summarization step with a local compression call. The agent structure is identical to notebooks 04 and 05 \u2014 only the tool processing node changes."
31
+ ]
32
+ },
33
+ {
34
+ "cell_type": "code",
35
+ "execution_count": null,
36
+ "metadata": {},
37
+ "outputs": [],
38
+ "source": [
39
+ "# Install headroom (one-time)\n",
40
+ "# !pip install \"xtream-head[all]\""
41
+ ]
42
+ },
43
+ {
44
+ "cell_type": "code",
45
+ "execution_count": null,
46
+ "metadata": {},
47
+ "outputs": [],
48
+ "source": [
49
+ "from langchain_community.document_loaders import WebBaseLoader\n",
50
+ "\n",
51
+ "urls = [\n",
52
+ " \"https://lilianweng.github.io/posts/2025-05-01-thinking/\",\n",
53
+ " \"https://lilianweng.github.io/posts/2024-11-28-reward-hacking/\",\n",
54
+ " \"https://lilianweng.github.io/posts/2024-07-07-hallucination/\",\n",
55
+ " \"https://lilianweng.github.io/posts/2024-04-12-diffusion-video/\",\n",
56
+ "]\n",
57
+ "\n",
58
+ "docs = [WebBaseLoader(url).load() for url in urls]"
59
+ ]
60
+ },
61
+ {
62
+ "cell_type": "code",
63
+ "execution_count": null,
64
+ "metadata": {},
65
+ "outputs": [],
66
+ "source": [
67
+ "from langchain_text_splitters import RecursiveCharacterTextSplitter\n",
68
+ "\n",
69
+ "docs_list = [item for sublist in docs for item in sublist]\n",
70
+ "\n",
71
+ "text_splitter = RecursiveCharacterTextSplitter.from_tiktoken_encoder(\n",
72
+ " chunk_size=3000, chunk_overlap=50\n",
73
+ ")\n",
74
+ "doc_splits = text_splitter.split_documents(docs_list)"
75
+ ]
76
+ },
77
+ {
78
+ "cell_type": "code",
79
+ "execution_count": null,
80
+ "metadata": {},
81
+ "outputs": [],
82
+ "source": [
83
+ "from langchain.embeddings import init_embeddings\n",
84
+ "from langchain_core.vectorstores import InMemoryVectorStore\n",
85
+ "\n",
86
+ "embeddings = init_embeddings(\"openai:text-embedding-3-small\")\n",
87
+ "vectorstore = InMemoryVectorStore.from_documents(documents=doc_splits, embedding=embeddings)\n",
88
+ "retriever = vectorstore.as_retriever()"
89
+ ]
90
+ },
91
+ {
92
+ "cell_type": "code",
93
+ "execution_count": null,
94
+ "metadata": {},
95
+ "outputs": [],
96
+ "source": [
97
+ "from langchain.tools.retriever import create_retriever_tool\n",
98
+ "from rich.console import Console\n",
99
+ "from rich.pretty import pprint\n",
100
+ "\n",
101
+ "console = Console()\n",
102
+ "\n",
103
+ "retriever_tool = create_retriever_tool(\n",
104
+ " retriever,\n",
105
+ " \"retrieve_blog_posts\",\n",
106
+ " \"Search and return information about Lilian Weng blog posts.\",\n",
107
+ ")\n",
108
+ "\n",
109
+ "result = retriever_tool.invoke({\"query\": \"types of reward hacking\"})\n",
110
+ "console.print(\"[bold green]Retriever Tool Results:[/bold green]\")\n",
111
+ "pprint(result)"
112
+ ]
113
+ },
114
+ {
115
+ "cell_type": "code",
116
+ "execution_count": null,
117
+ "metadata": {},
118
+ "outputs": [],
119
+ "source": [
120
+ "from langchain.chat_models import init_chat_model\n",
121
+ "\n",
122
+ "llm = init_chat_model(\"anthropic:claude-sonnet-4-20250514\", temperature=0)\n",
123
+ "\n",
124
+ "tools = [retriever_tool]\n",
125
+ "tools_by_name = {tool.name: tool for tool in tools}\n",
126
+ "\n",
127
+ "llm_with_tools = llm.bind_tools(tools)"
128
+ ]
129
+ },
130
+ {
131
+ "cell_type": "code",
132
+ "execution_count": null,
133
+ "metadata": {},
134
+ "outputs": [],
135
+ "source": [
136
+ "from typing import Literal\n",
137
+ "\n",
138
+ "from IPython.display import Image, display\n",
139
+ "from langchain_core.messages import SystemMessage, ToolMessage\n",
140
+ "from langgraph.graph import END, START, MessagesState, StateGraph\n",
141
+ "\n",
142
+ "from headroom import compress\n",
143
+ "\n",
144
+ "\n",
145
+ "class State(MessagesState):\n",
146
+ " \"\"\"Extended state that includes a summary field for context compression.\"\"\"\n",
147
+ "\n",
148
+ " summary: str\n",
149
+ "\n",
150
+ "\n",
151
+ "rag_prompt = \"\"\"You are a helpful assistant tasked with retrieving information from a series of technical blog posts by Lilian Weng.\n",
152
+ "Clarify the scope of research with the user before using your retrieval tool to gather context. Reflect on any context you fetch, and\n",
153
+ "proceed until you have sufficient context to answer the user's research request.\"\"\"\n",
154
+ "\n",
155
+ "\n",
156
+ "def llm_call(state: State) -> dict:\n",
157
+ " \"\"\"Execute LLM call with system prompt and message history.\"\"\"\n",
158
+ " messages = [SystemMessage(content=rag_prompt)] + state[\"messages\"]\n",
159
+ " response = llm_with_tools.invoke(messages)\n",
160
+ " return {\"messages\": [response]}\n",
161
+ "\n",
162
+ "\n",
163
+ "def should_continue(state: State) -> Literal[\"tool_node_with_compression\", \"__end__\"]:\n",
164
+ " \"\"\"Decide if we should continue the loop or stop.\"\"\"\n",
165
+ " messages = state[\"messages\"]\n",
166
+ " last_message = messages[-1]\n",
167
+ " if last_message.tool_calls:\n",
168
+ " return \"tool_node_with_compression\"\n",
169
+ " return END\n",
170
+ "\n",
171
+ "\n",
172
+ "def tool_node_with_compression(state: State):\n",
173
+ " \"\"\"Execute tool calls and compress results with Xtream Head.\n",
174
+ "\n",
175
+ " Instead of calling GPT-4o-mini to prune or summarize (notebooks 04, 05),\n",
176
+ " we use Headroom's compress() \u2014 no LLM call, no extra cost.\n",
177
+ "\n",
178
+ " Headroom auto-detects content type and applies the right compressor:\n",
179
+ " - JSON arrays \u2192 SmartCrusher (statistical, keeps anomalies + query-relevant items)\n",
180
+ " - Plain text \u2192 Kompress (ModernBERT token compression)\n",
181
+ " - Code \u2192 CodeCompressor (AST-aware)\n",
182
+ "\n",
183
+ " For diverse retriever results (each chunk is unique), Headroom keeps ALL\n",
184
+ " items and compresses the text within each one.\n",
185
+ " \"\"\"\n",
186
+ " result = []\n",
187
+ " for tool_call in state[\"messages\"][-1].tool_calls:\n",
188
+ " tool = tools_by_name[tool_call[\"name\"]]\n",
189
+ " observation = tool.invoke(tool_call[\"args\"])\n",
190
+ "\n",
191
+ " # Build a minimal message list so Headroom can extract the user query\n",
192
+ " # for relevance-aware compression (keeps chunks matching the question).\n",
193
+ " user_query = state[\"messages\"][0].content if state[\"messages\"] else \"\"\n",
194
+ " temp_messages = [\n",
195
+ " {\"role\": \"user\", \"content\": user_query},\n",
196
+ " {\"role\": \"tool\", \"content\": observation, \"tool_call_id\": tool_call[\"id\"]},\n",
197
+ " ]\n",
198
+ "\n",
199
+ " compressed = compress(temp_messages, model=\"claude-sonnet-4-20250514\")\n",
200
+ " compressed_content = compressed.messages[-1][\"content\"]\n",
201
+ "\n",
202
+ " result.append(ToolMessage(content=compressed_content, tool_call_id=tool_call[\"id\"]))\n",
203
+ "\n",
204
+ " return {\"messages\": result}\n",
205
+ "\n",
206
+ "\n",
207
+ "# Build workflow\n",
208
+ "agent_builder = StateGraph(State)\n",
209
+ "\n",
210
+ "agent_builder.add_node(\"llm_call\", llm_call)\n",
211
+ "agent_builder.add_node(\"tool_node_with_compression\", tool_node_with_compression)\n",
212
+ "\n",
213
+ "agent_builder.add_edge(START, \"llm_call\")\n",
214
+ "agent_builder.add_conditional_edges(\n",
215
+ " \"llm_call\",\n",
216
+ " should_continue,\n",
217
+ " {\n",
218
+ " \"tool_node_with_compression\": \"tool_node_with_compression\",\n",
219
+ " END: END,\n",
220
+ " },\n",
221
+ ")\n",
222
+ "agent_builder.add_edge(\"tool_node_with_compression\", \"llm_call\")\n",
223
+ "\n",
224
+ "agent = agent_builder.compile()\n",
225
+ "\n",
226
+ "display(Image(agent.get_graph(xray=True).draw_mermaid_png()))"
227
+ ]
228
+ },
229
+ {
230
+ "cell_type": "code",
231
+ "execution_count": null,
232
+ "metadata": {},
233
+ "outputs": [],
234
+ "source": [
235
+ "from utils import format_messages\n",
236
+ "\n",
237
+ "query = \"What are the types of reward hacking discussed in the blogs?\"\n",
238
+ "result = agent.invoke({\"messages\": [{\"role\": \"user\", \"content\": query}]})\n",
239
+ "format_messages(result[\"messages\"])"
240
+ ]
241
+ },
242
+ {
243
+ "cell_type": "markdown",
244
+ "metadata": {},
245
+ "source": [
246
+ "## How it compares\n",
247
+ "\n",
248
+ "| Technique | Notebook | Token Reduction | Extra LLM Call | Extra Cost |\n",
249
+ "|-----------|----------|----------------|----------------|------------|\n",
250
+ "| RAG Baseline | 01 | \u2014 | No | $0 |\n",
251
+ "| Context Pruning | 04 | ~56% | Yes (GPT-4o-mini) | ~$0.003/call |\n",
252
+ "| Context Summarization | 05 | ~68% | Yes (GPT-4o-mini) | ~$0.003/call |\n",
253
+ "| **Context Compression** | **07** | **~30-40%** | **No** | **$0** |\n",
254
+ "\n",
255
+ "Key differences:\n",
256
+ "\n",
257
+ "- **No LLM call**: Pruning and summarization call GPT-4o-mini per tool result. Compression runs locally.\n",
258
+ "- **No information loss**: For diverse retriever results (each chunk is unique), Headroom keeps ALL items and compresses text within each one. Pruning removes entire chunks; summarization rewrites them.\n",
259
+ "- **Reversible**: Headroom's CCR (Compress-Cache-Retrieve) stores originals. The LLM can call `headroom_retrieve` to get full uncompressed content if it needs more detail.\n",
260
+ "- **Content-aware**: Different content types get different treatment. JSON arrays \u2192 statistical analysis. Plain text \u2192 ML token compression. Code \u2192 AST-aware compression.\n",
261
+ "\n",
262
+ "The trade-off: pruning and summarization can achieve higher compression (56-68%) because they use an LLM to judge relevance. Compression achieves 30-40% without any LLM call \u2014 making it faster and free."
263
+ ]
264
+ }
265
+ ],
266
+ "metadata": {
267
+ "kernelspec": {
268
+ "display_name": "Python 3 (ipykernel)",
269
+ "language": "python",
270
+ "name": "python3"
271
+ },
272
+ "language_info": {
273
+ "name": "python",
274
+ "version": "3.11.0"
275
+ }
276
+ },
277
+ "nbformat": 4,
278
+ "nbformat_minor": 4
279
+ }
@@ -0,0 +1,65 @@
1
+ <?xml version="1.0" encoding="UTF-8"?>
2
+ <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
3
+ <plist version="1.0">
4
+ <dict>
5
+ <!-- Service Label: Must match the filename -->
6
+ <key>Label</key>
7
+ <string>com.headroom.proxy</string>
8
+
9
+ <!-- Program to run: REPLACE __HEADROOM_PATH__ with actual headroom location -->
10
+ <key>ProgramArguments</key>
11
+ <array>
12
+ <string>__HEADROOM_PATH__</string>
13
+ <string>proxy</string>
14
+ <string>--host</string>
15
+ <string>127.0.0.1</string>
16
+ <string>--port</string>
17
+ <string>__PORT__</string>
18
+ </array>
19
+
20
+ <!-- Environment Variables -->
21
+ <key>EnvironmentVariables</key>
22
+ <dict>
23
+ <!-- Default port: 8787 (can be overridden by install script) -->
24
+ <key>HEADROOM_PROXY_PORT</key>
25
+ <string>__PORT__</string>
26
+
27
+ <!-- ANTHROPIC_API_KEY should be set in your shell environment -->
28
+ <!-- or uncomment and set here: -->
29
+ <!-- <key>ANTHROPIC_API_KEY</key> -->
30
+ <!-- <string>your-api-key-here</string> -->
31
+
32
+ <!-- Optional: Enable LLMLingua compression (requires llmlingua extra) -->
33
+ <!-- <key>HEADROOM_COMPRESSION_PROVIDER</key> -->
34
+ <!-- <string>llmlingua</string> -->
35
+ </dict>
36
+
37
+ <!-- Working Directory: REPLACE __HOME__ with user's home directory -->
38
+ <key>WorkingDirectory</key>
39
+ <string>__HOME__</string>
40
+
41
+ <!-- Standard Output Log: REPLACE __HOME__ with user's home directory -->
42
+ <key>StandardOutPath</key>
43
+ <string>__HOME__/Library/Logs/headroom/proxy.log</string>
44
+
45
+ <!-- Standard Error Log: REPLACE __HOME__ with user's home directory -->
46
+ <key>StandardErrorPath</key>
47
+ <string>__HOME__/Library/Logs/headroom/proxy-error.log</string>
48
+
49
+ <!-- Keep the service running (restart on crash) -->
50
+ <key>KeepAlive</key>
51
+ <true/>
52
+
53
+ <!-- Start the service when the user logs in -->
54
+ <key>RunAtLoad</key>
55
+ <true/>
56
+
57
+ <!-- Process Type: Adaptive (allows for background processing) -->
58
+ <key>ProcessType</key>
59
+ <string>Adaptive</string>
60
+
61
+ <!-- Throttle Interval: Wait 10 seconds between restart attempts -->
62
+ <key>ThrottleInterval</key>
63
+ <integer>10</integer>
64
+ </dict>
65
+ </plist>