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,698 @@
1
+ //! PR-E3: Anthropic `cache_control` auto-placement.
2
+ //!
3
+ //! Anthropic's prompt cache is opt-in per content block: nothing is
4
+ //! cached unless the request body explicitly carries
5
+ //! `cache_control: {"type": "ephemeral"}` on at least one block.
6
+ //! Sophisticated clients (e.g. Claude Code) place those markers
7
+ //! themselves; less-sophisticated callers (hand-rolled SDK code,
8
+ //! smaller agents like Aider/Continue, plain `curl`) typically don't
9
+ //! even know `cache_control` exists. For *those* clients we can
10
+ //! get them cache hits at zero learning-cost by inserting one
11
+ //! marker on the highest-reuse content block in the request.
12
+ //!
13
+ //! # Safety contract
14
+ //!
15
+ //! This module is the only Phase E surface that **mutates request
16
+ //! bytes** — that's the whole point. To stay inside the Phase A
17
+ //! "passthrough is sacred" invariant we layer three independent
18
+ //! gates:
19
+ //!
20
+ //! 1. **Auth-mode gate (caller's responsibility).** Mutating bytes
21
+ //! on an OAuth-bearing or subscription-bound request risks
22
+ //! looking like cache-evasion to the upstream and can trigger
23
+ //! subscription revocation. The caller MUST classify the
24
+ //! inbound auth mode via [`headroom_core::auth_mode::classify`]
25
+ //! and only call this function when the mode is
26
+ //! [`headroom_core::auth_mode::AuthMode::Payg`]. The caller
27
+ //! emits a structured `event = "e3_skipped", reason =
28
+ //! "auth_mode"` log line on the non-PAYG path.
29
+ //! 2. **Customer-placement-wins gate.** If *any* `cache_control`
30
+ //! marker is found anywhere in the body the caller hands us we
31
+ //! return [`AutoPlaceOutcome::Skipped { reason:
32
+ //! SkipReason::MarkerPresent }`] and never mutate. This walks
33
+ //! `system` (string OR array of blocks), `messages[].content`
34
+ //! (string OR array of blocks), and `tools[]` (top-level on
35
+ //! each tool). The customer's cache layout is theirs to own.
36
+ //! 3. **Idempotency.** Re-running on a body that already carries
37
+ //! the markers we'd add is a no-op via gate (2) — the
38
+ //! previously-placed marker becomes the customer-placement-wins
39
+ //! signal on the next pass.
40
+ //!
41
+ //! Every skip / apply emits a structured `tracing::info!` with
42
+ //! `event = "e3_skipped"` or `event = "e3_applied"` so production
43
+ //! telemetry can confirm the gates fire as designed.
44
+ //!
45
+ //! # Placement strategy (first ship: ONE marker only)
46
+ //!
47
+ //! Anthropic's `cache_control` semantics: a marker on a block caches
48
+ //! *that block + everything before it* in the canonical request
49
+ //! order (`system → tools → messages`). Each cached prefix lasts
50
+ //! 5 minutes. A request may carry up to **4** markers (Anthropic's
51
+ //! hard limit).
52
+ //!
53
+ //! Future placement priority (not yet enabled — requires production
54
+ //! telemetry to validate before we mutate further bytes per request):
55
+ //!
56
+ //! 1. **Last tool definition (top-level).** Caches the entire
57
+ //! `tools` array — highest reuse across turns.
58
+ //! 2. **Last block of the system prompt.** Caches `system + tools`.
59
+ //! Only fires when `system` is already an array of blocks; we
60
+ //! do **not** convert a plain-string `system` to an array on
61
+ //! first ship — that's a bigger surgery and we'd want telemetry
62
+ //! first.
63
+ //! 3. **Last user message's last block** when the conversation
64
+ //! already has ≥ 2 turns of history (caches everything except
65
+ //! the live tool_result tail).
66
+ //! 4. Fourth slot reserved — left unplaced for safety.
67
+ //!
68
+ //! **First ship default:** place exactly one marker on the last tool
69
+ //! definition's top-level. Highest-value, lowest-risk, easiest to
70
+ //! revert. Slots 2/3/4 require production telemetry to enable.
71
+ //!
72
+ //! # Marker shape
73
+ //!
74
+ //! ```json
75
+ //! {"cache_control": {"type": "ephemeral"}}
76
+ //! ```
77
+ //!
78
+ //! No TTL field — the 5-minute default is the right one for the
79
+ //! first-ship "last tool" placement (tools rarely turn over within
80
+ //! 5 minutes; longer TTLs require careful auth-mode and per-tenant
81
+ //! sizing we don't yet have).
82
+
83
+ use serde_json::{json, Value};
84
+
85
+ /// Result of an auto-placement attempt.
86
+ ///
87
+ /// Returned by [`auto_place_anthropic_cache_control`]. The caller
88
+ /// uses the variant + count to emit structured telemetry. Variants
89
+ /// stay narrow — one happy path with a count, one skip with a
90
+ /// machine-readable reason.
91
+ #[derive(Debug, Clone, PartialEq, Eq)]
92
+ pub enum AutoPlaceOutcome {
93
+ /// At least one `cache_control` marker was inserted. `placed_count`
94
+ /// is the number of markers added in this call. With the
95
+ /// first-ship policy this is always `1` when the body has tools
96
+ /// and `0` when it doesn't (the latter still returns `Applied`
97
+ /// with `placed_count = 0` so the caller can log the
98
+ /// "we-tried-but-no-target" branch).
99
+ Applied {
100
+ /// Number of markers added on this call.
101
+ placed_count: usize,
102
+ /// JSON-pointer-style locations the markers were placed at.
103
+ /// Stable identifiers used by dashboards to spot which slots
104
+ /// fire most. Example: `"tools[3]"`.
105
+ locations: Vec<String>,
106
+ },
107
+ /// We did not mutate. `reason` tells dashboards which gate fired.
108
+ Skipped {
109
+ /// Why we skipped — see [`SkipReason`] for the closed set.
110
+ reason: SkipReason,
111
+ },
112
+ }
113
+
114
+ /// Why E3 declined to place a marker.
115
+ ///
116
+ /// Closed enum so the structured `event = "e3_skipped"` log carries
117
+ /// a stable `reason` field. Dashboards filter on these strings.
118
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
119
+ pub enum SkipReason {
120
+ /// Caller's auth-mode gate fired — request was not classified as
121
+ /// PAYG, so the safety contract bans mutation. The caller is the
122
+ /// one who detects this; surfaced here so the function's outcome
123
+ /// shape stays uniform across both gates.
124
+ AuthMode,
125
+ /// At least one `cache_control` marker was already present in the
126
+ /// body (`system`, any message block, any tool top-level).
127
+ /// Customer placement wins.
128
+ MarkerPresent,
129
+ }
130
+
131
+ impl SkipReason {
132
+ /// Stable string for structured-log `reason` field. Dashboards
133
+ /// filter on these — do not change without a deprecation note.
134
+ pub fn as_str(self) -> &'static str {
135
+ match self {
136
+ SkipReason::AuthMode => "auth_mode",
137
+ SkipReason::MarkerPresent => "marker_present",
138
+ }
139
+ }
140
+ }
141
+
142
+ /// Walk `body` and return `true` if any `cache_control` field appears
143
+ /// anywhere. Public so the caller can early-skip without going through
144
+ /// the full mutating path (e.g. when it wants to log a different
145
+ /// `reason` field on its own gate).
146
+ ///
147
+ /// The walker inspects the three places Anthropic's request schema
148
+ /// allows `cache_control`:
149
+ ///
150
+ /// - `body.system` — when it's an array of content blocks (string
151
+ /// form cannot carry a marker).
152
+ /// - `body.messages[].content` — when it's an array of blocks.
153
+ /// - `body.tools[]` — top-level on each tool definition.
154
+ ///
155
+ /// We do **not** descend into arbitrary nested objects. The only
156
+ /// shape Anthropic recognises `cache_control` on is the documented
157
+ /// surface above; descending into tool `input_schema` etc. would
158
+ /// false-positive on customer JSON Schemas that happen to mention
159
+ /// the field name as a property key.
160
+ pub fn any_anthropic_cache_control(body: &Value) -> bool {
161
+ // ── system: string OR array of blocks ─────────────────────────
162
+ // Only the array form can carry markers — string form is
163
+ // explicitly skipped (cannot carry a `cache_control` field).
164
+ if let Some(Value::Array(blocks)) = body.get("system") {
165
+ for block in blocks {
166
+ if block_has_cache_control(block) {
167
+ return true;
168
+ }
169
+ }
170
+ }
171
+
172
+ // ── messages[].content: string OR array of blocks ─────────────
173
+ if let Some(Value::Array(messages)) = body.get("messages") {
174
+ for msg in messages {
175
+ if let Some(Value::Array(blocks)) = msg.get("content") {
176
+ for block in blocks {
177
+ if block_has_cache_control(block) {
178
+ return true;
179
+ }
180
+ }
181
+ }
182
+ // string form: cannot carry a marker — skip.
183
+ }
184
+ }
185
+
186
+ // ── tools[]: top-level field on each tool ─────────────────────
187
+ if let Some(Value::Array(tools)) = body.get("tools") {
188
+ for tool in tools {
189
+ if block_has_cache_control(tool) {
190
+ return true;
191
+ }
192
+ }
193
+ }
194
+
195
+ false
196
+ }
197
+
198
+ /// Auto-place up to one Anthropic `cache_control` marker on the
199
+ /// last tool definition.
200
+ ///
201
+ /// **Caller contract:** caller MUST gate on auth_mode == PAYG before
202
+ /// invoking. This function does NOT classify auth mode itself; the
203
+ /// split lets unit tests exercise marker detection without
204
+ /// constructing a real `HeaderMap`.
205
+ ///
206
+ /// **Behaviour:**
207
+ ///
208
+ /// - If any `cache_control` marker is already present anywhere in
209
+ /// the body (`system` blocks, message blocks, or top-level on any
210
+ /// tool), returns [`AutoPlaceOutcome::Skipped { reason:
211
+ /// SkipReason::MarkerPresent }`] and does not mutate.
212
+ /// - If `body.tools[]` is missing, empty, or not an array, returns
213
+ /// [`AutoPlaceOutcome::Applied { placed_count: 0, locations: vec![] }`]
214
+ /// and does not mutate. (Distinguishes "we ran and found nothing
215
+ /// to do" from "we declined to run".)
216
+ /// - Otherwise, inserts a `cache_control: {"type": "ephemeral"}` field
217
+ /// on the last tool definition (top-level) and returns
218
+ /// [`AutoPlaceOutcome::Applied { placed_count: 1, locations: ["tools[N-1]"] }`].
219
+ ///
220
+ /// **Idempotency:** running this twice on the same body is a no-op.
221
+ /// The first call inserts the marker; the second call sees it via
222
+ /// the customer-placement-wins gate and returns `Skipped`.
223
+ ///
224
+ /// **First-ship scope:** only the "last tool" slot is enabled. The
225
+ /// system-prompt and message-history slots are documented in the
226
+ /// module-level docs but require production telemetry to enable.
227
+ pub fn auto_place_anthropic_cache_control(body: &mut Value) -> AutoPlaceOutcome {
228
+ // Gate 2: any pre-existing marker → customer wins, full skip.
229
+ if any_anthropic_cache_control(body) {
230
+ return AutoPlaceOutcome::Skipped {
231
+ reason: SkipReason::MarkerPresent,
232
+ };
233
+ }
234
+
235
+ // First-ship default: place ONE marker on the last tool.
236
+ let tools = match body.get_mut("tools") {
237
+ Some(Value::Array(t)) if !t.is_empty() => t,
238
+ _ => {
239
+ // No tools array, or empty, or not an array. We "ran"
240
+ // but had no target — return Applied{0} so the caller
241
+ // can log "no_targets_present" for telemetry.
242
+ return AutoPlaceOutcome::Applied {
243
+ placed_count: 0,
244
+ locations: Vec::new(),
245
+ };
246
+ }
247
+ };
248
+ let last_idx = tools.len() - 1;
249
+ let last_tool = &mut tools[last_idx];
250
+ if !insert_cache_control_on_object(last_tool) {
251
+ // The last "tool" is not an object (Anthropic's schema
252
+ // requires it to be — but we never panic on a malformed
253
+ // body). Skip the slot rather than crashing.
254
+ return AutoPlaceOutcome::Applied {
255
+ placed_count: 0,
256
+ locations: Vec::new(),
257
+ };
258
+ }
259
+ AutoPlaceOutcome::Applied {
260
+ placed_count: 1,
261
+ locations: vec![format!("tools[{last_idx}]")],
262
+ }
263
+ }
264
+
265
+ /// Does this content block carry a `cache_control` field at its top
266
+ /// level? Used by both the read-only walker
267
+ /// ([`any_anthropic_cache_control`]) and (transitively) the
268
+ /// idempotency gate.
269
+ fn block_has_cache_control(block: &Value) -> bool {
270
+ block.get("cache_control").is_some()
271
+ }
272
+
273
+ /// Insert `"cache_control": {"type": "ephemeral"}` on `value` if it
274
+ /// is a JSON object. Returns `true` on insert, `false` if `value`
275
+ /// was not an object (so the caller can decline to claim a slot).
276
+ fn insert_cache_control_on_object(value: &mut Value) -> bool {
277
+ match value.as_object_mut() {
278
+ Some(map) => {
279
+ map.insert("cache_control".to_string(), json!({"type": "ephemeral"}));
280
+ true
281
+ }
282
+ None => false,
283
+ }
284
+ }
285
+
286
+ #[cfg(test)]
287
+ mod tests {
288
+ use super::*;
289
+ use serde_json::json;
290
+
291
+ /// Fresh body with one tool, one short user message, plain-string
292
+ /// system. Used as the seed for "happy-path placement" tests.
293
+ fn body_one_tool_no_markers() -> Value {
294
+ json!({
295
+ "model": "claude-3-5-sonnet-20241022",
296
+ "system": "You are helpful.",
297
+ "tools": [
298
+ {
299
+ "name": "search",
300
+ "description": "search the web",
301
+ "input_schema": {"type": "object", "properties": {}}
302
+ }
303
+ ],
304
+ "messages": [
305
+ {"role": "user", "content": "hi"}
306
+ ],
307
+ })
308
+ }
309
+
310
+ #[test]
311
+ fn places_cache_control_on_last_tool_when_payg_and_no_markers() {
312
+ let mut body = body_one_tool_no_markers();
313
+ let outcome = auto_place_anthropic_cache_control(&mut body);
314
+ match outcome {
315
+ AutoPlaceOutcome::Applied {
316
+ placed_count,
317
+ locations,
318
+ } => {
319
+ assert_eq!(placed_count, 1);
320
+ assert_eq!(locations, vec!["tools[0]"]);
321
+ }
322
+ other => panic!("expected Applied{{1}}, got {other:?}"),
323
+ }
324
+ // Marker visible at the right path.
325
+ let cc = body
326
+ .pointer("/tools/0/cache_control")
327
+ .expect("marker inserted on tools[0]");
328
+ assert_eq!(cc, &json!({"type": "ephemeral"}));
329
+ }
330
+
331
+ #[test]
332
+ fn places_on_last_tool_when_multiple_tools() {
333
+ // With multiple tools, the marker must go on the last one.
334
+ let mut body = json!({
335
+ "tools": [
336
+ {"name": "a", "description": "a"},
337
+ {"name": "b", "description": "b"},
338
+ {"name": "c", "description": "c"}
339
+ ],
340
+ "messages": [{"role": "user", "content": "hi"}],
341
+ });
342
+ let outcome = auto_place_anthropic_cache_control(&mut body);
343
+ match outcome {
344
+ AutoPlaceOutcome::Applied {
345
+ placed_count,
346
+ locations,
347
+ } => {
348
+ assert_eq!(placed_count, 1);
349
+ assert_eq!(locations, vec!["tools[2]"]);
350
+ }
351
+ other => panic!("expected Applied{{1}}, got {other:?}"),
352
+ }
353
+ assert!(body.pointer("/tools/0/cache_control").is_none());
354
+ assert!(body.pointer("/tools/1/cache_control").is_none());
355
+ assert!(body.pointer("/tools/2/cache_control").is_some());
356
+ }
357
+
358
+ #[test]
359
+ fn skips_when_any_tool_already_has_marker() {
360
+ // Customer placed a marker on the FIRST tool (not the slot
361
+ // we'd pick). Customer-placement-wins still skips us.
362
+ let mut body = json!({
363
+ "tools": [
364
+ {
365
+ "name": "search",
366
+ "description": "search",
367
+ "cache_control": {"type": "ephemeral"}
368
+ },
369
+ {"name": "fetch", "description": "fetch"}
370
+ ],
371
+ "messages": [{"role": "user", "content": "hi"}],
372
+ });
373
+ let before = body.clone();
374
+ let outcome = auto_place_anthropic_cache_control(&mut body);
375
+ assert_eq!(
376
+ outcome,
377
+ AutoPlaceOutcome::Skipped {
378
+ reason: SkipReason::MarkerPresent
379
+ }
380
+ );
381
+ assert_eq!(body, before, "skip path must not mutate");
382
+ }
383
+
384
+ #[test]
385
+ fn skips_when_system_block_already_has_marker() {
386
+ // Customer used the array-form `system` and placed their own
387
+ // marker. Customer-placement-wins.
388
+ let mut body = json!({
389
+ "system": [
390
+ {"type": "text", "text": "you are helpful"},
391
+ {
392
+ "type": "text",
393
+ "text": "cite sources",
394
+ "cache_control": {"type": "ephemeral"}
395
+ }
396
+ ],
397
+ "tools": [{"name": "search", "description": "search"}],
398
+ "messages": [{"role": "user", "content": "hi"}],
399
+ });
400
+ let before = body.clone();
401
+ let outcome = auto_place_anthropic_cache_control(&mut body);
402
+ assert_eq!(
403
+ outcome,
404
+ AutoPlaceOutcome::Skipped {
405
+ reason: SkipReason::MarkerPresent
406
+ }
407
+ );
408
+ assert_eq!(body, before, "skip path must not mutate");
409
+ }
410
+
411
+ #[test]
412
+ fn skips_when_message_block_already_has_marker() {
413
+ // Customer placed a marker mid-conversation. Skip everything.
414
+ let mut body = json!({
415
+ "tools": [{"name": "search", "description": "search"}],
416
+ "messages": [
417
+ {
418
+ "role": "user",
419
+ "content": [
420
+ {
421
+ "type": "text",
422
+ "text": "remember this",
423
+ "cache_control": {"type": "ephemeral"}
424
+ }
425
+ ]
426
+ },
427
+ {"role": "assistant", "content": "ok"},
428
+ {"role": "user", "content": "now what?"}
429
+ ],
430
+ });
431
+ let before = body.clone();
432
+ let outcome = auto_place_anthropic_cache_control(&mut body);
433
+ assert_eq!(
434
+ outcome,
435
+ AutoPlaceOutcome::Skipped {
436
+ reason: SkipReason::MarkerPresent
437
+ }
438
+ );
439
+ assert_eq!(body, before, "skip path must not mutate");
440
+ }
441
+
442
+ #[test]
443
+ fn idempotent_when_we_already_placed_marker_last_run() {
444
+ // Run once: marker placed. Run again: customer-placement-wins
445
+ // gate fires (the marker we placed last time IS now a
446
+ // customer-side marker as far as gate 2 is concerned).
447
+ let mut body = body_one_tool_no_markers();
448
+ let first = auto_place_anthropic_cache_control(&mut body);
449
+ assert!(matches!(
450
+ first,
451
+ AutoPlaceOutcome::Applied {
452
+ placed_count: 1,
453
+ ..
454
+ }
455
+ ));
456
+ let after_first = body.clone();
457
+ let second = auto_place_anthropic_cache_control(&mut body);
458
+ assert_eq!(
459
+ second,
460
+ AutoPlaceOutcome::Skipped {
461
+ reason: SkipReason::MarkerPresent
462
+ }
463
+ );
464
+ assert_eq!(body, after_first, "second run must not mutate");
465
+ }
466
+
467
+ #[test]
468
+ fn does_nothing_when_no_tools_present() {
469
+ // Body with no tools field. Returns Applied{0}, no mutation.
470
+ let mut body = json!({
471
+ "model": "claude-3-5-sonnet-20241022",
472
+ "system": "You are helpful.",
473
+ "messages": [{"role": "user", "content": "hi"}],
474
+ });
475
+ let before = body.clone();
476
+ let outcome = auto_place_anthropic_cache_control(&mut body);
477
+ assert_eq!(
478
+ outcome,
479
+ AutoPlaceOutcome::Applied {
480
+ placed_count: 0,
481
+ locations: Vec::new(),
482
+ }
483
+ );
484
+ assert_eq!(body, before, "Applied{{0}} path must not mutate");
485
+ }
486
+
487
+ #[test]
488
+ fn does_nothing_when_tools_array_is_empty() {
489
+ let mut body = json!({
490
+ "tools": [],
491
+ "messages": [{"role": "user", "content": "hi"}],
492
+ });
493
+ let before = body.clone();
494
+ let outcome = auto_place_anthropic_cache_control(&mut body);
495
+ assert_eq!(
496
+ outcome,
497
+ AutoPlaceOutcome::Applied {
498
+ placed_count: 0,
499
+ locations: Vec::new(),
500
+ }
501
+ );
502
+ assert_eq!(body, before, "empty-tools path must not mutate");
503
+ }
504
+
505
+ #[test]
506
+ fn system_string_form_does_not_get_converted_to_array() {
507
+ // Conservative first-ship policy: a plain-string `system`
508
+ // stays a plain string. We only place on tools.
509
+ let mut body = json!({
510
+ "system": "You are helpful. Cite sources.",
511
+ "tools": [{"name": "search", "description": "search"}],
512
+ "messages": [{"role": "user", "content": "hi"}],
513
+ });
514
+ let outcome = auto_place_anthropic_cache_control(&mut body);
515
+ assert!(matches!(
516
+ outcome,
517
+ AutoPlaceOutcome::Applied {
518
+ placed_count: 1,
519
+ ..
520
+ }
521
+ ));
522
+ // System is still a plain string.
523
+ assert_eq!(
524
+ body.get("system"),
525
+ Some(&json!("You are helpful. Cite sources.")),
526
+ "string-form `system` must stay untouched on first ship",
527
+ );
528
+ // Marker landed on tools[0] instead.
529
+ assert_eq!(
530
+ body.pointer("/tools/0/cache_control"),
531
+ Some(&json!({"type": "ephemeral"})),
532
+ );
533
+ }
534
+
535
+ #[test]
536
+ fn applies_only_one_marker_in_first_ship_default() {
537
+ // Multi-turn conversation + multiple tools + array-form system.
538
+ // First-ship default places exactly ONE marker (last tool).
539
+ let mut body = json!({
540
+ "system": [
541
+ {"type": "text", "text": "rule 1"},
542
+ {"type": "text", "text": "rule 2"}
543
+ ],
544
+ "tools": [
545
+ {"name": "a", "description": "a"},
546
+ {"name": "b", "description": "b"}
547
+ ],
548
+ "messages": [
549
+ {"role": "user", "content": "first"},
550
+ {"role": "assistant", "content": "second"},
551
+ {"role": "user", "content": "third"},
552
+ {"role": "assistant", "content": "fourth"},
553
+ {"role": "user", "content": "fifth"}
554
+ ],
555
+ });
556
+ let outcome = auto_place_anthropic_cache_control(&mut body);
557
+ assert_eq!(
558
+ outcome,
559
+ AutoPlaceOutcome::Applied {
560
+ placed_count: 1,
561
+ locations: vec!["tools[1]".to_string()],
562
+ }
563
+ );
564
+ // Walk every other slot to confirm it stayed clean.
565
+ let system_blocks = body.pointer("/system").unwrap().as_array().unwrap();
566
+ for block in system_blocks {
567
+ assert!(
568
+ !block_has_cache_control(block),
569
+ "first-ship default must not place on system blocks: {block:?}"
570
+ );
571
+ }
572
+ for (i, msg) in body
573
+ .pointer("/messages")
574
+ .unwrap()
575
+ .as_array()
576
+ .unwrap()
577
+ .iter()
578
+ .enumerate()
579
+ {
580
+ // Messages with string-form content can't carry markers
581
+ // anyway, but assert no marker placed regardless.
582
+ if let Some(Value::Array(blocks)) = msg.get("content") {
583
+ for block in blocks {
584
+ assert!(
585
+ !block_has_cache_control(block),
586
+ "message[{i}] block carries unexpected marker: {block:?}"
587
+ );
588
+ }
589
+ }
590
+ }
591
+ // Only tools[1] carries a marker.
592
+ assert!(body.pointer("/tools/0/cache_control").is_none());
593
+ assert_eq!(
594
+ body.pointer("/tools/1/cache_control"),
595
+ Some(&json!({"type": "ephemeral"})),
596
+ );
597
+ }
598
+
599
+ #[test]
600
+ fn applied_path_preserves_other_tool_fields() {
601
+ // Property: post-placement body matches input body modulo
602
+ // the `tools[last].cache_control` key. Sort-stable, no
603
+ // collateral mutation elsewhere.
604
+ let original = body_one_tool_no_markers();
605
+ let mut body = original.clone();
606
+ let _ = auto_place_anthropic_cache_control(&mut body);
607
+
608
+ // Strip the marker we placed and compare to the original.
609
+ let tools = body
610
+ .get_mut("tools")
611
+ .and_then(Value::as_array_mut)
612
+ .expect("tools array");
613
+ for tool in tools {
614
+ if let Some(map) = tool.as_object_mut() {
615
+ map.remove("cache_control");
616
+ }
617
+ }
618
+ assert_eq!(
619
+ body, original,
620
+ "Applied path must mutate ONLY the cache_control field on the chosen slot",
621
+ );
622
+ }
623
+
624
+ #[test]
625
+ fn skip_reason_strings_are_stable() {
626
+ // Dashboards filter on these strings. Pin them.
627
+ assert_eq!(SkipReason::AuthMode.as_str(), "auth_mode");
628
+ assert_eq!(SkipReason::MarkerPresent.as_str(), "marker_present");
629
+ }
630
+
631
+ #[test]
632
+ fn any_marker_walker_scans_system_array_form_only() {
633
+ // String-form `system` cannot carry a marker — walker should
634
+ // not flag it even when the string contains the substring
635
+ // "cache_control".
636
+ let body = json!({
637
+ "system": "Note: cache_control is an Anthropic concept.",
638
+ "messages": [],
639
+ });
640
+ assert!(!any_anthropic_cache_control(&body));
641
+
642
+ // Array-form `system` with a marker — walker DOES flag it.
643
+ let body_with_marker = json!({
644
+ "system": [
645
+ {"type": "text", "text": "x", "cache_control": {"type": "ephemeral"}}
646
+ ],
647
+ "messages": [],
648
+ });
649
+ assert!(any_anthropic_cache_control(&body_with_marker));
650
+ }
651
+
652
+ #[test]
653
+ fn any_marker_walker_does_not_descend_into_input_schema() {
654
+ // Customer's tool input_schema happens to declare a property
655
+ // literally named `cache_control`. That's NOT a real Anthropic
656
+ // marker — it's a JSON Schema property name. Walker must NOT
657
+ // false-positive.
658
+ let body = json!({
659
+ "tools": [{
660
+ "name": "configure",
661
+ "description": "configure something",
662
+ "input_schema": {
663
+ "type": "object",
664
+ "properties": {
665
+ "cache_control": {"type": "string"}
666
+ }
667
+ }
668
+ }],
669
+ "messages": [{"role": "user", "content": "hi"}],
670
+ });
671
+ assert!(
672
+ !any_anthropic_cache_control(&body),
673
+ "walker must scope to documented Anthropic surfaces; \
674
+ schema property keys do not count as markers",
675
+ );
676
+ }
677
+
678
+ #[test]
679
+ fn malformed_tool_entry_does_not_panic() {
680
+ // Defensive: an Anthropic request with a non-object tool would
681
+ // get a 400 from upstream, but we never panic on a malformed
682
+ // body. Skip the slot instead.
683
+ let mut body = json!({
684
+ "tools": ["not-an-object"],
685
+ "messages": [{"role": "user", "content": "hi"}],
686
+ });
687
+ let before = body.clone();
688
+ let outcome = auto_place_anthropic_cache_control(&mut body);
689
+ assert_eq!(
690
+ outcome,
691
+ AutoPlaceOutcome::Applied {
692
+ placed_count: 0,
693
+ locations: Vec::new(),
694
+ }
695
+ );
696
+ assert_eq!(body, before, "malformed-tool path must not mutate");
697
+ }
698
+ }