ctxtop 0.0.0-stage → 4.0.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 (240) hide show
  1. package/.antigravity-plugin/plugin.json +36 -0
  2. package/.claude-plugin/plugin.json +18 -0
  3. package/CHECKSUMS.sha256 +149 -0
  4. package/LICENSE +27 -0
  5. package/README.md +330 -3
  6. package/SECURITY.md +22 -0
  7. package/agents/ah-flash-scout.md +25 -0
  8. package/assets/advanced_view_loaded_420px.png +0 -0
  9. package/assets/hero-demo.svg +188 -0
  10. package/assets/logo.svg +19 -0
  11. package/assets/simple_view_lean_420px.png +0 -0
  12. package/assets/simple_view_loaded_420px.png +0 -0
  13. package/assets/social-preview.svg +72 -0
  14. package/assets/zone_c_step3_shield_full.png +0 -0
  15. package/bin/ah-statusline.mjs +145 -0
  16. package/bin/cli.mjs +3 -0
  17. package/bin/ctxtop.mjs +1474 -0
  18. package/commands/cost-radar.md +11 -0
  19. package/commands/evolve.md +10 -0
  20. package/commands/handoff.md +10 -0
  21. package/commands/horizon.md +10 -0
  22. package/commands/inspect.md +10 -0
  23. package/commands/precheck.md +10 -0
  24. package/config/default_flightcheck.json +114 -0
  25. package/config/modelCatalog.json +620 -0
  26. package/config/platformQuirks.json +19 -0
  27. package/hooks/handlers/compact-lifecycle.mjs +262 -0
  28. package/hooks/handlers/hookIo.mjs +255 -0
  29. package/hooks/handlers/hookIpcClient.mjs +83 -0
  30. package/hooks/handlers/post-tool-use.mjs +265 -0
  31. package/hooks/handlers/pre-model-switch.mjs +249 -0
  32. package/hooks/handlers/pre-tool-use.mjs +365 -0
  33. package/hooks/handlers/stop-gate.mjs +240 -0
  34. package/hooks/handlers/user-prompt-submit.mjs +143 -0
  35. package/hooks/hooks.json +81 -0
  36. package/hooks/post_invocation.mjs +13 -0
  37. package/hooks/post_tool_use.mjs +17 -0
  38. package/hooks/pre_invocation.mjs +14 -0
  39. package/hooks/pre_tool_use.mjs +97 -0
  40. package/hooks/register.js +687 -0
  41. package/hooks/session_start.mjs +14 -0
  42. package/hooks/stop.mjs +13 -0
  43. package/hooks.json +56 -0
  44. package/package.json +103 -4
  45. package/packages/antigravity/package.json +14 -0
  46. package/packages/antigravity/src/index.mjs +1 -0
  47. package/packages/claude-code/package.json +14 -0
  48. package/packages/claude-code/src/index.mjs +2 -0
  49. package/packages/core/package.json +14 -0
  50. package/packages/core/src/index.mjs +1 -0
  51. package/packages/engine-node/package.json +14 -0
  52. package/packages/engine-node/src/index.mjs +1 -0
  53. package/packages/mcp/package.json +17 -0
  54. package/packages/mcp/src/server.mjs +396 -0
  55. package/packages/pro/LICENSE-COMMERCIAL.md +19 -0
  56. package/packages/pro/README-SIGNING.md +30 -0
  57. package/packages/pro/package.json +16 -0
  58. package/packages/pro/src/index.mjs +3 -0
  59. package/packages/pro/src/team_finops_pack.mjs +241 -0
  60. package/packages/pro/workers/polar_webhook_worker.mjs +215 -0
  61. package/plugin.json +36 -0
  62. package/rules/AGENTS.md +10 -0
  63. package/sidecars/horizon-daemon/ipcServer.mjs +24 -0
  64. package/sidecars/horizon-daemon/server.mjs +2002 -0
  65. package/sidecars/horizon-daemon/sidecar.json +19 -0
  66. package/skills/cost-radar/SKILL.md +21 -0
  67. package/skills/evolve/SKILL.md +21 -0
  68. package/skills/handoff/SKILL.md +42 -0
  69. package/skills/horizon/SKILL.md +17 -0
  70. package/skills/inspect/SKILL.md +18 -0
  71. package/skills/precheck/SKILL.md +44 -0
  72. package/src/adapters/antigravity/index.mjs +79 -0
  73. package/src/adapters/claude-code/index.mjs +155 -0
  74. package/src/cli/cost_radar.mjs +70 -0
  75. package/src/cli/doctor.mjs +351 -0
  76. package/src/cli/horizon_hud.mjs +686 -0
  77. package/src/cli/init.mjs +425 -0
  78. package/src/cli/postmortem.mjs +515 -0
  79. package/src/coach/cacheGravityRouter.mjs +12 -0
  80. package/src/config/modelCatalog.json +620 -0
  81. package/src/config/platformQuirks.json +19 -0
  82. package/src/core/action_queue.mjs +264 -0
  83. package/src/core/ag_bridge.mjs +346 -0
  84. package/src/core/atomic_io.mjs +124 -0
  85. package/src/core/baseline.mjs +607 -0
  86. package/src/core/blindspot_sensors.mjs +399 -0
  87. package/src/core/classifier.mjs +1757 -0
  88. package/src/core/coach/circuit_breakers.mjs +650 -0
  89. package/src/core/coach/contradiction_auditor.mjs +239 -0
  90. package/src/core/coach/effort_advisor.mjs +143 -0
  91. package/src/core/coach/handoff_hydrator.mjs +483 -0
  92. package/src/core/coach/progressive_checkpointer.mjs +551 -0
  93. package/src/core/coach/prompt_decomposer_coach.mjs +141 -0
  94. package/src/core/coach/reflector_queue.mjs +505 -0
  95. package/src/core/coach/saved_quota_ledger.mjs +615 -0
  96. package/src/core/coach/subagent_ipi_sanitizer.mjs +200 -0
  97. package/src/core/coach/subagent_phantom_auditor.mjs +261 -0
  98. package/src/core/coach/task_quota_router.mjs +955 -0
  99. package/src/core/coach/turn_zero_gate.mjs +574 -0
  100. package/src/core/compaction_coach.mjs +1126 -0
  101. package/src/core/config.mjs +214 -0
  102. package/src/core/constants.mjs +1800 -0
  103. package/src/core/detectors_det01_to_16.mjs +1474 -0
  104. package/src/core/episodic_memory.mjs +135 -0
  105. package/src/core/fts5_output_compressor.mjs +359 -0
  106. package/src/core/git_ledger.mjs +189 -0
  107. package/src/core/handoff_audit.mjs +558 -0
  108. package/src/core/history.mjs +221 -0
  109. package/src/core/hook_diagnostics.mjs +158 -0
  110. package/src/core/horizon_classifier.mjs +326 -0
  111. package/src/core/horizon_config.mjs +802 -0
  112. package/src/core/host_watchdog.mjs +200 -0
  113. package/src/core/layer5_hygiene.mjs +966 -0
  114. package/src/core/log_resolver.mjs +231 -0
  115. package/src/core/mcp_auditor.mjs +138 -0
  116. package/src/core/micro_skills_store.mjs +91 -0
  117. package/src/core/offenders.mjs +161 -0
  118. package/src/core/parser.mjs +1996 -0
  119. package/src/core/path_canonicalizer.mjs +73 -0
  120. package/src/core/paths.mjs +310 -0
  121. package/src/core/prefix_cache_shield.mjs +386 -0
  122. package/src/core/pro_license.mjs +385 -0
  123. package/src/core/prompt_rubric.mjs +518 -0
  124. package/src/core/pruner.mjs +433 -0
  125. package/src/core/quota.mjs +1860 -0
  126. package/src/core/rsi_instinct_engine.mjs +1197 -0
  127. package/src/core/sanitizer.mjs +121 -0
  128. package/src/core/session_forensics.mjs +303 -0
  129. package/src/core/session_timeline.mjs +358 -0
  130. package/src/core/settings.mjs +99 -0
  131. package/src/core/shared/detectors.mjs +1342 -0
  132. package/src/core/shared/fnv1a64.mjs +85 -0
  133. package/src/core/shared/handoff_schema.mjs +123 -0
  134. package/src/core/shared/index.mjs +5 -0
  135. package/src/core/shared/ipi_sanitizer.mjs +165 -0
  136. package/src/core/shared/micro_skills.mjs +1 -0
  137. package/src/core/shared/plugin_validator.mjs +202 -0
  138. package/src/core/shared/prompt_hygiene_governor.mjs +1 -0
  139. package/src/core/sidecar_store.mjs +302 -0
  140. package/src/core/sprint_metrics.mjs +366 -0
  141. package/src/core/sqlite_client.mjs +283 -0
  142. package/src/core/storage_doctor.mjs +358 -0
  143. package/src/core/subagents.mjs +609 -0
  144. package/src/core/swarm_topology.mjs +360 -0
  145. package/src/core/task_quota_router.mjs +1656 -0
  146. package/src/core/telemetry/cache_ttl_watchdog.mjs +284 -0
  147. package/src/core/telemetry/scope_lock_registry.mjs +578 -0
  148. package/src/core/telemetry/shadow_file_detector.mjs +291 -0
  149. package/src/core/telemetry/trajectory_watcher.mjs +259 -0
  150. package/src/core/timeline_svg.mjs +236 -0
  151. package/src/core/tool_surgeon.mjs +305 -0
  152. package/src/core/trajectory_stitcher.mjs +645 -0
  153. package/src/core/u_shaped_optimizer.mjs +789 -0
  154. package/src/core/wal_hygiene.mjs +233 -0
  155. package/src/core-isomorphic/catalog/detectorCatalog.mjs +558 -0
  156. package/src/core-isomorphic/catalog/index.mjs +1 -0
  157. package/src/core-isomorphic/coach/cacheGravityRouter.mjs +720 -0
  158. package/src/core-isomorphic/coach/microSkills.mjs +1 -0
  159. package/src/core-isomorphic/coach/promptHygieneGovernor.mjs +1 -0
  160. package/src/core-isomorphic/coach/repoCalibration.mjs +254 -0
  161. package/src/core-isomorphic/coach/savedQuotaLedger.mjs +527 -0
  162. package/src/core-isomorphic/coach/stateBatonHydrator.mjs +810 -0
  163. package/src/core-isomorphic/coach/ttlWatchdog.mjs +457 -0
  164. package/src/core-isomorphic/config/anthropicModelCatalog.json +203 -0
  165. package/src/core-isomorphic/config/catalogLoader.mjs +768 -0
  166. package/src/core-isomorphic/config/horizonConfig.mjs +1009 -0
  167. package/src/core-isomorphic/control/callTree.mjs +338 -0
  168. package/src/core-isomorphic/control/coachLatches.mjs +126 -0
  169. package/src/core-isomorphic/control/controlStateMachine.mjs +205 -0
  170. package/src/core-isomorphic/control/index.mjs +49 -0
  171. package/src/core-isomorphic/control/swarmWorktree.mjs +109 -0
  172. package/src/core-isomorphic/control/toolSuspension.mjs +197 -0
  173. package/src/core-isomorphic/diagnostics/drift_guard.mjs +382 -0
  174. package/src/core-isomorphic/diagnostics/index.mjs +9 -0
  175. package/src/core-isomorphic/diagnostics/micro_skills.mjs +471 -0
  176. package/src/core-isomorphic/diagnostics/prompt_hygiene_governor.mjs +622 -0
  177. package/src/core-isomorphic/economics/billingBlocks.mjs +251 -0
  178. package/src/core-isomorphic/economics/cacheGravity.mjs +351 -0
  179. package/src/core-isomorphic/economics/cliffBreaker.mjs +170 -0
  180. package/src/core-isomorphic/economics/driftLatency.mjs +319 -0
  181. package/src/core-isomorphic/economics/dualTtl.mjs +198 -0
  182. package/src/core-isomorphic/economics/index.mjs +47 -0
  183. package/src/core-isomorphic/economics/retentionRadar.mjs +348 -0
  184. package/src/core-isomorphic/guards/circuitBreakers.mjs +1202 -0
  185. package/src/core-isomorphic/guards/det01_03_shell_secret.mjs +1035 -0
  186. package/src/core-isomorphic/guards/det04_12_thrash_rot.mjs +480 -0
  187. package/src/core-isomorphic/guards/det13_20_mcp_scope.mjs +603 -0
  188. package/src/core-isomorphic/guards/losslessPostSanitizer.mjs +301 -0
  189. package/src/core-isomorphic/index.js +26 -0
  190. package/src/core-isomorphic/telemetry/otelExporter.mjs +187 -0
  191. package/src/core-isomorphic/telemetry/scopeLockRegistry.mjs +522 -0
  192. package/src/core-isomorphic/telemetry/sprintMetrics.mjs +327 -0
  193. package/src/core-isomorphic/telemetry/swarmTopology.mjs +152 -0
  194. package/src/core-isomorphic/telemetry/telemetryBridge.mjs +1132 -0
  195. package/src/core-isomorphic/ui/brailleSparkline.mjs +142 -0
  196. package/src/core-isomorphic/ui/costRadarSvg.mjs +276 -0
  197. package/src/core-isomorphic/ui/horizonGrid.mjs +475 -0
  198. package/src/core-isomorphic/ui/horizonPanelHtml.mjs +1181 -0
  199. package/src/core-isomorphic/ui/modViews.mjs +1478 -0
  200. package/src/core-isomorphic/ui/pdfReceiptGenerator.mjs +329 -0
  201. package/src/core-isomorphic/ustf/index.mjs +7 -0
  202. package/src/core-isomorphic/ustf/normalizer.mjs +512 -0
  203. package/src/core-isomorphic/ustf/schema.mjs +186 -0
  204. package/src/core-isomorphic/utils/runtime.mjs +962 -0
  205. package/src/demo/synthetic_states.mjs +661 -0
  206. package/src/diagnostics/bugReportGenerator.mjs +253 -0
  207. package/src/diagnostics/doctorEngine.mjs +203 -0
  208. package/src/engine-node/db/index.mjs +58 -0
  209. package/src/engine-node/db/jsonl_fallback.mjs +184 -0
  210. package/src/engine-node/db/probe.mjs +110 -0
  211. package/src/engine-node/db/sqlite_wrapper.mjs +122 -0
  212. package/src/engine-node/index.mjs +9 -0
  213. package/src/engine-node/ipc/client.mjs +447 -0
  214. package/src/engine-node/ipc/index.mjs +22 -0
  215. package/src/engine-node/ipc/protocol.mjs +177 -0
  216. package/src/engine-node/ipc/server.mjs +445 -0
  217. package/src/engine-node/offloader/index.mjs +6 -0
  218. package/src/engine-node/offloader/tool_offloader.mjs +241 -0
  219. package/src/engine-node/sensors/blindspots.mjs +369 -0
  220. package/src/engine-node/sensors/git_merge_tree.mjs +223 -0
  221. package/src/engine-node/sensors/index.mjs +7 -0
  222. package/src/hooks/portfolio_runtime.mjs +858 -0
  223. package/src/hooks/post_invocation.mjs +419 -0
  224. package/src/hooks/pre_invocation.mjs +1015 -0
  225. package/src/hooks/session_start.mjs +161 -0
  226. package/src/shims/agy_cli_compressor.mjs +705 -0
  227. package/src/shims/agy_git_guard.mjs +749 -0
  228. package/src/shims/ah_log_query.mjs +39 -0
  229. package/src/ui/costRadarSvg.mjs +6 -0
  230. package/src/ui/horizonGrid.mjs +1 -0
  231. package/src/ui/horizonPanelHtml.mjs +1 -0
  232. package/src/ui/horizon_panel.css +167 -0
  233. package/src/ui/horizon_panel.js +212 -0
  234. package/src/ui/modViews.mjs +1 -0
  235. package/src/utils/nodeIo.mjs +59 -0
  236. package/src/utils/runtime.mjs +1 -0
  237. package/src/webview/advanced_view.html +1808 -0
  238. package/src/webview/horizon_panel.html +11389 -0
  239. package/src/webview/registry.mjs +80 -0
  240. package/src/webview/simple_view.html +1370 -0
