ctxtop 0.0.0-stage → 4.1.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 (262) hide show
  1. package/.antigravity-plugin/plugin.json +36 -0
  2. package/.claude-plugin/plugin.json +18 -0
  3. package/CHECKSUMS.sha256 +166 -0
  4. package/LICENSE +27 -0
  5. package/README.md +350 -2
  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 +175 -0
  16. package/bin/cli.mjs +3 -0
  17. package/bin/ctxtop.mjs +1799 -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 +133 -0
  25. package/config/modelCatalog.json +785 -0
  26. package/config/platformQuirks.json +19 -0
  27. package/hooks/handlers/compact-lifecycle.mjs +577 -0
  28. package/hooks/handlers/config-change.mjs +402 -0
  29. package/hooks/handlers/hookIo.mjs +311 -0
  30. package/hooks/handlers/hookIpcClient.mjs +83 -0
  31. package/hooks/handlers/post-model-switch.mjs +111 -0
  32. package/hooks/handlers/post-tool-use.mjs +366 -0
  33. package/hooks/handlers/pre-model-switch.mjs +1048 -0
  34. package/hooks/handlers/pre-tool-use.mjs +632 -0
  35. package/hooks/handlers/stop-gate.mjs +526 -0
  36. package/hooks/handlers/user-prompt-submit.mjs +367 -0
  37. package/hooks/hooks.json +131 -0
  38. package/hooks/post_invocation.mjs +13 -0
  39. package/hooks/post_tool_use.mjs +25 -0
  40. package/hooks/pre_invocation.mjs +14 -0
  41. package/hooks/pre_tool_use.mjs +97 -0
  42. package/hooks/register.js +726 -0
  43. package/hooks/session_start.mjs +24 -0
  44. package/hooks/stop.mjs +23 -0
  45. package/hooks.json +56 -0
  46. package/package.json +110 -4
  47. package/packages/antigravity/package.json +14 -0
  48. package/packages/antigravity/src/index.mjs +1 -0
  49. package/packages/claude-code/package.json +14 -0
  50. package/packages/claude-code/src/index.mjs +2 -0
  51. package/packages/core/package.json +14 -0
  52. package/packages/core/src/index.mjs +1 -0
  53. package/packages/engine-node/package.json +14 -0
  54. package/packages/engine-node/src/index.mjs +1 -0
  55. package/packages/mcp/package.json +17 -0
  56. package/packages/mcp/src/server.mjs +396 -0
  57. package/packages/pro/LICENSE-COMMERCIAL.md +19 -0
  58. package/packages/pro/README-SIGNING.md +30 -0
  59. package/packages/pro/package.json +16 -0
  60. package/packages/pro/src/index.mjs +3 -0
  61. package/packages/pro/src/team_finops_pack.mjs +241 -0
  62. package/packages/pro/workers/polar_webhook_worker.mjs +215 -0
  63. package/plugin.json +36 -0
  64. package/rules/AGENTS.md +10 -0
  65. package/sidecars/horizon-daemon/ipcServer.mjs +24 -0
  66. package/sidecars/horizon-daemon/server.mjs +2038 -0
  67. package/sidecars/horizon-daemon/sidecar.json +19 -0
  68. package/skills/cost-radar/SKILL.md +21 -0
  69. package/skills/evolve/SKILL.md +21 -0
  70. package/skills/handoff/SKILL.md +50 -0
  71. package/skills/horizon/SKILL.md +17 -0
  72. package/skills/inspect/SKILL.md +18 -0
  73. package/skills/precheck/SKILL.md +44 -0
  74. package/src/adapters/antigravity/index.mjs +109 -0
  75. package/src/adapters/claude-code/index.mjs +194 -0
  76. package/src/cli/cost_radar.mjs +70 -0
  77. package/src/cli/doctor.mjs +351 -0
  78. package/src/cli/horizon_hud.mjs +888 -0
  79. package/src/cli/init.mjs +425 -0
  80. package/src/cli/postmortem.mjs +515 -0
  81. package/src/coach/cacheGravityRouter.mjs +12 -0
  82. package/src/config/modelCatalog.json +704 -0
  83. package/src/config/platformQuirks.json +19 -0
  84. package/src/core/action_queue.mjs +264 -0
  85. package/src/core/ag_bridge.mjs +346 -0
  86. package/src/core/atomic_io.mjs +124 -0
  87. package/src/core/baseline.mjs +607 -0
  88. package/src/core/blindspot_sensors.mjs +399 -0
  89. package/src/core/bucket_b_runtime.mjs +1200 -0
  90. package/src/core/classifier.mjs +1757 -0
  91. package/src/core/coach/circuit_breakers.mjs +650 -0
  92. package/src/core/coach/contradiction_auditor.mjs +239 -0
  93. package/src/core/coach/effort_advisor.mjs +143 -0
  94. package/src/core/coach/handoff_hydrator.mjs +483 -0
  95. package/src/core/coach/progressive_checkpointer.mjs +551 -0
  96. package/src/core/coach/prompt_decomposer_coach.mjs +141 -0
  97. package/src/core/coach/reflector_queue.mjs +505 -0
  98. package/src/core/coach/saved_quota_ledger.mjs +615 -0
  99. package/src/core/coach/subagent_ipi_sanitizer.mjs +200 -0
  100. package/src/core/coach/subagent_phantom_auditor.mjs +261 -0
  101. package/src/core/coach/task_quota_router.mjs +955 -0
  102. package/src/core/coach/turn_zero_gate.mjs +574 -0
  103. package/src/core/compaction_coach.mjs +1126 -0
  104. package/src/core/config.mjs +214 -0
  105. package/src/core/constants.mjs +1987 -0
  106. package/src/core/detectors_det01_to_16.mjs +1523 -0
  107. package/src/core/doc_indexer.mjs +338 -0
  108. package/src/core/episodic_memory.mjs +135 -0
  109. package/src/core/fts5_output_compressor.mjs +359 -0
  110. package/src/core/git_ledger.mjs +189 -0
  111. package/src/core/handoff_audit.mjs +558 -0
  112. package/src/core/history.mjs +221 -0
  113. package/src/core/hook_diagnostics.mjs +158 -0
  114. package/src/core/horizon_classifier.mjs +326 -0
  115. package/src/core/horizon_config.mjs +802 -0
  116. package/src/core/host_watchdog.mjs +200 -0
  117. package/src/core/layer5_hygiene.mjs +1084 -0
  118. package/src/core/log_resolver.mjs +231 -0
  119. package/src/core/mcp_auditor.mjs +138 -0
  120. package/src/core/micro_skills_store.mjs +91 -0
  121. package/src/core/offenders.mjs +161 -0
  122. package/src/core/parser.mjs +1997 -0
  123. package/src/core/path_canonicalizer.mjs +73 -0
  124. package/src/core/paths.mjs +311 -0
  125. package/src/core/prefix_cache_shield.mjs +386 -0
  126. package/src/core/pro_license.mjs +385 -0
  127. package/src/core/prompt_rubric.mjs +518 -0
  128. package/src/core/pruner.mjs +433 -0
  129. package/src/core/quota.mjs +1860 -0
  130. package/src/core/rsi_instinct_engine.mjs +1197 -0
  131. package/src/core/rsl_clash_auditor.mjs +423 -0
  132. package/src/core/rsl_distiller.mjs +372 -0
  133. package/src/core/rsl_ledger.mjs +969 -0
  134. package/src/core/rsl_triage.mjs +909 -0
  135. package/src/core/sanitizer.mjs +121 -0
  136. package/src/core/session_auditor.mjs +658 -0
  137. package/src/core/session_forensics.mjs +303 -0
  138. package/src/core/session_timeline.mjs +358 -0
  139. package/src/core/settings.mjs +99 -0
  140. package/src/core/shared/detectors.mjs +1342 -0
  141. package/src/core/shared/fnv1a64.mjs +85 -0
  142. package/src/core/shared/handoff_schema.mjs +123 -0
  143. package/src/core/shared/index.mjs +5 -0
  144. package/src/core/shared/ipi_sanitizer.mjs +165 -0
  145. package/src/core/shared/micro_skills.mjs +1 -0
  146. package/src/core/shared/plugin_validator.mjs +202 -0
  147. package/src/core/shared/prompt_hygiene_governor.mjs +1 -0
  148. package/src/core/shield_manager.mjs +1417 -0
  149. package/src/core/sidecar_store.mjs +302 -0
  150. package/src/core/sprint_metrics.mjs +366 -0
  151. package/src/core/sqlite_client.mjs +283 -0
  152. package/src/core/storage_doctor.mjs +358 -0
  153. package/src/core/subagents.mjs +609 -0
  154. package/src/core/swarm_topology.mjs +360 -0
  155. package/src/core/task_quota_router.mjs +1656 -0
  156. package/src/core/telemetry/cache_ttl_watchdog.mjs +284 -0
  157. package/src/core/telemetry/scope_lock_registry.mjs +578 -0
  158. package/src/core/telemetry/shadow_file_detector.mjs +291 -0
  159. package/src/core/telemetry/trajectory_watcher.mjs +259 -0
  160. package/src/core/timeline_svg.mjs +236 -0
  161. package/src/core/tool_surgeon.mjs +305 -0
  162. package/src/core/trajectory_stitcher.mjs +645 -0
  163. package/src/core/u_shaped_optimizer.mjs +789 -0
  164. package/src/core/wal_hygiene.mjs +233 -0
  165. package/src/core-isomorphic/catalog/detectorCatalog.mjs +558 -0
  166. package/src/core-isomorphic/catalog/index.mjs +1 -0
  167. package/src/core-isomorphic/coach/cacheGravityRouter.mjs +1547 -0
  168. package/src/core-isomorphic/coach/microSkills.mjs +1 -0
  169. package/src/core-isomorphic/coach/promptHygieneGovernor.mjs +1 -0
  170. package/src/core-isomorphic/coach/repoCalibration.mjs +254 -0
  171. package/src/core-isomorphic/coach/resumeToolsetAuditor.mjs +321 -0
  172. package/src/core-isomorphic/coach/savedQuotaLedger.mjs +527 -0
  173. package/src/core-isomorphic/coach/smartCompactAdvisor.mjs +305 -0
  174. package/src/core-isomorphic/coach/stateBatonHydrator.mjs +810 -0
  175. package/src/core-isomorphic/coach/ttlWatchdog.mjs +464 -0
  176. package/src/core-isomorphic/config/anthropicModelCatalog.json +606 -0
  177. package/src/core-isomorphic/config/catalogLoader.mjs +1268 -0
  178. package/src/core-isomorphic/config/horizonConfig.mjs +1055 -0
  179. package/src/core-isomorphic/control/callTree.mjs +338 -0
  180. package/src/core-isomorphic/control/coachLatches.mjs +126 -0
  181. package/src/core-isomorphic/control/controlStateMachine.mjs +205 -0
  182. package/src/core-isomorphic/control/index.mjs +49 -0
  183. package/src/core-isomorphic/control/swarmWorktree.mjs +109 -0
  184. package/src/core-isomorphic/control/toolSuspension.mjs +197 -0
  185. package/src/core-isomorphic/diagnostics/drift_guard.mjs +382 -0
  186. package/src/core-isomorphic/diagnostics/index.mjs +9 -0
  187. package/src/core-isomorphic/diagnostics/micro_skills.mjs +471 -0
  188. package/src/core-isomorphic/diagnostics/prompt_hygiene_governor.mjs +888 -0
  189. package/src/core-isomorphic/economics/billingBlocks.mjs +251 -0
  190. package/src/core-isomorphic/economics/cacheGravity.mjs +369 -0
  191. package/src/core-isomorphic/economics/cliffBreaker.mjs +256 -0
  192. package/src/core-isomorphic/economics/driftLatency.mjs +433 -0
  193. package/src/core-isomorphic/economics/dualTtl.mjs +198 -0
  194. package/src/core-isomorphic/economics/index.mjs +47 -0
  195. package/src/core-isomorphic/economics/retentionRadar.mjs +348 -0
  196. package/src/core-isomorphic/guards/bucketBAlphaBeta.mjs +860 -0
  197. package/src/core-isomorphic/guards/bucketBGamma.mjs +442 -0
  198. package/src/core-isomorphic/guards/bucketBHeuristics.mjs +37 -0
  199. package/src/core-isomorphic/guards/circuitBreakers.mjs +1202 -0
  200. package/src/core-isomorphic/guards/det01_03_shell_secret.mjs +1184 -0
  201. package/src/core-isomorphic/guards/det04_12_thrash_rot.mjs +572 -0
  202. package/src/core-isomorphic/guards/det13_20_mcp_scope.mjs +913 -0
  203. package/src/core-isomorphic/guards/docIndexCore.mjs +446 -0
  204. package/src/core-isomorphic/guards/losslessPostSanitizer.mjs +317 -0
  205. package/src/core-isomorphic/guards/slopsquatGate.mjs +551 -0
  206. package/src/core-isomorphic/index.js +27 -0
  207. package/src/core-isomorphic/telemetry/otelExporter.mjs +187 -0
  208. package/src/core-isomorphic/telemetry/scopeLockRegistry.mjs +522 -0
  209. package/src/core-isomorphic/telemetry/sprintMetrics.mjs +327 -0
  210. package/src/core-isomorphic/telemetry/swarmTopology.mjs +152 -0
  211. package/src/core-isomorphic/telemetry/telemetryBridge.mjs +1156 -0
  212. package/src/core-isomorphic/ui/brailleSparkline.mjs +142 -0
  213. package/src/core-isomorphic/ui/costRadarSvg.mjs +276 -0
  214. package/src/core-isomorphic/ui/horizonGrid.mjs +475 -0
  215. package/src/core-isomorphic/ui/horizonPanelHtml.mjs +1237 -0
  216. package/src/core-isomorphic/ui/modViews.mjs +1504 -0
  217. package/src/core-isomorphic/ui/pdfReceiptGenerator.mjs +329 -0
  218. package/src/core-isomorphic/ustf/index.mjs +7 -0
  219. package/src/core-isomorphic/ustf/normalizer.mjs +512 -0
  220. package/src/core-isomorphic/ustf/schema.mjs +186 -0
  221. package/src/core-isomorphic/utils/runtime.mjs +962 -0
  222. package/src/demo/synthetic_states.mjs +661 -0
  223. package/src/diagnostics/bugReportGenerator.mjs +253 -0
  224. package/src/diagnostics/claudeHookCapabilities.mjs +396 -0
  225. package/src/diagnostics/doctorEngine.mjs +295 -0
  226. package/src/engine-node/db/index.mjs +58 -0
  227. package/src/engine-node/db/jsonl_fallback.mjs +184 -0
  228. package/src/engine-node/db/probe.mjs +342 -0
  229. package/src/engine-node/db/sqlite_wrapper.mjs +122 -0
  230. package/src/engine-node/index.mjs +12 -0
  231. package/src/engine-node/ipc/client.mjs +447 -0
  232. package/src/engine-node/ipc/index.mjs +22 -0
  233. package/src/engine-node/ipc/protocol.mjs +177 -0
  234. package/src/engine-node/ipc/server.mjs +445 -0
  235. package/src/engine-node/offloader/index.mjs +6 -0
  236. package/src/engine-node/offloader/tool_offloader.mjs +241 -0
  237. package/src/engine-node/sensors/blindspots.mjs +376 -0
  238. package/src/engine-node/sensors/git_merge_tree.mjs +223 -0
  239. package/src/engine-node/sensors/index.mjs +7 -0
  240. package/src/hooks/antigravity_rsl_hook.mjs +250 -0
  241. package/src/hooks/claude_rsl_hook.mjs +288 -0
  242. package/src/hooks/portfolio_runtime.mjs +858 -0
  243. package/src/hooks/post_invocation.mjs +611 -0
  244. package/src/hooks/pre_invocation.mjs +1725 -0
  245. package/src/hooks/session_start.mjs +199 -0
  246. package/src/shims/agy_cli_compressor.mjs +705 -0
  247. package/src/shims/agy_git_guard.mjs +749 -0
  248. package/src/shims/ah_log_query.mjs +39 -0
  249. package/src/ui/costRadarSvg.mjs +6 -0
  250. package/src/ui/horizonGrid.mjs +1 -0
  251. package/src/ui/horizonPanelHtml.mjs +1 -0
  252. package/src/ui/horizon_panel.css +167 -0
  253. package/src/ui/horizon_panel.js +212 -0
  254. package/src/ui/modViews.mjs +1 -0
  255. package/src/utils/modelSwitchTelemetry.mjs +308 -0
  256. package/src/utils/nodeIo.mjs +59 -0
  257. package/src/utils/runtime.mjs +1 -0
  258. package/src/utils/sessionCalibration.mjs +657 -0
  259. package/src/webview/advanced_view.html +1808 -0
  260. package/src/webview/horizon_panel.html +12397 -0
  261. package/src/webview/registry.mjs +80 -0
  262. package/src/webview/simple_view.html +1370 -0
