ctxtop 0.0.0-stage → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (240) hide show
  1. package/.antigravity-plugin/plugin.json +36 -0
  2. package/.claude-plugin/plugin.json +18 -0
  3. package/CHECKSUMS.sha256 +149 -0
  4. package/LICENSE +27 -0
  5. package/README.md +330 -3
  6. package/SECURITY.md +22 -0
  7. package/agents/ah-flash-scout.md +25 -0
  8. package/assets/advanced_view_loaded_420px.png +0 -0
  9. package/assets/hero-demo.svg +188 -0
  10. package/assets/logo.svg +19 -0
  11. package/assets/simple_view_lean_420px.png +0 -0
  12. package/assets/simple_view_loaded_420px.png +0 -0
  13. package/assets/social-preview.svg +72 -0
  14. package/assets/zone_c_step3_shield_full.png +0 -0
  15. package/bin/ah-statusline.mjs +145 -0
  16. package/bin/cli.mjs +3 -0
  17. package/bin/ctxtop.mjs +1474 -0
  18. package/commands/cost-radar.md +11 -0
  19. package/commands/evolve.md +10 -0
  20. package/commands/handoff.md +10 -0
  21. package/commands/horizon.md +10 -0
  22. package/commands/inspect.md +10 -0
  23. package/commands/precheck.md +10 -0
  24. package/config/default_flightcheck.json +114 -0
  25. package/config/modelCatalog.json +620 -0
  26. package/config/platformQuirks.json +19 -0
  27. package/hooks/handlers/compact-lifecycle.mjs +262 -0
  28. package/hooks/handlers/hookIo.mjs +255 -0
  29. package/hooks/handlers/hookIpcClient.mjs +83 -0
  30. package/hooks/handlers/post-tool-use.mjs +265 -0
  31. package/hooks/handlers/pre-model-switch.mjs +249 -0
  32. package/hooks/handlers/pre-tool-use.mjs +365 -0
  33. package/hooks/handlers/stop-gate.mjs +240 -0
  34. package/hooks/handlers/user-prompt-submit.mjs +143 -0
  35. package/hooks/hooks.json +81 -0
  36. package/hooks/post_invocation.mjs +13 -0
  37. package/hooks/post_tool_use.mjs +17 -0
  38. package/hooks/pre_invocation.mjs +14 -0
  39. package/hooks/pre_tool_use.mjs +97 -0
  40. package/hooks/register.js +687 -0
  41. package/hooks/session_start.mjs +14 -0
  42. package/hooks/stop.mjs +13 -0
  43. package/hooks.json +56 -0
  44. package/package.json +103 -4
  45. package/packages/antigravity/package.json +14 -0
  46. package/packages/antigravity/src/index.mjs +1 -0
  47. package/packages/claude-code/package.json +14 -0
  48. package/packages/claude-code/src/index.mjs +2 -0
  49. package/packages/core/package.json +14 -0
  50. package/packages/core/src/index.mjs +1 -0
  51. package/packages/engine-node/package.json +14 -0
  52. package/packages/engine-node/src/index.mjs +1 -0
  53. package/packages/mcp/package.json +17 -0
  54. package/packages/mcp/src/server.mjs +396 -0
  55. package/packages/pro/LICENSE-COMMERCIAL.md +19 -0
  56. package/packages/pro/README-SIGNING.md +30 -0
  57. package/packages/pro/package.json +16 -0
  58. package/packages/pro/src/index.mjs +3 -0
  59. package/packages/pro/src/team_finops_pack.mjs +241 -0
  60. package/packages/pro/workers/polar_webhook_worker.mjs +215 -0
  61. package/plugin.json +36 -0
  62. package/rules/AGENTS.md +10 -0
  63. package/sidecars/horizon-daemon/ipcServer.mjs +24 -0
  64. package/sidecars/horizon-daemon/server.mjs +2002 -0
  65. package/sidecars/horizon-daemon/sidecar.json +19 -0
  66. package/skills/cost-radar/SKILL.md +21 -0
  67. package/skills/evolve/SKILL.md +21 -0
  68. package/skills/handoff/SKILL.md +42 -0
  69. package/skills/horizon/SKILL.md +17 -0
  70. package/skills/inspect/SKILL.md +18 -0
  71. package/skills/precheck/SKILL.md +44 -0
  72. package/src/adapters/antigravity/index.mjs +79 -0
  73. package/src/adapters/claude-code/index.mjs +155 -0
  74. package/src/cli/cost_radar.mjs +70 -0
  75. package/src/cli/doctor.mjs +351 -0
  76. package/src/cli/horizon_hud.mjs +686 -0
  77. package/src/cli/init.mjs +425 -0
  78. package/src/cli/postmortem.mjs +515 -0
  79. package/src/coach/cacheGravityRouter.mjs +12 -0
  80. package/src/config/modelCatalog.json +620 -0
  81. package/src/config/platformQuirks.json +19 -0
  82. package/src/core/action_queue.mjs +264 -0
  83. package/src/core/ag_bridge.mjs +346 -0
  84. package/src/core/atomic_io.mjs +124 -0
  85. package/src/core/baseline.mjs +607 -0
  86. package/src/core/blindspot_sensors.mjs +399 -0
  87. package/src/core/classifier.mjs +1757 -0
  88. package/src/core/coach/circuit_breakers.mjs +650 -0
  89. package/src/core/coach/contradiction_auditor.mjs +239 -0
  90. package/src/core/coach/effort_advisor.mjs +143 -0
  91. package/src/core/coach/handoff_hydrator.mjs +483 -0
  92. package/src/core/coach/progressive_checkpointer.mjs +551 -0
  93. package/src/core/coach/prompt_decomposer_coach.mjs +141 -0
  94. package/src/core/coach/reflector_queue.mjs +505 -0
  95. package/src/core/coach/saved_quota_ledger.mjs +615 -0
  96. package/src/core/coach/subagent_ipi_sanitizer.mjs +200 -0
  97. package/src/core/coach/subagent_phantom_auditor.mjs +261 -0
  98. package/src/core/coach/task_quota_router.mjs +955 -0
  99. package/src/core/coach/turn_zero_gate.mjs +574 -0
  100. package/src/core/compaction_coach.mjs +1126 -0
  101. package/src/core/config.mjs +214 -0
  102. package/src/core/constants.mjs +1800 -0
  103. package/src/core/detectors_det01_to_16.mjs +1474 -0
  104. package/src/core/episodic_memory.mjs +135 -0
  105. package/src/core/fts5_output_compressor.mjs +359 -0
  106. package/src/core/git_ledger.mjs +189 -0
  107. package/src/core/handoff_audit.mjs +558 -0
  108. package/src/core/history.mjs +221 -0
  109. package/src/core/hook_diagnostics.mjs +158 -0
  110. package/src/core/horizon_classifier.mjs +326 -0
  111. package/src/core/horizon_config.mjs +802 -0
  112. package/src/core/host_watchdog.mjs +200 -0
  113. package/src/core/layer5_hygiene.mjs +966 -0
  114. package/src/core/log_resolver.mjs +231 -0
  115. package/src/core/mcp_auditor.mjs +138 -0
  116. package/src/core/micro_skills_store.mjs +91 -0
  117. package/src/core/offenders.mjs +161 -0
  118. package/src/core/parser.mjs +1996 -0
  119. package/src/core/path_canonicalizer.mjs +73 -0
  120. package/src/core/paths.mjs +310 -0
  121. package/src/core/prefix_cache_shield.mjs +386 -0
  122. package/src/core/pro_license.mjs +385 -0
  123. package/src/core/prompt_rubric.mjs +518 -0
  124. package/src/core/pruner.mjs +433 -0
  125. package/src/core/quota.mjs +1860 -0
  126. package/src/core/rsi_instinct_engine.mjs +1197 -0
  127. package/src/core/sanitizer.mjs +121 -0
  128. package/src/core/session_forensics.mjs +303 -0
  129. package/src/core/session_timeline.mjs +358 -0
  130. package/src/core/settings.mjs +99 -0
  131. package/src/core/shared/detectors.mjs +1342 -0
  132. package/src/core/shared/fnv1a64.mjs +85 -0
  133. package/src/core/shared/handoff_schema.mjs +123 -0
  134. package/src/core/shared/index.mjs +5 -0
  135. package/src/core/shared/ipi_sanitizer.mjs +165 -0
  136. package/src/core/shared/micro_skills.mjs +1 -0
  137. package/src/core/shared/plugin_validator.mjs +202 -0
  138. package/src/core/shared/prompt_hygiene_governor.mjs +1 -0
  139. package/src/core/sidecar_store.mjs +302 -0
  140. package/src/core/sprint_metrics.mjs +366 -0
  141. package/src/core/sqlite_client.mjs +283 -0
  142. package/src/core/storage_doctor.mjs +358 -0
  143. package/src/core/subagents.mjs +609 -0
  144. package/src/core/swarm_topology.mjs +360 -0
  145. package/src/core/task_quota_router.mjs +1656 -0
  146. package/src/core/telemetry/cache_ttl_watchdog.mjs +284 -0
  147. package/src/core/telemetry/scope_lock_registry.mjs +578 -0
  148. package/src/core/telemetry/shadow_file_detector.mjs +291 -0
  149. package/src/core/telemetry/trajectory_watcher.mjs +259 -0
  150. package/src/core/timeline_svg.mjs +236 -0
  151. package/src/core/tool_surgeon.mjs +305 -0
  152. package/src/core/trajectory_stitcher.mjs +645 -0
  153. package/src/core/u_shaped_optimizer.mjs +789 -0
  154. package/src/core/wal_hygiene.mjs +233 -0
  155. package/src/core-isomorphic/catalog/detectorCatalog.mjs +558 -0
  156. package/src/core-isomorphic/catalog/index.mjs +1 -0
  157. package/src/core-isomorphic/coach/cacheGravityRouter.mjs +720 -0
  158. package/src/core-isomorphic/coach/microSkills.mjs +1 -0
  159. package/src/core-isomorphic/coach/promptHygieneGovernor.mjs +1 -0
  160. package/src/core-isomorphic/coach/repoCalibration.mjs +254 -0
  161. package/src/core-isomorphic/coach/savedQuotaLedger.mjs +527 -0
  162. package/src/core-isomorphic/coach/stateBatonHydrator.mjs +810 -0
  163. package/src/core-isomorphic/coach/ttlWatchdog.mjs +457 -0
  164. package/src/core-isomorphic/config/anthropicModelCatalog.json +203 -0
  165. package/src/core-isomorphic/config/catalogLoader.mjs +768 -0
  166. package/src/core-isomorphic/config/horizonConfig.mjs +1009 -0
  167. package/src/core-isomorphic/control/callTree.mjs +338 -0
  168. package/src/core-isomorphic/control/coachLatches.mjs +126 -0
  169. package/src/core-isomorphic/control/controlStateMachine.mjs +205 -0
  170. package/src/core-isomorphic/control/index.mjs +49 -0
  171. package/src/core-isomorphic/control/swarmWorktree.mjs +109 -0
  172. package/src/core-isomorphic/control/toolSuspension.mjs +197 -0
  173. package/src/core-isomorphic/diagnostics/drift_guard.mjs +382 -0
  174. package/src/core-isomorphic/diagnostics/index.mjs +9 -0
  175. package/src/core-isomorphic/diagnostics/micro_skills.mjs +471 -0
  176. package/src/core-isomorphic/diagnostics/prompt_hygiene_governor.mjs +622 -0
  177. package/src/core-isomorphic/economics/billingBlocks.mjs +251 -0
  178. package/src/core-isomorphic/economics/cacheGravity.mjs +351 -0
  179. package/src/core-isomorphic/economics/cliffBreaker.mjs +170 -0
  180. package/src/core-isomorphic/economics/driftLatency.mjs +319 -0
  181. package/src/core-isomorphic/economics/dualTtl.mjs +198 -0
  182. package/src/core-isomorphic/economics/index.mjs +47 -0
  183. package/src/core-isomorphic/economics/retentionRadar.mjs +348 -0
  184. package/src/core-isomorphic/guards/circuitBreakers.mjs +1202 -0
  185. package/src/core-isomorphic/guards/det01_03_shell_secret.mjs +1035 -0
  186. package/src/core-isomorphic/guards/det04_12_thrash_rot.mjs +480 -0
  187. package/src/core-isomorphic/guards/det13_20_mcp_scope.mjs +603 -0
  188. package/src/core-isomorphic/guards/losslessPostSanitizer.mjs +301 -0
  189. package/src/core-isomorphic/index.js +26 -0
  190. package/src/core-isomorphic/telemetry/otelExporter.mjs +187 -0
  191. package/src/core-isomorphic/telemetry/scopeLockRegistry.mjs +522 -0
  192. package/src/core-isomorphic/telemetry/sprintMetrics.mjs +327 -0
  193. package/src/core-isomorphic/telemetry/swarmTopology.mjs +152 -0
  194. package/src/core-isomorphic/telemetry/telemetryBridge.mjs +1132 -0
  195. package/src/core-isomorphic/ui/brailleSparkline.mjs +142 -0
  196. package/src/core-isomorphic/ui/costRadarSvg.mjs +276 -0
  197. package/src/core-isomorphic/ui/horizonGrid.mjs +475 -0
  198. package/src/core-isomorphic/ui/horizonPanelHtml.mjs +1181 -0
  199. package/src/core-isomorphic/ui/modViews.mjs +1478 -0
  200. package/src/core-isomorphic/ui/pdfReceiptGenerator.mjs +329 -0
  201. package/src/core-isomorphic/ustf/index.mjs +7 -0
  202. package/src/core-isomorphic/ustf/normalizer.mjs +512 -0
  203. package/src/core-isomorphic/ustf/schema.mjs +186 -0
  204. package/src/core-isomorphic/utils/runtime.mjs +962 -0
  205. package/src/demo/synthetic_states.mjs +661 -0
  206. package/src/diagnostics/bugReportGenerator.mjs +253 -0
  207. package/src/diagnostics/doctorEngine.mjs +203 -0
  208. package/src/engine-node/db/index.mjs +58 -0
  209. package/src/engine-node/db/jsonl_fallback.mjs +184 -0
  210. package/src/engine-node/db/probe.mjs +110 -0
  211. package/src/engine-node/db/sqlite_wrapper.mjs +122 -0
  212. package/src/engine-node/index.mjs +9 -0
  213. package/src/engine-node/ipc/client.mjs +447 -0
  214. package/src/engine-node/ipc/index.mjs +22 -0
  215. package/src/engine-node/ipc/protocol.mjs +177 -0
  216. package/src/engine-node/ipc/server.mjs +445 -0
  217. package/src/engine-node/offloader/index.mjs +6 -0
  218. package/src/engine-node/offloader/tool_offloader.mjs +241 -0
  219. package/src/engine-node/sensors/blindspots.mjs +369 -0
  220. package/src/engine-node/sensors/git_merge_tree.mjs +223 -0
  221. package/src/engine-node/sensors/index.mjs +7 -0
  222. package/src/hooks/portfolio_runtime.mjs +858 -0
  223. package/src/hooks/post_invocation.mjs +419 -0
  224. package/src/hooks/pre_invocation.mjs +1015 -0
  225. package/src/hooks/session_start.mjs +161 -0
  226. package/src/shims/agy_cli_compressor.mjs +705 -0
  227. package/src/shims/agy_git_guard.mjs +749 -0
  228. package/src/shims/ah_log_query.mjs +39 -0
  229. package/src/ui/costRadarSvg.mjs +6 -0
  230. package/src/ui/horizonGrid.mjs +1 -0
  231. package/src/ui/horizonPanelHtml.mjs +1 -0
  232. package/src/ui/horizon_panel.css +167 -0
  233. package/src/ui/horizon_panel.js +212 -0
  234. package/src/ui/modViews.mjs +1 -0
  235. package/src/utils/nodeIo.mjs +59 -0
  236. package/src/utils/runtime.mjs +1 -0
  237. package/src/webview/advanced_view.html +1808 -0
  238. package/src/webview/horizon_panel.html +11389 -0
  239. package/src/webview/registry.mjs +80 -0
  240. package/src/webview/simple_view.html +1370 -0
