@memnexus-ai/mx-agent-cli 0.1.230 → 0.1.231
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.
- package/dist/__tests__/doctor.test.d.ts +20 -0
- package/dist/__tests__/doctor.test.d.ts.map +1 -0
- package/dist/__tests__/doctor.test.js +849 -0
- package/dist/__tests__/doctor.test.js.map +1 -0
- package/dist/__tests__/fleet-data.test.d.ts +2 -0
- package/dist/__tests__/fleet-data.test.d.ts.map +1 -0
- package/dist/__tests__/fleet-data.test.js +340 -0
- package/dist/__tests__/fleet-data.test.js.map +1 -0
- package/dist/__tests__/fleet-tmux.test.d.ts +2 -0
- package/dist/__tests__/fleet-tmux.test.d.ts.map +1 -0
- package/dist/__tests__/fleet-tmux.test.js +242 -0
- package/dist/__tests__/fleet-tmux.test.js.map +1 -0
- package/dist/__tests__/worker-cap.test.d.ts +14 -0
- package/dist/__tests__/worker-cap.test.d.ts.map +1 -0
- package/dist/__tests__/worker-cap.test.js +97 -0
- package/dist/__tests__/worker-cap.test.js.map +1 -0
- package/dist/agent-config/agents/implementation-engineer.md +8 -0
- package/dist/agent-config/agents/qa-tester.md +13 -5
- package/dist/agent-config/skills/mx-pre-pr-check/SKILL.md +4 -0
- package/dist/commands/doctor.d.ts +203 -0
- package/dist/commands/doctor.d.ts.map +1 -0
- package/dist/commands/doctor.js +688 -0
- package/dist/commands/doctor.js.map +1 -0
- package/dist/commands/fleet-tmux.d.ts +68 -0
- package/dist/commands/fleet-tmux.d.ts.map +1 -0
- package/dist/commands/fleet-tmux.js +288 -0
- package/dist/commands/fleet-tmux.js.map +1 -0
- package/dist/commands/start.d.ts.map +1 -1
- package/dist/commands/start.js +36 -0
- package/dist/commands/start.js.map +1 -1
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +87 -0
- package/dist/index.js.map +1 -1
- package/dist/lib/fleet-data.d.ts +181 -0
- package/dist/lib/fleet-data.d.ts.map +1 -0
- package/dist/lib/fleet-data.js +375 -0
- package/dist/lib/fleet-data.js.map +1 -0
- package/dist/lib/fleet-render.d.ts +66 -0
- package/dist/lib/fleet-render.d.ts.map +1 -0
- package/dist/lib/fleet-render.js +184 -0
- package/dist/lib/fleet-render.js.map +1 -0
- package/dist/lib/tmux.d.ts +69 -0
- package/dist/lib/tmux.d.ts.map +1 -0
- package/dist/lib/tmux.js +115 -0
- package/dist/lib/tmux.js.map +1 -0
- package/dist/lib/vm-health.d.ts +562 -0
- package/dist/lib/vm-health.d.ts.map +1 -0
- package/dist/lib/vm-health.js +960 -0
- package/dist/lib/vm-health.js.map +1 -0
- package/package.json +1 -1
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* mx-agent doctor [--verbose] [--json]
|
|
3
|
+
*
|
|
4
|
+
* Measures the VM's performance state and names the host-side remedy when the
|
|
5
|
+
* condition that froze the product owner's editor on 2026-07-24 is present
|
|
6
|
+
* (#4498). Read-only: it reads /proc, /sys and statfs, and writes exactly one
|
|
7
|
+
* file — the last-reading cache under ~/.mx-agent/doctor-last-reading/.
|
|
8
|
+
*
|
|
9
|
+
* ADVISORY ONLY — THE EXIT CODE IS ALWAYS 0.
|
|
10
|
+
* Do not put this command in an `&&` chain, a CI gate, or a startup blocker. The
|
|
11
|
+
* failure it detects is host-side and cannot be fixed from inside the container,
|
|
12
|
+
* so a non-zero exit would be permanently red on every machine that has not
|
|
13
|
+
* applied the host fix. Everyone would learn to ignore it — which is the exact
|
|
14
|
+
* failure mode this command exists to prevent (nobody checked anything on
|
|
15
|
+
* 2026-07-24 until the editor had been frozen for two days).
|
|
16
|
+
*
|
|
17
|
+
* DELTA-BASED BY DEFAULT.
|
|
18
|
+
* Steady state is quiet. The command is loud only when a measured number has
|
|
19
|
+
* WORSENED since the previous run (OOM kills, swap in use, swap size, agent
|
|
20
|
+
* session count). `--verbose` prints every check and its current number
|
|
21
|
+
* regardless of delta, for when someone is actively debugging.
|
|
22
|
+
*
|
|
23
|
+
* CHEAP BY DEFAULT.
|
|
24
|
+
* The default path is single reads of /proc/meminfo, /proc/vmstat, /proc/uptime,
|
|
25
|
+
* one cgroup read, two statfs calls, and two bounded `pgrep` execs. It does NOT
|
|
26
|
+
* walk /proc/<pid>/* across hundreds of PIDs — that allocates under exactly the
|
|
27
|
+
* memory pressure being measured. The full per-process scan (capped to the top N
|
|
28
|
+
* by RSS) and the inotify fd walk run only under --verbose.
|
|
29
|
+
*
|
|
30
|
+
* MEASURED COST, and the basis matters — two honest numbers differ by 3x.
|
|
31
|
+
* In-process (one collectDoctorResult call, median of 10, excluding Node
|
|
32
|
+
* startup): startup mode 15.7 ms, interactive 15.6 ms, verbose 54.2 ms.
|
|
33
|
+
* Full CLI invocation (`node dist/index.js doctor`, wall clock, INCLUDING the
|
|
34
|
+
* ~130 ms of Node process startup a session pays anyway): default 148 ms,
|
|
35
|
+
* verbose 187 ms. Quote the in-process figure when reasoning about what the
|
|
36
|
+
* session-start path adds, since that path runs inside an existing process.
|
|
37
|
+
*
|
|
38
|
+
* TWO PATHS, TWO RISK BUDGETS.
|
|
39
|
+
* `mode: 'interactive'` (a human ran the command) runs everything.
|
|
40
|
+
* `mode: 'startup'` (the automatic session-start check) additionally skips the
|
|
41
|
+
* disk check, because `statfsSync` touches a REAL filesystem and, unlike
|
|
42
|
+
* `execFileSync`, cannot be given a timeout or cancelled from the calling
|
|
43
|
+
* thread. A diagnostic must never be able to hang a session; see checkDisk.
|
|
44
|
+
*
|
|
45
|
+
* RESIDUAL EXPOSURE — READ THIS BEFORE TRUSTING THE PARAGRAPH ABOVE.
|
|
46
|
+
* Skipping the disk check does NOT make the startup path free of real-filesystem
|
|
47
|
+
* I/O. The delta store lives at `~/.mx-agent/doctor-last-reading/`, and
|
|
48
|
+
* `~/.mx-agent` is a NAMED ext4 DOCKER VOLUME (`memnexus-mx-agent-config`,
|
|
49
|
+
* declared in .devcontainer/devcontainer.json) — not part of the container's
|
|
50
|
+
* overlay, and on a different device from the workspace. Verified with `df -T`,
|
|
51
|
+
* `findmnt` and `docker ps --filter volume=` on 2026-07-25:
|
|
52
|
+
* `~/.mx-agent` is /dev/sdd ext4, `$HOME` itself is overlay, `/workspace` is
|
|
53
|
+
* /dev/sdc ext4. `loadLastReading` and `saveReading` touch that volume on every
|
|
54
|
+
* startup run, and neither can be given a timeout, exactly like `statfsSync`.
|
|
55
|
+
* The store cannot simply be dropped from the startup path: it IS the delta
|
|
56
|
+
* mechanism.
|
|
57
|
+
*
|
|
58
|
+
* What has been closed is the FIFO/TOCTOU case (loadLastReading now validates an
|
|
59
|
+
* open descriptor, with O_NONBLOCK). What remains open is a genuinely STALLED
|
|
60
|
+
* MOUNT: if the volume backing `~/.mx-agent` hangs, the startup check hangs with
|
|
61
|
+
* it, and no fail-open layer helps because a process blocked in a kernel syscall
|
|
62
|
+
* never throws. That is a smaller exposure than the disk check was — one small
|
|
63
|
+
* file on a Docker volume, versus statfs on the workspace mount — but it is not
|
|
64
|
+
* zero.
|
|
65
|
+
*
|
|
66
|
+
* On the trust boundary in vm-health.ts's header: the store is not on the
|
|
67
|
+
* container's own overlay, it is on a named volume that OUTLIVES the container
|
|
68
|
+
* and that any container declaring the same mount would share. As checked on
|
|
69
|
+
* 2026-07-25, exactly one container currently mounts it — so treat "another
|
|
70
|
+
* container has written here" as possible, not as observed.
|
|
71
|
+
*
|
|
72
|
+
* Two earlier versions of this comment stated a checkable fact about this path
|
|
73
|
+
* without checking it. Re-run those three commands before editing these lines.
|
|
74
|
+
*/
|
|
75
|
+
import { type DoctorCheck, type DoctorReading, type Regression } from '../lib/vm-health.js';
|
|
76
|
+
/**
|
|
77
|
+
* Which path is running the checks.
|
|
78
|
+
*
|
|
79
|
+
* 'interactive' — a human typed `mx-agent doctor`. Everything runs.
|
|
80
|
+
* 'startup' — the automatic session-start check. Checks that touch a REAL
|
|
81
|
+
* filesystem are skipped. See checkDisk for why.
|
|
82
|
+
*/
|
|
83
|
+
export type DoctorRunMode = 'interactive' | 'startup';
|
|
84
|
+
export interface DoctorOptions {
|
|
85
|
+
/**
|
|
86
|
+
* REQUIRED, deliberately — there is no default.
|
|
87
|
+
*
|
|
88
|
+
* A default of 'interactive' would mean a future caller wired into a
|
|
89
|
+
* startup-like path who forgets to pass 'startup' silently inherits the
|
|
90
|
+
* unbounded `statfsSync`. That is a default that fails toward the hazard, and
|
|
91
|
+
* it fails silently. Making this required moves the decision to compile time:
|
|
92
|
+
* every call site has to state which risk budget it is spending.
|
|
93
|
+
*/
|
|
94
|
+
mode: DoctorRunMode;
|
|
95
|
+
/** Print every check with its current number, run the expensive scans. */
|
|
96
|
+
verbose?: boolean;
|
|
97
|
+
/** Machine-readable output. Implies verbose data collection. */
|
|
98
|
+
json?: boolean;
|
|
99
|
+
/** Override the last-reading cache path (test seam). */
|
|
100
|
+
readingPath?: string;
|
|
101
|
+
}
|
|
102
|
+
export interface AgentFootprint {
|
|
103
|
+
sessions: number;
|
|
104
|
+
totalRssKb: number;
|
|
105
|
+
peakRssKb: number;
|
|
106
|
+
projectedKb: number;
|
|
107
|
+
reclaimableKb: number;
|
|
108
|
+
}
|
|
109
|
+
/**
|
|
110
|
+
* Compute the RAM headroom assessment from measured inputs. Pure so the formula
|
|
111
|
+
* is unit-tested rather than only exercised against live state.
|
|
112
|
+
*
|
|
113
|
+
* projected = peak observed session RSS x session count. If every running
|
|
114
|
+
* session grew to the size of the largest one now running — which is
|
|
115
|
+
* what the 2026-07-24 post-mortem describes, with node processes
|
|
116
|
+
* reaching ~1.3 GB anon-rss each — this is the footprint.
|
|
117
|
+
* reclaimable = MemAvailable + the RSS the sessions already hold. That is the
|
|
118
|
+
* memory the box could give those sessions without swapping.
|
|
119
|
+
* WARN when projected > reclaimable.
|
|
120
|
+
*
|
|
121
|
+
* KNOWN LIMITATION, stated so a quiet check is not mistaken for a healthy box:
|
|
122
|
+
* because the projection is peak x count, it stays quiet when every session is
|
|
123
|
+
* ALREADY at the peak — there is no projected growth left to warn about. This
|
|
124
|
+
* check detects a fleet about to grow into trouble, not a box already in it.
|
|
125
|
+
* Checks 1-3 (swap sizing, swap occupancy, OOM kills) cover the already-in-it
|
|
126
|
+
* case.
|
|
127
|
+
*/
|
|
128
|
+
export declare function assessAgentFootprint(sessionRssKb: number[], memAvailableKb: number): AgentFootprint;
|
|
129
|
+
export interface DoctorResult {
|
|
130
|
+
timestamp: string;
|
|
131
|
+
checks: DoctorCheck[];
|
|
132
|
+
regressions: Regression[];
|
|
133
|
+
reading: DoctorReading;
|
|
134
|
+
previous: DoctorReading | null;
|
|
135
|
+
/** True when the host-side remedy applies to what we measured. */
|
|
136
|
+
remedyApplies: boolean;
|
|
137
|
+
}
|
|
138
|
+
/**
|
|
139
|
+
* Run every check and assemble the result. Exported so tests and future callers
|
|
140
|
+
* can consume the structured result without going through the renderer.
|
|
141
|
+
*/
|
|
142
|
+
export declare function collectDoctorResult(options: DoctorOptions): DoctorResult;
|
|
143
|
+
/**
|
|
144
|
+
* How often the session-start check may actually measure. One hour.
|
|
145
|
+
*
|
|
146
|
+
* The monitor check next to it in start.ts uses 6 hours, but that one calls a
|
|
147
|
+
* remote API; this one is local and costs single-digit milliseconds, and the
|
|
148
|
+
* thing it watches — memory pressure during a busy fleet window — moves on a
|
|
149
|
+
* much shorter timescale than fleet-wide autonomy trends. One hour keeps the
|
|
150
|
+
* delta baseline recent enough to attribute a regression to something that
|
|
151
|
+
* happened this session, while still meaning that nine teams starting sessions
|
|
152
|
+
* in the same window measure roughly once between them, not nine times.
|
|
153
|
+
*/
|
|
154
|
+
export declare const STARTUP_DOCTOR_INTERVAL_MS: number;
|
|
155
|
+
/**
|
|
156
|
+
* Whether the session-start check should measure this time.
|
|
157
|
+
*
|
|
158
|
+
* The rate limit reads the last reading's own timestamp rather than keeping a
|
|
159
|
+
* separate stamp file, so a manual `mx-agent doctor` also satisfies it — if
|
|
160
|
+
* someone measured five minutes ago, session start has nothing to add. The
|
|
161
|
+
* limit is GLOBAL, not per-worktree, because the thing being measured is the
|
|
162
|
+
* VM: nine worktrees share one kernel, one swap file, and one OOM counter.
|
|
163
|
+
*
|
|
164
|
+
* KNOWN LIMITATION — THE AUTOMATIC PATH IS BLIND TO PRE-EXISTING BAD STATE.
|
|
165
|
+
* It reports only what CHANGED since the last reading, so a box that is ALREADY
|
|
166
|
+
* bad before the first-ever measurement produces silence. The first session
|
|
167
|
+
* after this ships, and any session following a quiet period, can start with OOM
|
|
168
|
+
* kills non-zero and VS Code already evicted and see nothing — which is exactly
|
|
169
|
+
* the 2026-07-24 situation, when nobody thought to check. Do not read "no VM
|
|
170
|
+
* health output" as "the machine is healthy."
|
|
171
|
+
*
|
|
172
|
+
* The manual path does not have this hole: `mx-agent doctor` prints the swap and
|
|
173
|
+
* OOM checks on their current values, not on a delta, so a human running it
|
|
174
|
+
* during the 2026-07-24 freeze would have had the diagnosis in about 10 ms
|
|
175
|
+
* instead of two days. The automatic path narrows to regressions on purpose —
|
|
176
|
+
* printing current state at every session start is the alarm fatigue this design
|
|
177
|
+
* removes — and this is the cost of that choice, recorded rather than hidden.
|
|
178
|
+
*/
|
|
179
|
+
export declare function shouldRunStartupDoctorCheck(now?: number, path?: string): boolean;
|
|
180
|
+
/**
|
|
181
|
+
* Render a regression for the SESSION-START transcript.
|
|
182
|
+
*
|
|
183
|
+
* DEFENCE IN DEPTH — deliberately does not use `Regression.message`. That string
|
|
184
|
+
* is composed with values from the delta store, and this text is printed into an
|
|
185
|
+
* LLM's context in every agent session on every team. loadLastReading's
|
|
186
|
+
* validation already makes a hostile store unable to produce arbitrary text, and
|
|
187
|
+
* that alone is judged sufficient; this is the second layer, so that NO
|
|
188
|
+
* store-derived string reaches the transcript at all. Everything below comes
|
|
189
|
+
* from either a fixed label table or a number: `metric` is set by
|
|
190
|
+
* detectRegressions from a closed union, and both values are validated finite
|
|
191
|
+
* non-negative numbers rendered by JavaScript's own number formatting.
|
|
192
|
+
*
|
|
193
|
+
* The interactive `mx-agent doctor` output still uses the richer `message` — a
|
|
194
|
+
* human at a terminal chose to run it, and that is a different trust context
|
|
195
|
+
* from text injected into every session.
|
|
196
|
+
*/
|
|
197
|
+
export declare function formatRegressionForTranscript(r: Regression): string;
|
|
198
|
+
export declare function runStartupDoctorCheck(options?: {
|
|
199
|
+
now?: number;
|
|
200
|
+
readingPath?: string;
|
|
201
|
+
}): Regression[];
|
|
202
|
+
export declare function runDoctor(options: DoctorOptions): void;
|
|
203
|
+
//# sourceMappingURL=doctor.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AAGH,OAAO,EA4BL,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,UAAU,EAEhB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,aAAa,GAAG,SAAS,CAAC;AAEtD,MAAM,WAAW,aAAa;IAC5B;;;;;;;;OAQG;IACH,IAAI,EAAE,aAAa,CAAC;IACpB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gEAAgE;IAChE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA2MD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,MAAM,EAAE,EACtB,cAAc,EAAE,MAAM,GACrB,cAAc,CAWhB;AA+MD,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,OAAO,EAAE,aAAa,CAAC;IACvB,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IAC/B,kEAAkE;IAClE,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,aAAa,GAAG,YAAY,CA0CxE;AAID;;;;;;;;;;GAUG;AACH,eAAO,MAAM,0BAA0B,QAAiB,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,SAAa,EAAE,IAAI,SAAsB,GAAG,OAAO,CAWjG;AA6BD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,6BAA6B,CAAC,CAAC,EAAE,UAAU,GAAG,MAAM,CAEnE;AAED,wBAAgB,qBAAqB,CAAC,OAAO,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,UAAU,EAAE,CAQxG;AAoBD,wBAAgB,SAAS,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAkDtD"}
|