@memnexus-ai/mx-agent-cli 0.1.292 → 0.1.294-next.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 (242) hide show
  1. package/dist/__tests__/config-sync.test.js +54 -1
  2. package/dist/__tests__/config-sync.test.js.map +1 -1
  3. package/dist/__tests__/decision-check.test.d.ts +2 -0
  4. package/dist/__tests__/decision-check.test.d.ts.map +1 -0
  5. package/dist/__tests__/decision-check.test.js +105 -0
  6. package/dist/__tests__/decision-check.test.js.map +1 -0
  7. package/dist/__tests__/doctor-framework-version.test.d.ts +2 -0
  8. package/dist/__tests__/doctor-framework-version.test.d.ts.map +1 -0
  9. package/dist/__tests__/doctor-framework-version.test.js +146 -0
  10. package/dist/__tests__/doctor-framework-version.test.js.map +1 -0
  11. package/dist/__tests__/harness-extract.test.d.ts +19 -0
  12. package/dist/__tests__/harness-extract.test.d.ts.map +1 -0
  13. package/dist/__tests__/harness-extract.test.js +566 -0
  14. package/dist/__tests__/harness-extract.test.js.map +1 -0
  15. package/dist/__tests__/harness-wiring.test.d.ts +16 -0
  16. package/dist/__tests__/harness-wiring.test.d.ts.map +1 -0
  17. package/dist/__tests__/harness-wiring.test.js +469 -0
  18. package/dist/__tests__/harness-wiring.test.js.map +1 -0
  19. package/dist/__tests__/mx-agent-cli-pin-validation.test.d.ts +2 -0
  20. package/dist/__tests__/mx-agent-cli-pin-validation.test.d.ts.map +1 -0
  21. package/dist/__tests__/mx-agent-cli-pin-validation.test.js +256 -0
  22. package/dist/__tests__/mx-agent-cli-pin-validation.test.js.map +1 -0
  23. package/dist/__tests__/mx-agent-cli-version-pin.test.d.ts +2 -0
  24. package/dist/__tests__/mx-agent-cli-version-pin.test.d.ts.map +1 -0
  25. package/dist/__tests__/mx-agent-cli-version-pin.test.js +290 -0
  26. package/dist/__tests__/mx-agent-cli-version-pin.test.js.map +1 -0
  27. package/dist/__tests__/report-format.test.d.ts +2 -0
  28. package/dist/__tests__/report-format.test.d.ts.map +1 -0
  29. package/dist/__tests__/report-format.test.js +219 -0
  30. package/dist/__tests__/report-format.test.js.map +1 -0
  31. package/dist/__tests__/standards-injection.test.d.ts +2 -0
  32. package/dist/__tests__/standards-injection.test.d.ts.map +1 -0
  33. package/dist/__tests__/standards-injection.test.js +157 -0
  34. package/dist/__tests__/standards-injection.test.js.map +1 -0
  35. package/dist/agent-config/hooks/auto-capture-precompact.sh +74 -4
  36. package/dist/agent-config/hooks/auto-capture-session-end.sh +106 -4
  37. package/dist/agent-config/hooks/auto-checkpoint.sh +75 -5
  38. package/dist/agent-config/hooks/observability-sync.sh +46 -9
  39. package/dist/commands/config-sync.d.ts +37 -0
  40. package/dist/commands/config-sync.d.ts.map +1 -1
  41. package/dist/commands/config-sync.js +36 -18
  42. package/dist/commands/config-sync.js.map +1 -1
  43. package/dist/commands/dashboard.d.ts.map +1 -1
  44. package/dist/commands/dashboard.js +10 -2
  45. package/dist/commands/dashboard.js.map +1 -1
  46. package/dist/commands/decision.d.ts +20 -0
  47. package/dist/commands/decision.d.ts.map +1 -0
  48. package/dist/commands/decision.js +54 -0
  49. package/dist/commands/decision.js.map +1 -0
  50. package/dist/commands/doctor.d.ts +18 -0
  51. package/dist/commands/doctor.d.ts.map +1 -1
  52. package/dist/commands/doctor.js +41 -0
  53. package/dist/commands/doctor.js.map +1 -1
  54. package/dist/commands/monitor.d.ts.map +1 -1
  55. package/dist/commands/monitor.js +8 -2
  56. package/dist/commands/monitor.js.map +1 -1
  57. package/dist/commands/new.d.ts.map +1 -1
  58. package/dist/commands/new.js +15 -1
  59. package/dist/commands/new.js.map +1 -1
  60. package/dist/commands/report.d.ts +33 -0
  61. package/dist/commands/report.d.ts.map +1 -0
  62. package/dist/commands/report.js +73 -0
  63. package/dist/commands/report.js.map +1 -0
  64. package/dist/commands/start.d.ts +4 -0
  65. package/dist/commands/start.d.ts.map +1 -1
  66. package/dist/commands/start.js +6 -0
  67. package/dist/commands/start.js.map +1 -1
  68. package/dist/commands/update.d.ts +13 -1
  69. package/dist/commands/update.d.ts.map +1 -1
  70. package/dist/commands/update.js +50 -1
  71. package/dist/commands/update.js.map +1 -1
  72. package/dist/index.d.ts.map +1 -1
  73. package/dist/index.js +67 -3
  74. package/dist/index.js.map +1 -1
  75. package/dist/lib/agent-session.d.ts +12 -0
  76. package/dist/lib/agent-session.d.ts.map +1 -1
  77. package/dist/lib/agent-session.js +183 -41
  78. package/dist/lib/agent-session.js.map +1 -1
  79. package/dist/lib/claude.d.ts +12 -0
  80. package/dist/lib/claude.d.ts.map +1 -1
  81. package/dist/lib/claude.js +29 -2
  82. package/dist/lib/claude.js.map +1 -1
  83. package/dist/lib/decision-check.d.ts +48 -0
  84. package/dist/lib/decision-check.d.ts.map +1 -0
  85. package/dist/lib/decision-check.js +149 -0
  86. package/dist/lib/decision-check.js.map +1 -0
  87. package/dist/lib/framework-version.d.ts +144 -0
  88. package/dist/lib/framework-version.d.ts.map +1 -0
  89. package/dist/lib/framework-version.js +270 -0
  90. package/dist/lib/framework-version.js.map +1 -0
  91. package/dist/lib/harness/console/announce.d.ts +45 -0
  92. package/dist/lib/harness/console/announce.d.ts.map +1 -0
  93. package/dist/lib/harness/console/announce.js +48 -0
  94. package/dist/lib/harness/console/announce.js.map +1 -0
  95. package/dist/lib/harness/console/announce.test.d.ts +2 -0
  96. package/dist/lib/harness/console/announce.test.d.ts.map +1 -0
  97. package/dist/lib/harness/console/announce.test.js +104 -0
  98. package/dist/lib/harness/console/announce.test.js.map +1 -0
  99. package/dist/lib/harness/console/by-session.d.ts +50 -0
  100. package/dist/lib/harness/console/by-session.d.ts.map +1 -0
  101. package/dist/lib/harness/console/by-session.js +83 -0
  102. package/dist/lib/harness/console/by-session.js.map +1 -0
  103. package/dist/lib/harness/console/by-session.test.d.ts +2 -0
  104. package/dist/lib/harness/console/by-session.test.d.ts.map +1 -0
  105. package/dist/lib/harness/console/by-session.test.js +86 -0
  106. package/dist/lib/harness/console/by-session.test.js.map +1 -0
  107. package/dist/lib/harness/console/console.d.ts +67 -0
  108. package/dist/lib/harness/console/console.d.ts.map +1 -0
  109. package/dist/lib/harness/console/console.js +373 -0
  110. package/dist/lib/harness/console/console.js.map +1 -0
  111. package/dist/lib/harness/console/console.test.d.ts +2 -0
  112. package/dist/lib/harness/console/console.test.d.ts.map +1 -0
  113. package/dist/lib/harness/console/console.test.js +269 -0
  114. package/dist/lib/harness/console/console.test.js.map +1 -0
  115. package/dist/lib/harness/console/decision-request.d.ts +32 -0
  116. package/dist/lib/harness/console/decision-request.d.ts.map +1 -0
  117. package/dist/lib/harness/console/decision-request.js +112 -0
  118. package/dist/lib/harness/console/decision-request.js.map +1 -0
  119. package/dist/lib/harness/console/decision-request.test.d.ts +2 -0
  120. package/dist/lib/harness/console/decision-request.test.d.ts.map +1 -0
  121. package/dist/lib/harness/console/decision-request.test.js +75 -0
  122. package/dist/lib/harness/console/decision-request.test.js.map +1 -0
  123. package/dist/lib/harness/console/fixtures.d.ts +16 -0
  124. package/dist/lib/harness/console/fixtures.d.ts.map +1 -0
  125. package/dist/lib/harness/console/fixtures.js +49 -0
  126. package/dist/lib/harness/console/fixtures.js.map +1 -0
  127. package/dist/lib/harness/console/index.d.ts +15 -0
  128. package/dist/lib/harness/console/index.d.ts.map +1 -0
  129. package/dist/lib/harness/console/index.js +14 -0
  130. package/dist/lib/harness/console/index.js.map +1 -0
  131. package/dist/lib/harness/console/rank.d.ts +73 -0
  132. package/dist/lib/harness/console/rank.d.ts.map +1 -0
  133. package/dist/lib/harness/console/rank.js +113 -0
  134. package/dist/lib/harness/console/rank.js.map +1 -0
  135. package/dist/lib/harness/console/rank.test.d.ts +2 -0
  136. package/dist/lib/harness/console/rank.test.d.ts.map +1 -0
  137. package/dist/lib/harness/console/rank.test.js +124 -0
  138. package/dist/lib/harness/console/rank.test.js.map +1 -0
  139. package/dist/lib/harness/console/render.d.ts +22 -0
  140. package/dist/lib/harness/console/render.d.ts.map +1 -0
  141. package/dist/lib/harness/console/render.js +65 -0
  142. package/dist/lib/harness/console/render.js.map +1 -0
  143. package/dist/lib/harness/console/render.test.d.ts +2 -0
  144. package/dist/lib/harness/console/render.test.d.ts.map +1 -0
  145. package/dist/lib/harness/console/render.test.js +96 -0
  146. package/dist/lib/harness/console/render.test.js.map +1 -0
  147. package/dist/lib/harness/console/replay-cli.test.d.ts +2 -0
  148. package/dist/lib/harness/console/replay-cli.test.d.ts.map +1 -0
  149. package/dist/lib/harness/console/replay-cli.test.js +96 -0
  150. package/dist/lib/harness/console/replay-cli.test.js.map +1 -0
  151. package/dist/lib/harness/console/replay.d.ts +36 -0
  152. package/dist/lib/harness/console/replay.d.ts.map +1 -0
  153. package/dist/lib/harness/console/replay.js +59 -0
  154. package/dist/lib/harness/console/replay.js.map +1 -0
  155. package/dist/lib/harness/console/replay.test.d.ts +2 -0
  156. package/dist/lib/harness/console/replay.test.d.ts.map +1 -0
  157. package/dist/lib/harness/console/replay.test.js +81 -0
  158. package/dist/lib/harness/console/replay.test.js.map +1 -0
  159. package/dist/lib/harness/console/turn-reader.d.ts +50 -0
  160. package/dist/lib/harness/console/turn-reader.d.ts.map +1 -0
  161. package/dist/lib/harness/console/turn-reader.js +184 -0
  162. package/dist/lib/harness/console/turn-reader.js.map +1 -0
  163. package/dist/lib/harness/console/turn-reader.test.d.ts +2 -0
  164. package/dist/lib/harness/console/turn-reader.test.d.ts.map +1 -0
  165. package/dist/lib/harness/console/turn-reader.test.js +108 -0
  166. package/dist/lib/harness/console/turn-reader.test.js.map +1 -0
  167. package/dist/lib/harness/console/types.d.ts +109 -0
  168. package/dist/lib/harness/console/types.d.ts.map +1 -0
  169. package/dist/lib/harness/console/types.js +2 -0
  170. package/dist/lib/harness/console/types.js.map +1 -0
  171. package/dist/lib/harness/contract.d.ts +229 -0
  172. package/dist/lib/harness/contract.d.ts.map +1 -0
  173. package/dist/lib/harness/contract.js +22 -0
  174. package/dist/lib/harness/contract.js.map +1 -0
  175. package/dist/lib/harness/credential.d.ts +23 -0
  176. package/dist/lib/harness/credential.d.ts.map +1 -0
  177. package/dist/lib/harness/credential.js +81 -0
  178. package/dist/lib/harness/credential.js.map +1 -0
  179. package/dist/lib/harness/credential.test.d.ts +2 -0
  180. package/dist/lib/harness/credential.test.d.ts.map +1 -0
  181. package/dist/lib/harness/credential.test.js +74 -0
  182. package/dist/lib/harness/credential.test.js.map +1 -0
  183. package/dist/lib/harness/evaluate.d.ts +390 -0
  184. package/dist/lib/harness/evaluate.d.ts.map +1 -0
  185. package/dist/lib/harness/evaluate.js +988 -0
  186. package/dist/lib/harness/evaluate.js.map +1 -0
  187. package/dist/lib/harness/evaluate.test.d.ts +2 -0
  188. package/dist/lib/harness/evaluate.test.d.ts.map +1 -0
  189. package/dist/lib/harness/evaluate.test.js +621 -0
  190. package/dist/lib/harness/evaluate.test.js.map +1 -0
  191. package/dist/lib/harness/extract.d.ts +152 -0
  192. package/dist/lib/harness/extract.d.ts.map +1 -0
  193. package/dist/lib/harness/extract.js +1601 -0
  194. package/dist/lib/harness/extract.js.map +1 -0
  195. package/dist/lib/harness/gate.d.ts +48 -0
  196. package/dist/lib/harness/gate.d.ts.map +1 -0
  197. package/dist/lib/harness/gate.js +60 -0
  198. package/dist/lib/harness/gate.js.map +1 -0
  199. package/dist/lib/harness/gate.test.d.ts +2 -0
  200. package/dist/lib/harness/gate.test.d.ts.map +1 -0
  201. package/dist/lib/harness/gate.test.js +111 -0
  202. package/dist/lib/harness/gate.test.js.map +1 -0
  203. package/dist/lib/harness/self-check.d.ts +59 -0
  204. package/dist/lib/harness/self-check.d.ts.map +1 -0
  205. package/dist/lib/harness/self-check.js +56 -0
  206. package/dist/lib/harness/self-check.js.map +1 -0
  207. package/dist/lib/harness/self-check.test.d.ts +2 -0
  208. package/dist/lib/harness/self-check.test.d.ts.map +1 -0
  209. package/dist/lib/harness/self-check.test.js +43 -0
  210. package/dist/lib/harness/self-check.test.js.map +1 -0
  211. package/dist/lib/harness/transcript.d.ts +65 -0
  212. package/dist/lib/harness/transcript.d.ts.map +1 -0
  213. package/dist/lib/harness/transcript.js +144 -0
  214. package/dist/lib/harness/transcript.js.map +1 -0
  215. package/dist/lib/harness/transcript.test.d.ts +2 -0
  216. package/dist/lib/harness/transcript.test.d.ts.map +1 -0
  217. package/dist/lib/harness/transcript.test.js +118 -0
  218. package/dist/lib/harness/transcript.test.js.map +1 -0
  219. package/dist/lib/harness-wiring.d.ts +145 -0
  220. package/dist/lib/harness-wiring.d.ts.map +1 -0
  221. package/dist/lib/harness-wiring.js +280 -0
  222. package/dist/lib/harness-wiring.js.map +1 -0
  223. package/dist/lib/report-format.d.ts +132 -0
  224. package/dist/lib/report-format.d.ts.map +1 -0
  225. package/dist/lib/report-format.js +317 -0
  226. package/dist/lib/report-format.js.map +1 -0
  227. package/dist/lib/standards.d.ts +90 -0
  228. package/dist/lib/standards.d.ts.map +1 -0
  229. package/dist/lib/standards.js +194 -0
  230. package/dist/lib/standards.js.map +1 -0
  231. package/dist/lib/templates.d.ts +26 -0
  232. package/dist/lib/templates.d.ts.map +1 -1
  233. package/dist/lib/templates.js +81 -3
  234. package/dist/lib/templates.js.map +1 -1
  235. package/dist/lib/terminal-ui.d.ts.map +1 -1
  236. package/dist/lib/terminal-ui.js +12 -1
  237. package/dist/lib/terminal-ui.js.map +1 -1
  238. package/dist/standards/decision-request.md +90 -0
  239. package/dist/standards/fail-loud-standard.md +495 -0
  240. package/dist/standards/report-format.md +120 -0
  241. package/dist/standards/writing-standard.md +240 -0
  242. package/package.json +3 -2