@@ -0,0 +1,1860 @@
1
+ import fs from 'node:fs';
2
+ import path from 'node:path';
3
+ import crypto from 'node:crypto';
4
+ import { getHomeDir } from './paths.mjs';
5
+ import { atomicWriteFileSync } from './atomic_io.mjs';
6
+ import {
7
+ EFFORT_PROFILES,
8
+ normalizeModelId,
9
+ resolveModelDescriptor,
10
+ resolveModelRates,
11
+ formatAgentCacheKey,
12
+ formatAgentStreamKey,
13
+ parseAgentCacheKey
14
+ } from './constants.mjs';
15
+ import { parseSettingsChanges } from './parser.mjs';
16
+ import { computePrefixRetentionIndex, computeThinkingDrift } from './sprint_metrics.mjs';
17
+
18
+ export { formatAgentCacheKey, formatAgentStreamKey, parseAgentCacheKey };
19
+
20
+ /**
21
+ * 5-minute ephemeral cache session read-to-write ratio threshold (`1.25 / 0.90 ≈ 1.39`).
22
+ * Below 1.39 cached reads per 5m cache write token in a churning session, cache-creation
23
+ * overhead erodes practical session cache ROI.
24
+ */
25
+ export const SESSION_5M_READ_TO_WRITE_MIN_ROI_RATIO = 1.39;
26
+
27
+ /**
28
+ * Resolves the canonical `agent_id` for a step or turn, defaulting to `"primary"`
29
+ * when absent in single-agent Claude Code or Antigravity CLI payloads.
30
+ */
31
+ export function resolveStepAgentId(stepOrTurn = {}) {
32
+ const raw = stepOrTurn?.agent_id ?? stepOrTurn?.agentId ?? stepOrTurn?.senderId ?? null;
33
+ if (!raw) return 'primary';
34
+ const s = String(raw).trim();
35
+ if (!s || s.toLowerCase() === 'parent' || s.toLowerCase() === 'main') return 'primary';
36
+ return s;
37
+ }
38
+
39
+ /**
40
+ * Phase 3.2: Antigravity Turn-Boundary Model Switch Buffer.
41
+ *
42
+ * When a model change is detected mid-turn in Antigravity, records `pending_model_id`
43
+ * without mutating `active_model_id` for in-flight tool steps.
44
+ * Promotes `pending_model_id -> active_model_id` only on turn completion (`PostInvocation` or `Stop`).
45
+ */
46
+ export class TurnBoundaryModelSwitchBuffer {
47
+ constructor(initialModelId = 'gemini-4-carbon') {
48
+ this.streams = new Map();
49
+ this.defaultModelId = normalizeModelId(initialModelId || 'gemini-4-carbon');
50
+ }
51
+
52
+ _getOrCreate(sessionId = 'default_session', agentId = 'primary', initialModel = null) {
53
+ const key = formatAgentStreamKey(sessionId, agentId);
54
+ if (!this.streams.has(key)) {
55
+ this.streams.set(key, {
56
+ session_id: String(sessionId || 'default_session'),
57
+ agent_id: resolveStepAgentId({ agent_id: agentId }),
58
+ active_model_id: normalizeModelId(initialModel || this.defaultModelId),
59
+ pending_model_id: null,
60
+ switch_history: []
61
+ });
62
+ }
63
+ return this.streams.get(key);
64
+ }
65
+
66
+ getState(sessionId = 'default_session', agentId = 'primary') {
67
+ const st = this._getOrCreate(sessionId, agentId);
68
+ return { ...st, switch_history: [...st.switch_history] };
69
+ }
70
+
71
+ getActiveModelForStep(sessionId = 'default_session', agentId = 'primary') {
72
+ return this._getOrCreate(sessionId, agentId).active_model_id;
73
+ }
74
+
75
+ recordMidTurnModelChange(newModelId, options = {}) {
76
+ return this.recordModelSwitch(newModelId, { ...options, eventType: options.eventType || 'PreToolUse', inFlight: true });
77
+ }
78
+
79
+ onTurnBoundary(eventTypeOrOptions = 'PostInvocation', maybeOptions = {}) {
80
+ const opts = typeof eventTypeOrOptions === 'string'
81
+ ? { ...maybeOptions, eventType: eventTypeOrOptions }
82
+ : (eventTypeOrOptions || {});
83
+ return this.promoteOnTurnCompletion(opts);
84
+ }
85
+
86
+ /**
87
+ * Buffers a mid-turn model switch in `pending_model_id` while tool calls are in-flight,
88
+ * or promotes immediately only if the event is already `PostInvocation` or `Stop`.
89
+ */
90
+ recordModelSwitch(newModelId, {
91
+ sessionId = 'default_session',
92
+ agentId = 'primary',
93
+ eventType = 'PreToolUse',
94
+ inFlight = true,
95
+ timestampMs = Date.now()
96
+ } = {}) {
97
+ const st = this._getOrCreate(sessionId, agentId);
98
+ const normNew = normalizeModelId(newModelId);
99
+ if (!normNew || normNew === st.active_model_id) {
100
+ return this.getState(sessionId, agentId);
101
+ }
102
+
103
+ const isTurnCompletionBoundary =
104
+ eventType === 'PostInvocation' ||
105
+ eventType === 'Stop' ||
106
+ inFlight === false;
107
+
108
+ if (isTurnCompletionBoundary) {
109
+ const prev = st.active_model_id;
110
+ st.active_model_id = normNew;
111
+ st.pending_model_id = null;
112
+ st.switch_history.push({
113
+ from_model_id: prev,
114
+ to_model_id: normNew,
115
+ promoted_on: eventType,
116
+ timestampMs
117
+ });
118
+ } else {
119
+ st.pending_model_id = normNew;
120
+ }
121
+
122
+ return this.getState(sessionId, agentId);
123
+ }
124
+
125
+ /**
126
+ * Promotes `pending_model_id -> active_model_id` on turn completion (`PostInvocation` or `Stop`).
127
+ */
128
+ promoteOnTurnCompletion({
129
+ sessionId = 'default_session',
130
+ agentId = 'primary',
131
+ eventType = 'PostInvocation',
132
+ timestampMs = Date.now()
133
+ } = {}) {
134
+ const st = this._getOrCreate(sessionId, agentId);
135
+ if (eventType !== 'PostInvocation' && eventType !== 'Stop') {
136
+ return { promoted: false, ...this.getState(sessionId, agentId) };
137
+ }
138
+ if (!st.pending_model_id) {
139
+ return { promoted: false, ...this.getState(sessionId, agentId) };
140
+ }
141
+ const prev = st.active_model_id;
142
+ const promotedModel = st.pending_model_id;
143
+ st.active_model_id = promotedModel;
144
+ st.pending_model_id = null;
145
+ st.switch_history.push({
146
+ from_model_id: prev,
147
+ to_model_id: promotedModel,
148
+ promoted_on: eventType,
149
+ timestampMs
150
+ });
151
+ return {
152
+ promoted: true,
153
+ from_model_id: prev,
154
+ to_model_id: promotedModel,
155
+ ...this.getState(sessionId, agentId)
156
+ };
157
+ }
158
+ }
159
+
160
+ /**
161
+ * Dual-Pool Quota Estimator (5-Hour Sprint / 7-Day Weekly),
162
+ * Pool Reset Countdown Formatter, Prefix Bust Detector &
163
+ * Cache-Read Telemetry Engine.
164
+ */
165
+
166
+ export const QUOTA_CONSTANTS = Object.freeze({
167
+ SPRINT_WINDOW_MS: 5 * 60 * 60 * 1000, // 5 hours
168
+ WEEKLY_WINDOW_MS: 7 * 24 * 60 * 60 * 1000, // 7 days
169
+ DEFAULT_SPRINT_POOL_UNITS: 5000000, // ~5M weighted token units per 5h window
170
+ WEEKLY_TO_SPRINT_RATIO: 2.8, // 2.33x to 3.5x empirical Pro ratio
171
+ DEFAULT_WEEKLY_POOL_UNITS: 14000000, // 2.8 * 5M
172
+ CACHE_TTL_SECONDS: 300, // 5-minute prompt prefix cache TTL
173
+ TTL_PULSE_THRESHOLD_SECONDS: 45, // T-45s visual expiration pulse threshold
174
+ CACHE_READ_WEIGHT: 0.10,
175
+ UNCACHED_INPUT_WEIGHT: 1.00,
176
+ OUTPUT_THINKING_WEIGHT: 3.00
177
+ });
178
+
179
+ export const OVERAGE_ALERT_MESSAGES = Object.freeze({
180
+ LOCKOUT_ALERT: '7d Quota Exhausted. Enable AI Credit Overages in Settings > Models to prevent session lockout.',
181
+ OVERAGES_ACTIVE_VISION_WARN: 'Overages Active. Do NOT attach images or screenshots (known upstream HTTP 400 Bad Request bug on overage calls).',
182
+ PREFIX_BUST_LABEL: '⚠️ Prefix Bust (system_message / config drift)'
183
+ });
184
+
185
+ /**
186
+ * Formats a reset countdown in seconds into "3h 12m" (<24h) or "4d 18h" (>=24h).
187
+ */
188
+ export function formatResetCountdown(resetSeconds) {
189
+ const sec = Math.max(0, Math.round(Number(resetSeconds || 0)));
190
+ if (sec <= 0) return '0m';
191
+ const totalMinutes = Math.max(1, Math.floor(sec / 60));
192
+ const days = Math.floor(totalMinutes / (60 * 24));
193
+ if (days >= 1) {
194
+ const remHours = Math.floor((totalMinutes % (60 * 24)) / 60);
195
+ return `${days}d ${remHours}h`;
196
+ }
197
+ const hours = Math.floor(totalMinutes / 60);
198
+ const mins = totalMinutes % 60;
199
+ if (hours >= 1) {
200
+ return `${hours}h ${mins}m`;
201
+ }
202
+ return `${mins}m`;
203
+ }
204
+
205
+ /**
206
+ * Maps a raw model ID to a human-readable Antigravity quota pool name.
207
+ */
208
+ export function resolveModelPoolDisplayName(modelId = 'gemini-3.8-flash') {
209
+ const s = normalizeModelId(modelId);
210
+ if (s.includes('gemini-4-carbon-cyber-permissive')) return 'Gemini 4 Carbon (Cyber Permissive)';
211
+ if (s.includes('gemini-4-carbon') || s.includes('carbon')) return 'Gemini 4 Carbon';
212
+ if (s.includes('gemini-4-argon') || s.includes('argon')) return 'Gemini 4 Argon';
213
+ if (s.includes('gemini-3.8-flash') || s.includes('3.8-flash')) return 'Gemini 3.8 Flash';
214
+ if (s.includes('gemini-3.1-pro') || s.includes('3.1-pro')) return 'Gemini 3.1 Pro';
215
+ if (s.includes('claude-fable-5-2') || s.includes('fable-5-2') || s.includes('fable-5.2')) return 'Claude Fable 5.2';
216
+ if (s.includes('claude-fable-5-1') || s.includes('fable-5-1') || s.includes('fable-5.1')) return 'Claude Fable 5.1';
217
+ if (s.includes('claude-opus-5') || s.includes('opus-5')) return 'Claude Opus 5.5';
218
+ if (s.includes('claude-sonnet-5') || s.includes('sonnet-5')) return 'Claude Sonnet 5.5';
219
+ if (s.includes('claude-haiku-5') || s.includes('haiku-5')) return 'Claude Haiku 5.5';
220
+ if (s.includes('claude-opus-4-5') || s.includes('opus-4.5') || s.includes('opus-4-5')) return 'Claude Opus 4.5';
221
+ if (s.includes('claude-opus-4') || s.includes('opus-4')) return 'Claude Opus 4.6';
222
+ if (s.includes('claude-sonnet-4-5') || s.includes('sonnet-4.5') || s.includes('sonnet-4-5')) return 'Claude Sonnet 4.5';
223
+ if (s.includes('claude-sonnet-4') || s.includes('sonnet-4')) return 'Claude Sonnet 4.6';
224
+ if (s.includes('claude-haiku-4') || s.includes('haiku-4')) return 'Claude Haiku 4.5';
225
+ if (s.includes('claude-3-5-sonnet') || s.includes('sonnet')) return 'Claude Sonnet';
226
+ if (s.includes('gpt-oss')) return 'GPT-OSS 120B';
227
+ if (s.includes('flash')) return 'Gemini Flash';
228
+ return 'Gemini 4 Argon';
229
+ }
230
+
231
+ function getLedgerPath(cacheDir = null) {
232
+ const dir = cacheDir || path.join(getHomeDir(), '.gemini', 'antigravity', 'cache', 'agy-horizon');
233
+ return path.join(dir, 'quota_ledger.json');
234
+ }
235
+
236
+ export function loadQuotaLedger(cacheDir = null) {
237
+ const file = getLedgerPath(cacheDir);
238
+ try {
239
+ if (fs.existsSync(file)) {
240
+ const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
241
+ if (parsed && typeof parsed.sessions === 'object') return parsed;
242
+ }
243
+ } catch (err) {
244
+ // Corrupt or unreadable ledger: fall back to an empty rolling ledger (rebuilt on next save).
245
+ if (process.env.HORIZON_DEBUG) console.error('[quota] ledger read failed:', err?.message || err);
246
+ }
247
+ return { schemaRev: 1, sessions: {} };
248
+ }
249
+
250
+ export function saveQuotaLedger(ledger, cacheDir = null) {
251
+ try {
252
+ const file = getLedgerPath(cacheDir);
253
+ atomicWriteFileSync(file, JSON.stringify(ledger));
254
+ } catch (err) {
255
+ // Non-fatal: quota pacing still renders from in-memory telemetry this turn.
256
+ if (process.env.HORIZON_DEBUG) console.error('[quota] ledger write failed:', err?.message || err);
257
+ }
258
+ }
259
+
260
+ /**
261
+ * Detects whether a step or its immediately preceding step contained an explicit
262
+ * prefix-invalidating event (<USER_SETTINGS_CHANGE>, <system_message>, model/effort
263
+ * switch, or an edit to AGENTS.md / .agents/rules/ / mcp_config.json).
264
+ */
265
+ export function hasExplicitPrefixMutation(step = {}, prevStep = null) {
266
+ // Only genuine user/system turns can carry a settings change or system message.
267
+ // Tool output, code views, and planner text that merely *mention* the tags are ignored.
268
+ const isUserOrSystemStep = (st) => {
269
+ const t = String(st?.type || '').toUpperCase();
270
+ return t === 'USER_INPUT' || t.startsWith('SYSTEM');
271
+ };
272
+ const checkText = (st) => {
273
+ if (!isUserOrSystemStep(st)) return false;
274
+ const txt = String(st?.content || '');
275
+ return /<USER_SETTINGS_CHANGE>|<system_message>/i.test(txt);
276
+ };
277
+ const checkToolEdit = (st) => {
278
+ for (const c of (st?.toolCalls || [])) {
279
+ if (!/write|edit|replace|create/i.test(String(c?.name || ''))) continue;
280
+ const p = String(c?.args?.Path || c?.args?.path || c?.args?.TargetFile || c?.args?.AbsolutePath || '');
281
+ if (/(^|[\\/])(AGENTS\.md|mcp_config\.json)$|[\\/]\.agents[\\/]rules[\\/]/i.test(p)) {
282
+ return true;
283
+ }
284
+ }
285
+ return false;
286
+ };
287
+ if (checkText(step) || checkToolEdit(step)) return true;
288
+ if (prevStep && (checkText(prevStep) || checkToolEdit(prevStep))) return true;
289
+ if (prevStep?.model && step?.model && prevStep.model !== step.model) return true;
290
+ if (prevStep?.effort && step?.effort && prevStep.effort !== step.effort) return true;
291
+ return false;
292
+ }
293
+
294
+ /**
295
+ * attributes a prefix bust to a model switch when the busting step (or the step
296
+ * just before it) is a USER_INPUT carrying a `Model Selection` settings change, or when
297
+ * consecutive steps carry different model ids.
298
+ */
299
+ export function detectModelSwitchCause(step = {}, prevStep = null) {
300
+ for (const st of [step, prevStep]) {
301
+ if (!st || String(st.type || '').toUpperCase() !== 'USER_INPUT') continue;
302
+ const changes = parseSettingsChanges(String(st.content || '')).filter(c => /model selection/i.test(c.setting));
303
+ if (changes.length > 0) {
304
+ const last = changes[changes.length - 1];
305
+ return { cause: 'model_switch', from: last.from, to: last.to };
306
+ }
307
+ }
308
+ if (prevStep?.model && step?.model && prevStep.model !== step.model) {
309
+ return { cause: 'model_switch', from: prevStep.model, to: step.model };
310
+ }
311
+ return null;
312
+ }
313
+
314
+ /**
315
+ * Human-readable label for a model id ("claude-opus-5.5" -> "Claude Opus 5.5").
316
+ * Already-readable labels ("Claude Opus 5.5 (Medium)") are returned without the effort suffix.
317
+ */
318
+ export function humanizeModelLabel(model = '') {
319
+ const raw = String(model || '').trim();
320
+ if (!raw) return '';
321
+ const noEffort = raw.replace(/\s*\([^()]*\)\s*$/, '');
322
+ if (/[A-Z ]/.test(noEffort)) return noEffort;
323
+ return noEffort.split('-').map(w => (/^\d/.test(w) ? w : w.charAt(0).toUpperCase() + w.slice(1))).join(' ');
324
+ }
325
+
326
+ /**
327
+ * Maps a raw model ID to a concise human-readable short name.
328
+ * e.g. "gemini-4-argon" -> "Argon", "gemini-3.8-flash" -> "Flash".
329
+ */
330
+ export function resolveModelShortName(modelId = '') {
331
+ const s = normalizeModelId(String(modelId || ''));
332
+ if (s.includes('carbon')) return 'Carbon';
333
+ if (s.includes('argon')) return 'Argon';
334
+ if (s.includes('3.8-flash') || s.includes('flash')) return 'Flash';
335
+ if (s.includes('3.1-pro') || s.includes('pro')) return 'Pro';
336
+ if (s.includes('fable-5-2') || s.includes('fable-5.2')) return 'Fable 5.2';
337
+ if (s.includes('fable-5-1') || s.includes('fable-5.1') || s.includes('fable')) return 'Fable 5.1';
338
+ if (s.includes('opus-5')) return 'Opus 5.5';
339
+ if (s.includes('opus-4-5') || s.includes('opus-4.5')) return 'Opus 4.5';
340
+ if (s.includes('opus')) return 'Opus 4.6';
341
+ if (s.includes('sonnet-5')) return 'Sonnet 5.5';
342
+ if (s.includes('sonnet-4-5') || s.includes('sonnet-4.5')) return 'Sonnet 4.5';
343
+ if (s.includes('sonnet')) return 'Sonnet 4.6';
344
+ if (s.includes('haiku-5')) return 'Haiku 5.5';
345
+ if (s.includes('haiku')) return 'Haiku 4.5';
346
+ if (s.includes('gpt-oss')) return 'GPT-OSS';
347
+ const human = humanizeModelLabel(modelId);
348
+ return human ? human.split(' ').pop() : 'Model';
349
+ }
350
+
351
+ /**
352
+ * Computes exact multi-rate USD cache ROI and 5-minute session read-to-write churn diagnostics.
353
+ * Single-write algebraic break-even is `(writeRate - inputRate) / (inputRate - cachedReadRate)`
354
+ * (`~0.2632` at 95% discount, `~0.2778` at 90% discount for 5m `1.25x` writes), while
355
+ * churning 5m sessions require `readToWriteRatio >= 1.39` (`1.25 / 0.90`) for sustained healthy ROI.
356
+ */
357
+ export function computeCacheRoi({
358
+ cacheReadTokens = 0,
359
+ write5mTokens = 0,
360
+ write1hTokens = 0,
361
+ cacheCreationTokens = 0,
362
+ uncachedInputTokens = 0,
363
+ outputTokens = 0,
364
+ modelId = 'claude-sonnet-5-5',
365
+ eventTimestampUtc = null,
366
+ serviceTier = 'standard',
367
+ totalPromptTokens = null
368
+ } = {}) {
369
+ const readTok = Math.max(0, Number(cacheReadTokens) || 0);
370
+ const rawW5m = Math.max(0, Number(write5mTokens) || 0);
371
+ const rawW1h = Math.max(0, Number(write1hTokens) || 0);
372
+ const rawCreate = Math.max(0, Number(cacheCreationTokens) || 0);
373
+ const uncachedTok = Math.max(0, Number(uncachedInputTokens) || 0);
374
+ const outTok = Math.max(0, Number(outputTokens) || 0);
375
+
376
+ const effWrite1h = rawW1h;
377
+ const effWrite5m = (rawW5m > 0 || rawW1h > 0) ? rawW5m : rawCreate;
378
+ const totalWriteTokens = effWrite5m + effWrite1h;
379
+ const promptEnvelope = totalPromptTokens !== null && totalPromptTokens !== undefined
380
+ ? Math.max(0, Number(totalPromptTokens) || 0)
381
+ : (uncachedTok + readTok + totalWriteTokens);
382
+
383
+ const rates = resolveModelRates(modelId, eventTimestampUtc, serviceTier, {
384
+ totalPromptTokens: promptEnvelope
385
+ });
386
+
387
+ const write5mRate = rates.write5m > 0 ? rates.write5m : rates.input;
388
+ const write1hRate = rates.write1h > 0 ? rates.write1h : rates.input;
389
+ const hasExplicitWriteSurcharge = write5mRate > rates.input || write1hRate > rates.input;
390
+
391
+ const writePremiumUsd =
392
+ ((effWrite5m / 1_000_000) * Math.max(0, write5mRate - rates.input)) +
393
+ ((effWrite1h / 1_000_000) * Math.max(0, write1hRate - rates.input));
394
+ const readDiscountSavingsUsd =
395
+ (readTok / 1_000_000) * Math.max(0, rates.input - rates.cachedRead);
396
+ const netCacheSavingsUsd = Number((readDiscountSavingsUsd - writePremiumUsd).toFixed(6));
397
+
398
+ const actualCacheCostUsd = Number((
399
+ ((uncachedTok / 1_000_000) * rates.input) +
400
+ ((effWrite5m / 1_000_000) * write5mRate) +
401
+ ((effWrite1h / 1_000_000) * write1hRate) +
402
+ ((readTok / 1_000_000) * rates.cachedRead) +
403
+ ((outTok / 1_000_000) * rates.output)
404
+ ).toFixed(6));
405
+
406
+ const uncachedBaselineUsd = Number((
407
+ (((uncachedTok + totalWriteTokens + readTok) / 1_000_000) * rates.input) +
408
+ ((outTok / 1_000_000) * rates.output)
409
+ ).toFixed(6));
410
+
411
+ const readToWriteRatio = totalWriteTokens > 0
412
+ ? Number((readTok / totalWriteTokens).toFixed(4))
413
+ : (readTok > 0 ? null : 0);
414
+
415
+ const avgWriteRate = totalWriteTokens > 0
416
+ ? ((effWrite5m * write5mRate + effWrite1h * write1hRate) / totalWriteTokens)
417
+ : write5mRate;
418
+ const singleWriteBreakEvenRatio = (avgWriteRate > rates.input && rates.input > rates.cachedRead)
419
+ ? Number(((avgWriteRate - rates.input) / (rates.input - rates.cachedRead)).toFixed(4))
420
+ : 0;
421
+
422
+ const belowSessionRoiThreshold = totalWriteTokens > 0 &&
423
+ (readTok / totalWriteTokens) < SESSION_5M_READ_TO_WRITE_MIN_ROI_RATIO;
424
+ const isNetUsdNegative = netCacheSavingsUsd < 0;
425
+ const isNegativeCacheRoi = isNetUsdNegative || (hasExplicitWriteSurcharge && belowSessionRoiThreshold);
426
+
427
+ return {
428
+ rates: {
429
+ input: rates.input,
430
+ output: rates.output,
431
+ write5m: rates.write5m,
432
+ write1h: rates.write1h,
433
+ cachedRead: rates.cachedRead,
434
+ isAbovePromptCliff: Boolean(rates.isAbovePromptCliff)
435
+ },
436
+ cacheReadTokens: readTok,
437
+ write5mTokens: effWrite5m,
438
+ write1hTokens: effWrite1h,
439
+ totalWriteTokens,
440
+ readToWriteRatio,
441
+ singleWriteBreakEvenRatio,
442
+ minSessionReadToWriteRatio: SESSION_5M_READ_TO_WRITE_MIN_ROI_RATIO,
443
+ belowSessionRoiThreshold,
444
+ writePremiumUsd: Number(writePremiumUsd.toFixed(6)),
445
+ readDiscountSavingsUsd: Number(readDiscountSavingsUsd.toFixed(6)),
446
+ netCacheSavingsUsd,
447
+ actualCacheCostUsd,
448
+ uncachedBaselineUsd,
449
+ isNetUsdNegative,
450
+ isNegativeCacheRoi
451
+ };
452
+ }
453
+
454
+ /**
455
+ * Formats a token count into a compact string ("140k", "3.7k").
456
+ */
457
+ export function formatK(num) {
458
+ const n = Number(num || 0);
459
+ if (n <= 0) return '0k';
460
+ if (n < 1000) return `${Math.round(n)}`;
461
+ const k = n / 1000;
462
+ return k >= 10 ? `${Math.round(k)}k` : `${parseFloat(k.toFixed(1))}k`;
463
+ }
464
+
465
+ /**
466
+ * Prefix Bust label. A known model-switch cause gets a plain-language amber label; an unknown
467
+ * cause keeps the legacy label.
468
+ */
469
+ export function formatPrefixBustLabel(cause = null) {
470
+ if (cause && cause.cause === 'auto_router_thrash') {
471
+ return cause.badgeText || `\u26A0\uFE0F Router Thrash: ${cause.switchCount} model hops`;
472
+ }
473
+ if (cause && cause.cause === 'model_switch' && cause.to) {
474
+ return `Last turn: cache miss (model switch \u2192 ${humanizeModelLabel(cause.to)})`;
475
+ }
476
+ if (cause && cause.cause === 'warm_pool_busted') {
477
+ return cause.reason === 'RULE_FILE_DRIFT'
478
+ ? '\u26A0\uFE0F Prefix Bust (system_message / config drift)'
479
+ : '\u26A0\uFE0F Prefix Bust (history mutation)';
480
+ }
481
+ return OVERAGE_ALERT_MESSAGES.PREFIX_BUST_LABEL;
482
+ }
483
+
484
+ /**
485
+ * Pure, deterministic tracker for per-model and composite (`${session_id}::${agent_id}::${model_id}`) KV cache pools.
486
+ * Scopes model-switch detection strictly within the same `(session_id, agent_id)` stream so parallel
487
+ * `/swarm` and `/teamwork` agents never cross-contaminate each other's cache baselines.
488
+ */
489
+ export function trackModelCachePools(turns = [], {
490
+ sessionId = 'default_session',
491
+ nowMs = Date.now(),
492
+ prefixDiff = null
493
+ } = {}) {
494
+ const modelCachePools = new Map();
495
+ const compositeCachePools = new Map();
496
+ const prevTurnByStream = new Map();
497
+ let standbyCache = null;
498
+ let lastSwitchEvent = null;
499
+
500
+ for (let i = 0; i < turns.length; i++) {
501
+ const turn = turns[i];
502
+ const turnSessionId = String(turn.session_id || turn.sessionId || sessionId || 'default_session');
503
+ const agentId = resolveStepAgentId(turn);
504
+ const streamKey = formatAgentStreamKey(turnSessionId, agentId);
505
+ const prevTurn = prevTurnByStream.get(streamKey) || null;
506
+
507
+ const mId = normalizeModelId(turn.active_model_id || turn.modelId || turn.model || 'gemini-4-argon');
508
+ const compositeKey = formatAgentCacheKey(turnSessionId, agentId, mId);
509
+ const shortName = resolveModelShortName(turn.modelRaw || turn.model || mId);
510
+ const displayName = resolveModelPoolDisplayName(mId);
511
+ const ts = turn.timestampMs || (turn.createdAt ? Date.parse(turn.createdAt) : nowMs);
512
+ const ttlWindow = Number(turn.ttlSeconds || QUOTA_CONSTANTS.CACHE_TTL_SECONDS);
513
+
514
+ const prevMId = prevTurn
515
+ ? normalizeModelId(prevTurn.active_model_id || prevTurn.modelId || prevTurn.model || 'gemini-4-argon')
516
+ : null;
517
+ const prevCompositeKey = prevTurn ? formatAgentCacheKey(turnSessionId, agentId, prevMId) : null;
518
+ const isModelSwitch = Boolean(prevTurn && prevMId && prevMId !== mId);
519
+
520
+ // Update remaining TTL for all existing pools up to this turn
521
+ for (const pool of compositeCachePools.values()) {
522
+ const elapsedSec = Math.max(0, Math.floor((ts - pool.lastSeenTimestampMs) / 1000));
523
+ pool.remainingTtl = Math.max(0, pool.ttlSecondsAtLastTurn - elapsedSec);
524
+ pool.isWarm = pool.remainingTtl > 0 && pool.lastCachedTokens > 0;
525
+ }
526
+ for (const pool of modelCachePools.values()) {
527
+ const elapsedSec = Math.max(0, Math.floor((ts - pool.lastSeenTimestampMs) / 1000));
528
+ pool.remainingTtl = Math.max(0, pool.ttlSecondsAtLastTurn - elapsedSec);
529
+ pool.isWarm = pool.remainingTtl > 0 && pool.lastCachedTokens > 0;
530
+ }
531
+
532
+ if (isModelSwitch) {
533
+ const modelA = compositeCachePools.get(prevCompositeKey) || modelCachePools.get(prevMId);
534
+ const modelB = compositeCachePools.get(compositeKey);
535
+
536
+ // Check if Model A still has remainingTtl > 30 and lastCachedTokens > 20000
537
+ if (modelA && modelA.remainingTtl > 30 && modelA.lastCachedTokens > 20000) {
538
+ standbyCache = {
539
+ modelName: modelA.shortName,
540
+ remainingTtl: modelA.remainingTtl,
541
+ cachedTokens: modelA.lastCachedTokens,
542
+ agentId
543
+ };
544
+ } else {
545
+ standbyCache = null;
546
+ }
547
+
548
+ // Check if Model B already had a warm entry in compositeCachePools for this agent that unexpectedly missed
549
+ let warmPoolBustedReason = null;
550
+ if (modelB && modelB.remainingTtl > 0 && Number(turn.cacheReadTokens || 0) === 0) {
551
+ const isRuleDrift = Boolean(turn.explicitMutation || prefixDiff?.mutated);
552
+ warmPoolBustedReason = isRuleDrift ? 'RULE_FILE_DRIFT' : 'HISTORY_MUTATION';
553
+ }
554
+
555
+ lastSwitchEvent = {
556
+ sessionId: turnSessionId,
557
+ agentId,
558
+ streamKey,
559
+ fromModelId: prevMId,
560
+ toModelId: mId,
561
+ fromShortName: resolveModelShortName(prevTurn.modelRaw || prevTurn.model || prevMId),
562
+ toShortName: shortName,
563
+ toDisplayName: displayName,
564
+ turnIndex: turn.stepIndex ?? i,
565
+ timestampMs: ts,
566
+ warmPoolBustedReason,
567
+ standbyCache: standbyCache ? { ...standbyCache } : null
568
+ };
569
+ }
570
+
571
+ const cachedTokens = turn.cacheReadTokens > 0
572
+ ? turn.cacheReadTokens
573
+ : (turn.cacheCreationTokens > 0 ? turn.cacheCreationTokens : (turn.cachedTokens || 0));
574
+
575
+ const existingComposite = compositeCachePools.get(compositeKey);
576
+ const poolEntry = {
577
+ compositeKey,
578
+ sessionId: turnSessionId,
579
+ agentId,
580
+ modelId: mId,
581
+ shortName,
582
+ displayName,
583
+ lastSeenTurnId: turn.stepIndex ?? i,
584
+ lastSeenTimestampMs: ts,
585
+ lastCachedTokens: cachedTokens > 0 ? cachedTokens : (existingComposite?.lastCachedTokens || 0),
586
+ lastPrefixHash: turn.prefixHash || existingComposite?.lastPrefixHash || '',
587
+ ttlSecondsAtLastTurn: ttlWindow,
588
+ remainingTtl: ttlWindow,
589
+ isWarm: cachedTokens > 0
590
+ };
591
+ compositeCachePools.set(compositeKey, poolEntry);
592
+ modelCachePools.set(mId, { ...poolEntry });
593
+ prevTurnByStream.set(streamKey, turn);
594
+ }
595
+
596
+ // Final evaluation of remaining TTL against nowMs
597
+ for (const pool of compositeCachePools.values()) {
598
+ const elapsedSec = Math.max(0, Math.floor((nowMs - pool.lastSeenTimestampMs) / 1000));
599
+ pool.remainingTtl = Math.max(0, pool.ttlSecondsAtLastTurn - elapsedSec);
600
+ pool.isWarm = pool.remainingTtl > 0 && pool.lastCachedTokens > 0;
601
+ }
602
+ for (const pool of modelCachePools.values()) {
603
+ const elapsedSec = Math.max(0, Math.floor((nowMs - pool.lastSeenTimestampMs) / 1000));
604
+ pool.remainingTtl = Math.max(0, pool.ttlSecondsAtLastTurn - elapsedSec);
605
+ pool.isWarm = pool.remainingTtl > 0 && pool.lastCachedTokens > 0;
606
+ }
607
+
608
+ if (standbyCache && lastSwitchEvent) {
609
+ const prevKey = formatAgentCacheKey(lastSwitchEvent.sessionId, lastSwitchEvent.agentId, lastSwitchEvent.fromModelId);
610
+ const modelA = compositeCachePools.get(prevKey) || modelCachePools.get(lastSwitchEvent.fromModelId);
611
+ if (modelA) {
612
+ standbyCache.remainingTtl = modelA.remainingTtl;
613
+ if (standbyCache.remainingTtl <= 0) {
614
+ standbyCache = null;
615
+ }
616
+ }
617
+ }
618
+
619
+ return {
620
+ modelCachePools,
621
+ compositeCachePools,
622
+ standbyCache,
623
+ lastSwitchEvent
624
+ };
625
+ }
626
+
627
+ /**
628
+ * Pure sliding-window (last 5 turns) Auto-Router Thrash and Model Switch detector.
629
+ * Scopes switch counting strictly within the same `(session_id, agent_id)` stream so multi-agent
630
+ * `/swarm` turns never trigger false-positive thrash alerts across distinct agents.
631
+ */
632
+ export function detectRouterThrash(recentTurns = [], isAutoMode = false, {
633
+ sessionId = 'default_session',
634
+ totalTokens = 0,
635
+ reclaimableTokens = 0,
636
+ standbyCache = null,
637
+ lastSwitchEvent = null
638
+ } = {}) {
639
+ if (!Array.isArray(recentTurns) || recentTurns.length === 0) {
640
+ return {
641
+ detected: false,
642
+ thrashDetected: false,
643
+ state: 'HEALTHY',
644
+ severity: 'none',
645
+ isAutoMode,
646
+ windowTurns: 0,
647
+ switchCount: 0,
648
+ thrashUncachedTokens: 0,
649
+ modelSequenceString: '',
650
+ modelsInvolved: [],
651
+ badgeText: '',
652
+ tooltip: '',
653
+ standbyNote: '',
654
+ preSwitchCompactionAdvice: ''
655
+ };
656
+ }
657
+
658
+ const windowTurns = recentTurns.slice(-5);
659
+ let switchCount = 0;
660
+ let thrashUncachedTokens = 0;
661
+ const lastModelByStream = new Map();
662
+
663
+ for (let i = 0; i < windowTurns.length; i++) {
664
+ const curr = windowTurns[i];
665
+ const tSid = String(curr.session_id || curr.sessionId || sessionId || 'default_session');
666
+ const aId = resolveStepAgentId(curr);
667
+ const streamKey = formatAgentStreamKey(tSid, aId);
668
+ const currM = normalizeModelId(curr.active_model_id || curr.modelId || curr.model || 'gemini-4-argon');
669
+ const prevM = lastModelByStream.get(streamKey);
670
+ if (prevM && currM !== prevM) {
671
+ switchCount++;
672
+ const uncached = Number(curr.inputTokens || 0) || Number(curr.uncachedInputTokens || 0) || Math.max(0, Number(curr.totalTokens || 0) - Number(curr.cacheReadTokens || 0));
673
+ thrashUncachedTokens += uncached;
674
+ }
675
+ lastModelByStream.set(streamKey, currM);
676
+ }
677
+
678
+ if (thrashUncachedTokens === 0 && switchCount > 0 && totalTokens > 0) {
679
+ thrashUncachedTokens = totalTokens * switchCount;
680
+ }
681
+
682
+ const seqShort = [];
683
+ for (const t of windowTurns) {
684
+ const sName = resolveModelShortName(t.modelRaw || t.model || t.modelId);
685
+ if (seqShort.length === 0 || seqShort[seqShort.length - 1] !== sName) {
686
+ seqShort.push(sName);
687
+ }
688
+ }
689
+ const modelSequenceString = seqShort.join(' \u2192 ');
690
+ const modelsInvolved = [...new Set(seqShort)];
691
+
692
+ const lastTurn = windowTurns[windowTurns.length - 1];
693
+ const lastTurnAgentId = lastTurn ? resolveStepAgentId(lastTurn) : 'primary';
694
+ const lastTurnSid = lastTurn ? String(lastTurn.session_id || lastTurn.sessionId || sessionId || 'default_session') : sessionId;
695
+ const lastStreamKey = formatAgentStreamKey(lastTurnSid, lastTurnAgentId);
696
+ let prevTurnSameStream = null;
697
+ for (let i = windowTurns.length - 2; i >= 0; i--) {
698
+ const candidate = windowTurns[i];
699
+ const cSid = String(candidate.session_id || candidate.sessionId || sessionId || 'default_session');
700
+ const cAid = resolveStepAgentId(candidate);
701
+ if (formatAgentStreamKey(cSid, cAid) === lastStreamKey) {
702
+ prevTurnSameStream = candidate;
703
+ break;
704
+ }
705
+ }
706
+ const isCurrentTurnSwitch = Boolean(
707
+ lastTurn && prevTurnSameStream &&
708
+ normalizeModelId(lastTurn.active_model_id || lastTurn.modelId || lastTurn.model || '') !==
709
+ normalizeModelId(prevTurnSameStream.active_model_id || prevTurnSameStream.modelId || prevTurnSameStream.model || '')
710
+ );
711
+ const currentShortName = lastTurn ? resolveModelShortName(lastTurn.modelRaw || lastTurn.model || lastTurn.modelId) : 'Model';
712
+ const currentDisplayName = lastTurn ? resolveModelPoolDisplayName(lastTurn.modelId || lastTurn.model) : 'Model';
713
+
714
+ const totalPrompt = Number(lastTurn?.cacheReadTokens || 0) + Number(lastTurn?.cacheCreationTokens || 0) + Number(lastTurn?.inputTokens || 0);
715
+ const cacheHitPct = totalPrompt > 0 ? (Number(lastTurn?.cacheReadTokens || 0) / totalPrompt) * 100 : 0;
716
+
717
+ // Case A: Router Thrashing (2+ switches in 5 turns in [Auto] mode)
718
+ if (switchCount >= 2 && isAutoMode) {
719
+ const badgeText = `\u26A0\uFE0F Router Thrash: ${switchCount} model hops (${formatK(thrashUncachedTokens)} uncached)`;
720
+ const tooltip = `Auto-routing is bouncing between models (${modelSequenceString}), paying full uncached prefill cost on every hop. Pin a single model or run /compact.`;
721
+ return {
722
+ detected: true,
723
+ thrashDetected: true,
724
+ state: 'AUTO_ROUTER_THRASH',
725
+ severity: 'warn',
726
+ isAutoMode,
727
+ windowTurns: windowTurns.length,
728
+ switchCount,
729
+ thrashUncachedTokens,
730
+ modelSequenceString,
731
+ modelsInvolved,
732
+ currentShortName,
733
+ currentDisplayName,
734
+ badgeText,
735
+ tooltip,
736
+ standbyNote: standbyCache ? `(${standbyCache.modelName} cache still warm: ${standbyCache.remainingTtl}s left)` : '',
737
+ preSwitchCompactionAdvice: ''
738
+ };
739
+ }
740
+
741
+ // Case B: Single Model Switch / Cold Start
742
+ const lastTurnMissedCache = Number(lastTurn?.cacheReadTokens || 0) === 0;
743
+ const isLastTurnSwitchEvent = Boolean(
744
+ lastSwitchEvent && lastTurn && (lastTurn.stepIndex ?? (recentTurns.length - 1)) === lastSwitchEvent.turnIndex
745
+ );
746
+ if ((isCurrentTurnSwitch || isLastTurnSwitchEvent) && lastTurnMissedCache) {
747
+ const severity = (isAutoMode && totalTokens >= 100000) ? 'warn' : 'info';
748
+ const badgeText = `Last turn: cache miss (model switch \u2192 ${currentShortName})`;
749
+ const standbyNote = standbyCache ? `(${standbyCache.modelName} cache still warm: ${standbyCache.remainingTtl}s left)` : '';
750
+ const tooltip = standbyCache
751
+ ? `Last turn missed prompt cache due to model switch \u2192 ${currentDisplayName}. (${standbyCache.modelName} cache still warm: ${standbyCache.remainingTtl}s left)`
752
+ : `Last turn missed prompt cache due to model switch \u2192 ${currentDisplayName}.`;
753
+
754
+ let preSwitchCompactionAdvice = '';
755
+ if (reclaimableTokens >= 40000) {
756
+ preSwitchCompactionAdvice = `Switching to ${currentShortName} forced a full ${formatK(totalTokens)} uncached rebuild (including ${formatK(reclaimableTokens)} of reclaimable waste). Tip: Run /compact before switching models so the incoming model only warms up active signal.`;
757
+ }
758
+
759
+ return {
760
+ detected: false,
761
+ thrashDetected: false,
762
+ state: 'MODEL_SWITCH_COLD_START',
763
+ severity,
764
+ isAutoMode,
765
+ windowTurns: windowTurns.length,
766
+ switchCount,
767
+ thrashUncachedTokens,
768
+ modelSequenceString,
769
+ modelsInvolved,
770
+ currentShortName,
771
+ currentDisplayName,
772
+ badgeText,
773
+ tooltip,
774
+ standbyNote,
775
+ preSwitchCompactionAdvice
776
+ };
777
+ }
778
+
779
+ // Case C: One-Turn Decay to Healthy
780
+ // When session stays on the same model and achieves cacheHit > 50% (or positive cacheReadTokens)
781
+ if (!isCurrentTurnSwitch && (cacheHitPct > 50 || Number(lastTurn?.cacheReadTokens || 0) > 0)) {
782
+ return {
783
+ detected: false,
784
+ thrashDetected: false,
785
+ state: 'HEALTHY',
786
+ severity: 'none',
787
+ isAutoMode,
788
+ windowTurns: windowTurns.length,
789
+ switchCount: 0,
790
+ thrashUncachedTokens: 0,
791
+ modelSequenceString,
792
+ modelsInvolved,
793
+ currentShortName,
794
+ currentDisplayName,
795
+ badgeText: '',
796
+ tooltip: '',
797
+ standbyNote: '',
798
+ preSwitchCompactionAdvice: ''
799
+ };
800
+ }
801
+
802
+ return {
803
+ detected: false,
804
+ thrashDetected: false,
805
+ state: 'HEALTHY',
806
+ severity: 'none',
807
+ isAutoMode,
808
+ windowTurns: windowTurns.length,
809
+ switchCount,
810
+ thrashUncachedTokens,
811
+ modelSequenceString,
812
+ modelsInvolved,
813
+ currentShortName,
814
+ currentDisplayName,
815
+ badgeText: '',
816
+ tooltip: '',
817
+ standbyNote: '',
818
+ preSwitchCompactionAdvice: ''
819
+ };
820
+ }
821
+
822
+ /**
823
+ * Computes session and rolling 5h/7d dual-pool quota & cache telemetry.
824
+ */
825
+ export function computeQuotaAndCacheTelemetry(steps = [], {
826
+ sessionId = 'unknown',
827
+ modelId = 'gemini-4-argon',
828
+ totalActiveTokens = 0,
829
+ activeEffortProfile = EFFORT_PROFILES.STANDARD,
830
+ stdinQuota = null,
831
+ genMetadata = null,
832
+ aiCreditOveragesEnabled = undefined,
833
+ cacheDir = null,
834
+ reclaimableTokens = 0,
835
+ sludgeTokens = 0,
836
+ isAutoMode = undefined,
837
+ nowMs = Date.now()
838
+ } = {}) {
839
+ let sessionInputTokens = 0;
840
+ let sessionOutputTokens = 0;
841
+ let sessionCacheReadTokens = 0;
842
+ let sessionCacheCreationTokens = 0;
843
+ let sessionWrite5mTokens = 0;
844
+ let sessionWrite1hTokens = 0;
845
+ let sessionThinkingTokens = 0;
846
+ let sessionCostUsd = 0;
847
+ let sessionUncachedBaselineUsd = 0;
848
+ let sessionWeightedUnitsExact = 0;
849
+ let latestStepTimestampMs = 0;
850
+ let cumContextEst = 0;
851
+ let stepPrefixBustDetected = false;
852
+ let stepPrefixBustDeltaSec = null;
853
+ let stepPrefixBustCause = null;
854
+ let lastTurnCacheRead = 0;
855
+ let lastTurnCacheCreation = 0;
856
+ const turns = [];
857
+ let runningModel = normalizeModelId(modelId || 'gemini-4-argon');
858
+ let runningModelRaw = modelId || 'gemini-4-argon';
859
+ const prevStepByStream = new Map();
860
+ const hadPriorCacheHitByStream = new Map();
861
+ const streamTtlSecByStream = new Map();
862
+ const modelSwitchBuffer = new TurnBoundaryModelSwitchBuffer(runningModel);
863
+
864
+ for (let i = 0; i < steps.length; i++) {
865
+ const s = steps[i] || {};
866
+ const stepTok = s.outputTokens || Math.round((s.untruncatedLength || 0) / 4) || 0;
867
+ cumContextEst += stepTok;
868
+
869
+ const stepSessionId = String(s.session_id || s.sessionId || sessionId || 'default_session');
870
+ const stepAgentId = resolveStepAgentId(s);
871
+ const streamKey = formatAgentStreamKey(stepSessionId, stepAgentId);
872
+ const prevStepSameStream = prevStepByStream.get(streamKey) || null;
873
+
874
+ let detectedRawModel = null;
875
+ const changes = s.content ? parseSettingsChanges(s.content).filter(c => /model selection/i.test(c.setting)) : [];
876
+ if (changes.length > 0) {
877
+ detectedRawModel = changes[changes.length - 1].to;
878
+ } else if (s.turnMetadata?.model) {
879
+ detectedRawModel = s.turnMetadata.model;
880
+ } else if (s.model) {
881
+ detectedRawModel = s.model;
882
+ }
883
+
884
+ const currTs = s.createdAt ? Date.parse(s.createdAt) : 0;
885
+ const isMidTurnInFlight = Boolean(
886
+ s.inFlight === true ||
887
+ s.eventType === 'PreToolUse' ||
888
+ s.eventType === 'PostToolUse' ||
889
+ s.turnBoundary === false
890
+ );
891
+ const isTurnCompletion = Boolean(
892
+ s.eventType === 'PostInvocation' ||
893
+ s.eventType === 'Stop' ||
894
+ s.turnCompleted === true
895
+ );
896
+
897
+ if (detectedRawModel) {
898
+ runningModelRaw = detectedRawModel;
899
+ const bufState = modelSwitchBuffer.recordModelSwitch(detectedRawModel, {
900
+ sessionId: stepSessionId,
901
+ agentId: stepAgentId,
902
+ eventType: s.eventType || (isMidTurnInFlight ? 'PreToolUse' : 'PostInvocation'),
903
+ inFlight: isMidTurnInFlight,
904
+ timestampMs: currTs || nowMs
905
+ });
906
+ runningModel = bufState.active_model_id;
907
+ } else {
908
+ const bufState = modelSwitchBuffer._getOrCreate(stepSessionId, stepAgentId, runningModel);
909
+ runningModel = bufState.active_model_id;
910
+ }
911
+
912
+ if (isTurnCompletion) {
913
+ const promoted = modelSwitchBuffer.promoteOnTurnCompletion({
914
+ sessionId: stepSessionId,
915
+ agentId: stepAgentId,
916
+ eventType: s.eventType || 'PostInvocation',
917
+ timestampMs: currTs || nowMs
918
+ });
919
+ runningModel = promoted.active_model_id;
920
+ }
921
+
922
+ const stepModelUsage = s.costState?.modelUsage || s['cost-state']?.modelUsage || s.modelUsage || {};
923
+ const stepWrite1h = Math.max(0, Number(
924
+ s.write1hTokens ??
925
+ s.cacheCreationEphemeral1hInputTokens ??
926
+ s.usage?.cache_creation?.ephemeral_1h_input_tokens ??
927
+ s.usage?.cache_creation_ephemeral_1h_input_tokens ??
928
+ stepModelUsage.cacheCreationEphemeral1hInputTokens ??
929
+ 0
930
+ ));
931
+ const stepWrite5mRaw = Math.max(0, Number(
932
+ s.write5mTokens ??
933
+ s.cacheCreationEphemeral5mInputTokens ??
934
+ s.usage?.cache_creation?.ephemeral_5m_input_tokens ??
935
+ s.usage?.cache_creation_ephemeral_5m_input_tokens ??
936
+ stepModelUsage.cacheCreationEphemeral5mInputTokens ??
937
+ 0
938
+ ));
939
+
940
+ const rawInput = Number(s.inputTokens || 0);
941
+ const rawOutput = Number(s.outputTokens || stepTok);
942
+ const rawCacheRead = Number(s.cacheReadTokens || 0);
943
+ const rawCacheCreateBase = Number(s.cacheCreationTokens || 0);
944
+ const rawCacheCreate = rawCacheCreateBase > 0
945
+ ? rawCacheCreateBase
946
+ : (stepWrite1h + stepWrite5mRaw);
947
+ const stepWrite5m = (stepWrite1h > 0 || stepWrite5mRaw > 0)
948
+ ? stepWrite5mRaw
949
+ : rawCacheCreate;
950
+ const rawThinking = Number(
951
+ s.thinkingTokens ||
952
+ (s.type === 'PLANNER_RESPONSE' && activeEffortProfile?.tier === 'HIGH' ? 4000 : 0)
953
+ );
954
+
955
+ const prevStreamTtlSec = streamTtlSecByStream.get(streamKey) || QUOTA_CONSTANTS.CACHE_TTL_SECONDS;
956
+ let streamTtlSec = Number(s.ttlSeconds || 0) > 0
957
+ ? Number(s.ttlSeconds)
958
+ : (stepWrite1h > 0 ? 3600 : (stepWrite5mRaw > 0 ? 300 : prevStreamTtlSec));
959
+ streamTtlSecByStream.set(streamKey, streamTtlSec);
960
+
961
+ const prevTs = prevStepSameStream?.createdAt ? Date.parse(prevStepSameStream.createdAt) : 0;
962
+ const gapSec = (prevTs > 0 && currTs >= prevTs) ? (currTs - prevTs) / 1000 : null;
963
+
964
+ let effInputForStep = rawInput;
965
+ let effCacheReadForStep = rawCacheRead;
966
+ let effCacheCreateForStep = rawCacheCreate;
967
+ let effWrite5mForStep = stepWrite5m;
968
+ let effWrite1hForStep = stepWrite1h;
969
+
970
+ if (rawCacheRead > 0 || rawCacheCreate > 0 || rawInput > 0) {
971
+ const hadPriorCacheHit = Boolean(hadPriorCacheHitByStream.get(streamKey));
972
+ const explicitMutation = Boolean(prevStepSameStream && hasExplicitPrefixMutation(s, prevStepSameStream));
973
+ sessionInputTokens += rawInput;
974
+ sessionCacheReadTokens += rawCacheRead;
975
+ sessionCacheCreationTokens += rawCacheCreate;
976
+ sessionWrite5mTokens += stepWrite5m;
977
+ sessionWrite1hTokens += stepWrite1h;
978
+ lastTurnCacheRead = rawCacheRead;
979
+ lastTurnCacheCreation = rawCacheCreate;
980
+ if (rawCacheRead > 0 || rawCacheCreate > 0) {
981
+ hadPriorCacheHitByStream.set(streamKey, true);
982
+ }
983
+ // Detect mid-run prefix bust strictly within the same (session_id, agent_id) stream
984
+ if (
985
+ prevStepSameStream &&
986
+ rawCacheRead === 0 &&
987
+ rawInput > 0 &&
988
+ (hadPriorCacheHit || explicitMutation) &&
989
+ gapSec !== null &&
990
+ gapSec < prevStreamTtlSec
991
+ ) {
992
+ stepPrefixBustDetected = true;
993
+ stepPrefixBustDeltaSec = Math.round(gapSec);
994
+ stepPrefixBustCause = detectModelSwitchCause(s, prevStepSameStream);
995
+ } else if (rawCacheRead > 0) {
996
+ stepPrefixBustDetected = false;
997
+ stepPrefixBustCause = null;
998
+ }
999
+ } else if (s.type === 'PLANNER_RESPONSE' && prevStepSameStream && gapSec !== null) {
1000
+ // Only infer prefix cache read when real step timestamps exist and prove turnaround within active TTL
1001
+ if (gapSec <= prevStreamTtlSec) {
1002
+ effCacheReadForStep = Math.max(0, cumContextEst - stepTok);
1003
+ effCacheCreateForStep = stepTok;
1004
+ effWrite5mForStep = stepTok;
1005
+ effWrite1hForStep = 0;
1006
+ sessionCacheReadTokens += effCacheReadForStep;
1007
+ sessionCacheCreationTokens += effCacheCreateForStep;
1008
+ sessionWrite5mTokens += effWrite5mForStep;
1009
+ lastTurnCacheRead = effCacheReadForStep;
1010
+ lastTurnCacheCreation = effCacheCreateForStep;
1011
+ hadPriorCacheHitByStream.set(streamKey, true);
1012
+ } else {
1013
+ effInputForStep = cumContextEst;
1014
+ sessionInputTokens += cumContextEst;
1015
+ lastTurnCacheRead = 0;
1016
+ lastTurnCacheCreation = 0;
1017
+ }
1018
+ }
1019
+
1020
+ const stepTotalPrompt = effInputForStep + effCacheReadForStep + effCacheCreateForStep;
1021
+ const stepRates = resolveModelRates(runningModel, currTs || nowMs, 'standard', {
1022
+ totalPromptTokens: stepTotalPrompt
1023
+ });
1024
+ const effWrite5mRate = stepRates.write5m > 0 ? stepRates.write5m : stepRates.input;
1025
+ const effWrite1hRate = stepRates.write1h > 0 ? stepRates.write1h : stepRates.input;
1026
+ const stepReadWeight = stepRates.input > 0
1027
+ ? (stepRates.cachedRead / stepRates.input)
1028
+ : QUOTA_CONSTANTS.CACHE_READ_WEIGHT;
1029
+ const stepWrite5mWeight = stepRates.input > 0
1030
+ ? (effWrite5mRate / stepRates.input)
1031
+ : QUOTA_CONSTANTS.UNCACHED_INPUT_WEIGHT;
1032
+ const stepWrite1hWeight = stepRates.input > 0
1033
+ ? (effWrite1hRate / stepRates.input)
1034
+ : QUOTA_CONSTANTS.UNCACHED_INPUT_WEIGHT;
1035
+
1036
+ const turnCostUsd =
1037
+ ((effInputForStep / 1_000_000) * stepRates.input) +
1038
+ ((effWrite5mForStep / 1_000_000) * effWrite5mRate) +
1039
+ ((effWrite1hForStep / 1_000_000) * effWrite1hRate) +
1040
+ ((effCacheReadForStep / 1_000_000) * stepRates.cachedRead) +
1041
+ (((rawOutput + rawThinking) / 1_000_000) * stepRates.output);
1042
+ const turnBaselineUsd =
1043
+ (((effInputForStep + effCacheCreateForStep + effCacheReadForStep) / 1_000_000) * stepRates.input) +
1044
+ (((rawOutput + rawThinking) / 1_000_000) * stepRates.output);
1045
+
1046
+ sessionCostUsd += turnCostUsd;
1047
+ sessionUncachedBaselineUsd += turnBaselineUsd;
1048
+ sessionWeightedUnitsExact +=
1049
+ (effCacheReadForStep * stepReadWeight) +
1050
+ (effInputForStep * QUOTA_CONSTANTS.UNCACHED_INPUT_WEIGHT) +
1051
+ (effWrite5mForStep * stepWrite5mWeight) +
1052
+ (effWrite1hForStep * stepWrite1hWeight) +
1053
+ ((rawOutput + rawThinking) * QUOTA_CONSTANTS.OUTPUT_THINKING_WEIGHT);
1054
+
1055
+ if (rawCacheRead > 0 || rawCacheCreate > 0 || rawInput > 0 || s.type === 'USER_INPUT' || s.type === 'PLANNER_RESPONSE') {
1056
+ const bufState = modelSwitchBuffer.getState(stepSessionId, stepAgentId);
1057
+ turns.push({
1058
+ stepIndex: s.stepIndex ?? i,
1059
+ session_id: stepSessionId,
1060
+ agent_id: stepAgentId,
1061
+ modelId: runningModel,
1062
+ active_model_id: bufState.active_model_id,
1063
+ pending_model_id: bufState.pending_model_id,
1064
+ modelRaw: runningModelRaw,
1065
+ inputTokens: rawInput,
1066
+ cacheReadTokens: rawCacheRead,
1067
+ cacheCreationTokens: rawCacheCreate,
1068
+ write5mTokens: stepWrite5m,
1069
+ write1hTokens: stepWrite1h,
1070
+ outputTokens: rawOutput,
1071
+ type: s.type || null,
1072
+ thinkingTokens: Number(s.thinkingTokens || 0),
1073
+ thinkingEstimated: !s.thinkingTokens && rawThinking > 0,
1074
+ ttlSeconds: streamTtlSec,
1075
+ rates: {
1076
+ input: stepRates.input,
1077
+ output: stepRates.output,
1078
+ write5m: stepRates.write5m,
1079
+ write1h: stepRates.write1h,
1080
+ cachedRead: stepRates.cachedRead,
1081
+ isAbovePromptCliff: Boolean(stepRates.isAbovePromptCliff)
1082
+ },
1083
+ turnCostUsd: Number(turnCostUsd.toFixed(6)),
1084
+ timestampMs: currTs || nowMs,
1085
+ createdAt: s.createdAt,
1086
+ explicitMutation: Boolean(prevStepSameStream && hasExplicitPrefixMutation(s, prevStepSameStream))
1087
+ });
1088
+ }
1089
+
1090
+ prevStepByStream.set(streamKey, { ...s, model: runningModel });
1091
+
1092
+ sessionOutputTokens += rawOutput;
1093
+ sessionThinkingTokens += rawThinking;
1094
+
1095
+ if (s.createdAt) {
1096
+ const ts = Date.parse(s.createdAt);
1097
+ if (Number.isFinite(ts) && ts > latestStepTimestampMs) {
1098
+ latestStepTimestampMs = ts;
1099
+ }
1100
+ }
1101
+ }
1102
+
1103
+ const totalPromptTokens = sessionCacheReadTokens + sessionCacheCreationTokens + sessionInputTokens;
1104
+ const cacheHitRatePct = totalPromptTokens > 0
1105
+ ? Math.min(100, Math.round((sessionCacheReadTokens / totalPromptTokens) * 100))
1106
+ : 0;
1107
+
1108
+ const weightedUnits = Math.round(sessionWeightedUnitsExact);
1109
+
1110
+ // Update rolling 7-day ledger
1111
+ const ledger = loadQuotaLedger(cacheDir);
1112
+ const cutoff7d = nowMs - QUOTA_CONSTANTS.WEEKLY_WINDOW_MS;
1113
+ const cutoff5h = nowMs - QUOTA_CONSTANTS.SPRINT_WINDOW_MS;
1114
+
1115
+ for (const [sid, entry] of Object.entries(ledger.sessions)) {
1116
+ if (!entry || (entry.updatedAtMs || 0) < cutoff7d) {
1117
+ delete ledger.sessions[sid];
1118
+ }
1119
+ }
1120
+
1121
+ if (sessionId && sessionId !== 'unknown') {
1122
+ const prev = ledger.sessions[sessionId];
1123
+ const unchanged = Boolean(
1124
+ prev &&
1125
+ prev.weightedUnits === weightedUnits &&
1126
+ prev.cacheReadTokens === sessionCacheReadTokens &&
1127
+ prev.inputTokens === sessionInputTokens &&
1128
+ prev.outputTokens === sessionOutputTokens &&
1129
+ prev.thinkingTokens === sessionThinkingTokens
1130
+ );
1131
+ ledger.sessions[sessionId] = {
1132
+ updatedAtMs: latestStepTimestampMs || nowMs,
1133
+ weightedUnits,
1134
+ cacheReadTokens: sessionCacheReadTokens,
1135
+ inputTokens: sessionInputTokens,
1136
+ outputTokens: sessionOutputTokens,
1137
+ thinkingTokens: sessionThinkingTokens
1138
+ };
1139
+ if (!unchanged) {
1140
+ saveQuotaLedger(ledger, cacheDir);
1141
+ }
1142
+ }
1143
+
1144
+ let sprintUnitsUsed = 0;
1145
+ let weeklyUnitsUsed = 0;
1146
+ let oldest5hTs = nowMs;
1147
+ let oldest7dTs = nowMs;
1148
+ for (const entry of Object.values(ledger.sessions)) {
1149
+ const ts = entry.updatedAtMs || 0;
1150
+ const units = Number(entry.weightedUnits || 0);
1151
+ if (ts >= cutoff7d) {
1152
+ weeklyUnitsUsed += units;
1153
+ if (ts < oldest7dTs) oldest7dTs = ts;
1154
+ }
1155
+ if (ts >= cutoff5h) {
1156
+ sprintUnitsUsed += units;
1157
+ if (ts < oldest5hTs) oldest5hTs = ts;
1158
+ }
1159
+ }
1160
+
1161
+ if (sprintUnitsUsed === 0 && weightedUnits > 0) sprintUnitsUsed = weightedUnits;
1162
+ if (weeklyUnitsUsed === 0 && weightedUnits > 0) weeklyUnitsUsed = weightedUnits;
1163
+
1164
+ let sprintUsedPct = parseFloat(Math.min(100, (sprintUnitsUsed / QUOTA_CONSTANTS.DEFAULT_SPRINT_POOL_UNITS) * 100).toFixed(1));
1165
+ let weeklyUsedPct = parseFloat(Math.min(100, (weeklyUnitsUsed / QUOTA_CONSTANTS.DEFAULT_WEEKLY_POOL_UNITS) * 100).toFixed(1));
1166
+
1167
+ // Default rolling reset timers (seconds remaining in active 5h sprint and 7d weekly windows)
1168
+ let sprintResetInSec = Math.max(60, Math.round(((oldest5hTs + QUOTA_CONSTANTS.SPRINT_WINDOW_MS) - nowMs) / 1000));
1169
+ let weeklyResetInSec = Math.max(300, Math.round(((oldest7dTs + QUOTA_CONSTANTS.WEEKLY_WINDOW_MS) - nowMs) / 1000));
1170
+ let aiCreditsBalance = null;
1171
+ // Per-metric provenance: 'host' only when the host actually supplied a numeric fraction;
1172
+ // otherwise the value is a local estimate from transcript token counts.
1173
+ let sprintSource = 'estimate';
1174
+ let weeklySource = 'estimate';
1175
+
1176
+ // Reconcile with host-reported quota buckets (stdin) if present
1177
+ if (stdinQuota && typeof stdinQuota === 'object') {
1178
+ if (typeof stdinQuota.remaining_fraction === 'number') {
1179
+ sprintUsedPct = parseFloat(Math.max(0, Math.min(100, (1 - stdinQuota.remaining_fraction) * 100)).toFixed(1));
1180
+ sprintSource = 'host';
1181
+ }
1182
+ const weeklyFrac = stdinQuota.buckets?.weekly?.remaining_fraction ?? stdinQuota.weekly_remaining_fraction;
1183
+ if (typeof weeklyFrac === 'number') {
1184
+ weeklyUsedPct = parseFloat(Math.max(0, Math.min(100, (1 - weeklyFrac) * 100)).toFixed(1));
1185
+ weeklySource = 'host';
1186
+ }
1187
+ if (typeof stdinQuota.reset_in_seconds === 'number' && stdinQuota.reset_in_seconds > 0) {
1188
+ sprintResetInSec = Math.round(stdinQuota.reset_in_seconds);
1189
+ } else if (typeof stdinQuota.buckets?.sprint?.reset_in_seconds === 'number') {
1190
+ sprintResetInSec = Math.round(stdinQuota.buckets.sprint.reset_in_seconds);
1191
+ }
1192
+ const hostWeeklyReset = stdinQuota.weekly_reset_in_seconds ?? stdinQuota.buckets?.weekly?.reset_in_seconds;
1193
+ if (typeof hostWeeklyReset === 'number' && hostWeeklyReset > 0) {
1194
+ weeklyResetInSec = Math.round(hostWeeklyReset);
1195
+ }
1196
+ const rawCredits = stdinQuota.ai_credits ?? stdinQuota.remaining_ai_credits ?? stdinQuota.aiCredits ?? stdinQuota.userStatus?.aiCredits;
1197
+ if (typeof rawCredits === 'number' && Number.isFinite(rawCredits)) {
1198
+ aiCreditsBalance = Math.max(0, Math.round(rawCredits));
1199
+ }
1200
+ }
1201
+
1202
+ const overagesEnabled = Boolean(
1203
+ aiCreditOveragesEnabled !== undefined
1204
+ ? aiCreditOveragesEnabled
1205
+ : (stdinQuota?.enable_ai_credit_overages ?? stdinQuota?.aiCreditOveragesEnabled ?? false)
1206
+ );
1207
+
1208
+ const subagentSteps = steps.filter(s => s && (s.isSidechain || (s.agentId && s.agentId !== 'parent')));
1209
+ const dualTtl = computeDualTtlState(steps, { nowMs, subagentSteps });
1210
+ const prefixDiff = computePrefixMutationDiff(steps);
1211
+
1212
+ const hasMultipleModelsInSteps = new Set(turns.map(t => t.modelId)).size > 1;
1213
+ const turnsToUse = (!hasMultipleModelsInSteps && Array.isArray(genMetadata?.recentTurns) && genMetadata.recentTurns.length > 0)
1214
+ ? genMetadata.recentTurns.map((r, idx) => ({
1215
+ stepIndex: r.stepIndex ?? idx,
1216
+ modelId: normalizeModelId(r.model || runningModel),
1217
+ modelRaw: r.model || runningModelRaw,
1218
+ inputTokens: Number(r.inputTokens || 0),
1219
+ cacheReadTokens: Number(r.cacheReadTokens || 0),
1220
+ cacheCreationTokens: 0,
1221
+ outputTokens: Number(r.outputTokens || 0),
1222
+ timestampMs: r.createdAt ? Date.parse(r.createdAt) : nowMs,
1223
+ createdAt: r.createdAt
1224
+ }))
1225
+ : turns;
1226
+
1227
+ const effectiveIsAuto = Boolean(
1228
+ isAutoMode ??
1229
+ (activeEffortProfile?.tier === 'STANDARD' || activeEffortProfile?.shortLabel === 'Auto')
1230
+ );
1231
+ const poolsResult = trackModelCachePools(turnsToUse, { sessionId, nowMs, prefixDiff });
1232
+ const thrashResult = detectRouterThrash(turnsToUse, effectiveIsAuto, {
1233
+ sessionId,
1234
+ totalTokens: totalActiveTokens,
1235
+ reclaimableTokens: reclaimableTokens || sludgeTokens || 0,
1236
+ standbyCache: poolsResult.standbyCache,
1237
+ lastSwitchEvent: poolsResult.lastSwitchEvent
1238
+ });
1239
+
1240
+ if (thrashResult.state === 'AUTO_ROUTER_THRASH') {
1241
+ stepPrefixBustDetected = true;
1242
+ stepPrefixBustCause = {
1243
+ cause: 'auto_router_thrash',
1244
+ switchCount: thrashResult.switchCount,
1245
+ models: thrashResult.modelsInvolved,
1246
+ badgeText: thrashResult.badgeText,
1247
+ tooltip: thrashResult.tooltip
1248
+ };
1249
+ } else if (thrashResult.state === 'MODEL_SWITCH_COLD_START' && !stepPrefixBustCause) {
1250
+ stepPrefixBustDetected = true;
1251
+ stepPrefixBustCause = {
1252
+ cause: 'model_switch',
1253
+ to: thrashResult.currentDisplayName || thrashResult.currentShortName
1254
+ };
1255
+ } else if (poolsResult.lastSwitchEvent?.warmPoolBustedReason && !stepPrefixBustCause) {
1256
+ stepPrefixBustDetected = true;
1257
+ stepPrefixBustCause = {
1258
+ cause: 'warm_pool_busted',
1259
+ reason: poolsResult.lastSwitchEvent.warmPoolBustedReason
1260
+ };
1261
+ }
1262
+
1263
+ // Prefix cache TTL state & Prefix Bust vs Natural Expiration (honors 5m 300s vs 1h 3600s TTL)
1264
+ const activeMaxTtlSec = dualTtl.mainTtlTier === '1h'
1265
+ ? 3600
1266
+ : QUOTA_CONSTANTS.CACHE_TTL_SECONDS;
1267
+ const idleSeconds = latestStepTimestampMs > 0
1268
+ ? Math.max(0, Math.round((nowMs - latestStepTimestampMs) / 1000))
1269
+ : 0;
1270
+ const cacheTtlRemainingSec = latestStepTimestampMs > 0
1271
+ ? Math.max(0, activeMaxTtlSec - idleSeconds)
1272
+ : activeMaxTtlSec;
1273
+ const isCacheCold = latestStepTimestampMs > 0 && cacheTtlRemainingSec === 0;
1274
+ const cacheBreakRisk = !isCacheCold && cacheTtlRemainingSec > 0 && cacheTtlRemainingSec <= 60;
1275
+ const ttlExpirationPulse = !isCacheCold && cacheTtlRemainingSec > 0 && cacheTtlRemainingSec <= QUOTA_CONSTANTS.TTL_PULSE_THRESHOLD_SECONDS;
1276
+
1277
+ const lastTurnPrefixBust = Boolean(
1278
+ genMetadata?.prefixBustDetected ||
1279
+ stepPrefixBustDetected ||
1280
+ (stdinQuota?.prefix_bust === true)
1281
+ );
1282
+ const prefixBustDetected = Boolean(
1283
+ lastTurnPrefixBust &&
1284
+ !isCacheCold &&
1285
+ cacheTtlRemainingSec > 0 &&
1286
+ idleSeconds < activeMaxTtlSec
1287
+ );
1288
+ const prefixBustDeltaSec = genMetadata?.prefixBustDeltaSec ?? stepPrefixBustDeltaSec ?? null;
1289
+ const prefixBustCause = prefixBustDetected
1290
+ ? (genMetadata?.prefixBustCause || stepPrefixBustCause || null)
1291
+ : null;
1292
+ const prefixBustLabel = prefixBustDetected
1293
+ ? (thrashResult.state === 'AUTO_ROUTER_THRASH' ? thrashResult.badgeText : formatPrefixBustLabel(prefixBustCause))
1294
+ : '';
1295
+ // a turn that read OR wrote the prefix cache (including a busting turn, which writes a
1296
+ // fresh prefix) leaves the next turn likely warm while the TTL is still running.
1297
+ const nextTurnLikelyWarm = Boolean(
1298
+ cacheTtlRemainingSec > 0 &&
1299
+ !isCacheCold &&
1300
+ (lastTurnCacheRead > 0 || lastTurnCacheCreation > 0 || prefixBustDetected)
1301
+ );
1302
+
1303
+ // Next-turn High-effort quota burn projection at current context depth using model-specific read discount
1304
+ const effectiveActive = Math.max(totalActiveTokens, 10000);
1305
+ const activeRates = resolveModelRates(runningModel || modelId, latestStepTimestampMs || nowMs, 'standard', {
1306
+ totalPromptTokens: effectiveActive
1307
+ });
1308
+ const activeReadWeight = activeRates.input > 0
1309
+ ? (activeRates.cachedRead / activeRates.input)
1310
+ : QUOTA_CONSTANTS.CACHE_READ_WEIGHT;
1311
+ const nextTurnInputCost = (isCacheCold || prefixBustDetected)
1312
+ ? effectiveActive * QUOTA_CONSTANTS.UNCACHED_INPUT_WEIGHT
1313
+ : effectiveActive * activeReadWeight;
1314
+ const nextTurnHighThinkingCost = (EFFORT_PROFILES.HIGH.thinkingReserve + 4000) * QUOTA_CONSTANTS.OUTPUT_THINKING_WEIGHT;
1315
+ const nextTurnHighUnits = nextTurnInputCost + nextTurnHighThinkingCost;
1316
+ const nextTurnHighSprintPct = parseFloat(((nextTurnHighUnits / QUOTA_CONSTANTS.DEFAULT_SPRINT_POOL_UNITS) * 100).toFixed(2));
1317
+ const nextTurnHighWeeklyPct = parseFloat(((nextTurnHighUnits / QUOTA_CONSTANTS.DEFAULT_WEEKLY_POOL_UNITS) * 100).toFixed(2));
1318
+
1319
+ // Estimates never drive lockout risk or overage alerts (they are a local guess, not host quota).
1320
+ const weeklyLockoutRisk = weeklySource !== 'estimate' &&
1321
+ (weeklyUsedPct >= 80 || (weeklyUsedPct >= 60 && weeklyUsedPct > sprintUsedPct * 1.2));
1322
+
1323
+ // AI Credit Overage Guardrail & Vision Bug Alert when host-reported 7d usage reaches 100%
1324
+ let overageAlert = {
1325
+ state: 'NONE',
1326
+ severity: 'none',
1327
+ message: ''
1328
+ };
1329
+ if (weeklySource !== 'estimate' && weeklyUsedPct >= 100) {
1330
+ if (!overagesEnabled) {
1331
+ overageAlert = {
1332
+ state: 'LOCKOUT_ALERT',
1333
+ severity: 'danger',
1334
+ message: OVERAGE_ALERT_MESSAGES.LOCKOUT_ALERT
1335
+ };
1336
+ } else {
1337
+ overageAlert = {
1338
+ state: 'OVERAGES_ACTIVE_VISION_WARN',
1339
+ severity: 'warn',
1340
+ message: OVERAGE_ALERT_MESSAGES.OVERAGES_ACTIVE_VISION_WARN
1341
+ };
1342
+ }
1343
+ }
1344
+
1345
+ const modelPoolName = resolveModelPoolDisplayName(modelId);
1346
+ const sprintResetLabel = formatResetCountdown(sprintResetInSec);
1347
+ const weeklyResetLabel = formatResetCountdown(weeklyResetInSec);
1348
+ const formattedAiCredits = aiCreditsBalance !== null ? aiCreditsBalance.toLocaleString('en-US') : null;
1349
+
1350
+ const effectiveTtlSec = dualTtl.mainTtlTier === '1h' ? dualTtl.mainTtlRemainingSec : cacheTtlRemainingSec;
1351
+ const hadWarmCache = sessionCacheReadTokens > 0 || sessionCacheCreationTokens > 0;
1352
+ const costGate = evaluateColdSessionCostGate({
1353
+ ttlRemainingSec: effectiveTtlSec,
1354
+ totalActiveTokens,
1355
+ modelId: runningModel || modelId,
1356
+ cacheTtlTier: dualTtl.mainTtlTier || '5m',
1357
+ eventTimestampUtc: latestStepTimestampMs || nowMs,
1358
+ isCacheCold: isCacheCold || effectiveTtlSec <= 0,
1359
+ hadWarmCache
1360
+ });
1361
+
1362
+ const cacheRoi = computeCacheRoi({
1363
+ cacheReadTokens: sessionCacheReadTokens,
1364
+ write5mTokens: sessionWrite5mTokens,
1365
+ write1hTokens: sessionWrite1hTokens,
1366
+ cacheCreationTokens: sessionCacheCreationTokens,
1367
+ uncachedInputTokens: sessionInputTokens,
1368
+ outputTokens: sessionOutputTokens + sessionThinkingTokens,
1369
+ modelId: runningModel || modelId,
1370
+ eventTimestampUtc: latestStepTimestampMs || nowMs,
1371
+ totalPromptTokens: Math.max(totalActiveTokens, totalPromptTokens)
1372
+ });
1373
+
1374
+ const prefixRetention = computePrefixRetentionIndex(turns);
1375
+ const thinkingDrift = computeThinkingDrift(steps);
1376
+
1377
+ const activeDescriptor = resolveModelDescriptor(runningModel || modelId);
1378
+ const supportsExplicitCache = activeDescriptor ? Boolean(activeDescriptor.supports_explicit_cache) : true;
1379
+ const cachingMode = activeDescriptor?.caching_mode || (supportsExplicitCache ? 'explicit_and_implicit' : 'implicit_only');
1380
+
1381
+ return {
1382
+ sprint5h: {
1383
+ usedUnits: sprintUnitsUsed,
1384
+ poolUnits: QUOTA_CONSTANTS.DEFAULT_SPRINT_POOL_UNITS,
1385
+ usedPct: sprintUsedPct,
1386
+ remainingPct: parseFloat((100 - sprintUsedPct).toFixed(1)),
1387
+ resetInSeconds: sprintResetInSec,
1388
+ resetLabel: sprintResetLabel,
1389
+ modelPoolName,
1390
+ source: sprintSource,
1391
+ poolCountdownLabel: `${modelPoolName} resets in ${sprintResetLabel}`
1392
+ },
1393
+ weekly7d: {
1394
+ usedUnits: weeklyUnitsUsed,
1395
+ poolUnits: QUOTA_CONSTANTS.DEFAULT_WEEKLY_POOL_UNITS,
1396
+ usedPct: weeklyUsedPct,
1397
+ remainingPct: parseFloat((100 - weeklyUsedPct).toFixed(1)),
1398
+ sprintToWeeklyMultiplier: QUOTA_CONSTANTS.WEEKLY_TO_SPRINT_RATIO,
1399
+ lockoutRisk: weeklyLockoutRisk,
1400
+ source: weeklySource,
1401
+ resetInSeconds: weeklyResetInSec,
1402
+ resetLabel: weeklyResetLabel,
1403
+ poolCountdownLabel: `7d resets in ${weeklyResetLabel}`,
1404
+ aiCreditOveragesEnabled: overagesEnabled
1405
+ },
1406
+ aiCredits: {
1407
+ balance: aiCreditsBalance,
1408
+ formatted: formattedAiCredits,
1409
+ label: formattedAiCredits !== null ? `\u2726 AI Credits: ${formattedAiCredits}` : null,
1410
+ overagesEnabled
1411
+ },
1412
+ overageAlert,
1413
+ cache: {
1414
+ hitRatePct: cacheHitRatePct,
1415
+ cacheReadTokens: sessionCacheReadTokens,
1416
+ cacheCreationTokens: sessionCacheCreationTokens,
1417
+ write5mTokens: sessionWrite5mTokens,
1418
+ write1hTokens: sessionWrite1hTokens,
1419
+ uncachedInputTokens: sessionInputTokens,
1420
+ thinkingTokens: sessionThinkingTokens,
1421
+ idleSeconds,
1422
+ ttlRemainingSec: cacheTtlRemainingSec,
1423
+ isCacheCold,
1424
+ cacheBreakRisk,
1425
+ ttlExpirationPulse,
1426
+ lastTurnPrefixBust,
1427
+ prefixBustDetected,
1428
+ bustDetected: prefixBustDetected,
1429
+ prefixBustDeltaSec,
1430
+ prefixBustCause,
1431
+ prefixBustLabel,
1432
+ lastTurnCacheReadTokens: lastTurnCacheRead,
1433
+ lastTurnCacheCreationTokens: lastTurnCacheCreation,
1434
+ nextTurnLikelyWarm,
1435
+ cachingMode,
1436
+ supportsExplicitCache,
1437
+ missingExplicitCacheWarning: supportsExplicitCache && sessionCacheCreationTokens === 0 && sessionCacheReadTokens === 0 && sessionInputTokens > 50000,
1438
+ dualTtl,
1439
+ prefixDiff,
1440
+ costGate,
1441
+ prefixRetention,
1442
+ roi: cacheRoi,
1443
+ pricing: {
1444
+ rates: {
1445
+ input: activeRates.input,
1446
+ output: activeRates.output,
1447
+ write5m: activeRates.write5m,
1448
+ write1h: activeRates.write1h,
1449
+ cachedRead: activeRates.cachedRead,
1450
+ isAbovePromptCliff: Boolean(activeRates.isAbovePromptCliff)
1451
+ },
1452
+ sessionCostUsd: Number(sessionCostUsd.toFixed(6)),
1453
+ uncachedBaselineUsd: Number(sessionUncachedBaselineUsd.toFixed(6)),
1454
+ netCacheSavingsUsd: Number((sessionUncachedBaselineUsd - sessionCostUsd).toFixed(6))
1455
+ },
1456
+ modelPools: Array.from(poolsResult.modelCachePools.values()),
1457
+ compositeModelPools: Array.from(poolsResult.compositeCachePools.values()),
1458
+ compositeCacheMap: Object.fromEntries(poolsResult.compositeCachePools.entries()),
1459
+ agentCacheMap: Object.fromEntries(poolsResult.compositeCachePools.entries()),
1460
+ turnBoundarySwitchState: modelSwitchBuffer.getState(sessionId, 'primary'),
1461
+ standbyCache: poolsResult.standbyCache,
1462
+ routerThrash: thrashResult,
1463
+ preSwitchCompactionAdvice: thrashResult.preSwitchCompactionAdvice || ''
1464
+ },
1465
+ routerThrash: thrashResult,
1466
+ thinkingDrift,
1467
+ forecast: {
1468
+ nextTurnHighSprintPct,
1469
+ nextTurnHighWeeklyPct,
1470
+ summary: `Next High-effort turn costs ~${nextTurnHighSprintPct}% of 5h Sprint (${isCacheCold || prefixBustDetected ? 'cold cache rebuild' : 'warm prefix cache'})`
1471
+ }
1472
+ };
1473
+ }
1474
+
1475
+ function formatSecondsCompact(sec) {
1476
+ const s = Math.max(0, Math.round(Number(sec || 0)));
1477
+ if (s <= 0) return '0s';
1478
+ if (s >= 60) {
1479
+ const m = Math.floor(s / 60);
1480
+ const rem = s % 60;
1481
+ return rem > 0 ? `${m}m ${rem}s` : `${m}m`;
1482
+ }
1483
+ return `${s}s`;
1484
+ }
1485
+
1486
+ /**
1487
+ * Computes live dual-TTL countdown timers (main-thread 1h vs 5m + active subagent 5m)
1488
+ * and fires an immediate Overage TTL Cliff Alert when a session shifts from 1h to 5m
1489
+ * ephemeral cache creation tokens.
1490
+ */
1491
+ export function computeDualTtlState(steps = [], { nowMs = Date.now(), subagentSteps = [] } = {}) {
1492
+ let ephemeral1hTokens = 0;
1493
+ let ephemeral5mTokens = 0;
1494
+ let saw1hEarlier = false;
1495
+ let overageTtlCliffDetected = false;
1496
+ let overageTtlCliffStepIndex = null;
1497
+ let mainTtlTier = '5m';
1498
+ let latestMainTs = 0;
1499
+ let latestSubagentTs = 0;
1500
+
1501
+ for (let i = 0; i < steps.length; i++) {
1502
+ const s = steps[i] || {};
1503
+ const modelUsage = s.costState?.modelUsage || s['cost-state']?.modelUsage || s.modelUsage || {};
1504
+ let turn1h = Number(
1505
+ s.write1hTokens ??
1506
+ s.cacheCreationEphemeral1hInputTokens ??
1507
+ s.usage?.cache_creation?.ephemeral_1h_input_tokens ??
1508
+ s.usage?.cache_creation_ephemeral_1h_input_tokens ??
1509
+ modelUsage.cacheCreationEphemeral1hInputTokens ??
1510
+ 0
1511
+ );
1512
+ let turn5m = Number(
1513
+ s.write5mTokens ??
1514
+ s.cacheCreationEphemeral5mInputTokens ??
1515
+ s.usage?.cache_creation?.ephemeral_5m_input_tokens ??
1516
+ s.usage?.cache_creation_ephemeral_5m_input_tokens ??
1517
+ modelUsage.cacheCreationEphemeral5mInputTokens ??
1518
+ 0
1519
+ );
1520
+
1521
+ if (turn1h === 0 && turn5m === 0) {
1522
+ for (const val of Object.values(modelUsage)) {
1523
+ if (val && typeof val === 'object') {
1524
+ turn1h += Number(val.cacheCreationEphemeral1hInputTokens || 0);
1525
+ turn5m += Number(val.cacheCreationEphemeral5mInputTokens || 0);
1526
+ }
1527
+ }
1528
+ }
1529
+
1530
+ if (turn1h > 0) {
1531
+ ephemeral1hTokens += turn1h;
1532
+ saw1hEarlier = true;
1533
+ mainTtlTier = '1h';
1534
+ }
1535
+ if (turn5m > 0) {
1536
+ ephemeral5mTokens += turn5m;
1537
+ if (saw1hEarlier && turn1h === 0) {
1538
+ overageTtlCliffDetected = true;
1539
+ overageTtlCliffStepIndex = s.stepIndex ?? i;
1540
+ }
1541
+ if (turn1h === 0) {
1542
+ mainTtlTier = '5m';
1543
+ }
1544
+ }
1545
+
1546
+ const ts = s.createdAt ? Date.parse(s.createdAt) : (s.timestamp ? Date.parse(s.timestamp) : 0);
1547
+ const isSub = Boolean(s.isSidechain || (s.agentId && s.agentId !== 'parent'));
1548
+ if (Number.isFinite(ts) && ts > 0) {
1549
+ if (isSub) {
1550
+ if (ts > latestSubagentTs) latestSubagentTs = ts;
1551
+ } else if (ts > latestMainTs) {
1552
+ latestMainTs = ts;
1553
+ }
1554
+ }
1555
+ }
1556
+
1557
+ for (const sub of (subagentSteps || [])) {
1558
+ const ts = sub?.createdAt ? Date.parse(sub.createdAt) : (sub?.timestamp ? Date.parse(sub.timestamp) : 0);
1559
+ if (Number.isFinite(ts) && ts > latestSubagentTs) {
1560
+ latestSubagentTs = ts;
1561
+ }
1562
+ }
1563
+
1564
+ const mainTtlMaxSec = mainTtlTier === '1h' ? 3600 : 300;
1565
+ const mainIdleSec = latestMainTs > 0 ? Math.max(0, Math.round((nowMs - latestMainTs) / 1000)) : 0;
1566
+ const mainTtlRemainingSec = latestMainTs > 0
1567
+ ? Math.max(0, mainTtlMaxSec - mainIdleSec)
1568
+ : mainTtlMaxSec;
1569
+
1570
+ let subagentTtlRemainingSec = null;
1571
+ if (latestSubagentTs > 0) {
1572
+ const subIdleSec = Math.max(0, Math.round((nowMs - latestSubagentTs) / 1000));
1573
+ subagentTtlRemainingSec = Math.max(0, 300 - subIdleSec);
1574
+ }
1575
+
1576
+ const overageTtlCliffMessage = overageTtlCliffDetected
1577
+ ? `⚠️ Overage TTL Cliff Alert: Session shifted from 1h to 5m ephemeral cache TTL at Turn #${overageTtlCliffStepIndex} (12.5x–20x rewrite risk on >5m pauses).`
1578
+ : '';
1579
+
1580
+ return {
1581
+ mainTtlTier,
1582
+ mainTtlMaxSec,
1583
+ mainTtlRemainingSec,
1584
+ mainTtlFormatted: `${formatSecondsCompact(mainTtlRemainingSec)} (${mainTtlTier})`,
1585
+ subagentTtlRemainingSec,
1586
+ subagentTtlFormatted: subagentTtlRemainingSec !== null ? `${formatSecondsCompact(subagentTtlRemainingSec)} (5m subagent)` : null,
1587
+ ephemeral1hTokens,
1588
+ ephemeral5mTokens,
1589
+ overageTtlCliffDetected,
1590
+ overageTtlCliffStepIndex,
1591
+ overageTtlCliffMessage
1592
+ };
1593
+ }
1594
+
1595
+ function sha256Short(str) {
1596
+ return crypto.createHash('sha256').update(String(str || ''), 'utf8').digest('hex').slice(0, 12);
1597
+ }
1598
+
1599
+ function firstDiffByteOffset(a = '', b = '') {
1600
+ const s1 = String(a || '');
1601
+ const s2 = String(b || '');
1602
+ const minLen = Math.min(s1.length, s2.length);
1603
+ for (let i = 0; i < minLen; i++) {
1604
+ if (s1.charCodeAt(i) !== s2.charCodeAt(i)) {
1605
+ return Buffer.byteLength(s1.slice(0, i), 'utf8');
1606
+ }
1607
+ }
1608
+ return Buffer.byteLength(s1.slice(0, minLen), 'utf8');
1609
+ }
1610
+
1611
+ /**
1612
+ * Computes rolling hashes across consecutive turns over `api-request-shape` (`shapeHash`),
1613
+ * `attachment` deltas (`mcp_instructions_delta`, `deferred_tools_delta`), and message arrays
1614
+ * to pinpoint the exact block and byte/token offset that mutated during an unexpected cache miss.
1615
+ */
1616
+ export function computePrefixMutationDiff(steps = []) {
1617
+ if (!Array.isArray(steps) || steps.length < 2) {
1618
+ return {
1619
+ mutated: false,
1620
+ turnIndex: null,
1621
+ mutatedComponent: null,
1622
+ blockIndex: null,
1623
+ byteOffset: 0,
1624
+ tokenOffset: 0,
1625
+ prevHash: null,
1626
+ currHash: null,
1627
+ prevShapeHash: null,
1628
+ currShapeHash: null,
1629
+ summary: ''
1630
+ };
1631
+ }
1632
+
1633
+ for (let i = steps.length - 1; i >= 1; i--) {
1634
+ const curr = steps[i] || {};
1635
+ const prev = steps[i - 1] || {};
1636
+
1637
+ const prevShape = prev.shapeHash || prev['api-request-shape']?.shapeHash || null;
1638
+ const currShape = curr.shapeHash || curr['api-request-shape']?.shapeHash || null;
1639
+ const prevMcp = String(prev.mcpInstructions || prev.mcp_instructions_delta || prev.attachment?.mcp_instructions_delta || '');
1640
+ const currMcp = String(curr.mcpInstructions || curr.mcp_instructions_delta || curr.attachment?.mcp_instructions_delta || '');
1641
+ const prevDef = String(prev.deferredTools || prev.deferred_tools_delta || prev.attachment?.deferred_tools_delta || '');
1642
+ const currDef = String(curr.deferredTools || curr.deferred_tools_delta || curr.attachment?.deferred_tools_delta || '');
1643
+
1644
+ if ((prevMcp || currMcp) && prevMcp !== currMcp) {
1645
+ const byteOffset = firstDiffByteOffset(prevMcp, currMcp);
1646
+ const tokenOffset = Math.ceil(byteOffset / 4);
1647
+ const pHash = sha256Short(prevMcp);
1648
+ const cHash = sha256Short(currMcp);
1649
+ return {
1650
+ mutated: true,
1651
+ turnIndex: curr.stepIndex ?? i,
1652
+ mutatedComponent: 'MCP_INSTRUCTIONS',
1653
+ blockIndex: 0,
1654
+ byteOffset,
1655
+ tokenOffset,
1656
+ prevHash: pHash,
1657
+ currHash: cHash,
1658
+ prevShapeHash: prevShape || pHash,
1659
+ currShapeHash: currShape || cHash,
1660
+ summary: `Prefix mutated at Turn #${curr.stepIndex ?? i} in MCP_INSTRUCTIONS (block #0, byte +${byteOffset}, ~token +${tokenOffset})`
1661
+ };
1662
+ }
1663
+
1664
+ if ((prevDef || currDef) && prevDef !== currDef) {
1665
+ const byteOffset = firstDiffByteOffset(prevDef, currDef);
1666
+ const tokenOffset = Math.ceil(byteOffset / 4);
1667
+ const pHash = sha256Short(prevDef);
1668
+ const cHash = sha256Short(currDef);
1669
+ return {
1670
+ mutated: true,
1671
+ turnIndex: curr.stepIndex ?? i,
1672
+ mutatedComponent: 'DEFERRED_TOOLS',
1673
+ blockIndex: 1,
1674
+ byteOffset,
1675
+ tokenOffset,
1676
+ prevHash: pHash,
1677
+ currHash: cHash,
1678
+ prevShapeHash: prevShape || pHash,
1679
+ currShapeHash: currShape || cHash,
1680
+ summary: `Prefix mutated at Turn #${curr.stepIndex ?? i} in DEFERRED_TOOLS (block #1, byte +${byteOffset}, ~token +${tokenOffset})`
1681
+ };
1682
+ }
1683
+
1684
+ if (prevShape && currShape && prevShape !== currShape) {
1685
+ const prevBody = String(prev.content || '');
1686
+ const currBody = String(curr.content || '');
1687
+ const byteOffset = firstDiffByteOffset(prevBody, currBody);
1688
+ const tokenOffset = Math.ceil(byteOffset / 4);
1689
+ return {
1690
+ mutated: true,
1691
+ turnIndex: curr.stepIndex ?? i,
1692
+ mutatedComponent: 'SYSTEM_SHAPE',
1693
+ blockIndex: 0,
1694
+ byteOffset,
1695
+ tokenOffset,
1696
+ prevHash: prevShape,
1697
+ currHash: currShape,
1698
+ prevShapeHash: prevShape,
1699
+ currShapeHash: currShape,
1700
+ summary: `Prefix shapeHash mutated at Turn #${curr.stepIndex ?? i} (${prevShape.slice(0, 8)} -> ${currShape.slice(0, 8)}, byte +${byteOffset}, ~token +${tokenOffset})`
1701
+ };
1702
+ }
1703
+
1704
+ const prevBlocks = Array.isArray(prev.prefixBlocks || prev.messageRequestContext) ? (prev.prefixBlocks || prev.messageRequestContext) : null;
1705
+ const currBlocks = Array.isArray(curr.prefixBlocks || curr.messageRequestContext) ? (curr.prefixBlocks || curr.messageRequestContext) : null;
1706
+ if (prevBlocks && currBlocks) {
1707
+ let runningBytes = 0;
1708
+ const minBlocks = Math.min(prevBlocks.length, currBlocks.length);
1709
+ for (let bIdx = 0; bIdx < minBlocks; bIdx++) {
1710
+ const pb = typeof prevBlocks[bIdx] === 'string' ? prevBlocks[bIdx] : JSON.stringify(prevBlocks[bIdx]);
1711
+ const cb = typeof currBlocks[bIdx] === 'string' ? currBlocks[bIdx] : JSON.stringify(currBlocks[bIdx]);
1712
+ if (pb !== cb) {
1713
+ const innerByte = firstDiffByteOffset(pb, cb);
1714
+ const byteOffset = runningBytes + innerByte;
1715
+ const tokenOffset = Math.ceil(byteOffset / 4);
1716
+ const pHash = sha256Short(pb);
1717
+ const cHash = sha256Short(cb);
1718
+ return {
1719
+ mutated: true,
1720
+ turnIndex: curr.stepIndex ?? i,
1721
+ mutatedComponent: 'MESSAGE_PREFIX',
1722
+ blockIndex: bIdx,
1723
+ byteOffset,
1724
+ tokenOffset,
1725
+ prevHash: pHash,
1726
+ currHash: cHash,
1727
+ prevShapeHash: pHash,
1728
+ currShapeHash: cHash,
1729
+ summary: `Prefix message block #${bIdx} mutated at Turn #${curr.stepIndex ?? i} (byte +${byteOffset}, ~token +${tokenOffset})`
1730
+ };
1731
+ }
1732
+ runningBytes += Buffer.byteLength(pb, 'utf8');
1733
+ }
1734
+ }
1735
+ }
1736
+
1737
+ return {
1738
+ mutated: false,
1739
+ turnIndex: null,
1740
+ mutatedComponent: null,
1741
+ blockIndex: null,
1742
+ byteOffset: 0,
1743
+ tokenOffset: 0,
1744
+ prevHash: null,
1745
+ currHash: null,
1746
+ prevShapeHash: null,
1747
+ currShapeHash: null,
1748
+ summary: ''
1749
+ };
1750
+ }
1751
+
1752
+ /**
1753
+ * Cold-Session Cost Gate & Optional Keepwarm Controller.
1754
+ * At `TTL <= 120s` on contexts >50k tokens, compares warm compaction cost vs cold rewrite.
1755
+ * When expired (`TTL === 0s`), renders a Cold Session Cost Gate banner with exact dollar/quota penalty.
1756
+ */
1757
+ export function evaluateColdSessionCostGate({
1758
+ ttlRemainingSec = 300,
1759
+ totalActiveTokens = 0,
1760
+ activeTokens = 0,
1761
+ modelId = 'gemini-4-argon',
1762
+ pricePerMillionUsd = null,
1763
+ cacheTtlTier = '5m',
1764
+ eventTimestampUtc = null,
1765
+ serviceTier = 'standard',
1766
+ isCacheCold = false,
1767
+ hadWarmCache = true
1768
+ } = {}) {
1769
+ const activeTok = Math.max(0, Number(totalActiveTokens || activeTokens) || 0);
1770
+ const ttlSec = Math.max(0, Math.round(Number(ttlRemainingSec ?? 300)));
1771
+ const resolvedRates = resolveModelRates(modelId, eventTimestampUtc, serviceTier, {
1772
+ totalPromptTokens: activeTok
1773
+ });
1774
+
1775
+ const hasExplicitOverride = pricePerMillionUsd !== null &&
1776
+ pricePerMillionUsd !== undefined &&
1777
+ Number(pricePerMillionUsd) > 0;
1778
+ const overrideScale = hasExplicitOverride && resolvedRates.input > 0
1779
+ ? (Number(pricePerMillionUsd) / resolvedRates.input)
1780
+ : 1;
1781
+
1782
+ const baseInputRate = hasExplicitOverride ? Number(pricePerMillionUsd) : resolvedRates.input;
1783
+ const warmReadRate = (resolvedRates.cachedRead > 0 ? resolvedRates.cachedRead : baseInputRate * 0.10) * overrideScale;
1784
+ const rawWriteRate = cacheTtlTier === '1h' ? resolvedRates.write1h : resolvedRates.write5m;
1785
+ const coldPrefillRate = (rawWriteRate > 0 ? rawWriteRate : resolvedRates.input) * overrideScale;
1786
+
1787
+ // Warm cache read vs Cold 5m/1h cache write (or cold uncached prefill)
1788
+ const rawWarmUsd = (activeTok / 1_000_000) * warmReadRate;
1789
+ const rawColdUsd = (activeTok / 1_000_000) * coldPrefillRate;
1790
+ const warmCompactionCostUsd = Number(rawWarmUsd.toFixed(6));
1791
+ const coldRewriteCostUsd = Number(rawColdUsd.toFixed(6));
1792
+ const costMultiplier = warmReadRate > 0
1793
+ ? parseFloat((coldPrefillRate / warmReadRate).toFixed(1))
1794
+ : 12.5;
1795
+ const readWeight = baseInputRate > 0
1796
+ ? (warmReadRate / baseInputRate)
1797
+ : QUOTA_CONSTANTS.CACHE_READ_WEIGHT;
1798
+ const quotaPenaltyUnits = Math.round(activeTok * Math.max(0, QUOTA_CONSTANTS.UNCACHED_INPUT_WEIGHT - readWeight));
1799
+
1800
+ const fmtUsd = (val) => (val >= 0.01 ? val.toFixed(2) : val.toFixed(4));
1801
+ const ratesSummary = {
1802
+ input: Number((baseInputRate).toFixed(4)),
1803
+ output: Number((resolvedRates.output * overrideScale).toFixed(4)),
1804
+ write5m: Number((resolvedRates.write5m * overrideScale).toFixed(4)),
1805
+ write1h: Number((resolvedRates.write1h * overrideScale).toFixed(4)),
1806
+ cachedRead: Number((warmReadRate).toFixed(4)),
1807
+ isAbovePromptCliff: Boolean(resolvedRates.isAbovePromptCliff)
1808
+ };
1809
+
1810
+ if (activeTok <= 50000 || !hadWarmCache) {
1811
+ return {
1812
+ state: 'NOMINAL',
1813
+ ttlRemainingSec: ttlSec,
1814
+ warmCompactionCostUsd,
1815
+ coldRewriteCostUsd,
1816
+ costMultiplier,
1817
+ quotaPenaltyUnits,
1818
+ rates: ratesSummary,
1819
+ bannerMessage: ''
1820
+ };
1821
+ }
1822
+
1823
+ if (isCacheCold || ttlSec === 0) {
1824
+ return {
1825
+ state: 'COLD_COST_GATE',
1826
+ ttlRemainingSec: 0,
1827
+ warmCompactionCostUsd,
1828
+ coldRewriteCostUsd,
1829
+ costMultiplier,
1830
+ quotaPenaltyUnits,
1831
+ rates: ratesSummary,
1832
+ bannerMessage: `🛑 Cold Session Cost Gate: Prefix cache expired (0s TTL). Sending next message cold costs ~$${fmtUsd(coldRewriteCostUsd)} (+${Math.round(quotaPenaltyUnits / 1000)}k quota units, ${costMultiplier}x warm rate) vs $0.00 1-Click Handoff Distillation (.handoff.md).`
1833
+ };
1834
+ }
1835
+
1836
+ if (ttlSec <= 120) {
1837
+ return {
1838
+ state: 'KEEPWARM_WARNING',
1839
+ ttlRemainingSec: ttlSec,
1840
+ warmCompactionCostUsd,
1841
+ coldRewriteCostUsd,
1842
+ costMultiplier,
1843
+ quotaPenaltyUnits,
1844
+ rates: ratesSummary,
1845
+ bannerMessage: `⏱️ Cache Expiring (${ttlSec}s left): Warm compaction now costs ~$${fmtUsd(warmCompactionCostUsd)} vs ~$${fmtUsd(coldRewriteCostUsd)} cold rewrite after TTL expires.`
1846
+ };
1847
+ }
1848
+
1849
+ return {
1850
+ state: 'NOMINAL',
1851
+ ttlRemainingSec: ttlSec,
1852
+ warmCompactionCostUsd,
1853
+ coldRewriteCostUsd,
1854
+ costMultiplier,
1855
+ quotaPenaltyUnits,
1856
+ rates: ratesSummary,
1857
+ bannerMessage: ''
1858
+ };
1859
+ }
1860
+