@@ -0,0 +1,251 @@
1
+ /**
2
+ * @file src/core-isomorphic/economics/billingBlocks.mjs
3
+ * Feature 22: 5-Hour Rolling Billing Blocks & Subagent Cost Attribution.
4
+ *
5
+ * Implements:
6
+ * - 18,000,000 ms (5-hour) rolling billing window partitioning
7
+ * - Velocity metrics: burn rate in USD/hour and tokens/min per block
8
+ * - Per-subagent spend and token attribution
9
+ * - Cumulative session cost calculation across active rolling blocks
10
+ * - Clean empty-array handling returning `[]`
11
+ * - Resilient input validation: filters null/undefined events and sanitizes non-numeric costs/tokens
12
+ *
13
+ * Adheres strictly to Claude Mod Laws 1–5: pure ESM, zero `node:*` imports, zero Node globals.
14
+ */
15
+
16
+ export const BILLING_BLOCK_CONSTANTS = Object.freeze({
17
+ BLOCK_DURATION_MS: 5 * 3600 * 1000, // 18,000,000 ms (5 hours)
18
+ BLOCK_DURATION_HOURS: 5.0,
19
+ TOKENS_PER_MIN_DIVISOR: 300 // 5 hours * 60 minutes
20
+ });
21
+
22
+ /**
23
+ * Partitions continuous session token usage events into rolling 5-hour billing blocks.
24
+ *
25
+ * @param {Array<{ timestamp: number, costUsd?: number, tokens?: number, subagentId?: string }>} [usageEvents=[]]
26
+ * @param {number} [blockDurationMs=18000000] Block window in ms (default 5 hours)
27
+ * @returns {Array<{
28
+ * blockIndex: number,
29
+ * startTime: number,
30
+ * endTime: number,
31
+ * totalCostUsd: number,
32
+ * totalTokens: number,
33
+ * eventCount: number,
34
+ * subagentSpend: Record<string, number>,
35
+ * burnRateUsdPerHour: number,
36
+ * tokensPerMin: number
37
+ * }>}
38
+ */
39
+ export function partitionBillingBlocks(
40
+ usageEvents = [],
41
+ blockDurationMs = BILLING_BLOCK_CONSTANTS.BLOCK_DURATION_MS
42
+ ) {
43
+ if (!Array.isArray(usageEvents) || usageEvents.length === 0) {
44
+ return [];
45
+ }
46
+
47
+ // Filter usageEvents to keep only valid non-null object entries
48
+ const validEvents = usageEvents.filter(ev => ev && typeof ev === 'object');
49
+ if (validEvents.length === 0) {
50
+ return [];
51
+ }
52
+
53
+ const duration = Number(blockDurationMs) > 0
54
+ ? Number(blockDurationMs)
55
+ : BILLING_BLOCK_CONSTANTS.BLOCK_DURATION_MS;
56
+
57
+ const sorted = [...validEvents].sort((a, b) => {
58
+ const tsA = Number(a.timestamp) || 0;
59
+ const tsB = Number(b.timestamp) || 0;
60
+ return tsA - tsB;
61
+ });
62
+
63
+ const startTimestamp = Number(sorted[0].timestamp) || 0;
64
+ const blocksMap = new Map();
65
+
66
+ for (const event of sorted) {
67
+ const rawTs = Number(event.timestamp);
68
+ const ts = Number.isFinite(rawTs) ? rawTs : startTimestamp;
69
+ const blockIndex = Math.max(0, Math.floor((ts - startTimestamp) / duration));
70
+
71
+ if (!blocksMap.has(blockIndex)) {
72
+ blocksMap.set(blockIndex, {
73
+ blockIndex,
74
+ startTime: startTimestamp + (blockIndex * duration),
75
+ endTime: startTimestamp + ((blockIndex + 1) * duration),
76
+ totalCostUsd: 0,
77
+ totalTokens: 0,
78
+ eventCount: 0,
79
+ subagentSpend: {}
80
+ });
81
+ }
82
+
83
+ const block = blocksMap.get(blockIndex);
84
+ const cost = Math.max(0, Number(event.costUsd) || 0);
85
+ const tokens = Math.max(0, Number(event.tokens) || 0);
86
+ const agent = String(event.subagentId || 'main');
87
+
88
+ block.totalCostUsd = parseFloat((block.totalCostUsd + cost).toFixed(4));
89
+ block.totalTokens += tokens;
90
+ block.eventCount += 1;
91
+ block.subagentSpend[agent] = parseFloat(((block.subagentSpend[agent] || 0) + cost).toFixed(4));
92
+ }
93
+
94
+ const durationHours = duration / 3600000;
95
+ const durationMins = durationHours * 60;
96
+
97
+ return Array.from(blocksMap.values()).map(b => {
98
+ const burnRateUsdPerHour = durationHours > 0
99
+ ? parseFloat((b.totalCostUsd / durationHours).toFixed(4))
100
+ : 0;
101
+ const tokensPerMin = durationMins > 0
102
+ ? Math.round(b.totalTokens / durationMins)
103
+ : 0;
104
+ return {
105
+ ...b,
106
+ burnRateUsdPerHour,
107
+ tokensPerMin
108
+ };
109
+ });
110
+ }
111
+
112
+ /**
113
+ * Attributes total spend and token consumption across subagent IDs.
114
+ *
115
+ * @param {Array<{ timestamp?: number, costUsd?: number, tokens?: number, subagentId?: string }>} [usageEvents=[]]
116
+ * @returns {Record<string, { costUsd: number, tokens: number, pct: number }>}
117
+ */
118
+ export function attributeSubagentCosts(usageEvents = []) {
119
+ if (!Array.isArray(usageEvents) || usageEvents.length === 0) {
120
+ return {};
121
+ }
122
+
123
+ const validEvents = usageEvents.filter(ev => ev && typeof ev === 'object');
124
+ if (validEvents.length === 0) {
125
+ return {};
126
+ }
127
+
128
+ const result = {};
129
+ let totalCost = 0;
130
+
131
+ for (const ev of validEvents) {
132
+ const agent = String(ev.subagentId || 'main');
133
+ const cost = Math.max(0, Number(ev.costUsd) || 0);
134
+ const tokens = Math.max(0, Number(ev.tokens) || 0);
135
+
136
+ if (!result[agent]) {
137
+ result[agent] = { costUsd: 0, tokens: 0, pct: 0 };
138
+ }
139
+ result[agent].costUsd = parseFloat((result[agent].costUsd + cost).toFixed(4));
140
+ result[agent].tokens += tokens;
141
+ totalCost += cost;
142
+ }
143
+
144
+ for (const agent of Object.keys(result)) {
145
+ result[agent].pct = totalCost > 0
146
+ ? parseFloat(((result[agent].costUsd / totalCost) * 100).toFixed(1))
147
+ : 0;
148
+ }
149
+
150
+ return result;
151
+ }
152
+
153
+ /**
154
+ * Computes aggregate summary metrics across multiple billing blocks.
155
+ *
156
+ * @param {Array<object>} blocks
157
+ * @returns {{
158
+ * blockCount: number,
159
+ * cumulativeCostUsd: number,
160
+ * cumulativeTokens: number,
161
+ * maxBurnRateUsdPerHour: number,
162
+ * avgTokensPerMin: number
163
+ * }}
164
+ */
165
+ export function computeBillingBlockSummary(blocks = []) {
166
+ if (!Array.isArray(blocks) || blocks.length === 0) {
167
+ return {
168
+ blockCount: 0,
169
+ cumulativeCostUsd: 0,
170
+ cumulativeTokens: 0,
171
+ maxBurnRateUsdPerHour: 0,
172
+ avgTokensPerMin: 0
173
+ };
174
+ }
175
+
176
+ const validBlocks = blocks.filter(b => b && typeof b === 'object');
177
+ if (validBlocks.length === 0) {
178
+ return {
179
+ blockCount: 0,
180
+ cumulativeCostUsd: 0,
181
+ cumulativeTokens: 0,
182
+ maxBurnRateUsdPerHour: 0,
183
+ avgTokensPerMin: 0
184
+ };
185
+ }
186
+
187
+ let totalCost = 0;
188
+ let totalTokens = 0;
189
+ let maxBurn = 0;
190
+ let sumTokPerMin = 0;
191
+
192
+ for (const b of validBlocks) {
193
+ const cost = Math.max(0, Number(b.totalCostUsd) || 0);
194
+ const tokens = Math.max(0, Number(b.totalTokens) || 0);
195
+ const burn = Math.max(0, Number(b.burnRateUsdPerHour) || 0);
196
+ const tokPerMin = Math.max(0, Number(b.tokensPerMin) || 0);
197
+
198
+ totalCost += cost;
199
+ totalTokens += tokens;
200
+ if (burn > maxBurn) {
201
+ maxBurn = burn;
202
+ }
203
+ sumTokPerMin += tokPerMin;
204
+ }
205
+
206
+ return {
207
+ blockCount: validBlocks.length,
208
+ cumulativeCostUsd: parseFloat(totalCost.toFixed(4)),
209
+ cumulativeTokens: totalTokens,
210
+ maxBurnRateUsdPerHour: parseFloat(maxBurn.toFixed(4)),
211
+ avgTokensPerMin: Math.round(sumTokPerMin / validBlocks.length)
212
+ };
213
+ }
214
+
215
+ /**
216
+ * Stateful RollingBillingBlockTracker.
217
+ */
218
+ export class RollingBillingBlockTracker {
219
+ constructor(options = {}) {
220
+ const opts = (options && typeof options === 'object') ? options : {};
221
+ this.blockDurationMs = Number(opts.blockDurationMs) > 0
222
+ ? Number(opts.blockDurationMs)
223
+ : BILLING_BLOCK_CONSTANTS.BLOCK_DURATION_MS;
224
+ this.events = [];
225
+ }
226
+
227
+ recordEvent(event = {}) {
228
+ if (!event || typeof event !== 'object') {
229
+ return;
230
+ }
231
+ const rawTs = Number(event.timestamp);
232
+ this.events.push({
233
+ timestamp: Number.isFinite(rawTs) ? rawTs : Date.now(),
234
+ costUsd: Math.max(0, Number(event.costUsd) || 0),
235
+ tokens: Math.max(0, Number(event.tokens) || 0),
236
+ subagentId: String(event.subagentId || 'main')
237
+ });
238
+ }
239
+
240
+ getBlocks() {
241
+ return partitionBillingBlocks(this.events, this.blockDurationMs);
242
+ }
243
+
244
+ getSummary() {
245
+ return computeBillingBlockSummary(this.getBlocks());
246
+ }
247
+
248
+ getSubagentAttribution() {
249
+ return attributeSubagentCosts(this.events);
250
+ }
251
+ }
@@ -0,0 +1,351 @@
1
+ /**
2
+ * @file src/core-isomorphic/economics/cacheGravity.mjs
3
+ * Feature 19: Algebraic C* Break-Even Cache Gravity Router.
4
+ *
5
+ * Implements the exact algebraic cross-model break-even equation:
6
+ * C* = [ O * (P_out,curr - P_out,target) + Delta_uncached * (P_write,curr - P_write,target) ]
7
+ * / [ P_write,target - P_read,curr ]
8
+ *
9
+ * Canonical test values at O = 1,500, Delta = 0:
10
+ * - Opus 5.5 -> Sonnet 5.5: C* = 6,522 tokens
11
+ * - Opus 4.6 -> Sonnet 4.6: C* = 4,615 tokens
12
+ *
13
+ * Boundary rules:
14
+ * - Capability upshift (P_out,curr <= P_out,target): C* = 0, shouldHold = false
15
+ * - Cheaper target write than current read (P_write,target <= P_read,curr): C* = Infinity
16
+ * - Identical models: C* = 0, shouldHold = false
17
+ * - Cold cache (cachedTokens = 0, cacheWarm = false): switch is cheaper if target is cheaper
18
+ * - Warm cache (cachedTokens > C*): shouldHold = true
19
+ *
20
+ * Adheres strictly to Claude Mod Laws 1–5: pure ESM, zero `node:*` imports, zero Node globals.
21
+ */
22
+
23
+ import {
24
+ normalizeModelId,
25
+ computeTotalPromptTokens,
26
+ resolveEffectiveRates
27
+ } from '../config/catalogLoader.mjs';
28
+
29
+ export const DEFAULT_EXPECTED_OUTPUT_TOKENS = 1500;
30
+
31
+ export const EXPECTED_OUTPUT_TOKENS_BY_EFFORT = Object.freeze({
32
+ low: 800,
33
+ medium: 1500,
34
+ high: 3500,
35
+ max: 6000
36
+ });
37
+
38
+ export const FLIGHT_MODES = Object.freeze({
39
+ OFF: 'OFF',
40
+ SILENT: 'SILENT',
41
+ COACH: 'COACH',
42
+ AUTO_PILOT: 'AUTO_PILOT'
43
+ });
44
+
45
+ export const MODEL_BREAK_EVEN_RATES = Object.freeze({
46
+ 'claude-opus-5-5': { output: 20.0, read: 0.2, write5m: 5.0, write1h: 8.0 },
47
+ 'claude-sonnet-5-5': { output: 10.0, read: 0.1, write5m: 2.5, write1h: 4.0 },
48
+ 'claude-opus-4-6': { output: 25.0, read: 0.5, write5m: 6.25, write1h: 10.0 },
49
+ 'claude-sonnet-4-6': { output: 15.0, read: 0.3, write5m: 3.75, write1h: 6.0 },
50
+ 'claude-haiku-5-5': { output: 0.5, read: 0.01, write5m: 0.125, write1h: 0.2 },
51
+ 'claude-haiku-4-5': { output: 5.0, read: 0.10, write5m: 1.25, write1h: 2.0 },
52
+ 'claude-fable-5-2': { output: 40.0, read: 0.20, write5m: 10.0, write1h: 16.0 },
53
+ 'claude-fable-5-1': { output: 50.0, read: 0.25, write5m: 12.5, write1h: 20.0 }
54
+ });
55
+
56
+ /**
57
+ * Maps an active model to its natural one-tier downshift peer.
58
+ * @param {string} [modelId='claude-opus-5-5']
59
+ * @returns {string}
60
+ */
61
+ export function resolveNaturalDownshiftPeer(modelId = 'claude-opus-5-5') {
62
+ const norm = normalizeModelId(modelId);
63
+ switch (norm) {
64
+ case 'claude-fable-5-2':
65
+ case 'claude-fable-5-1':
66
+ return 'claude-opus-5-5';
67
+ case 'claude-opus-5-5':
68
+ return 'claude-sonnet-5-5';
69
+ case 'claude-opus-4-6':
70
+ return 'claude-sonnet-4-6';
71
+ case 'claude-sonnet-5-5':
72
+ return 'claude-haiku-5-5';
73
+ case 'claude-sonnet-4-6':
74
+ return 'claude-haiku-4-5';
75
+ case 'claude-haiku-4-5':
76
+ case 'claude-haiku-5-5':
77
+ return 'claude-haiku-5-5';
78
+ default:
79
+ return 'claude-sonnet-5-5';
80
+ }
81
+ }
82
+
83
+ /**
84
+ * Closed-form break-even equation computation.
85
+ *
86
+ * @param {number} expectedOutputTokens O
87
+ * @param {number} pOutCurr P_out,curr
88
+ * @param {number} pOutTarget P_out,target
89
+ * @param {number} pWriteTarget P_write,target
90
+ * @param {number} pReadCurr P_read,curr
91
+ * @param {number} [uncachedDeltaTokens=0] Delta_uncached
92
+ * @param {number} [pWriteCurr=pWriteTarget] P_write,curr
93
+ * @returns {number} C* (rounded integer, 0 for upshifts, Infinity if write <= read)
94
+ */
95
+ export function computeClosedFormBreakEven(
96
+ expectedOutputTokens,
97
+ pOutCurr,
98
+ pOutTarget,
99
+ pWriteTarget,
100
+ pReadCurr,
101
+ uncachedDeltaTokens = 0,
102
+ pWriteCurr = pWriteTarget
103
+ ) {
104
+ if (pOutCurr <= pOutTarget) {
105
+ return 0; // Capability upshift
106
+ }
107
+
108
+ const numerator =
109
+ expectedOutputTokens * (pOutCurr - pOutTarget) +
110
+ uncachedDeltaTokens * (pWriteCurr - pWriteTarget);
111
+
112
+ const denominator = pWriteTarget - pReadCurr;
113
+
114
+ if (numerator <= 0) {
115
+ return 0;
116
+ }
117
+ if (denominator <= 0) {
118
+ return Infinity;
119
+ }
120
+
121
+ return Math.round(numerator / denominator);
122
+ }
123
+
124
+ /**
125
+ * Calculates the exact algebraic break-even token count C*.
126
+ * Supports invocation via options object or positional arguments.
127
+ *
128
+ * Canonical test values:
129
+ * - Opus 5.5 -> Sonnet 5.5 (default): C* = 6,522
130
+ * - Opus 4.6 -> Sonnet 4.6: C* = 4,615
131
+ *
132
+ * @param {object|number} [optionsOrOutputTokens={}]
133
+ * @param {object} [maybeRatesCurr]
134
+ * @param {object} [maybeRatesTarget]
135
+ * @returns {number}
136
+ */
137
+ export function calculateBreakEvenCStar(optionsOrOutputTokens = {}, maybeRatesCurr, maybeRatesTarget) {
138
+ let expectedOutputTokens = DEFAULT_EXPECTED_OUTPUT_TOKENS;
139
+ let pOutCurr = 20.0;
140
+ let pOutTarget = 10.0;
141
+ let pWrite5mTarget = 2.5;
142
+ let pReadCurr = 0.2;
143
+ let uncachedDeltaTokens = 0;
144
+ let pWriteCurr = 5.0;
145
+
146
+ if (typeof optionsOrOutputTokens === 'number') {
147
+ expectedOutputTokens = Math.max(0, optionsOrOutputTokens);
148
+ if (maybeRatesCurr && typeof maybeRatesCurr === 'object') {
149
+ pOutCurr = Number(maybeRatesCurr.output ?? maybeRatesCurr.outputPer1M ?? maybeRatesCurr.pOut ?? pOutCurr);
150
+ pReadCurr = Number(maybeRatesCurr.read ?? maybeRatesCurr.readPer1M ?? maybeRatesCurr.pRead ?? pReadCurr);
151
+ pWriteCurr = Number(maybeRatesCurr.write5m ?? maybeRatesCurr.write5mPer1M ?? maybeRatesCurr.write ?? pWriteCurr);
152
+ }
153
+ if (maybeRatesTarget && typeof maybeRatesTarget === 'object') {
154
+ pOutTarget = Number(maybeRatesTarget.output ?? maybeRatesTarget.outputPer1M ?? maybeRatesTarget.pOut ?? pOutTarget);
155
+ pWrite5mTarget = Number(
156
+ maybeRatesTarget.write5m ??
157
+ maybeRatesTarget.write5mPer1M ??
158
+ maybeRatesTarget.write ??
159
+ maybeRatesTarget.pWrite5m ??
160
+ pWrite5mTarget
161
+ );
162
+ }
163
+ } else if (typeof optionsOrOutputTokens === 'object' && optionsOrOutputTokens !== null) {
164
+ const opts = optionsOrOutputTokens;
165
+ if (opts.expectedOutputTokens !== undefined || opts.O !== undefined) {
166
+ const rawO = Number(opts.expectedOutputTokens ?? opts.O);
167
+ expectedOutputTokens = Number.isFinite(rawO) ? Math.max(0, rawO) : DEFAULT_EXPECTED_OUTPUT_TOKENS;
168
+ }
169
+ if (opts.uncachedDeltaTokens !== undefined) {
170
+ const rawDelta = Number(opts.uncachedDeltaTokens);
171
+ uncachedDeltaTokens = Number.isFinite(rawDelta) ? Math.max(0, rawDelta) : 0;
172
+ }
173
+
174
+ const curModel = opts.currentModel ? normalizeModelId(opts.currentModel) : null;
175
+ const tgtModel = opts.targetModel ? normalizeModelId(opts.targetModel) : null;
176
+
177
+ if (curModel && MODEL_BREAK_EVEN_RATES[curModel]) {
178
+ const m = MODEL_BREAK_EVEN_RATES[curModel];
179
+ pOutCurr = m.output;
180
+ pReadCurr = m.read;
181
+ pWriteCurr = m.write5m;
182
+ }
183
+ if (tgtModel && MODEL_BREAK_EVEN_RATES[tgtModel]) {
184
+ const m = MODEL_BREAK_EVEN_RATES[tgtModel];
185
+ pOutTarget = m.output;
186
+ pWrite5mTarget = m.write5m;
187
+ }
188
+
189
+ const rc = opts.ratesCurr || opts.currentRates;
190
+ if (rc && typeof rc === 'object') {
191
+ pOutCurr = Number(rc.output ?? rc.outputPer1M ?? rc.pOut ?? pOutCurr);
192
+ pReadCurr = Number(rc.read ?? rc.readPer1M ?? rc.pRead ?? pReadCurr);
193
+ pWriteCurr = Number(rc.write5m ?? rc.write5mPer1M ?? rc.write ?? pWriteCurr);
194
+ }
195
+ const rt = opts.ratesTarget || opts.targetRates;
196
+ if (rt && typeof rt === 'object') {
197
+ pOutTarget = Number(rt.output ?? rt.outputPer1M ?? rt.pOut ?? pOutTarget);
198
+ pWrite5mTarget = Number(
199
+ rt.write5m ??
200
+ rt.write5mPer1M ??
201
+ rt.write ??
202
+ rt.pWrite5m ??
203
+ pWrite5mTarget
204
+ );
205
+ }
206
+
207
+ if (opts.pOutCurr !== undefined) pOutCurr = Number(opts.pOutCurr);
208
+ if (opts.pOutTarget !== undefined) pOutTarget = Number(opts.pOutTarget);
209
+ if (opts.pWrite5mTarget !== undefined) pWrite5mTarget = Number(opts.pWrite5mTarget);
210
+ if (opts.pReadCurr !== undefined) pReadCurr = Number(opts.pReadCurr);
211
+ }
212
+
213
+ return computeClosedFormBreakEven(
214
+ expectedOutputTokens,
215
+ pOutCurr,
216
+ pOutTarget,
217
+ pWrite5mTarget,
218
+ pReadCurr,
219
+ uncachedDeltaTokens,
220
+ pWriteCurr
221
+ );
222
+ }
223
+
224
+ /**
225
+ * Computes exact break-even token thresholds and USD turn costs for staying on current vs switching.
226
+ *
227
+ * @param {object} [params={}]
228
+ * @param {string} [params.currentModel='claude-opus-5-5']
229
+ * @param {string} [params.targetModel='claude-sonnet-5-5']
230
+ * @param {number} [params.expectedOutputTokens=1500]
231
+ * @param {number} [params.cachedTokens=0]
232
+ * @param {number} [params.uncachedDeltaTokens=0]
233
+ * @param {boolean} [params.cacheWarm]
234
+ * @param {'5m'|'1h'} [params.cacheTtlTier='5m']
235
+ * @param {object} [options={}]
236
+ * @returns {object}
237
+ */
238
+ export function computeBreakEvenCachedTokens(params = {}, options = {}) {
239
+ const rawCurrentModel = params.currentModel || 'claude-opus-5-5';
240
+ const rawTargetModel = params.targetModel || 'claude-sonnet-5-5';
241
+ const currentModel = normalizeModelId(rawCurrentModel);
242
+ const targetModel = normalizeModelId(rawTargetModel);
243
+ const rawExpected = Number(params.expectedOutputTokens ?? DEFAULT_EXPECTED_OUTPUT_TOKENS);
244
+ const expectedOutputTokens = Number.isFinite(rawExpected) ? Math.max(0, rawExpected) : DEFAULT_EXPECTED_OUTPUT_TOKENS;
245
+ const rawCached = Number(params.cachedTokens ?? 0);
246
+ const cachedTokens = Number.isFinite(rawCached) ? Math.max(0, rawCached) : 0;
247
+ const rawUncached = Number(params.uncachedDeltaTokens ?? 0);
248
+ const uncachedDeltaTokens = Number.isFinite(rawUncached) ? Math.max(0, rawUncached) : 0;
249
+ const cacheWarm = params.cacheWarm !== undefined ? Boolean(params.cacheWarm) : cachedTokens > 0;
250
+ const ttlTier = params.cacheTtlTier === '1h' ? '1h' : '5m';
251
+
252
+ const totalPromptTokens = Math.max(
253
+ cachedTokens + uncachedDeltaTokens,
254
+ computeTotalPromptTokens(params)
255
+ );
256
+ const currRates = resolveEffectiveRates(rawCurrentModel, totalPromptTokens, options);
257
+ const targetRates = resolveEffectiveRates(rawTargetModel, totalPromptTokens, options);
258
+
259
+ const pOutCurr = currRates.outputPer1M;
260
+ const pOutTarget = targetRates.outputPer1M;
261
+ const pReadCurr = currRates.readPer1M;
262
+ const pWriteCurr = ttlTier === '1h' ? currRates.write1hPer1M : currRates.write5mPer1M;
263
+ const pWriteTarget = ttlTier === '1h' ? targetRates.write1hPer1M : targetRates.write5mPer1M;
264
+
265
+ const isCapabilityUpshift = pOutCurr <= pOutTarget;
266
+
267
+ let breakEvenTokens = 0;
268
+ if (currentModel === targetModel || isCapabilityUpshift) {
269
+ breakEvenTokens = 0;
270
+ } else {
271
+ breakEvenTokens = computeClosedFormBreakEven(
272
+ expectedOutputTokens,
273
+ pOutCurr,
274
+ pOutTarget,
275
+ pWriteTarget,
276
+ pReadCurr,
277
+ uncachedDeltaTokens,
278
+ pWriteCurr
279
+ );
280
+ }
281
+
282
+ // Exact USD turn cost if staying on currentModel
283
+ const stayPrefixCostUSD = cacheWarm
284
+ ? (cachedTokens / 1_000_000) * pReadCurr + (uncachedDeltaTokens / 1_000_000) * pWriteCurr
285
+ : ((cachedTokens + uncachedDeltaTokens) / 1_000_000) * pWriteCurr;
286
+ const stayOutputCostUSD = (expectedOutputTokens / 1_000_000) * pOutCurr;
287
+ const stayOnCurrentModelUSD = stayPrefixCostUSD + stayOutputCostUSD;
288
+
289
+ // Switching to a different model invalidates isolated cache, forcing cold write
290
+ const switchPrefixCostUSD =
291
+ currentModel === targetModel && cacheWarm
292
+ ? stayPrefixCostUSD
293
+ : ((cachedTokens + uncachedDeltaTokens) / 1_000_000) * pWriteTarget;
294
+ const switchOutputCostUSD = (expectedOutputTokens / 1_000_000) * pOutTarget;
295
+ const switchToTargetModelUSD = switchPrefixCostUSD + switchOutputCostUSD;
296
+
297
+ const coldWritePenaltyUSD = Number(
298
+ (switchToTargetModelUSD - stayOnCurrentModelUSD).toFixed(6)
299
+ );
300
+
301
+ const shouldHoldModel = Boolean(
302
+ currentModel !== targetModel &&
303
+ !isCapabilityUpshift &&
304
+ cacheWarm &&
305
+ coldWritePenaltyUSD > 0 &&
306
+ cachedTokens > breakEvenTokens
307
+ );
308
+
309
+ return {
310
+ currentModel,
311
+ targetModel,
312
+ expectedOutputTokens,
313
+ cachedTokens,
314
+ uncachedDeltaTokens,
315
+ totalPromptTokens,
316
+ cacheWarm,
317
+ cacheTtlTier: ttlTier,
318
+ writeMultiplierLabel: ttlTier === '1h' ? '2.0x' : '1.25x',
319
+ isCapabilityUpshift,
320
+ breakEvenTokens,
321
+ rates: {
322
+ currentOutputPer1M: pOutCurr,
323
+ targetOutputPer1M: pOutTarget,
324
+ currentReadPer1M: pReadCurr,
325
+ currentWritePer1M: pWriteCurr,
326
+ targetWritePer1M: pWriteTarget
327
+ },
328
+ stayOnCurrentModelUSD,
329
+ switchToTargetModelUSD,
330
+ coldWritePenaltyUSD,
331
+ shouldHold: shouldHoldModel,
332
+ shouldHoldModel
333
+ };
334
+ }
335
+
336
+ /**
337
+ * Evaluates cache gravity recommendation for flight controller.
338
+ *
339
+ * @param {object} params
340
+ * @param {object} [options={}]
341
+ * @returns {object}
342
+ */
343
+ export function evaluateCacheGravity(params = {}, options = {}) {
344
+ const result = computeBreakEvenCachedTokens(params, options);
345
+ const recommendation = result.shouldHoldModel ? 'STAY_ON_CURRENT' : 'SWITCH_TO_TARGET';
346
+ return {
347
+ ...result,
348
+ recommendation,
349
+ action: result.shouldHoldModel ? 'hold' : 'allow'
350
+ };
351
+ }