@@ -0,0 +1,302 @@
1
+ import fs from 'node:fs';
2
+ import path from 'node:path';
3
+ import os from 'node:os';
4
+ import { fileURLToPath } from 'node:url';
5
+ import { canonicalizePath } from './path_canonicalizer.mjs';
6
+ import { atomicWriteFileSync } from './atomic_io.mjs';
7
+
8
+ function resolveVersion() {
9
+ try {
10
+ let curr = path.dirname(fileURLToPath(import.meta.url));
11
+ for (let i = 0; i < 4; i++) {
12
+ const p = path.join(curr, 'package.json');
13
+ if (fs.existsSync(p)) {
14
+ const data = JSON.parse(fs.readFileSync(p, 'utf8'));
15
+ if (data.version) return data.version;
16
+ }
17
+ const pl = path.join(curr, 'plugin.json');
18
+ if (fs.existsSync(pl)) {
19
+ const data = JSON.parse(fs.readFileSync(pl, 'utf8'));
20
+ if (data.version) return data.version;
21
+ }
22
+ const parent = path.dirname(curr);
23
+ if (parent === curr) break;
24
+ curr = parent;
25
+ }
26
+ } catch {}
27
+ return '3.2.0';
28
+ }
29
+
30
+ export const SIDECAR_VERSION = resolveVersion();
31
+ const UUID_SESSION_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
32
+ const TEST_FLIGHTCHECK_DIR = path.join(os.tmpdir(), 'agy-flightcheck-test');
33
+
34
+ /**
35
+ * Returns default flightcheck root directory (~/.gemini/flightcheck)
36
+ */
37
+ export function getFlightcheckDir(baseDirOverride = null) {
38
+ if (baseDirOverride) return baseDirOverride;
39
+ const home = process.env.USERPROFILE || process.env.HOME || os.homedir();
40
+ return path.join(home, '.gemini', 'flightcheck');
41
+ }
42
+
43
+ /**
44
+ * Returns path to session sidecar file.
45
+ * Non-UUID synthetic/test session IDs are routed to os.tmpdir() so unit tests never pollute ~/.gemini/flightcheck/sessions.
46
+ */
47
+ export function getSidecarPath(conversationId, baseDirOverride = null) {
48
+ if (baseDirOverride) {
49
+ return path.join(baseDirOverride, 'sessions', `${conversationId}.sidecar.json`);
50
+ }
51
+ const isRealUuid = UUID_SESSION_RE.test(String(conversationId || '').trim());
52
+ const root = isRealUuid ? getFlightcheckDir() : TEST_FLIGHTCHECK_DIR;
53
+ return path.join(root, 'sessions', `${conversationId}.sidecar.json`);
54
+ }
55
+
56
+ /**
57
+ * Returns path to tool usage ledger
58
+ */
59
+ export function getToolUsagePath(baseDirOverride = null) {
60
+ const root = getFlightcheckDir(baseDirOverride);
61
+ return path.join(root, 'tool_usage.json');
62
+ }
63
+
64
+ /**
65
+ * Creates a clean default sidecar state object.
66
+ */
67
+ export function createDefaultSidecar(conversationId = '', workspacePath = '') {
68
+ return {
69
+ version: SIDECAR_VERSION,
70
+ conversationId: String(conversationId || ''),
71
+ workspacePath: canonicalizePath(workspacePath || ''),
72
+ updatedAtMs: Date.now(),
73
+ sessionMeta: {
74
+ turnCount: 0,
75
+ activeModel: 'gemini-3.8-flash',
76
+ active_model_id: 'gemini-3.8-flash',
77
+ pending_model_id: null,
78
+ activeEffort: 'high',
79
+ inPlanMode: false,
80
+ effortLocked: false,
81
+ lastTurnUsedSubagent: false,
82
+ consecutiveTrivialOnMax: 0,
83
+ consecutiveErrorStreak: 0,
84
+ turnsSinceLastPassingTest: 0
85
+ },
86
+ swarmRoster: {},
87
+ agentCacheMap: {},
88
+ telemetry: {
89
+ totalInputTokens: 0,
90
+ usedPercentage: 0,
91
+ exceeds200kTokens: false,
92
+ signalPurityPct: 100.0,
93
+ sludgeTaxUsdPerTurn: 0.0,
94
+ amputationRisk: false,
95
+ agentState: 'idle',
96
+ mode: 'auto',
97
+ quota: {
98
+ remaining_fraction: 1.0,
99
+ remaining_amount: 100,
100
+ reset_in_seconds: 18000,
101
+ buckets: {}
102
+ },
103
+ history: []
104
+ },
105
+ cells: [],
106
+ fileState: {
107
+ activeSetPaths: [],
108
+ staleDupPaths: [],
109
+ dirtySnapshotPaths: [],
110
+ legacyPoisonPaths: [],
111
+ unseenCallers: [],
112
+ streamCutoffRiskFiles: [],
113
+ foreignBleedKiIds: []
114
+ },
115
+ sensors: {
116
+ schemaTaxPct: 0.0,
117
+ unusedMcpServers: [],
118
+ oversizedPayloadDetected: false,
119
+ quotaFloorBreached: false,
120
+ planToFlashHandoffNeeded: false,
121
+ threeStrikeLoop: false,
122
+ loopFingerprint: null,
123
+ uncheckpointedGitDrift: false,
124
+ dirtyGitFileCount: 0,
125
+ planRevisions: 0,
126
+ planRevisionWarn: false,
127
+ proofQuality: 'None',
128
+ proofQualityReason: '',
129
+ splitRecommended: false,
130
+ splitReason: ''
131
+ },
132
+ handoff: {
133
+ result: 'MISSING',
134
+ targetFile: null,
135
+ failingChecks: [],
136
+ fixes: []
137
+ },
138
+ cursor: {
139
+ filePath: null,
140
+ byteOffset: 0,
141
+ tier: 0
142
+ }
143
+ };
144
+ }
145
+
146
+ const _sidecarMemCache = new Map();
147
+ const SIDECAR_CACHE_TTL_MS = 250;
148
+
149
+ /**
150
+ * Reads sidecar JSON synchronously with <2ms guaranteed SLA.
151
+ * Falls back to default state on ENOENT or parse error.
152
+ */
153
+ export function readSidecarSync(conversationId, baseDirOverride = null) {
154
+ if (!conversationId) return createDefaultSidecar();
155
+ const filePath = getSidecarPath(conversationId, baseDirOverride);
156
+ const now = Date.now();
157
+ const cached = _sidecarMemCache.get(filePath);
158
+ if (cached && (now - cached.timeMs) < SIDECAR_CACHE_TTL_MS) {
159
+ return JSON.parse(JSON.stringify(cached.data));
160
+ }
161
+
162
+ try {
163
+ const raw = fs.readFileSync(filePath, 'utf8');
164
+ const parsed = JSON.parse(raw);
165
+ if (parsed && typeof parsed === 'object') {
166
+ _sidecarMemCache.set(filePath, { timeMs: now, data: parsed });
167
+ return JSON.parse(JSON.stringify(parsed));
168
+ }
169
+ } catch {
170
+ _sidecarMemCache.delete(filePath);
171
+ }
172
+
173
+ return createDefaultSidecar(conversationId);
174
+ }
175
+
176
+ /**
177
+ * Writes an arbitrary JSON object to disk atomically via temporary file, fsync, and bounded rename retry.
178
+ */
179
+ export function writeJsonAtomicSync(filePath, dataObj) {
180
+ const jsonStr = JSON.stringify(dataObj, null, 2);
181
+ atomicWriteFileSync(filePath, jsonStr, { encoding: 'utf8' });
182
+ _sidecarMemCache.set(filePath, { timeMs: Date.now(), data: JSON.parse(jsonStr) });
183
+ return dataObj;
184
+ }
185
+
186
+ /**
187
+ * Performs lock-free atomic write via unique temp file + renameSync.
188
+ * Includes Windows EPERM/EBUSY exponential backoff retry.
189
+ */
190
+ export function writeSidecarAtomicSync(conversationId, stateObj, baseDirOverride = null) {
191
+ const filePath = getSidecarPath(conversationId, baseDirOverride);
192
+ const payload = {
193
+ ...stateObj,
194
+ conversationId: String(conversationId),
195
+ updatedAtMs: Date.now()
196
+ };
197
+ return writeJsonAtomicSync(filePath, payload);
198
+ }
199
+
200
+ /**
201
+ * Reads the freshest sidecar state immediately before write, merges only the targeted
202
+ * section (e.g. 'sessionMeta', 'telemetry'), and writes back atomically.
203
+ * Prevents race conditions and lost updates between concurrent writers.
204
+ */
205
+ export function mergeSidecarSectionSync(conversationId, sectionName, patchObj, baseDirOverride = null) {
206
+ if (!conversationId || !sectionName) return null;
207
+ const current = readSidecarSync(conversationId, baseDirOverride);
208
+ const existingSection = (current[sectionName] && typeof current[sectionName] === 'object' && !Array.isArray(current[sectionName]))
209
+ ? current[sectionName]
210
+ : {};
211
+ const updated = {
212
+ ...current,
213
+ [sectionName]: {
214
+ ...existingSection,
215
+ ...patchObj
216
+ }
217
+ };
218
+ return writeSidecarAtomicSync(conversationId, updated, baseDirOverride);
219
+ }
220
+
221
+ /**
222
+ * Mutates sidecar state atomically and returns updated state.
223
+ */
224
+ export function updateSidecarPartialSync(conversationId, mutatorFn, baseDirOverride = null) {
225
+ const current = readSidecarSync(conversationId, baseDirOverride);
226
+ const updated = mutatorFn(current) || current;
227
+ return writeSidecarAtomicSync(conversationId, updated, baseDirOverride);
228
+ }
229
+
230
+ /**
231
+ * Atomically updates a single `/swarm` agent's state inside `sidecar.swarmRoster`
232
+ * using UTF-8 temp-file swap-and-rename so concurrent hook processes never corrupt session telemetry.
233
+ */
234
+ export function updateSwarmAgentStateAtomicSync(conversationId, agentId, agentStatePatch = {}, baseDirOverride = null) {
235
+ if (!conversationId || !agentId) return null;
236
+ const current = readSidecarSync(conversationId, baseDirOverride);
237
+ const roster = (current.swarmRoster && typeof current.swarmRoster === 'object' && !Array.isArray(current.swarmRoster))
238
+ ? { ...current.swarmRoster }
239
+ : {};
240
+ const existingAgent = (roster[agentId] && typeof roster[agentId] === 'object') ? roster[agentId] : {};
241
+ roster[agentId] = {
242
+ ...existingAgent,
243
+ ...agentStatePatch,
244
+ agent_id: String(agentId)
245
+ };
246
+ return writeSidecarAtomicSync(
247
+ conversationId,
248
+ { ...current, swarmRoster: roster },
249
+ baseDirOverride
250
+ );
251
+ }
252
+
253
+ /**
254
+ * Reads the 15-session tool usage ledger.
255
+ */
256
+ export function readToolUsageSync(baseDirOverride = null) {
257
+ const filePath = getToolUsagePath(baseDirOverride);
258
+ try {
259
+ const raw = fs.readFileSync(filePath, 'utf8');
260
+ return JSON.parse(raw);
261
+ } catch {
262
+ return {
263
+ version: SIDECAR_VERSION,
264
+ updatedAtMs: Date.now(),
265
+ servers: {}
266
+ };
267
+ }
268
+ }
269
+
270
+ /**
271
+ * Writes the tool usage ledger atomically with backoff.
272
+ */
273
+ export function writeToolUsageAtomicSync(ledgerObj, baseDirOverride = null) {
274
+ const filePath = getToolUsagePath(baseDirOverride);
275
+ const targetDir = path.dirname(filePath);
276
+
277
+ if (!fs.existsSync(targetDir)) {
278
+ fs.mkdirSync(targetDir, { recursive: true });
279
+ }
280
+
281
+ const payload = {
282
+ ...ledgerObj,
283
+ version: SIDECAR_VERSION,
284
+ updatedAtMs: Date.now()
285
+ };
286
+ const jsonStr = JSON.stringify(payload, null, 2);
287
+ atomicWriteFileSync(filePath, jsonStr, { encoding: 'utf8' });
288
+ return payload;
289
+ }
290
+
291
+ function sleepSync(ms) {
292
+ try {
293
+ const sab = new SharedArrayBuffer(4);
294
+ const int32 = new Int32Array(sab);
295
+ Atomics.wait(int32, 0, 0, ms);
296
+ } catch {
297
+ const start = Date.now();
298
+ while (Date.now() - start < ms) {
299
+ // spin wait fallback
300
+ }
301
+ }
302
+ }
@@ -0,0 +1,366 @@
1
+ /**
2
+ * @file src/core/sprint_metrics.mjs
3
+ * Sprint 1 "Metrics Wedge" — pure, zero-dependency telemetry derivations:
4
+ *
5
+ * 1. Prefix-Cache Retention Index (0–100%)
6
+ * Of the prompt prefix that *should* have been served from a warm KV cache
7
+ * (prior turn in the same session::agent stream, inside the active TTL),
8
+ * how much actually was? Reports $ retained (discount captured) vs. $ leaked
9
+ * (cold re-prefill paid because the prefix was busted).
10
+ *
11
+ * 2. Thinking vs. Generation Drift + DET-30 Scratchpad Loop Detector
12
+ * Per user turn: reasoning tokens / visible emission tokens, TTFT, and
13
+ * whether the agent is burning reasoning budget without mutating anything.
14
+ *
15
+ * Integrity rule: only *measured* usage is scored. Turns with no recorded token
16
+ * usage, or thinking tokens that were estimated rather than reported, never
17
+ * contribute — the index returns `null` (rendered as "—") instead of a fabricated 100%.
18
+ */
19
+
20
+ export const RETENTION_CONSTANTS = Object.freeze({
21
+ DEFAULT_TTL_SECONDS: 300,
22
+ BUST_RETAINED_RATIO: 0.5, // a turn retaining <50% of its eligible prefix counts as a prefix bust
23
+ GRADE_A_PCT: 90,
24
+ GRADE_B_PCT: 70
25
+ });
26
+
27
+ export const DRIFT_THRESHOLDS = Object.freeze({
28
+ MIN_THINKING_TOKENS: 4000,
29
+ LOOP_RATIO: 12,
30
+ ELEVATED_RATIO: 4,
31
+ CUMULATIVE_THINKING_TOKENS: 10000,
32
+ CONSECUTIVE_TURNS_CRITICAL: 2,
33
+ ROLLING_WINDOW: 3
34
+ });
35
+
36
+ export const THINKING_DRIFT_DETECTOR_ID = 'DET-30';
37
+ export const THINKING_DRIFT_SLUG = 'thinking-drift-loop';
38
+
39
+ const MUTATING_TOOL_RE = /write|edit|replace|create|patch|apply|delete|move|rename|run_command|bash|exec|shell|test/i;
40
+
41
+ function num(v) {
42
+ const n = Number(v);
43
+ return Number.isFinite(n) && n > 0 ? n : 0;
44
+ }
45
+
46
+ function round2(v) {
47
+ return Number((Number(v) || 0).toFixed(2));
48
+ }
49
+
50
+ function round6(v) {
51
+ return Number((Number(v) || 0).toFixed(6));
52
+ }
53
+
54
+ function promptTotal(t) {
55
+ return num(t.inputTokens) + num(t.cacheReadTokens) + num(t.cacheCreationTokens);
56
+ }
57
+
58
+ function classifyBustCause(turn, prev) {
59
+ if (prev && turn.modelId && prev.modelId && turn.modelId !== prev.modelId) return 'model_switch';
60
+ if (turn.explicitMutation) return 'prefix_mutation';
61
+ return 'prefix_drift';
62
+ }
63
+
64
+ /**
65
+ * Computes the Prefix-Cache Retention Index from per-turn usage records.
66
+ *
67
+ * @param {Array<object>} turns - records with { agent_id?, session_id?, modelId?, inputTokens,
68
+ * cacheReadTokens, cacheCreationTokens, timestampMs?, ttlSeconds?, explicitMutation?,
69
+ * rates?: { input, cachedRead } } (USD per 1M tokens)
70
+ * @param {object} [options]
71
+ * @param {{input:number, cachedRead:number}} [options.defaultRates]
72
+ * @returns {{
73
+ * measured: boolean, retentionIndexPct: number|null, grade: 'A'|'B'|'C'|'n/a',
74
+ * eligiblePrefixTokens: number, retainedPrefixTokens: number, leakedPrefixTokens: number,
75
+ * measuredTurns: number, bustCount: number, ttlExpiredTurns: number,
76
+ * bustCauses: Record<string, number>, lastBust: object|null,
77
+ * retainedDiscountSavingsUSD: number, leakedColdPrefillUSD: number, label: string
78
+ * }}
79
+ */
80
+ export function computePrefixRetentionIndex(turns = [], options = {}) {
81
+ const defaultRates = options.defaultRates || null;
82
+ const prevByStream = new Map();
83
+ let eligible = 0;
84
+ let retained = 0;
85
+ let measuredTurns = 0;
86
+ let bustCount = 0;
87
+ let ttlExpiredTurns = 0;
88
+ let savingsUSD = 0;
89
+ let leakedUSD = 0;
90
+ const bustCauses = {};
91
+ let lastBust = null;
92
+ const series = []; // per-turn retention points for the /cost-radar timeline (last 40 kept)
93
+
94
+ for (const turn of Array.isArray(turns) ? turns : []) {
95
+ if (!turn || typeof turn !== 'object') continue;
96
+ const total = promptTotal(turn);
97
+ if (total <= 0) continue; // unmeasured (inferred / no usage) — never scored
98
+ const streamKey = `${turn.session_id || turn.sessionId || 'default'}::${turn.agent_id || turn.agentId || 'primary'}`;
99
+ const prev = prevByStream.get(streamKey) || null;
100
+ prevByStream.set(streamKey, turn);
101
+ if (!prev) continue; // first measured turn in stream is a mandatory cold prefill
102
+
103
+ const ttlSec = num(prev.ttlSeconds) || RETENTION_CONSTANTS.DEFAULT_TTL_SECONDS;
104
+ const prevTs = num(prev.timestampMs);
105
+ const currTs = num(turn.timestampMs);
106
+ const gapSec = prevTs > 0 && currTs >= prevTs ? (currTs - prevTs) / 1000 : null;
107
+ if (gapSec !== null && gapSec > ttlSec) {
108
+ ttlExpiredTurns += 1; // idle expiry is a TTL problem, not a prefix-structure bust
109
+ series.push({ stepIndex: turn.stepIndex ?? null, eligible: 0, retained: 0, pct: null, bust: false, cause: null, ttlExpired: true });
110
+ continue;
111
+ }
112
+
113
+ const turnEligible = Math.min(promptTotal(prev), total);
114
+ if (turnEligible <= 0) continue;
115
+ const turnRetained = Math.min(num(turn.cacheReadTokens), turnEligible);
116
+ const turnLeaked = turnEligible - turnRetained;
117
+ measuredTurns += 1;
118
+ eligible += turnEligible;
119
+ retained += turnRetained;
120
+
121
+ const rates = turn.rates || defaultRates || {};
122
+ const discountPerToken = Math.max(0, num(rates.input) - num(rates.cachedRead)) / 1_000_000;
123
+ savingsUSD += turnRetained * discountPerToken;
124
+ leakedUSD += turnLeaked * discountPerToken;
125
+
126
+ const isBust = turnRetained / turnEligible < RETENTION_CONSTANTS.BUST_RETAINED_RATIO;
127
+ series.push({
128
+ stepIndex: turn.stepIndex ?? null,
129
+ eligible: turnEligible,
130
+ retained: turnRetained,
131
+ pct: Math.round((100 * turnRetained) / turnEligible),
132
+ bust: isBust,
133
+ cause: isBust ? classifyBustCause(turn, prev) : null,
134
+ ttlExpired: false,
135
+ savedUSD: round6(turnRetained * discountPerToken)
136
+ });
137
+ if (isBust) {
138
+ bustCount += 1;
139
+ const cause = classifyBustCause(turn, prev);
140
+ bustCauses[cause] = (bustCauses[cause] || 0) + 1;
141
+ lastBust = {
142
+ cause,
143
+ stepIndex: turn.stepIndex ?? null,
144
+ leakedTokens: turnLeaked,
145
+ leakedUSD: round6(turnLeaked * discountPerToken)
146
+ };
147
+ }
148
+ }
149
+
150
+ // Honesty gate: if the transcript never reports any cache read/write for any turn, the
151
+ // provider/harness is not exposing cache telemetry — that is "unmeasured", not "0% retained".
152
+ const hasCacheTelemetry = (Array.isArray(turns) ? turns : []).some((t) =>
153
+ t && typeof t === 'object' && (num(t.cacheReadTokens) > 0 || num(t.cacheCreationTokens) > 0));
154
+ const measured = measuredTurns > 0 && hasCacheTelemetry;
155
+ const retentionIndexPct = measured
156
+ ? Math.max(0, Math.min(100, Math.round((100 * retained) / eligible)))
157
+ : null;
158
+ const grade = !measured
159
+ ? 'n/a'
160
+ : retentionIndexPct >= RETENTION_CONSTANTS.GRADE_A_PCT
161
+ ? 'A'
162
+ : retentionIndexPct >= RETENTION_CONSTANTS.GRADE_B_PCT ? 'B' : 'C';
163
+
164
+ const result = {
165
+ measured,
166
+ retentionIndexPct,
167
+ grade,
168
+ eligiblePrefixTokens: eligible,
169
+ retainedPrefixTokens: retained,
170
+ leakedPrefixTokens: eligible - retained,
171
+ measuredTurns,
172
+ bustCount: measured ? bustCount : 0,
173
+ ttlExpiredTurns,
174
+ bustCauses: measured ? bustCauses : {},
175
+ lastBust: measured ? lastBust : null,
176
+ retainedDiscountSavingsUSD: round6(savingsUSD),
177
+ leakedColdPrefillUSD: measured ? round6(leakedUSD) : 0,
178
+ unmeasuredReason: measured ? null : (measuredTurns > 0 ? 'no_cache_telemetry' : 'insufficient_turns'),
179
+ series: measured ? series.slice(-40) : []
180
+ };
181
+ result.label = formatRetentionLabel(result);
182
+ return result;
183
+ }
184
+
185
+ /**
186
+ * Compact single-line label: "Retain 97% · Saved $1.42 · Leaked $0.08" or "Retain — (no multi-turn usage yet)".
187
+ */
188
+ export function formatRetentionLabel(r = {}) {
189
+ if (r && r.unmeasuredReason === 'no_cache_telemetry') return 'Retain — (no cache telemetry reported)';
190
+ if (!r || !r.measured || r.retentionIndexPct === null) return 'Retain — (no multi-turn usage yet)';
191
+ const parts = [`Retain ${r.retentionIndexPct}%`, `Saved $${round2(r.retainedDiscountSavingsUSD).toFixed(2)}`];
192
+ if (num(r.leakedColdPrefillUSD) > 0.005) parts.push(`Leaked $${round2(r.leakedColdPrefillUSD).toFixed(2)}`);
193
+ if (r.bustCount > 0) parts.push(`${r.bustCount} bust${r.bustCount === 1 ? '' : 's'}`);
194
+ return parts.join(' · ');
195
+ }
196
+
197
+ function stepTs(s) {
198
+ if (!s) return 0;
199
+ if (typeof s.timestampMs === 'number' && s.timestampMs > 0) return s.timestampMs;
200
+ const parsed = s.createdAt ? Date.parse(s.createdAt) : NaN;
201
+ return Number.isFinite(parsed) ? parsed : 0;
202
+ }
203
+
204
+ function countMutatingCalls(step) {
205
+ const calls = Array.isArray(step?.toolCalls) ? step.toolCalls : (Array.isArray(step?.tool_calls) ? step.tool_calls : []);
206
+ let n = 0;
207
+ for (const c of calls) {
208
+ if (MUTATING_TOOL_RE.test(String(c?.name || c?.toolName || ''))) n += 1;
209
+ }
210
+ return n;
211
+ }
212
+
213
+ /**
214
+ * Classifies a single turn's drift.
215
+ * @param {{thinkingTokens:number, visibleOutputTokens:number, mutatingCalls:number}} t
216
+ * @returns {'nominal'|'elevated'|'loop_suspect'}
217
+ */
218
+ export function classifyTurnDrift(t = {}) {
219
+ const thinking = num(t.thinkingTokens);
220
+ const ratio = thinking / Math.max(1, num(t.visibleOutputTokens));
221
+ if (thinking >= DRIFT_THRESHOLDS.MIN_THINKING_TOKENS && ratio >= DRIFT_THRESHOLDS.LOOP_RATIO && num(t.mutatingCalls) === 0) {
222
+ return 'loop_suspect';
223
+ }
224
+ if (thinking > 0 && ratio >= DRIFT_THRESHOLDS.ELEVATED_RATIO) return 'elevated';
225
+ return 'nominal';
226
+ }
227
+
228
+ /**
229
+ * Evaluates DET-30 across a chronological list of per-turn drift records.
230
+ * WARN on one loop-suspect turn; CRITICAL on ≥2 consecutive loop-suspect turns,
231
+ * or ≥10k cumulative thinking tokens across the trailing run with zero mutations.
232
+ */
233
+ export function evaluateThinkingDriftLoop(turnRecords = []) {
234
+ const records = Array.isArray(turnRecords) ? turnRecords : [];
235
+ let consecutive = 0;
236
+ let runThinking = 0;
237
+ for (let i = records.length - 1; i >= 0; i--) {
238
+ const r = records[i];
239
+ if (num(r.mutatingCalls) > 0) break;
240
+ runThinking += num(r.thinkingTokens);
241
+ if (classifyTurnDrift(r) === 'loop_suspect') consecutive += 1;
242
+ else break;
243
+ }
244
+ const last = records[records.length - 1] || null;
245
+ let severity = 'none';
246
+ if (consecutive >= DRIFT_THRESHOLDS.CONSECUTIVE_TURNS_CRITICAL ||
247
+ (consecutive >= 1 && runThinking >= DRIFT_THRESHOLDS.CUMULATIVE_THINKING_TOKENS)) {
248
+ severity = 'critical';
249
+ } else if (consecutive === 1) {
250
+ severity = 'warn';
251
+ }
252
+ const triggered = severity !== 'none';
253
+ const ratio = last ? round2(num(last.thinkingTokens) / Math.max(1, num(last.visibleOutputTokens))) : 0;
254
+ return {
255
+ detectorId: THINKING_DRIFT_DETECTOR_ID,
256
+ slug: THINKING_DRIFT_SLUG,
257
+ triggered,
258
+ severity,
259
+ consecutiveLoopTurns: consecutive,
260
+ trailingThinkingTokens: runThinking,
261
+ message: triggered
262
+ ? `${severity === 'critical' ? '🚨' : '⚠️'} ${THINKING_DRIFT_DETECTOR_ID} Scratchpad Loop: ${ratio}x reasoning-to-output over ${consecutive} turn(s) with 0 edits. Inject a concrete constraint (target file + acceptance test) or step effort down.`
263
+ : ''
264
+ };
265
+ }
266
+
267
+ /**
268
+ * Computes Thinking vs. Generation Drift from raw chronological steps
269
+ * (USER_INPUT / PLANNER_RESPONSE / tool steps). Only *reported* thinking tokens count;
270
+ * steps flagged `thinkingEstimated` are excluded from the ratio.
271
+ *
272
+ * @param {Array<object>} steps
273
+ * @returns {{
274
+ * measured: boolean, turns: Array<object>, lastTtftMs: number|null, avgTtftMs: number|null,
275
+ * lastDriftRatio: number|null, rollingDriftRatio: number|null,
276
+ * driftState: 'nominal'|'elevated'|'loop_detected'|'n/a', loop: object, label: string
277
+ * }}
278
+ */
279
+ export function computeThinkingDrift(steps = []) {
280
+ const turns = [];
281
+ let current = null;
282
+ const flush = () => {
283
+ if (current && (current.thinkingTokens > 0 || current.visibleOutputTokens > 0 || current.ttftMs !== null)) {
284
+ turns.push(current);
285
+ }
286
+ };
287
+
288
+ for (const s of Array.isArray(steps) ? steps : []) {
289
+ if (!s || typeof s !== 'object') continue;
290
+ if (s.type === 'USER_INPUT') {
291
+ flush();
292
+ current = {
293
+ userStepIndex: s.stepIndex ?? null,
294
+ startTs: stepTs(s),
295
+ ttftMs: null,
296
+ thinkingTokens: 0,
297
+ visibleOutputTokens: 0,
298
+ mutatingCalls: 0
299
+ };
300
+ continue;
301
+ }
302
+ if (!current) {
303
+ current = { userStepIndex: null, startTs: 0, ttftMs: null, thinkingTokens: 0, visibleOutputTokens: 0, mutatingCalls: 0 };
304
+ }
305
+ if (s.type === 'PLANNER_RESPONSE' || s.type === 'ASSISTANT' || s.role === 'assistant') {
306
+ const ts = stepTs(s);
307
+ if (current.ttftMs === null && current.startTs > 0 && ts > current.startTs) {
308
+ // Strictly positive only: second-resolution timestamps yield 0ms deltas, which are unmeasured, not instant.
309
+ current.ttftMs = ts - current.startTs;
310
+ }
311
+ if (!s.thinkingEstimated) current.thinkingTokens += num(s.thinkingTokens);
312
+ current.visibleOutputTokens += num(s.outputTokens);
313
+ }
314
+ current.mutatingCalls += countMutatingCalls(s);
315
+ }
316
+ flush();
317
+
318
+ for (const t of turns) {
319
+ t.driftRatio = round2(t.thinkingTokens / Math.max(1, t.visibleOutputTokens));
320
+ t.driftState = classifyTurnDrift(t);
321
+ }
322
+
323
+ const withThinking = turns.filter((t) => t.thinkingTokens > 0 || t.visibleOutputTokens > 0);
324
+ const ttfts = turns.map((t) => t.ttftMs).filter((v) => typeof v === 'number');
325
+ const last = withThinking[withThinking.length - 1] || null;
326
+ const rolling = withThinking.slice(-DRIFT_THRESHOLDS.ROLLING_WINDOW);
327
+ const rollThinking = rolling.reduce((a, t) => a + t.thinkingTokens, 0);
328
+ const rollVisible = rolling.reduce((a, t) => a + t.visibleOutputTokens, 0);
329
+ const measured = withThinking.some((t) => t.thinkingTokens > 0);
330
+ const loop = evaluateThinkingDriftLoop(withThinking);
331
+
332
+ let driftState = 'n/a';
333
+ if (measured) {
334
+ driftState = loop.triggered ? 'loop_detected' : (last && last.driftState === 'elevated' ? 'elevated' : 'nominal');
335
+ }
336
+
337
+ const result = {
338
+ measured,
339
+ turns: turns.slice(-20),
340
+ lastTtftMs: ttfts.length ? ttfts[ttfts.length - 1] : null,
341
+ avgTtftMs: ttfts.length ? Math.round(ttfts.reduce((a, b) => a + b, 0) / ttfts.length) : null,
342
+ lastDriftRatio: measured && last ? last.driftRatio : null,
343
+ rollingDriftRatio: measured ? round2(rollThinking / Math.max(1, rollVisible)) : null,
344
+ driftState,
345
+ loop
346
+ };
347
+ result.label = formatDriftLabel(result);
348
+ return result;
349
+ }
350
+
351
+ export function formatTtft(ms) {
352
+ if (typeof ms !== 'number' || !Number.isFinite(ms)) return '—';
353
+ if (ms < 1000) return `${Math.round(ms)}ms`;
354
+ if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
355
+ return `${Math.floor(ms / 60000)}m${Math.round((ms % 60000) / 1000)}s`;
356
+ }
357
+
358
+ /**
359
+ * "Think 1.8x · TTFT 1.1s" | "LOOP 16.4x · TTFT 9.2s" | "Think — · TTFT 1.1s"
360
+ */
361
+ export function formatDriftLabel(d = {}) {
362
+ const ttft = `TTFT ${formatTtft(d.lastTtftMs)}`;
363
+ if (!d.measured || d.lastDriftRatio === null) return `Think — · ${ttft}`;
364
+ if (d.driftState === 'loop_detected') return `LOOP ${d.lastDriftRatio}x · ${ttft}`;
365
+ return `Think ${d.lastDriftRatio}x · ${ttft}`;
366
+ }