@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,280 @@
1
+ /**
2
+ * Connects the harness to a live session.
3
+ *
4
+ * `agent-session.ts` drives an Agent SDK loop and owns terminal input, the
5
+ * message bus and the resume cycle. This file owns everything between a tool
6
+ * call and a permission result, so that the session file holds no policy and
7
+ * this file holds no SDK.
8
+ *
9
+ * What it composes, all of which existed and none of which ran:
10
+ *
11
+ * credential.ts refuses to start a session that would bill as metered
12
+ * self-check.ts refuses to start when the callback would be shadowed, and
13
+ * proves afterwards that it fired
14
+ * evaluate.ts compiles the rules and decides
15
+ * extract.ts turns a tool call into what it would touch
16
+ * gate.ts joins them and fails closed
17
+ *
18
+ * Three decisions this file makes, each with the measurement behind it.
19
+ *
20
+ * **It replaces `checkWorktreeGuard`.** That function refused 28.6% of the
21
+ * commands it exists to refuse (`docs/guard-coverage.md`). Through this path
22
+ * the same 2,043 commands produce 50.1% (`scripts/gate-coverage.mjs`).
23
+ *
24
+ * **A session-level observe mode exists and is not the default.** Observe
25
+ * records the decision and runs the call. It is at the session edge rather than
26
+ * in the ruleset because flipping `mode` on a `RuleSource` contradicts that
27
+ * rule's own examples and the compiler refuses the ruleset.
28
+ *
29
+ * **`ask` asks.** `gate.ts` maps `ask` to deny because no rule may become an
30
+ * allow through nobody being present. This session has a person at a terminal,
31
+ * so the effect reaches them as a question. With no terminal it stays a deny.
32
+ */
33
+ import chalk from 'chalk';
34
+ import { createGate } from './harness/gate.js';
35
+ import { extractor, hostAbsolute } from './harness/extract.js';
36
+ import { compileRuleset, RulesetRefused, STARTER_RULES, } from './harness/evaluate.js';
37
+ import { checkCallbackReachable, ProbeSelfCheck } from './harness/self-check.js';
38
+ import { checkCredential, refuseToStart } from './harness/credential.js';
39
+ /** The surface a permission callback is. Rules that name no other surface can
40
+ * only run here, and rules that do not name this one never reach it. */
41
+ export const SESSION_SURFACE = 'permission-callback';
42
+ /** Files that define policy. The rules refuse to compile when this list does
43
+ * not cover the paths their own examples name, which is how a wrong context is
44
+ * found at startup rather than by a rule silently never firing. */
45
+ export function governingRulePaths(repoRoot, worktreeRoot) {
46
+ const under = (root) => [
47
+ `${root}/.claude/settings.json`,
48
+ `${root}/.claude/hooks/**`,
49
+ `${root}/.claude/rules/**`,
50
+ `${root}/.mx-agent/**`,
51
+ ];
52
+ return repoRoot === worktreeRoot ? under(repoRoot) : [...under(repoRoot), ...under(worktreeRoot)];
53
+ }
54
+ export function policyContext(repoRoot, worktreeRoot, testGuardedPaths = [], scratchRoots) {
55
+ return {
56
+ worktreeRoot,
57
+ repoRoot,
58
+ governingRulePaths: governingRulePaths(repoRoot, worktreeRoot),
59
+ testGuardedPaths,
60
+ ...(scratchRoots ? { scratchRoots } : {}),
61
+ };
62
+ }
63
+ /**
64
+ * The rules this surface can enforce.
65
+ *
66
+ * A rule that names only `integration-lane` is not a rule this session is
67
+ * failing to run, it is a rule for a component that is not built. Selecting by
68
+ * surface keeps that distinction, and it also keeps the compiler from refusing
69
+ * the whole ruleset over a rule whose path token a project left empty.
70
+ */
71
+ export function rulesForSurface(rules = STARTER_RULES) {
72
+ return rules.filter((r) => r.surfaces.includes(SESSION_SURFACE));
73
+ }
74
+ /**
75
+ * Everything that has to be true before the first tool call.
76
+ *
77
+ * All three checks run even when the first one fails, so the operator sees
78
+ * every reason at once instead of fixing them one session at a time.
79
+ */
80
+ export function prepareHarness(input) {
81
+ const lines = [];
82
+ let ok = true;
83
+ const credential = checkCredential({
84
+ env: input.env,
85
+ ...(input.credentialsFile ? { credentialsFile: input.credentialsFile } : {}),
86
+ });
87
+ const billing = refuseToStart(credential, { allowMetered: input.allowMetered === true });
88
+ if (billing.refuse) {
89
+ ok = false;
90
+ lines.push(...(billing.message ?? '').split('\n'));
91
+ }
92
+ else if (credential.kind === 'api-key') {
93
+ lines.push(` [harness] metered billing accepted by --allow-metered (${credential.source})`);
94
+ }
95
+ const reachable = checkCallbackReachable({
96
+ ...(input.permissionMode !== undefined ? { permissionMode: input.permissionMode } : {}),
97
+ canUseToolSupplied: input.canUseToolSupplied,
98
+ });
99
+ if (!reachable.ok) {
100
+ ok = false;
101
+ lines.push(...(reachable.message ?? '').split('\n'));
102
+ }
103
+ const selected = rulesForSurface(input.rules ?? STARTER_RULES);
104
+ const withheld = (input.rules ?? STARTER_RULES).filter((r) => !selected.includes(r));
105
+ let evaluator;
106
+ try {
107
+ evaluator = compileRuleset(selected, policyContext(input.repoRoot, input.worktreeRoot, input.testGuardedPaths ?? [], input.scratchRoots));
108
+ }
109
+ catch (err) {
110
+ ok = false;
111
+ if (err instanceof RulesetRefused) {
112
+ lines.push(' Refusing to start: the ruleset did not compile, so no rule would run.');
113
+ for (const r of err.refusals)
114
+ lines.push(` ${r.ruleId} [${r.code}]: ${r.detail}`);
115
+ }
116
+ else {
117
+ lines.push(` Refusing to start: the ruleset threw: ${err instanceof Error ? err.message : String(err)}`);
118
+ }
119
+ }
120
+ const notEnforcedHere = evaluator ? evaluator.unenforceableOn(SESSION_SURFACE) : [];
121
+ if (evaluator) {
122
+ lines.push(` [harness] enforcing ${evaluator.ruleIds.length} rule(s) on ${SESSION_SURFACE}: ${evaluator.ruleIds.join(', ')}`);
123
+ for (const r of withheld) {
124
+ lines.push(` [harness] not enforced here: ${r.id} (needs ${r.surfaces.join(' or ')})`);
125
+ }
126
+ for (const r of notEnforcedHere) {
127
+ lines.push(` [harness] holds but cannot enforce on this surface: ${r.id}`);
128
+ }
129
+ // The compiler's warnings are things a rule author could not be refused
130
+ // for and an operator should still know. Printing them at startup is the
131
+ // only place they reach anyone.
132
+ for (const w of evaluator.warnings) {
133
+ lines.push(` [harness] note on ${w.ruleId}: ${w.detail}`);
134
+ }
135
+ // A worktree named by a drive letter or a UNC share means the session runs
136
+ // on a Windows host, and the boundary rules compare paths as strings. That
137
+ // host names one file three ways: `C:/x`, `C:\x` and `/c/x`. The extractor
138
+ // folds the first two together and has no basis for folding the third,
139
+ // because `/c` is a legitimate directory on a POSIX host. Which spelling
140
+ // the model picks decides whether a write is inside the worktree.
141
+ //
142
+ // Measured on 2026-08-18 by `scripts/live-session-proof.mjs`: across live
143
+ // runs the model chose all three forms for the same file. On `/c/...` the
144
+ // rule refused a write into the session's own worktree.
145
+ //
146
+ // Every coverage figure comes from a corpus whose paths all begin
147
+ // `/workspace`, so none of them measures this. Saying so at startup is the
148
+ // only place it reaches an operator.
149
+ if (hostAbsolute(input.worktreeRoot)) {
150
+ lines.push(` [harness] note: the worktree ${input.worktreeRoot} is a Windows path. Boundary rules ` +
151
+ `compare paths textually, and this host spells one file as C:/x, C:\\x and /c/x. ` +
152
+ `The first two are folded together; /c/x reads as a different tree and a write there ` +
153
+ `into this worktree is refused. Run the session on a POSIX path to get the measured ` +
154
+ `behaviour.`);
155
+ }
156
+ }
157
+ // The evaluator is withheld when any check refused, so a caller that reads
158
+ // `evaluator` without reading `ok` cannot start an ungoverned session by
159
+ // accident. The compile still ran, and its result is in `lines` either way.
160
+ return { ok, lines, credential, ...(ok && evaluator ? { evaluator } : {}), notEnforcedHere };
161
+ }
162
+ /**
163
+ * A subagent's role is not disclosed by the runtime, so it is recorded as
164
+ * `subagent` rather than as the session's role. A rule bound to a role must not
165
+ * match a principal whose role nobody stated.
166
+ */
167
+ export function principalFor(opts, meta) {
168
+ const subagentId = meta?.agentID ?? null;
169
+ return {
170
+ team: opts.team,
171
+ role: subagentId ? 'subagent' : opts.role,
172
+ subagentId,
173
+ sessionId: opts.sessionId,
174
+ };
175
+ }
176
+ export function createSessionGate(opts) {
177
+ const probe = new ProbeSelfCheck();
178
+ const now = opts.now ?? (() => new Date().toISOString());
179
+ const cwd = opts.cwd ?? opts.worktreeRoot;
180
+ let calls = 0;
181
+ let denied = 0;
182
+ let asked = 0;
183
+ let observed = 0;
184
+ async function decide(toolName, input, meta) {
185
+ calls += 1;
186
+ const principal = principalFor({ team: opts.team, role: opts.role, sessionId: opts.sessionId() }, meta);
187
+ let captured = null;
188
+ // Read through a call so control-flow analysis does not narrow `captured`
189
+ // to null: the only assignment happens inside the sink callback.
190
+ const takeCapture = () => captured;
191
+ const gate = createGate({
192
+ extractor,
193
+ evaluator: opts.evaluator,
194
+ principal,
195
+ surface: SESSION_SURFACE,
196
+ context: { cwd, worktreeRoot: opts.worktreeRoot },
197
+ sink: {
198
+ emit(event) {
199
+ if (event.type === 'decision')
200
+ captured = { attrs: event.attrs, decision: event.decision };
201
+ opts.sink?.emit(event);
202
+ },
203
+ },
204
+ onInvoked: () => probe.observe(),
205
+ now,
206
+ });
207
+ const call = {
208
+ name: toolName,
209
+ input,
210
+ ...(meta?.toolUseID ? { callId: meta.toolUseID } : {}),
211
+ };
212
+ const result = await gate(call);
213
+ if (result.behavior === 'allow')
214
+ return result;
215
+ const seen = takeCapture();
216
+ // Observe mode: the decision is recorded and the call runs. The record is
217
+ // the point, so this reports rather than staying silent.
218
+ if (opts.mode === 'observe') {
219
+ observed += 1;
220
+ return { behavior: 'allow', updatedInput: input };
221
+ }
222
+ if (seen && seen.decision.effect === 'ask' && opts.askOperator) {
223
+ asked += 1;
224
+ const approved = await opts.askOperator(seen.decision, seen.attrs);
225
+ if (approved)
226
+ return { behavior: 'allow', updatedInput: input };
227
+ return result;
228
+ }
229
+ denied += 1;
230
+ return result;
231
+ }
232
+ return { probe, decide, stats: () => ({ calls, denied, asked, observed }) };
233
+ }
234
+ // ── Terminal output ──────────────────────────────────────────────────────────
235
+ /** Prints every decision that is not a plain allow. An allow is the common case
236
+ * and printing it would bury the refusals. */
237
+ export function terminalSink(mode, write = (s) => console.log(s)) {
238
+ return {
239
+ emit(event) {
240
+ if (event.type !== 'decision')
241
+ return;
242
+ const { decision, attrs } = event;
243
+ if (decision.effect === 'allow' && !decision.observedOnly)
244
+ return;
245
+ const who = event.principal.subagentId
246
+ ? `${event.principal.team}/subagent ${event.principal.subagentId}`
247
+ : `${event.principal.team}/${event.principal.role}`;
248
+ const head = decision.observedOnly
249
+ ? chalk.yellow(' [harness observed]')
250
+ : decision.effect === 'deny'
251
+ ? chalk.red(' [harness refused]')
252
+ : chalk.yellow(' [harness asks]');
253
+ const suffix = mode === 'observe' && !decision.observedOnly ? chalk.dim(' (observe mode: the call ran)') : '';
254
+ write(`${head} ${attrs.operation} by ${who}${suffix}`);
255
+ if (decision.reason)
256
+ for (const line of decision.reason.split('\n'))
257
+ write(chalk.dim(` ${line}`));
258
+ if (attrs.command)
259
+ write(chalk.dim(` command: ${attrs.command.replace(/\s+/g, ' ').slice(0, 160)}`));
260
+ },
261
+ };
262
+ }
263
+ /** Sends one event to several sinks. A sink that throws does not stop the rest,
264
+ * because a reporting failure must not become a permission decision. */
265
+ export function fanOut(...sinks) {
266
+ const live = sinks.filter((s) => s !== undefined);
267
+ return {
268
+ emit(event) {
269
+ for (const s of live) {
270
+ try {
271
+ s.emit(event);
272
+ }
273
+ catch {
274
+ // A console that throws is a console defect, not a permission one.
275
+ }
276
+ }
277
+ },
278
+ };
279
+ }
280
+ //# sourceMappingURL=harness-wiring.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"harness-wiring.js","sourceRoot":"","sources":["../../src/lib/harness-wiring.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,132 @@
1
+ /**
2
+ * report-format.ts — the seven sections every agent report answers, the
3
+ * skeleton the framework writes, and the check that refuses a report missing
4
+ * one.
5
+ *
6
+ * PROBLEM. Across 12 real sessions and 190 moments where an agent needed the
7
+ * operator, 3 reached him. 25 of the 28 moments classed as an explicit question
8
+ * were agents writing that they needed a decision, in prose, into a channel
9
+ * nobody reads (`docs/fleet-behavior-from-transcripts.md` finding 3c). The same
10
+ * repository produced roughly forty commits and nine documents in two days, and
11
+ * the person they were written for asked four times what the work was. The
12
+ * defect is the format rather than the effort, so the format is the fix.
13
+ *
14
+ * Two sections do most of the work. Section 3 states the command behind each
15
+ * claim, which is what makes a finding challengeable; this repository published
16
+ * eight figures in one week that were correct against the wrong thing, and the
17
+ * source line is what made them findable (`.mx-agent/lessons.md` L2). Section 5
18
+ * states what would overturn the finding, which is what makes a wrong finding
19
+ * cheap to check.
20
+ *
21
+ * FAILURE MODEL — loud and FAIL-CLOSED at the check. `checkReport` is pure and
22
+ * never throws; it returns every problem it found. `mx-agent report check`
23
+ * refuses on any problem, the same shape as the provisioning behavioral-block
24
+ * contract in `commands/create.ts`: a throw rather than a `process.exit`, so a
25
+ * caller that wraps it keeps its recovery path. Refusing at the moment a person
26
+ * is looking is what stops the state being created, and warning is what let the
27
+ * roleguide gap run for four weeks (#4541).
28
+ *
29
+ * ONE SOURCE FOR THE SEVEN. `REPORT_SECTIONS` below is the only list. The
30
+ * skeleton is generated from it and `mx-agent-system/standards/report-format.md`
31
+ * is checked against it by a test, so the document and the validator cannot
32
+ * drift apart.
33
+ */
34
+ /** Canonical heading text, plus everything needed to match and to generate. */
35
+ export interface ReportSection {
36
+ /** 1 through 7, and the order they must appear in. */
37
+ index: number;
38
+ /** Heading text the skeleton writes. */
39
+ heading: string;
40
+ /** Normalised forms this heading is accepted under. */
41
+ aliases: string[];
42
+ /** One line under the heading in the skeleton, written as an HTML comment. */
43
+ prompt: string;
44
+ }
45
+ export declare const REPORT_SECTIONS: readonly ReportSection[];
46
+ export type ReportProblemCode = 'section-missing' | 'section-empty' | 'section-repeated' | 'sections-out-of-order' | 'goal-rung-missing' | 'evidence-missing';
47
+ export interface ReportProblem {
48
+ code: ReportProblemCode;
49
+ /** Section number the problem belongs to, or null for a whole-report problem. */
50
+ section: number | null;
51
+ /** One line naming the problem and the fix. */
52
+ detail: string;
53
+ }
54
+ export interface ReportCheckResult {
55
+ ok: boolean;
56
+ problems: ReportProblem[];
57
+ /** Section body text, keyed by section index. Present only for headings found. */
58
+ bodies: Map<number, string>;
59
+ /** Section indexes in the order the document states them. */
60
+ order: number[];
61
+ }
62
+ /**
63
+ * Match a heading tolerantly.
64
+ *
65
+ * Any heading level, an optional leading number, optional bold, and any
66
+ * trailing punctuation. Apostrophes are dropped so "What I'm not sure about"
67
+ * matches "what im not sure about". A report is refused for missing a section,
68
+ * never for how it punctuated one.
69
+ */
70
+ export declare function normaliseHeading(line: string): string;
71
+ /**
72
+ * Strip what the writer did not write.
73
+ *
74
+ * The skeleton's prompts are HTML comments, so an unfilled skeleton has no body
75
+ * text at all and fails `section-empty`. That is deliberate: `report new` piped
76
+ * straight into `report check` must be refused, or the skeleton becomes a way
77
+ * to pass the check without answering anything.
78
+ */
79
+ export declare function stripNonContent(body: string): string;
80
+ /**
81
+ * Does section 3 state a source a reader could re-run?
82
+ *
83
+ * Deliberately shallow. It cannot tell whether the command is the one that
84
+ * produced the number, which is exactly the failure L2 records, and only
85
+ * re-running catches that. What it can do is refuse a section of bare
86
+ * assertions, which is the common case.
87
+ */
88
+ export declare function statesEvidence(body: string): boolean;
89
+ /** Does section 1 name a rung of the goal ladder? */
90
+ export declare function namesGoalRung(body: string): boolean;
91
+ /**
92
+ * Check a report. Pure, never throws, returns every problem it found.
93
+ *
94
+ * Reporting all problems at once matters more than it sounds. A check that
95
+ * stops at the first missing section turns one fix into seven round trips, and
96
+ * an agent that has been refused seven times stops using the format.
97
+ */
98
+ export declare function checkReport(text: string): ReportCheckResult;
99
+ export interface SkeletonOptions {
100
+ /** One line for section 1, written above the prompt. */
101
+ task?: string;
102
+ /** Goal rung, 1 to 3. Written into section 1 so the check has something to read. */
103
+ rung?: 1 | 2 | 3;
104
+ /** Title line. Defaults to no title. */
105
+ title?: string;
106
+ }
107
+ /**
108
+ * Write the seven headings.
109
+ *
110
+ * Prompts are HTML comments so they render as nothing and strip to nothing.
111
+ * A skeleton with no answers therefore fails `report check`, which is the
112
+ * property that keeps the skeleton from becoming a way past it.
113
+ */
114
+ export declare function renderReportSkeleton(options?: SkeletonOptions): string;
115
+ /**
116
+ * Refusal from the report-format contract.
117
+ *
118
+ * A THROW, not a `process.exit`, for the reason `BehavioralContractError`
119
+ * records: a caller that wraps this keeps its own recovery path, and the
120
+ * top-level action already catches, prints and exits 1.
121
+ */
122
+ export declare class ReportFormatError extends Error {
123
+ readonly code = "report-format-refused";
124
+ readonly problems: ReportProblem[];
125
+ constructor(message: string, problems: ReportProblem[]);
126
+ }
127
+ /**
128
+ * The refusal an operator reads. Plain text, no colour, so it is testable and
129
+ * so it survives being piped into a file or a pull request comment.
130
+ */
131
+ export declare function refusalMessage(result: ReportCheckResult, label: string): string;
132
+ //# sourceMappingURL=report-format.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"report-format.d.ts","sourceRoot":"","sources":["../../src/lib/report-format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,+EAA+E;AAC/E,MAAM,WAAW,aAAa;IAC5B,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,eAAe,EAAE,SAAS,aAAa,EAiD1C,CAAC;AAEX,MAAM,MAAM,iBAAiB,GACzB,iBAAiB,GACjB,eAAe,GACf,kBAAkB,GAClB,uBAAuB,GACvB,mBAAmB,GACnB,kBAAkB,CAAC;AAEvB,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,iBAAiB,CAAC;IACxB,iFAAiF;IACjF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,kFAAkF;IAClF,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,6DAA6D;IAC7D,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAUrD;AAaD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKpD;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAKpD;AAED,qDAAqD;AACrD,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,CA+G3D;AAED,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oFAAoF;IACpF,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACjB,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,eAAoB,GAAG,MAAM,CAc1E;AAED;;;;;;GAMG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,2BAA2B;IACxC,QAAQ,CAAC,QAAQ,EAAE,aAAa,EAAE,CAAC;gBACvB,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,EAAE;CAKvD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CA6B/E"}