@@ -0,0 +1,270 @@
1
+ /**
2
+ * Which framework version is this project running? (#5371, A5.)
3
+ *
4
+ * Two numbers, and until now nothing printed either one:
5
+ * RUNNING — the version of the mx-agent CLI executing right now, read from the
6
+ * package.json that ships beside it. This is authoritative for "what code is
7
+ * making decisions in this session".
8
+ * PINNED — the version `.devcontainer/mx-agent-cli-version.pin` says this
9
+ * project's containers should install. This is authoritative for "what the
10
+ * project asked for".
11
+ *
12
+ * A MISMATCH is a real, previously invisible condition: someone ran
13
+ * `npm i -g @memnexus-ai/mx-agent-cli@latest` by hand, or the container has not
14
+ * been restarted since the pin moved. Before the pin existed the answer to
15
+ * "which framework version is this project running" was unobtainable, which is
16
+ * the gap this report closes.
17
+ *
18
+ * REPORT, NOT A GATE — READ THIS BEFORE ADDING AN EXIT CODE HERE.
19
+ * Nothing in this file returns or sets an exit code, and doctor's renderer must
20
+ * not derive one from it. `mx-agent doctor`'s exit code has exactly one owner,
21
+ * the fail-closed config-fidelity verdict (0 match / 1 drift / 2 undetermined) —
22
+ * see the header of commands/doctor.ts. A second contributor would make `$?`
23
+ * ambiguous: a caller seeing 1 could no longer tell "deployed .claude/ has
24
+ * drifted from source" from "this container is a release behind", and the
25
+ * fidelity gate is the one people are told to trust.
26
+ *
27
+ * The PARSER approximates the devcontainer scripts' behaviour and cannot equal
28
+ * it. Both scripts `.`-source the pin file as shell, so anything shell treats as
29
+ * an assignment sets the value; the regex below covers the plain, indented,
30
+ * `export` and `declare` forms and states what it cannot reach. A file with no
31
+ * matching line is NO_PIN, the same case the scripts refuse on, not a silent pass.
32
+ */
33
+ import { createRequire } from 'module';
34
+ import { execFileSync } from 'child_process';
35
+ import { existsSync, readFileSync } from 'fs';
36
+ import { dirname, join } from 'path';
37
+ import { fileURLToPath } from 'url';
38
+ const __dirname = dirname(fileURLToPath(import.meta.url));
39
+ const require = createRequire(import.meta.url);
40
+ /** Path of the pin file relative to a project root. Kept in one place so the
41
+ * doctor report, the new-project scaffold and the docs cannot drift apart. */
42
+ export const CLI_VERSION_PIN_RELPATH = '.devcontainer/mx-agent-cli-version.pin';
43
+ /**
44
+ * The assignment forms this parser can see. NOT all the forms `.`-sourcing honours.
45
+ *
46
+ * Covered: leading whitespace, `export VAR=`, `declare [-flags] VAR=`.
47
+ * NOT covered, and this is the honest limit rather than an oversight: a compound
48
+ * command that puts an assignment somewhere a line-anchored regex cannot reach —
49
+ * `:; MX_AGENT_CLI_VERSION=9.9.9`, `if true; then MX_AGENT_CLI_VERSION=9.9.9; fi`,
50
+ * a `$(...)` value, an assignment inside a sourced-from-here file. Closing those
51
+ * means implementing a shell parser for a file we are about to hand to a shell,
52
+ * and a parser that is nearly a shell is worse than one with a stated boundary.
53
+ *
54
+ * What the boundary costs: an uncovered form makes the parser see one assignment
55
+ * where the shell sees two, so doctor reports the FIRST value while the container
56
+ * installs the SECOND — and the MISMATCH line then tells the operator to install
57
+ * the version doctor believes is pinned, which post-start reverts on the next
58
+ * container start. The count check below catches every form listed as covered;
59
+ * it cannot catch the ones listed as not.
60
+ */
61
+ const PIN_ASSIGNMENT = /^[ \t]*(?:export[ \t]+|declare[ \t]+(?:-[a-zA-Z]+[ \t]+)*)?MX_AGENT_CLI_VERSION=(.+)$/gm;
62
+ /**
63
+ * Accepts `1.2.3` and `1.2.3-rc.1`; rejects `latest`, `^1.2.3`, `1.2`, empty.
64
+ *
65
+ * The devcontainer scripts carry a DELIBERATE SHELL TWIN of this pattern
66
+ * (`^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$` in post-create.sh, post-start.sh
67
+ * and the generated bootstrap in templates.ts). It has to be a twin rather than
68
+ * a shared constant because the scripts run before this CLI exists. Change one,
69
+ * change all four: a value this file calls "not a pin" while a script installs
70
+ * it is the exact gap that let `latest`, a range, a tarball URL and a
71
+ * `github:owner/repo` spec through the shell side.
72
+ *
73
+ * The twin is EXACT under the C and C.UTF-8 locales only (this container is
74
+ * C.UTF-8): bash's bracket ranges are locale-collated, so under en_US.UTF-8 a
75
+ * handful of values — fullwidth digits, Arabic-Indic digits, accented prerelease
76
+ * tags — are accepted by the shell and rejected here. None is a valid npm spec
77
+ * (a URL or git spec needs `:` and `/`, outside `[0-9A-Za-z.-]` in every locale),
78
+ * so the shell side ends in an E404, which is loud on both paths.
79
+ */
80
+ const CONCRETE_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
81
+ /**
82
+ * The version of the CLI executing right now.
83
+ *
84
+ * Same resolution as `src/index.ts` and `commands/update.ts`: the package.json
85
+ * that ships next to the built code, reached from this module's own URL. NOT the
86
+ * repo's checked-in package.json by path guesswork — a globally installed CLI has
87
+ * no repo, and this must answer in that case above all, since that is how every
88
+ * consumer team runs it.
89
+ *
90
+ * Returns null rather than throwing: a diagnostic must not be able to fail the
91
+ * command it is diagnosing.
92
+ */
93
+ export function runningCliVersion() {
94
+ try {
95
+ const pkg = require(join(__dirname, '../../package.json'));
96
+ return typeof pkg.version === 'string' && pkg.version.length > 0 ? pkg.version : null;
97
+ }
98
+ catch {
99
+ return null;
100
+ }
101
+ }
102
+ /**
103
+ * Every `MX_AGENT_CLI_VERSION=` assignment in a pin file's text, in file order.
104
+ *
105
+ * Exported because the COUNT is the interesting part. Shell `.`-sourcing honours
106
+ * the LAST assignment; this parser used to return the FIRST, so a two-line pin
107
+ * file made doctor report one version while the devcontainer installed another —
108
+ * the report concealing the very value it exists to surface.
109
+ */
110
+ export function pinAssignments(text) {
111
+ return [...text.matchAll(PIN_ASSIGNMENT)].map((m) => m[1].trim());
112
+ }
113
+ /**
114
+ * Parse a pin file's TEXT. Exported so the parser is testable without a filesystem.
115
+ *
116
+ * TWO assignments is a REFUSAL, not a choice. The shell would take the last one,
117
+ * so that is the value reported in the error text (see readPinnedCliVersion), but
118
+ * a file that says two different things is not a pin and reporting either value as
119
+ * "the pin" would be a claim this parser cannot support. Null here means doctor
120
+ * prints NOT PINNED, which is the loud direction.
121
+ */
122
+ export function parsePinnedVersion(text) {
123
+ const values = pinAssignments(text);
124
+ if (values.length !== 1)
125
+ return null;
126
+ const value = values[0];
127
+ return CONCRETE_VERSION.test(value) ? value : null;
128
+ }
129
+ /** Read the pin for a project root. Never throws. */
130
+ export function readPinnedCliVersion(projectRoot) {
131
+ const path = join(projectRoot, CLI_VERSION_PIN_RELPATH);
132
+ if (!existsSync(path)) {
133
+ return { version: null, path, error: 'no pin file — this project does not pin its framework version' };
134
+ }
135
+ let text;
136
+ try {
137
+ text = readFileSync(path, 'utf-8');
138
+ }
139
+ catch (e) {
140
+ return { version: null, path, error: `pin file unreadable: ${e.message}` };
141
+ }
142
+ const version = parsePinnedVersion(text);
143
+ if (version)
144
+ return { version, path, error: null };
145
+ // Name the ambiguous case explicitly. "no parseable line" would be false and
146
+ // would send someone looking for a missing line in a file that has two.
147
+ const assignments = pinAssignments(text);
148
+ if (assignments.length > 1) {
149
+ return {
150
+ version: null,
151
+ path,
152
+ error: `pin file has ${assignments.length} MX_AGENT_CLI_VERSION assignments — the devcontainer scripts source it as ` +
153
+ `shell and would install the LAST one (${assignments[assignments.length - 1]}). Refusing to report either as the pin; ` +
154
+ `leave exactly one.`,
155
+ };
156
+ }
157
+ return { version: null, path, error: 'pin file has no parseable MX_AGENT_CLI_VERSION=<x.y.z> line' };
158
+ }
159
+ export function collectFrameworkVersion(projectRoot) {
160
+ const running = runningCliVersion();
161
+ const pin = readPinnedCliVersion(projectRoot);
162
+ let status;
163
+ if (running === null)
164
+ status = 'UNKNOWN';
165
+ else if (pin.version === null)
166
+ status = 'NO_PIN';
167
+ else
168
+ status = pin.version === running ? 'MATCH' : 'MISMATCH';
169
+ return { running, pinned: pin.version, pinPath: pin.path, pinError: pin.error, status };
170
+ }
171
+ const REGISTRY_PACKAGE = '@memnexus-ai/mx-agent-cli';
172
+ const REGISTRY_TIMEOUT_MS = 5000;
173
+ /**
174
+ * Exported for the bound test only — production callers get it as the default
175
+ * argument of checkPinAgainstRegistry.
176
+ *
177
+ * `killSignal: 'SIGKILL'` is what makes REGISTRY_TIMEOUT_MS a bound rather than a
178
+ * hint. `timeout` alone sends SIGTERM and then keeps waiting for the child to
179
+ * exit: measured against an npm that ignores SIGTERM, this call took 66,682 ms
180
+ * against a documented 5-second limit. With SIGKILL the same case is 5,005 ms,
181
+ * including when npm exits immediately but leaves a grandchild holding the stdout
182
+ * pipe (5,003 ms).
183
+ */
184
+ export function defaultRegistryReader() {
185
+ return execFileSync('npm', ['view', REGISTRY_PACKAGE, 'dist-tags.latest', 'versions', '--json'], {
186
+ encoding: 'utf-8',
187
+ timeout: REGISTRY_TIMEOUT_MS,
188
+ killSignal: 'SIGKILL',
189
+ stdio: ['ignore', 'pipe', 'pipe'],
190
+ });
191
+ }
192
+ export function checkPinAgainstRegistry(pinned, read = defaultRegistryReader) {
193
+ if (!pinned)
194
+ return null; // nothing to compare a pin against
195
+ if (process.env.MX_AGENT_DOCTOR_NO_NETWORK === '1') {
196
+ return { latest: null, pinnedIsPublished: null, error: 'skipped (MX_AGENT_DOCTOR_NO_NETWORK=1)' };
197
+ }
198
+ let parsed;
199
+ try {
200
+ parsed = JSON.parse(read());
201
+ }
202
+ catch (e) {
203
+ return { latest: null, pinnedIsPublished: null, error: `registry unreachable or unreadable: ${e.message}` };
204
+ }
205
+ const obj = parsed;
206
+ const latest = typeof obj['dist-tags.latest'] === 'string' ? obj['dist-tags.latest'] : null;
207
+ const versions = Array.isArray(obj.versions) ? obj.versions.filter((v) => typeof v === 'string') : null;
208
+ if (latest === null && versions === null) {
209
+ return { latest: null, pinnedIsPublished: null, error: 'registry returned no version fields' };
210
+ }
211
+ return { latest, pinnedIsPublished: versions ? versions.includes(pinned) : null, error: null };
212
+ }
213
+ /** Advisory lines appended to the framework-version report. Never a verdict. */
214
+ export function describePinRegistryStatus(pinned, s) {
215
+ if (!pinned || !s)
216
+ return [];
217
+ if (s.error)
218
+ return [` registry: not checked — ${s.error} (advisory only; does not affect the exit code)`];
219
+ if (s.pinnedIsPublished === false) {
220
+ return [
221
+ ` registry: pin ${pinned} is NOT published — withdrawn, unpublished, or a typo.`,
222
+ ` A devcontainer REBUILD will fail with E404 at post-create; a restart keeps the installed version and warns.`,
223
+ ];
224
+ }
225
+ if (s.latest && s.latest !== pinned) {
226
+ return [
227
+ ` registry: pin ${pinned} is behind latest ${s.latest}.`,
228
+ ` A pin does not update itself — moving ${CLI_VERSION_PIN_RELPATH} is how a release reaches the fleet.`,
229
+ ];
230
+ }
231
+ if (s.latest)
232
+ return [` registry: pin ${pinned} is the latest published version.`];
233
+ return [];
234
+ }
235
+ /**
236
+ * Human lines. First line is the headline; the rest is detail.
237
+ *
238
+ * The MISMATCH text names the remedy, because the remedy is not obvious: the fix
239
+ * is to install the pinned version, NOT to move the pin to whatever happens to be
240
+ * installed. Bumping a pin to silence a mismatch is the same defect the codex pin's
241
+ * header calls out.
242
+ */
243
+ export function describeFrameworkVersion(r) {
244
+ const running = r.running ?? 'unknown';
245
+ switch (r.status) {
246
+ case 'MATCH':
247
+ return [`Framework version: ${running} (matches the pin)`, ` pin: ${r.pinPath}`];
248
+ case 'MISMATCH':
249
+ return [
250
+ `Framework version: MISMATCH — running ${running}, pinned ${r.pinned}`,
251
+ ` pin: ${r.pinPath}`,
252
+ ` This container is not running the version the project pins. To fix the container:`,
253
+ ` npm install -g @memnexus-ai/mx-agent-cli@${r.pinned}`,
254
+ ` To roll the fleet forward instead, move the pin deliberately — do not edit it to match what is installed.`,
255
+ ` Advisory: this does not affect the exit code (the config-fidelity verdict owns it).`,
256
+ ];
257
+ case 'NO_PIN':
258
+ return [
259
+ `Framework version: ${running} — NOT PINNED`,
260
+ ` ${r.pinError ?? 'no pin'} (${r.pinPath})`,
261
+ ` Without a pin, a container restart can install a different framework version (#5371).`,
262
+ ];
263
+ default:
264
+ return [
265
+ `Framework version: unknown — could not read the running CLI's package.json`,
266
+ ` pin: ${r.pinned ?? 'not read'} (${r.pinPath})`,
267
+ ];
268
+ }
269
+ }
270
+ //# sourceMappingURL=framework-version.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"framework-version.js","sourceRoot":"","sources":["../../src/lib/framework-version.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,45 @@
1
+ /**
2
+ * Saying it out loud.
3
+ *
4
+ * `FleetConsole` already classifies, ranks and pushes: `subscribe` fires with
5
+ * what appeared and what cleared, and it only computes when somebody is
6
+ * listening. Until now nothing subscribed, so a live session built a perfectly
7
+ * good list of things needing a person and showed it to nobody. The milestone
8
+ * asks that a refusal reach the operator without them going to look, and this
9
+ * is the missing half of that sentence.
10
+ *
11
+ * WHAT IT PRINTS AND WHAT IT WITHHOLDS. Only what is new. Reprinting the whole
12
+ * list on every change is the fastest way to teach someone to skim past it, and
13
+ * POC-3 measured the cost of a console that reports quiet while things go
14
+ * wrong: three of eight moments reached the operator. So new items announce,
15
+ * cleared items say so in one line, and an unchanged list says nothing at all.
16
+ *
17
+ * CONFIDENCE IS SHOWN, NOT FLATTENED. Items read out of an agent's prose are
18
+ * marked. POC-3b measured a post-hoc reader at about a third of what matters,
19
+ * unstably, and POC-3e showed a better model does not fix it. Presenting that
20
+ * beside a guard refusal as though they carry the same weight would be a claim
21
+ * neither measurement supports.
22
+ */
23
+ import type { ConsoleItem } from './types.js';
24
+ import type { FleetConsole } from './console.js';
25
+ export interface AnnounceOptions {
26
+ /** Where the lines go. Injected so this is testable and so a caller can
27
+ * route it somewhere other than the session's own output. */
28
+ write: (line: string) => void;
29
+ /** Announce items the console cannot vouch for. On by default: they are the
30
+ * largest category by far, 276 of 325 in a measured week. */
31
+ includeLowConfidence?: boolean;
32
+ /** Most items to announce in one change. A burst larger than this is
33
+ * summarised rather than printed, because a wall is not a notification. */
34
+ maxPerChange?: number;
35
+ }
36
+ /** One item, as two lines: what it is, and the evidence for it. */
37
+ export declare function renderAnnouncement(item: ConsoleItem): string[];
38
+ /**
39
+ * Subscribe to a console and print what appears.
40
+ *
41
+ * Returns the unsubscribe function, so a session can stop announcing without
42
+ * tearing down the console that other sessions are still feeding.
43
+ */
44
+ export declare function attachAnnouncer(fleet: FleetConsole, options: AnnounceOptions): () => void;
45
+ //# sourceMappingURL=announce.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"announce.d.ts","sourceRoot":"","sources":["../../../../src/lib/harness/console/announce.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAiB,WAAW,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,MAAM,WAAW,eAAe;IAC9B;kEAC8D;IAC9D,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B;kEAC8D;IAC9D,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;gFAC4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAOD,mEAAmE;AACnE,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,EAAE,CAS9D;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,eAAe,GAAG,MAAM,IAAI,CAyBzF"}
@@ -0,0 +1,48 @@
1
+ const clip = (s, n = 110) => {
2
+ const line = String(s ?? '').replace(/\s+/g, ' ').trim();
3
+ return line.length > n ? line.slice(0, n).trimEnd() + '…' : line;
4
+ };
5
+ /** One item, as two lines: what it is, and the evidence for it. */
6
+ export function renderAnnouncement(item) {
7
+ const mark = item.lowConfidence ? ' (unverified, read from the agent\'s own words)' : '';
8
+ const lines = [` NEEDS YOU ${item.kind} ${item.principal.team}${mark}`];
9
+ lines.push(` ${clip(item.headline, 120)}`);
10
+ // Two detail lines, not one. For a refusal the first is the rule and the
11
+ // second is the reason, and the reason is the half a person needs to decide
12
+ // whether the rule was wrong or the attempt was.
13
+ for (const d of (item.detail ?? []).slice(0, 2))
14
+ lines.push(` ${clip(d)}`);
15
+ return lines;
16
+ }
17
+ /**
18
+ * Subscribe to a console and print what appears.
19
+ *
20
+ * Returns the unsubscribe function, so a session can stop announcing without
21
+ * tearing down the console that other sessions are still feeding.
22
+ */
23
+ export function attachAnnouncer(fleet, options) {
24
+ const { write } = options;
25
+ const includeLow = options.includeLowConfidence !== false;
26
+ const maxPerChange = options.maxPerChange ?? 3;
27
+ return fleet.subscribe((change) => {
28
+ const added = change.added.filter((i) => includeLow || i.lowConfidence !== true);
29
+ if (added.length > 0) {
30
+ write('');
31
+ const shown = added.slice(0, maxPerChange);
32
+ for (const item of shown)
33
+ for (const line of renderAnnouncement(item))
34
+ write(line);
35
+ if (added.length > shown.length) {
36
+ write(` and ${added.length - shown.length} more. Run \`mx-agent console\` for the list.`);
37
+ }
38
+ write('');
39
+ return;
40
+ }
41
+ // Nothing new. A cleared item is worth one line, because an operator who
42
+ // was told about something is owed the news that it went away.
43
+ if (change.removed.length > 0) {
44
+ write(` cleared: ${change.removed.length} item(s) no longer need you.`);
45
+ }
46
+ });
47
+ }
48
+ //# sourceMappingURL=announce.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"announce.js","sourceRoot":"","sources":["../../../../src/lib/harness/console/announce.ts"],"names":[],"mappings":"AAqCA,MAAM,IAAI,GAAG,CAAC,CAAS,EAAE,CAAC,GAAG,GAAG,EAAU,EAAE;IAC1C,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACzD,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AACnE,CAAC,CAAC;AAEF,mEAAmE;AACnE,MAAM,UAAU,kBAAkB,CAAC,IAAiB;IAClD,MAAM,IAAI,GAAG,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,iDAAiD,CAAC,CAAC,CAAC,EAAE,CAAC;IACzF,MAAM,KAAK,GAAG,CAAC,gBAAgB,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,SAAS,CAAC,IAAI,GAAG,IAAI,EAAE,CAAC,CAAC;IAC3E,KAAK,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;IAC9C,yEAAyE;IACzE,4EAA4E;IAC5E,iDAAiD;IACjD,KAAK,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC9E,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,KAAmB,EAAE,OAAwB;IAC3E,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;IAC1B,MAAM,UAAU,GAAG,OAAO,CAAC,oBAAoB,KAAK,KAAK,CAAC;IAC1D,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,CAAC,CAAC;IAE/C,OAAO,KAAK,CAAC,SAAS,CAAC,CAAC,MAAqB,EAAE,EAAE;QAC/C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,IAAI,CAAC,CAAC,aAAa,KAAK,IAAI,CAAC,CAAC;QAEjF,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,KAAK,CAAC,EAAE,CAAC,CAAC;YACV,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;YAC3C,KAAK,MAAM,IAAI,IAAI,KAAK;gBAAE,KAAK,MAAM,IAAI,IAAI,kBAAkB,CAAC,IAAI,CAAC;oBAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YACnF,IAAI,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;gBAChC,KAAK,CAAC,SAAS,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,+CAA+C,CAAC,CAAC;YAC7F,CAAC;YACD,KAAK,CAAC,EAAE,CAAC,CAAC;YACV,OAAO;QACT,CAAC;QAED,yEAAyE;QACzE,+DAA+D;QAC/D,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC9B,KAAK,CAAC,cAAc,MAAM,CAAC,OAAO,CAAC,MAAM,8BAA8B,CAAC,CAAC;QAC3E,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC"}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=announce.test.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"announce.test.d.ts","sourceRoot":"","sources":["../../../../src/lib/harness/console/announce.test.ts"],"names":[],"mappings":""}
@@ -0,0 +1,104 @@
1
+ import { describe, it, expect } from 'vitest';
2
+ import { FleetConsole } from './console.js';
3
+ import { attachAnnouncer, renderAnnouncement } from './announce.js';
4
+ const principal = { team: 'product', role: 'lead', subagentId: null, sessionId: 's1' };
5
+ const at = (n) => new Date(Date.UTC(2026, 7, 18, 10, n)).toISOString();
6
+ const refusal = (n, session = 's1') => ({
7
+ type: 'decision',
8
+ at: at(n),
9
+ principal: { ...principal, sessionId: session },
10
+ attrs: { operation: 'write', writes: ['/workspace/other/x.ts'], reads: [], uncertain: false },
11
+ decision: { effect: 'deny', matchedRules: ['no-write-outside'], reason: 'outside the worktree' },
12
+ });
13
+ function harness() {
14
+ const lines = [];
15
+ const fleet = new FleetConsole();
16
+ const stop = attachAnnouncer(fleet, { write: (l) => lines.push(l) });
17
+ return { fleet, lines, stop, out: () => lines.join('\n') };
18
+ }
19
+ describe('attachAnnouncer', () => {
20
+ it('says nothing until something needs a person', () => {
21
+ const h = harness();
22
+ h.fleet.emit({ type: 'session-start', at: at(0), principal, credential: { kind: 'subscription', source: 'x' } });
23
+ h.fleet.emit({ type: 'turn', at: at(1), principal, text: 'working on it', turnIndex: 1 });
24
+ expect(h.out()).toBe('');
25
+ });
26
+ it('announces a refusal without anybody asking', () => {
27
+ const h = harness();
28
+ h.fleet.emit(refusal(2));
29
+ expect(h.out()).toContain('NEEDS YOU');
30
+ expect(h.out()).toContain('product');
31
+ expect(h.out()).toContain('outside the worktree');
32
+ });
33
+ it('does not repeat an item it has already announced', () => {
34
+ const h = harness();
35
+ h.fleet.emit(refusal(2));
36
+ const first = h.lines.length;
37
+ h.fleet.emit({ type: 'turn', at: at(3), principal, text: 'still going', turnIndex: 2 });
38
+ expect(h.lines.length).toBe(first);
39
+ });
40
+ // The console notifies per event, so `added` holds one item almost always and
41
+ // the burst path is defensive rather than routine. Asserted through the
42
+ // subscriber directly, because driving six events produces six changes of one
43
+ // rather than one change of six.
44
+ it('summarises a burst rather than printing a wall', () => {
45
+ const lines = [];
46
+ const fleet = new FleetConsole();
47
+ let captured = null;
48
+ const original = fleet.subscribe.bind(fleet);
49
+ fleet.subscribe = ((fn) => { captured = fn; return original(fn); });
50
+ attachAnnouncer(fleet, { write: (l) => lines.push(l) });
51
+ const item = (n) => ({
52
+ id: `i${n}`, kind: 'refusal', sessionId: `s${n}`, principal, at: at(n), score: 900,
53
+ headline: `refusal ${n}`, detail: [], repeats: 1,
54
+ });
55
+ captured({ items: [], added: [1, 2, 3, 4, 5, 6].map(item), removed: [] });
56
+ expect(lines.join('\n')).toContain('more. Run `mx-agent console`');
57
+ });
58
+ // A session ending adds a `stopped` item, which is itself something a person
59
+ // may need. So the correct behaviour after session-end is a new announcement
60
+ // about the stop, not silence. The property that matters is that the original
61
+ // refusal is not announced a second time.
62
+ it('announces a stop as its own item, without repeating what it already said', () => {
63
+ const h = harness();
64
+ h.fleet.emit(refusal(2));
65
+ expect(h.out()).toContain('outside the worktree');
66
+ h.lines.length = 0;
67
+ h.fleet.emit({ type: 'session-end', at: at(9), principal, reason: 'finished' });
68
+ expect(h.out()).not.toContain('outside the worktree');
69
+ });
70
+ it('stops when unsubscribed', () => {
71
+ const h = harness();
72
+ h.stop();
73
+ h.fleet.emit(refusal(2));
74
+ expect(h.out()).toBe('');
75
+ });
76
+ it('can withhold items the console cannot vouch for', () => {
77
+ const lines = [];
78
+ const fleet = new FleetConsole();
79
+ attachAnnouncer(fleet, { write: (l) => lines.push(l), includeLowConfidence: false });
80
+ fleet.emit({
81
+ type: 'turn', at: at(2), principal,
82
+ text: 'This one needs your decision, and I did not ask.', turnIndex: 1,
83
+ });
84
+ expect(lines.join('\n')).not.toContain('NEEDS YOU');
85
+ });
86
+ });
87
+ describe('renderAnnouncement', () => {
88
+ it('marks an item read from prose as unverified', () => {
89
+ const out = renderAnnouncement({
90
+ id: 'x', kind: 'prose', sessionId: 's1', principal, at: at(1), score: 100,
91
+ headline: 'the agent says a decision is needed', detail: ['turn 12'], repeats: 1,
92
+ lowConfidence: true,
93
+ }).join('\n');
94
+ expect(out).toContain('unverified');
95
+ });
96
+ it('does not mark a guard refusal as unverified', () => {
97
+ const out = renderAnnouncement({
98
+ id: 'y', kind: 'refusal', sessionId: 's1', principal, at: at(1), score: 900,
99
+ headline: 'a guard refused a write', detail: ['rule: no-write-outside'], repeats: 1,
100
+ }).join('\n');
101
+ expect(out).not.toContain('unverified');
102
+ });
103
+ });
104
+ //# sourceMappingURL=announce.test.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"announce.test.js","sourceRoot":"","sources":["../../../../src/lib/harness/console/announce.test.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,50 @@
1
+ /**
2
+ * One row per session instead of one per moment.
3
+ *
4
+ * A week of real fleet work produced 411 ranked items across 47 sessions. As a
5
+ * list of moments that is unreadable, and one session appeared nine times, once
6
+ * with a repeat count of 44. The operator's question is not "what happened",
7
+ * it is "does this team need me", and that question has one answer per team.
8
+ *
9
+ * So a row is a session, showing its worst open item and a count of the rest.
10
+ * The detail stays reachable rather than discarded, because the moment the
11
+ * operator decides a team needs them, the next thing they want is everything
12
+ * that team is holding.
13
+ *
14
+ * Chosen on 2026-08-18 with the product owner's agreement to pick and iterate.
15
+ * The alternative, one row per moment, is still available: it is the ungrouped
16
+ * `snapshot()` this builds on.
17
+ */
18
+ import type { ConsoleItem, ItemKind } from './types.js';
19
+ export interface SessionRow {
20
+ sessionId: string;
21
+ team: string;
22
+ /** Highest-consequence open item. The row is sorted by this item's score. */
23
+ top: ConsoleItem;
24
+ /** Everything else this session is holding, worst first. */
25
+ rest: ConsoleItem[];
26
+ /** How many items in total, including `top`. */
27
+ total: number;
28
+ /** Counts by kind, so a row can say what shape the backlog is. */
29
+ byKind: Partial<Record<ItemKind, number>>;
30
+ /** The most recent item's timestamp, for age. */
31
+ latest: string;
32
+ /** True when every item is one the console cannot vouch for. */
33
+ allLowConfidence: boolean;
34
+ }
35
+ /**
36
+ * Group ranked items into one row per session.
37
+ *
38
+ * Order is by the worst item in each session, not by the count. A session with
39
+ * one refusal outranks a session with nine pieces of prose, because ranking by
40
+ * volume would put the noisiest team at the top rather than the one in trouble.
41
+ */
42
+ export declare function groupBySession(items: ConsoleItem[]): SessionRow[];
43
+ export interface SessionRenderOptions {
44
+ limit?: number;
45
+ /** Show the other items under each row. Off by default: the point of the row
46
+ * is to be scannable, and the detail is one keystroke away in a real UI. */
47
+ expand?: boolean;
48
+ }
49
+ export declare function renderSessions(rows: SessionRow[], options?: SessionRenderOptions): string;
50
+ //# sourceMappingURL=by-session.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"by-session.d.ts","sourceRoot":"","sources":["../../../../src/lib/harness/console/by-session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAExD,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,GAAG,EAAE,WAAW,CAAC;IACjB,4DAA4D;IAC5D,IAAI,EAAE,WAAW,EAAE,CAAC;IACpB,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;IAC1C,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,UAAU,EAAE,CA0BjE;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;iFAC6E;IAC7E,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAcD,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,OAAO,GAAE,oBAAyB,GAAG,MAAM,CAiC7F"}
@@ -0,0 +1,83 @@
1
+ /**
2
+ * Group ranked items into one row per session.
3
+ *
4
+ * Order is by the worst item in each session, not by the count. A session with
5
+ * one refusal outranks a session with nine pieces of prose, because ranking by
6
+ * volume would put the noisiest team at the top rather than the one in trouble.
7
+ */
8
+ export function groupBySession(items) {
9
+ const bySession = new Map();
10
+ for (const item of items) {
11
+ const list = bySession.get(item.sessionId);
12
+ if (list)
13
+ list.push(item);
14
+ else
15
+ bySession.set(item.sessionId, [item]);
16
+ }
17
+ const rows = [];
18
+ for (const [sessionId, group] of bySession) {
19
+ const sorted = [...group].sort((a, b) => b.score - a.score || b.at.localeCompare(a.at));
20
+ const byKind = {};
21
+ for (const i of sorted)
22
+ byKind[i.kind] = (byKind[i.kind] ?? 0) + 1;
23
+ rows.push({
24
+ sessionId,
25
+ team: sorted[0].principal.team,
26
+ top: sorted[0],
27
+ rest: sorted.slice(1),
28
+ total: sorted.length,
29
+ byKind,
30
+ latest: sorted.reduce((m, i) => (i.at > m ? i.at : m), sorted[0].at),
31
+ allLowConfidence: sorted.every((i) => i.lowConfidence === true),
32
+ });
33
+ }
34
+ return rows.sort((a, b) => b.top.score - a.top.score || b.latest.localeCompare(a.latest));
35
+ }
36
+ /**
37
+ * Render the rows.
38
+ *
39
+ * Empty string when there is nothing, for the same reason the item renderer
40
+ * does it: a console that prints a header over an empty list trains the reader
41
+ * to skip the header.
42
+ */
43
+ const clip = (s, n = 150) => {
44
+ const oneLine = s.replace(/\s+/g, ' ').trim();
45
+ return oneLine.length > n ? oneLine.slice(0, n).trimEnd() + '…' : oneLine;
46
+ };
47
+ export function renderSessions(rows, options = {}) {
48
+ if (rows.length === 0)
49
+ return '';
50
+ const limit = options.limit ?? 20;
51
+ const shown = rows.slice(0, limit);
52
+ const lines = [`TEAMS NEEDING YOU (${rows.length})`, ''];
53
+ shown.forEach((r, n) => {
54
+ const others = r.total - 1;
55
+ const tail = others > 0 ? ` +${others} more` : '';
56
+ const doubt = r.allLowConfidence ? ' (all unverified)' : '';
57
+ lines.push(`${String(n + 1).padStart(2)} ${r.team.padEnd(22)} ${r.top.kind.padEnd(9)}${tail}${doubt}`);
58
+ lines.push(` ${clip(r.top.headline, 120)}`);
59
+ // Detail is for scanning. One recorded hook message ran to several thousand
60
+ // words of forwarded queue traffic, which pushed every other row off the
61
+ // screen. A row that cannot be scanned is not a row.
62
+ for (const d of r.top.detail.slice(0, 2))
63
+ lines.push(` ${clip(d)}`);
64
+ if (others > 0) {
65
+ const summary = Object.entries(r.byKind)
66
+ .filter(([k]) => k !== r.top.kind || (r.byKind[r.top.kind] ?? 0) > 1)
67
+ .map(([k, n2]) => `${n2} ${k}`)
68
+ .join(', ');
69
+ if (summary)
70
+ lines.push(` also holding: ${summary}`);
71
+ }
72
+ if (options.expand) {
73
+ for (const item of r.rest)
74
+ lines.push(` - ${item.kind}: ${clip(item.headline, 110)}`);
75
+ }
76
+ lines.push('');
77
+ });
78
+ if (rows.length > shown.length) {
79
+ lines.push(` ${rows.length - shown.length} more teams not shown.`);
80
+ }
81
+ return lines.join('\n');
82
+ }
83
+ //# sourceMappingURL=by-session.js.map