@mainwave/cli 0.3.2 → 0.4.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.
- package/README.md +133 -10
- package/dist/adapters/claude-code.js +22 -2
- package/dist/adapters/claude-code.js.map +1 -1
- package/dist/adapters/claude-desktop.js +3 -0
- package/dist/adapters/claude-desktop.js.map +1 -1
- package/dist/adapters/codex-cli.js +18 -1
- package/dist/adapters/codex-cli.js.map +1 -1
- package/dist/adapters/copilot-chat.js +22 -0
- package/dist/adapters/copilot-chat.js.map +1 -1
- package/dist/adapters/copilot-cli.js +10 -0
- package/dist/adapters/copilot-cli.js.map +1 -1
- package/dist/adapters/cursor-enterprise.js +155 -0
- package/dist/adapters/cursor-enterprise.js.map +1 -0
- package/dist/adapters/cursor.js +205 -0
- package/dist/adapters/cursor.js.map +1 -0
- package/dist/adapters/index.js +4 -0
- package/dist/adapters/index.js.map +1 -1
- package/dist/api/index.js +3 -0
- package/dist/api/index.js.map +1 -0
- package/dist/api/types.gen.js +3 -0
- package/dist/api/types.gen.js.map +1 -0
- package/dist/core/apply.js +269 -0
- package/dist/core/apply.js.map +1 -0
- package/dist/core/auth-commands.js +167 -0
- package/dist/core/auth-commands.js.map +1 -0
- package/dist/core/behaviour-hooks.js +101 -0
- package/dist/core/behaviour-hooks.js.map +1 -0
- package/dist/core/browser.js +41 -0
- package/dist/core/browser.js.map +1 -0
- package/dist/core/codecs/cursor-hooks-json.js +90 -0
- package/dist/core/codecs/cursor-hooks-json.js.map +1 -0
- package/dist/core/detect.js +52 -0
- package/dist/core/detect.js.map +1 -0
- package/dist/core/device-login.js +76 -0
- package/dist/core/device-login.js.map +1 -0
- package/dist/core/doctor.js +51 -2
- package/dist/core/doctor.js.map +1 -1
- package/dist/core/errors.js +23 -0
- package/dist/core/errors.js.map +1 -1
- package/dist/core/flags.js +57 -0
- package/dist/core/flags.js.map +1 -0
- package/dist/core/headers.js +15 -1
- package/dist/core/headers.js.map +1 -1
- package/dist/core/interview.js +199 -0
- package/dist/core/interview.js.map +1 -0
- package/dist/core/keys.js +41 -0
- package/dist/core/keys.js.map +1 -0
- package/dist/core/markers.js +5 -1
- package/dist/core/markers.js.map +1 -1
- package/dist/core/platform.js +155 -0
- package/dist/core/platform.js.map +1 -0
- package/dist/core/prompts.js +73 -22
- package/dist/core/prompts.js.map +1 -1
- package/dist/core/skills.js +203 -0
- package/dist/core/skills.js.map +1 -0
- package/dist/core/status.js +25 -1
- package/dist/core/status.js.map +1 -1
- package/dist/core/store.js +118 -0
- package/dist/core/store.js.map +1 -0
- package/dist/core/tty.js +6 -0
- package/dist/core/tty.js.map +1 -1
- package/dist/core/ucid.js +25 -0
- package/dist/core/ucid.js.map +1 -0
- package/dist/core/ui.js +26 -0
- package/dist/core/ui.js.map +1 -0
- package/dist/core/use-case.js +75 -0
- package/dist/core/use-case.js.map +1 -0
- package/dist/core/validate.js +22 -0
- package/dist/core/validate.js.map +1 -1
- package/dist/core/verify.js +154 -0
- package/dist/core/verify.js.map +1 -0
- package/dist/core/wizard.js +236 -266
- package/dist/core/wizard.js.map +1 -1
- package/dist/main.js +215 -29
- package/dist/main.js.map +1 -1
- package/hooks/cursor-otlp.mjs +244 -0
- package/hooks/github-pr-marker.mjs +30 -10
- package/hooks/jira-ticket-marker.mjs +69 -17
- package/hooks/linear-ticket-marker.mjs +68 -12
- package/hooks/marker-core.mjs +5 -0
- package/hooks/vocabulary.d.mts +35 -0
- package/hooks/vocabulary.mjs +109 -0
- package/package.json +7 -3
- package/skills/mainwave-instrument/SKILL.md +168 -0
- package/skills/mainwave-instrument/reference/api.md +142 -0
- package/skills/mainwave-instrument/reference/frameworks.md +170 -0
- package/skills/mainwave-instrument/reference/troubleshooting.md +131 -0
- package/skills/mainwave-setup/SKILL.md +114 -0
|
@@ -8,19 +8,24 @@
|
|
|
8
8
|
// key out of the tool *result*, and emits one small OTLP marker span so the
|
|
9
9
|
// platform counts distinct tickets filed instead of raw tool calls.
|
|
10
10
|
//
|
|
11
|
-
//
|
|
12
|
-
//
|
|
13
|
-
//
|
|
14
|
-
//
|
|
15
|
-
//
|
|
16
|
-
//
|
|
17
|
-
// touch both hooks and the reader together.
|
|
11
|
+
// It emits the SAME v2 work-item events (work.item.created / .updated) and the
|
|
12
|
+
// SAME work.item.* keys as the Linear hook; the two are told apart by
|
|
13
|
+
// `work.vendor` (jira vs linear) — the fix for the old vendor-blind `linear.*`
|
|
14
|
+
// misnomer, where a Jira and a Linear ticket were indistinguishable (MAI-1469 /
|
|
15
|
+
// MAI-1480). The read side (app/read/_vocab.py) coalesces the v2 keys over the
|
|
16
|
+
// legacy `linear.*` ones, so history keeps counting.
|
|
18
17
|
//
|
|
19
18
|
// Shared OTLP plumbing (config resolution, MAI-936 source neutralization, payload
|
|
20
19
|
// build, fail-open emit) lives in ./marker-core.mjs; this file keeps only the
|
|
21
|
-
// Jira-specific extraction and main().
|
|
22
|
-
// "KAN-4"),
|
|
23
|
-
//
|
|
20
|
+
// Jira-specific extraction and main(). Emits the issue key (work.item.id, e.g.
|
|
21
|
+
// "KAN-4"), vendor (work.vendor=jira), issue url, operation, and work.instance
|
|
22
|
+
// (the site cloudId from the result envelope's top-level context.cloudId) —
|
|
23
|
+
// never the summary or body. work.instance is best-effort: present when the MCP
|
|
24
|
+
// result carries the cloudId, omitted when it doesn't. It matches the value the
|
|
25
|
+
// Jira connector (MAI-1465) emits, so MAI-1483 can reconcile marker spans against
|
|
26
|
+
// connector events on a shared instance id (MAI-1480 first deferred it, wrongly
|
|
27
|
+
// assuming a hook couldn't produce it). Fails open and fast so a telemetry hiccup
|
|
28
|
+
// can never block or slow the session.
|
|
24
29
|
|
|
25
30
|
import { homedir } from 'node:os'
|
|
26
31
|
import { join } from 'node:path'
|
|
@@ -36,6 +41,18 @@ import {
|
|
|
36
41
|
readStdin,
|
|
37
42
|
toolOutput,
|
|
38
43
|
} from './marker-core.mjs'
|
|
44
|
+
import {
|
|
45
|
+
ATTR_WORK_INSTANCE,
|
|
46
|
+
ATTR_WORK_ITEM_ID,
|
|
47
|
+
ATTR_WORK_ITEM_OP,
|
|
48
|
+
ATTR_WORK_ITEM_URL,
|
|
49
|
+
ATTR_WORK_VENDOR,
|
|
50
|
+
VENDOR_JIRA,
|
|
51
|
+
WI_CREATED,
|
|
52
|
+
WI_UPDATED,
|
|
53
|
+
WORK_OP_CREATED,
|
|
54
|
+
WORK_OP_UPDATED,
|
|
55
|
+
} from './vocabulary.mjs'
|
|
39
56
|
|
|
40
57
|
const log = makeLog(
|
|
41
58
|
process.env.MAINWAVE_HOOK_LOG || join(homedir(), '.mainwave-jira-ticket-marker.log'),
|
|
@@ -44,7 +61,7 @@ const log = makeLog(
|
|
|
44
61
|
// The same non-coding source/service the Linear ticket hook stamps, so a Jira
|
|
45
62
|
// marker is classified identically to a Linear one: an ordinary ("other") span
|
|
46
63
|
// that stays out of the coding-work segmentation (MAI-936).
|
|
47
|
-
const MARKER_SOURCE = '
|
|
64
|
+
const MARKER_SOURCE = 'hook.jira'
|
|
48
65
|
const MARKER_SERVICE = 'mainwave.ticket-hook'
|
|
49
66
|
|
|
50
67
|
const KEY = '[A-Z][A-Z0-9]+-\\d+'
|
|
@@ -112,21 +129,54 @@ export const extractIssueUrl = (toolResult) => {
|
|
|
112
129
|
return url && new RegExp(`/(?:browse|issue)/${KEY}`, 'i').test(url) ? url : undefined
|
|
113
130
|
}
|
|
114
131
|
|
|
132
|
+
/**
|
|
133
|
+
* The Jira site cloudId (work.instance) from a create/edit result — the immutable
|
|
134
|
+
* site-global id the connector also emits, so a marker span and a connector event
|
|
135
|
+
* on the same site reconcile (MAI-1483). The Atlassian MCP envelope carries it at
|
|
136
|
+
* TOP-LEVEL `context.cloudId`, a sibling of `issues` — NOT under `issues.nodes[0]`
|
|
137
|
+
* — so this reads the full parsed result, not the issue node. Best-effort:
|
|
138
|
+
* undefined for a non-JSON result or one without the cloudId, so the attr is
|
|
139
|
+
* dropped rather than fabricated (the node's numeric `id` is site-scoped, not a
|
|
140
|
+
* global id, so it is never a substitute). Never throws.
|
|
141
|
+
*/
|
|
142
|
+
export const extractInstance = (toolResult) => {
|
|
143
|
+
const cloudId = resultObject(toolResult)?.context?.cloudId
|
|
144
|
+
return typeof cloudId === 'string' && cloudId ? cloudId : undefined
|
|
145
|
+
}
|
|
146
|
+
|
|
115
147
|
/** create for the createJiraIssue tool, update for editJiraIssue (or anything
|
|
116
148
|
* else that reaches this hook). Op is derived from the tool NAME — unlike Linear,
|
|
117
149
|
* Jira splits create and edit across two tools rather than one save call. An
|
|
118
150
|
* `update` is counted as "ticket updated", never filed. */
|
|
119
151
|
export const detectOp = (toolName) =>
|
|
120
|
-
typeof toolName === 'string' && toolName.endsWith('createJiraIssue')
|
|
152
|
+
typeof toolName === 'string' && toolName.endsWith('createJiraIssue')
|
|
153
|
+
? WORK_OP_CREATED
|
|
154
|
+
: WORK_OP_UPDATED
|
|
121
155
|
|
|
122
156
|
/** Build the OTLP/JSON payload for one Jira ticket-marker span. Emits the same
|
|
123
|
-
*
|
|
124
|
-
*
|
|
125
|
-
|
|
157
|
+
* v2 work-item event names and keys as the Linear hook — the two are now told
|
|
158
|
+
* apart by `work.vendor` (jira vs linear), the fix for the vendor-blind
|
|
159
|
+
* `linear.*`-on-Jira misnomer (MAI-1469 / MAI-1480). `issueUrl` and `instance`
|
|
160
|
+
* are dropped by `buildMarkerPayload` when absent. */
|
|
161
|
+
export const buildTracePayload = ({
|
|
162
|
+
issueKey,
|
|
163
|
+
issueUrl,
|
|
164
|
+
instance,
|
|
165
|
+
op,
|
|
166
|
+
sessionId,
|
|
167
|
+
resourceAttrs,
|
|
168
|
+
nowNs,
|
|
169
|
+
}) =>
|
|
126
170
|
buildMarkerPayload({
|
|
127
|
-
spanName:
|
|
171
|
+
spanName: op === WORK_OP_CREATED ? WI_CREATED : WI_UPDATED,
|
|
128
172
|
scopeName: 'mainwave.jira-ticket-marker',
|
|
129
|
-
attributes: {
|
|
173
|
+
attributes: {
|
|
174
|
+
[ATTR_WORK_ITEM_ID]: issueKey,
|
|
175
|
+
[ATTR_WORK_ITEM_OP]: op,
|
|
176
|
+
[ATTR_WORK_ITEM_URL]: issueUrl,
|
|
177
|
+
[ATTR_WORK_VENDOR]: VENDOR_JIRA,
|
|
178
|
+
[ATTR_WORK_INSTANCE]: instance,
|
|
179
|
+
},
|
|
130
180
|
sessionId,
|
|
131
181
|
resourceAttrs,
|
|
132
182
|
source: MARKER_SOURCE,
|
|
@@ -150,6 +200,7 @@ const main = async () => {
|
|
|
150
200
|
return
|
|
151
201
|
}
|
|
152
202
|
const issueUrl = extractIssueUrl(output)
|
|
203
|
+
const instance = extractInstance(output)
|
|
153
204
|
const op = detectOp(payload.tool_name)
|
|
154
205
|
|
|
155
206
|
const cwd = payload.cwd || process.cwd()
|
|
@@ -170,6 +221,7 @@ const main = async () => {
|
|
|
170
221
|
const body = buildTracePayload({
|
|
171
222
|
issueKey,
|
|
172
223
|
issueUrl,
|
|
224
|
+
instance,
|
|
173
225
|
op,
|
|
174
226
|
sessionId: payload.session_id,
|
|
175
227
|
resourceAttrs,
|
|
@@ -17,9 +17,16 @@
|
|
|
17
17
|
//
|
|
18
18
|
// Shared OTLP plumbing (config resolution, MAI-936 source neutralization,
|
|
19
19
|
// payload build, fail-open emit) lives in ./marker-core.mjs; this file keeps
|
|
20
|
-
// only the ticket-specific extraction and main().
|
|
21
|
-
// (e.g. "MAI-930")
|
|
22
|
-
//
|
|
20
|
+
// only the ticket-specific extraction and main(). Emits the v2 work-item
|
|
21
|
+
// vocabulary — the issue key (work.item.id, e.g. "MAI-930"), vendor
|
|
22
|
+
// (work.vendor=linear), issue url, operation (the typed event name
|
|
23
|
+
// work.item.created / .updated), and work.instance (the Linear team UUID from
|
|
24
|
+
// the save_issue result's teamId / team.id) — never the ticket title or body.
|
|
25
|
+
// work.instance is best-effort: present when the MCP result carries the team id,
|
|
26
|
+
// omitted when it doesn't. It matches the value the connector emits, so MAI-1483
|
|
27
|
+
// can reconcile marker spans against connector events on a shared instance id
|
|
28
|
+
// (MAI-1480 first deferred it, wrongly assuming a hook couldn't produce it).
|
|
29
|
+
// Fails open and fast so a telemetry hiccup can never block the session.
|
|
23
30
|
|
|
24
31
|
import { homedir } from 'node:os'
|
|
25
32
|
import { join } from 'node:path'
|
|
@@ -36,6 +43,18 @@ import {
|
|
|
36
43
|
readStdin,
|
|
37
44
|
toolOutput,
|
|
38
45
|
} from './marker-core.mjs'
|
|
46
|
+
import {
|
|
47
|
+
ATTR_WORK_INSTANCE,
|
|
48
|
+
ATTR_WORK_ITEM_ID,
|
|
49
|
+
ATTR_WORK_ITEM_OP,
|
|
50
|
+
ATTR_WORK_ITEM_URL,
|
|
51
|
+
ATTR_WORK_VENDOR,
|
|
52
|
+
VENDOR_LINEAR,
|
|
53
|
+
WI_CREATED,
|
|
54
|
+
WI_UPDATED,
|
|
55
|
+
WORK_OP_CREATED,
|
|
56
|
+
WORK_OP_UPDATED,
|
|
57
|
+
} from './vocabulary.mjs'
|
|
39
58
|
|
|
40
59
|
// Re-export the shared pure helpers so existing importers keep resolving them here.
|
|
41
60
|
export {
|
|
@@ -52,7 +71,7 @@ const log = makeLog(process.env.MAINWAVE_HOOK_LOG || join(homedir(), '.mainwave-
|
|
|
52
71
|
// A source tag the collector does NOT classify as a coding agent, and a service
|
|
53
72
|
// name outside its coding-agent `service.name` allow-list, so the marker lands
|
|
54
73
|
// as an ordinary ("other") span rather than a Claude Code one (MAI-936).
|
|
55
|
-
const MARKER_SOURCE = '
|
|
74
|
+
const MARKER_SOURCE = 'hook.linear'
|
|
56
75
|
const MARKER_SERVICE = 'mainwave.ticket-hook'
|
|
57
76
|
|
|
58
77
|
const KEY = '[A-Z][A-Z0-9]+-\\d+'
|
|
@@ -137,6 +156,21 @@ export const extractIssueUrl = (toolResult) => {
|
|
|
137
156
|
return url && new RegExp(`/issue/${KEY}`, 'i').test(url) ? url : undefined
|
|
138
157
|
}
|
|
139
158
|
|
|
159
|
+
/**
|
|
160
|
+
* The Linear team UUID (work.instance) from a save_issue result — the immutable
|
|
161
|
+
* instance-global id the connector also emits, so a marker span and a connector
|
|
162
|
+
* event on the same team reconcile (MAI-1483). The linear-server MCP puts it at
|
|
163
|
+
* top-level `teamId`; some other Linear MCPs nest it at `team.id` — read either.
|
|
164
|
+
* Best-effort: undefined for a non-JSON result or one carrying neither, so the
|
|
165
|
+
* attr is dropped rather than fabricated (the result's `id` is the display KEY,
|
|
166
|
+
* not the global id, so it is never a substitute). Never throws.
|
|
167
|
+
*/
|
|
168
|
+
export const extractInstance = (toolResult) => {
|
|
169
|
+
const obj = resultObject(toolResult)
|
|
170
|
+
const instance = obj?.teamId ?? obj?.team?.id
|
|
171
|
+
return typeof instance === 'string' && instance ? instance : undefined
|
|
172
|
+
}
|
|
173
|
+
|
|
140
174
|
/**
|
|
141
175
|
* create vs update, preferring the tool NAME when it says so. `save_issue` is one
|
|
142
176
|
* tool for both operations, so the only signal there is whether the input carried
|
|
@@ -148,23 +182,43 @@ export const extractIssueUrl = (toolResult) => {
|
|
|
148
182
|
*/
|
|
149
183
|
export const detectOp = (toolName, toolInput) => {
|
|
150
184
|
if (typeof toolName === 'string') {
|
|
151
|
-
if (toolName.endsWith('create_issue')) return
|
|
152
|
-
if (toolName.endsWith('update_issue')) return
|
|
185
|
+
if (toolName.endsWith('create_issue')) return WORK_OP_CREATED
|
|
186
|
+
if (toolName.endsWith('update_issue')) return WORK_OP_UPDATED
|
|
153
187
|
}
|
|
154
|
-
return toolInput && toolInput.id ?
|
|
188
|
+
return toolInput && toolInput.id ? WORK_OP_UPDATED : WORK_OP_CREATED
|
|
155
189
|
}
|
|
156
190
|
|
|
157
191
|
/** Marker resource attrs with the ticket hook's non-coding source/service (MAI-936). */
|
|
158
192
|
export const markerResourceAttrs = (resourceAttrs) =>
|
|
159
193
|
coreMarkerResourceAttrs(resourceAttrs, MARKER_SOURCE, MARKER_SERVICE)
|
|
160
194
|
|
|
161
|
-
/** Build the OTLP/JSON payload for one ticket-marker span.
|
|
162
|
-
*
|
|
163
|
-
|
|
195
|
+
/** Build the OTLP/JSON payload for one ticket-marker span. The v2 event NAME
|
|
196
|
+
* encodes the operation (work.item.created / work.item.updated); the span
|
|
197
|
+
* self-declares `mainwave.source = hook.linear`, honored verbatim by the
|
|
198
|
+
* collector (MAI-1539). It stays out of coding-activity segmentation because
|
|
199
|
+
* `hook.*` is outside the CODING_TOOL_SOURCES allowlist and markers are admitted
|
|
200
|
+
* by span NAME (MAI-936) — not because of the old `other` fallback. `issueUrl`
|
|
201
|
+
* and `instance` are dropped by `buildMarkerPayload` when absent (an older
|
|
202
|
+
* result with no url, or one that carries no team id). */
|
|
203
|
+
export const buildTracePayload = ({
|
|
204
|
+
issueKey,
|
|
205
|
+
issueUrl,
|
|
206
|
+
instance,
|
|
207
|
+
op,
|
|
208
|
+
sessionId,
|
|
209
|
+
resourceAttrs,
|
|
210
|
+
nowNs,
|
|
211
|
+
}) =>
|
|
164
212
|
buildMarkerPayload({
|
|
165
|
-
spanName:
|
|
213
|
+
spanName: op === WORK_OP_CREATED ? WI_CREATED : WI_UPDATED,
|
|
166
214
|
scopeName: 'mainwave.linear-ticket-marker',
|
|
167
|
-
attributes: {
|
|
215
|
+
attributes: {
|
|
216
|
+
[ATTR_WORK_ITEM_ID]: issueKey,
|
|
217
|
+
[ATTR_WORK_ITEM_OP]: op,
|
|
218
|
+
[ATTR_WORK_ITEM_URL]: issueUrl,
|
|
219
|
+
[ATTR_WORK_VENDOR]: VENDOR_LINEAR,
|
|
220
|
+
[ATTR_WORK_INSTANCE]: instance,
|
|
221
|
+
},
|
|
168
222
|
sessionId,
|
|
169
223
|
resourceAttrs,
|
|
170
224
|
source: MARKER_SOURCE,
|
|
@@ -188,6 +242,7 @@ const main = async () => {
|
|
|
188
242
|
return
|
|
189
243
|
}
|
|
190
244
|
const issueUrl = extractIssueUrl(output)
|
|
245
|
+
const instance = extractInstance(output)
|
|
191
246
|
const op = detectOp(payload.tool_name, payload.tool_input)
|
|
192
247
|
|
|
193
248
|
const cwd = payload.cwd || process.cwd()
|
|
@@ -208,6 +263,7 @@ const main = async () => {
|
|
|
208
263
|
const body = buildTracePayload({
|
|
209
264
|
issueKey,
|
|
210
265
|
issueUrl,
|
|
266
|
+
instance,
|
|
211
267
|
op,
|
|
212
268
|
sessionId: payload.session_id,
|
|
213
269
|
resourceAttrs,
|
package/hooks/marker-core.mjs
CHANGED
|
@@ -13,6 +13,8 @@ import { appendFileSync, readFileSync } from 'node:fs'
|
|
|
13
13
|
import { homedir } from 'node:os'
|
|
14
14
|
import { join } from 'node:path'
|
|
15
15
|
|
|
16
|
+
import { ATTR_SCHEMA_VERSION, SCHEMA_VERSION } from './vocabulary.mjs'
|
|
17
|
+
|
|
16
18
|
const EMIT_TIMEOUT_MS = 3000
|
|
17
19
|
|
|
18
20
|
/** A best-effort appender to `logPath` — never throws (a log hiccup must not
|
|
@@ -166,6 +168,9 @@ export const markerResourceAttrs = (resourceAttrs, source, service) => ({
|
|
|
166
168
|
...(resourceAttrs ?? {}),
|
|
167
169
|
'mainwave.source': source,
|
|
168
170
|
'service.name': service,
|
|
171
|
+
// The v2 contract stamp on every hook emission (marker + cursor), so the
|
|
172
|
+
// collector shim's lifetime can be measured against v1-vs-v2 traffic (MAI-1480).
|
|
173
|
+
[ATTR_SCHEMA_VERSION]: SCHEMA_VERSION,
|
|
169
174
|
})
|
|
170
175
|
|
|
171
176
|
const attr = (key, stringValue) => ({ key, value: { stringValue } })
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
// Type declarations for vocabulary.mjs — the hooks are runtime-dep-free .mjs and
|
|
2
|
+
// aren't compiled by tsc, but the vitest registry-conformance test (.ts) imports
|
|
3
|
+
// this module, so NodeNext needs a .d.mts sibling to type it (MAI-1480).
|
|
4
|
+
|
|
5
|
+
export const ATTR_SCHEMA_VERSION: string
|
|
6
|
+
export const SCHEMA_VERSION: string
|
|
7
|
+
|
|
8
|
+
export const WI_CREATED: string
|
|
9
|
+
export const WI_UPDATED: string
|
|
10
|
+
export const ATTR_WORK_ITEM_ID: string
|
|
11
|
+
export const ATTR_WORK_ITEM_OP: string
|
|
12
|
+
export const ATTR_WORK_ITEM_URL: string
|
|
13
|
+
export const ATTR_WORK_VENDOR: string
|
|
14
|
+
export const ATTR_WORK_INSTANCE: string
|
|
15
|
+
export const WORK_OP_CREATED: string
|
|
16
|
+
export const WORK_OP_UPDATED: string
|
|
17
|
+
export const VENDOR_LINEAR: string
|
|
18
|
+
export const VENDOR_JIRA: string
|
|
19
|
+
export const WORK_MARKER_KEYS: readonly string[]
|
|
20
|
+
|
|
21
|
+
export const VCS_OPENED: string
|
|
22
|
+
export const ATTR_VCS_REPOSITORY_URL_FULL: string
|
|
23
|
+
export const ATTR_VCS_CHANGE_ID: string
|
|
24
|
+
export const ATTR_VCS_CHANGE_TITLE: string
|
|
25
|
+
export const ATTR_VCS_PROVIDER_NAME: string
|
|
26
|
+
export const ATTR_VCS_CHANGE_FILES_CHANGED: string
|
|
27
|
+
export const ATTR_VCS_CHANGE_LINES_ADDED: string
|
|
28
|
+
export const ATTR_VCS_CHANGE_LINES_REMOVED: string
|
|
29
|
+
export const VCS_PROVIDER_GITHUB: string
|
|
30
|
+
export const VCS_MARKER_KEYS: readonly string[]
|
|
31
|
+
|
|
32
|
+
export const ATTR_CODE_FILE_PATH: string
|
|
33
|
+
export const CODE_KEYS: readonly string[]
|
|
34
|
+
|
|
35
|
+
export const CLI_EVENT_NAMES: readonly string[]
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
// The v2 telemetry vocabulary the CLI marker + cursor hooks emit (MAI-1480).
|
|
2
|
+
//
|
|
3
|
+
// This is the CLI's checkable copy of the work.item.* / vcs.change.* / code.*
|
|
4
|
+
// contract in the repo-root `telemetry/registry.yaml` — the .mjs twin of the
|
|
5
|
+
// backend's `app/devtool/vocabulary.py`. The conformance test
|
|
6
|
+
// `tests/registry-conformance.test.ts` asserts every name and key declared here
|
|
7
|
+
// is a registered `emitted` entry, so a name changed on one side without the
|
|
8
|
+
// other fails the build (telemetry/README.md § Enforcement coverage).
|
|
9
|
+
//
|
|
10
|
+
// Unlike the poller connector, a marker hook mints a RANDOM span id per emit
|
|
11
|
+
// (marker-core `randomBytes`), and the read side counts distinct entity ids
|
|
12
|
+
// (`uniqExact(work.item.id)`), not span ids. So there is no frozen `id_seed`
|
|
13
|
+
// concern here — renaming a marker event name never re-mints history the way it
|
|
14
|
+
// would for the connector's deterministic span ids (see vocabulary.py). The
|
|
15
|
+
// marker self-declares `mainwave.source = hook.<vendor>` (MAI-1539), honored
|
|
16
|
+
// verbatim by the collector's Generic processor. It stays out of coding-activity
|
|
17
|
+
// segmentation because `hook.*` is outside the CODING_TOOL_SOURCES allowlist and
|
|
18
|
+
// markers are admitted by span NAME (MAI-936) — NOT because of the old `other`
|
|
19
|
+
// fallback (before MAI-1539 the hooks stamped `mainwave.ticket_marker` /
|
|
20
|
+
// `mainwave.pr_marker`, which the collector ignored and mapped to `other`).
|
|
21
|
+
|
|
22
|
+
// ── The v2 contract stamp ───────────────────────────────────────────────────
|
|
23
|
+
// Every v2 emission stamps this on its resource; v1 traffic carries no stamp,
|
|
24
|
+
// and the collector shim's lifetime is measured against it (registry header).
|
|
25
|
+
export const ATTR_SCHEMA_VERSION = 'mainwave.schema.version'
|
|
26
|
+
export const SCHEMA_VERSION = '2'
|
|
27
|
+
|
|
28
|
+
// ── Work-item events (tickets) — CLI ticket-marker hooks ─────────────────────
|
|
29
|
+
// The event NAME encodes the operation (a v2 event's name IS its op), so create
|
|
30
|
+
// and update are distinct span names rather than one span discriminated by an
|
|
31
|
+
// attribute the way the v1 `mainwave.ticket_marker` + `linear.op` pair was.
|
|
32
|
+
export const WI_CREATED = 'work.item.created'
|
|
33
|
+
export const WI_UPDATED = 'work.item.updated'
|
|
34
|
+
|
|
35
|
+
export const ATTR_WORK_ITEM_ID = 'work.item.id'
|
|
36
|
+
export const ATTR_WORK_ITEM_OP = 'work.item.op'
|
|
37
|
+
export const ATTR_WORK_ITEM_URL = 'work.item.url'
|
|
38
|
+
export const ATTR_WORK_VENDOR = 'work.vendor'
|
|
39
|
+
// The vendor's immutable instance/site global id — the same value the connector
|
|
40
|
+
// emits as work.instance (Linear team UUID, Jira site cloudId). A marker CAN
|
|
41
|
+
// produce it after all: it sits in the MCP save result the hook already parses
|
|
42
|
+
// (Linear's top-level teamId, Jira's context.cloudId). Emitted best-effort —
|
|
43
|
+
// present when the result supplies it, cleanly omitted otherwise — so MAI-1483
|
|
44
|
+
// can reconcile marker spans against connector events on a shared instance id.
|
|
45
|
+
// (MAI-1480 first deferred this on the assumption a hook couldn't produce the
|
|
46
|
+
// global id; live MCP probes disproved that — MAI-1481 follow-up.)
|
|
47
|
+
export const ATTR_WORK_INSTANCE = 'work.instance'
|
|
48
|
+
|
|
49
|
+
// `work.item.op` values — the registry's entities.item.operations axis. Past
|
|
50
|
+
// tense, matching the connector (vocabulary.py WORK_ITEM_OP_*), not the v1
|
|
51
|
+
// `linear.op` present-tense create/update.
|
|
52
|
+
export const WORK_OP_CREATED = 'created'
|
|
53
|
+
export const WORK_OP_UPDATED = 'updated'
|
|
54
|
+
|
|
55
|
+
// `work.vendor` values a ticket marker stamps — the fix for the vendor-blind
|
|
56
|
+
// `linear.*`-on-Jira misnomer (MAI-1469): a Jira and a Linear ticket are now
|
|
57
|
+
// distinguishable end to end.
|
|
58
|
+
export const VENDOR_LINEAR = 'linear'
|
|
59
|
+
export const VENDOR_JIRA = 'jira'
|
|
60
|
+
|
|
61
|
+
// The exact work keys a ticket marker may emit — what the conformance test
|
|
62
|
+
// checks against the registry's `emitted` work entries.
|
|
63
|
+
export const WORK_MARKER_KEYS = [
|
|
64
|
+
ATTR_WORK_ITEM_ID,
|
|
65
|
+
ATTR_WORK_ITEM_OP,
|
|
66
|
+
ATTR_WORK_ITEM_URL,
|
|
67
|
+
ATTR_WORK_VENDOR,
|
|
68
|
+
ATTR_WORK_INSTANCE,
|
|
69
|
+
]
|
|
70
|
+
|
|
71
|
+
// ── Change-request events (PRs) — CLI github-pr-marker hook ──────────────────
|
|
72
|
+
// `gh pr create` only ever opens; merged/closed/review are the poller
|
|
73
|
+
// connector's to emit (a hook sees the create call, not the later lifecycle).
|
|
74
|
+
export const VCS_OPENED = 'vcs.change.opened'
|
|
75
|
+
|
|
76
|
+
// The PR URL lands under vcs.repository.url.full and the PR number under
|
|
77
|
+
// vcs.change.id — the registry alias map for github.pr_url / github.pr_number
|
|
78
|
+
// (a house mapping the read side already coalesces on; app/read/_vocab.py).
|
|
79
|
+
export const ATTR_VCS_REPOSITORY_URL_FULL = 'vcs.repository.url.full'
|
|
80
|
+
export const ATTR_VCS_CHANGE_ID = 'vcs.change.id'
|
|
81
|
+
export const ATTR_VCS_CHANGE_TITLE = 'vcs.change.title'
|
|
82
|
+
export const ATTR_VCS_PROVIDER_NAME = 'vcs.provider.name'
|
|
83
|
+
export const ATTR_VCS_CHANGE_FILES_CHANGED = 'vcs.change.files_changed'
|
|
84
|
+
export const ATTR_VCS_CHANGE_LINES_ADDED = 'vcs.change.lines_added'
|
|
85
|
+
export const ATTR_VCS_CHANGE_LINES_REMOVED = 'vcs.change.lines_removed'
|
|
86
|
+
|
|
87
|
+
// `vcs.provider.name` value — vendor-as-value, replacing the implicit vendor in
|
|
88
|
+
// the old `github.pr_*` key prefix.
|
|
89
|
+
export const VCS_PROVIDER_GITHUB = 'github'
|
|
90
|
+
|
|
91
|
+
export const VCS_MARKER_KEYS = [
|
|
92
|
+
ATTR_VCS_REPOSITORY_URL_FULL,
|
|
93
|
+
ATTR_VCS_CHANGE_ID,
|
|
94
|
+
ATTR_VCS_CHANGE_TITLE,
|
|
95
|
+
ATTR_VCS_PROVIDER_NAME,
|
|
96
|
+
ATTR_VCS_CHANGE_FILES_CHANGED,
|
|
97
|
+
ATTR_VCS_CHANGE_LINES_ADDED,
|
|
98
|
+
ATTR_VCS_CHANGE_LINES_REMOVED,
|
|
99
|
+
]
|
|
100
|
+
|
|
101
|
+
// ── File references — CLI cursor behaviour hook ──────────────────────────────
|
|
102
|
+
// The standard OTel Code (Stable) key, replacing the hook's former
|
|
103
|
+
// `cursor.file_path`.
|
|
104
|
+
export const ATTR_CODE_FILE_PATH = 'code.file.path'
|
|
105
|
+
export const CODE_KEYS = [ATTR_CODE_FILE_PATH]
|
|
106
|
+
|
|
107
|
+
// Every governed v2 event name the CLI hooks emit — checked against the
|
|
108
|
+
// registry's events_v2 lists.
|
|
109
|
+
export const CLI_EVENT_NAMES = [WI_CREATED, WI_UPDATED, VCS_OPENED]
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mainwave/cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
4
4
|
"description": "Setup wizard for connecting third-party coding tools to Mainwave AI.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -9,6 +9,7 @@
|
|
|
9
9
|
"files": [
|
|
10
10
|
"dist",
|
|
11
11
|
"hooks",
|
|
12
|
+
"skills",
|
|
12
13
|
"README.md",
|
|
13
14
|
"LICENSE"
|
|
14
15
|
],
|
|
@@ -36,19 +37,22 @@
|
|
|
36
37
|
"test": "vitest",
|
|
37
38
|
"test:run": "vitest run",
|
|
38
39
|
"test:hooks": "node --test tests/hooks/*.test.mjs",
|
|
39
|
-
"prepare": "lefthook install"
|
|
40
|
+
"prepare": "lefthook install",
|
|
41
|
+
"api:generate": "openapi-ts"
|
|
40
42
|
},
|
|
41
43
|
"dependencies": {
|
|
42
44
|
"@inquirer/prompts": "7.10.0",
|
|
43
45
|
"picocolors": "1.1.1"
|
|
44
46
|
},
|
|
45
47
|
"devDependencies": {
|
|
48
|
+
"@hey-api/openapi-ts": "^0.99.0",
|
|
46
49
|
"@types/node": "24.8.0",
|
|
47
50
|
"lefthook": "2.1.5",
|
|
48
51
|
"oxlint": "1.71.0",
|
|
49
52
|
"prettier": "3.8.3",
|
|
50
53
|
"typescript": "6.0.2",
|
|
51
|
-
"vitest": "4.1.4"
|
|
54
|
+
"vitest": "4.1.4",
|
|
55
|
+
"yaml": "2.9.0"
|
|
52
56
|
},
|
|
53
57
|
"keywords": [
|
|
54
58
|
"mainwave",
|
|
@@ -0,0 +1,168 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: mainwave-instrument
|
|
3
|
+
description: Instrument a Python AI agent or LLM application with the Mainwave SDK so its runs, tokens, cost, and tool calls arrive in Mainwave. Use when asked to add Mainwave, add tracing/observability to an agent, connect an app to Mainwave, or when telemetry is configured but no spans are showing up. Covers init placement, framework wiring, use-case identity, flushing, and verification.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Instrumenting an application with Mainwave
|
|
7
|
+
|
|
8
|
+
Mainwave traces LLM applications. The SDK wraps OpenTelemetry and OpenInference
|
|
9
|
+
auto-instrumentation, so most applications need an `init()` call and nothing
|
|
10
|
+
else — the framework's own calls are captured automatically.
|
|
11
|
+
|
|
12
|
+
Your job is to place that call correctly, wire the right framework, bind the
|
|
13
|
+
work to a use case, and then **prove a span arrived**. An instrumentation task
|
|
14
|
+
that ends without verification is not finished.
|
|
15
|
+
|
|
16
|
+
## Before you touch code
|
|
17
|
+
|
|
18
|
+
**Never invent an API key or a use-case id.** Both come from the user's Mainwave
|
|
19
|
+
account. Read them from the environment; if they are absent, stop and ask, or
|
|
20
|
+
have the user run:
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
npx @mainwave/cli@latest login
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Keys and use cases are visible in the app at `app.mainwave.com`. Put them in the
|
|
27
|
+
project's existing secret mechanism (`.env`, the deployment's secret store) —
|
|
28
|
+
**never a literal in source, never a committed file.**
|
|
29
|
+
|
|
30
|
+
## 1. Survey before editing
|
|
31
|
+
|
|
32
|
+
Answer these from the codebase, not from assumption:
|
|
33
|
+
|
|
34
|
+
- **Which LLM libraries are actually called?** Search imports for `openai`,
|
|
35
|
+
`anthropic`, `langchain`, `crewai`, `llama_index`, `litellm`, `boto3`
|
|
36
|
+
(Bedrock), `google.genai`, `mistralai`, `groq`, `vertexai`.
|
|
37
|
+
- **Where does the process start?** The `main()`, the FastAPI/Django app module,
|
|
38
|
+
the Celery worker bootstrap, the CLI entry point. That is where `init()` goes.
|
|
39
|
+
- **What is one "unit of work"?** A ticket triaged, a question answered, a
|
|
40
|
+
document processed. This becomes a run, and it is the level a business
|
|
41
|
+
operator reads results at — not one HTTP request, not one LLM call.
|
|
42
|
+
- **Is OpenTelemetry already set up?** If the app builds its own
|
|
43
|
+
`TracerProvider`, the SDK detects it and runs in coexist mode. Do not remove
|
|
44
|
+
their setup; `init()` attaches to it.
|
|
45
|
+
|
|
46
|
+
## 2. Install with narrow extras
|
|
47
|
+
|
|
48
|
+
One extra per framework the app genuinely uses:
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
uv add 'mainwave[openai]' # or: pip install 'mainwave[openai]'
|
|
52
|
+
uv add 'mainwave[langchain,openai]'
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
**Never install `mainwave[all]`** — it exists for CI matrices, and in an
|
|
56
|
+
application it drags in instrumentors for libraries that aren't there. Python
|
|
57
|
+
3.10+ is required.
|
|
58
|
+
|
|
59
|
+
## 3. Initialize once, at process entry
|
|
60
|
+
|
|
61
|
+
```python
|
|
62
|
+
import mainwave
|
|
63
|
+
|
|
64
|
+
mainwave.init(service_name="support-triage")
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
`api_key` and `use_case_id` come from `MAINWAVE_API_KEY` and
|
|
68
|
+
`MAINWAVE_USE_CASE_ID` when not passed. Call it **before** the framework does
|
|
69
|
+
its work, and prefer placing it before the framework imports — instrumentors
|
|
70
|
+
patch libraries at wire time.
|
|
71
|
+
|
|
72
|
+
Rules that bite:
|
|
73
|
+
|
|
74
|
+
- **Once per process.** A second `init()` with different settings raises
|
|
75
|
+
`MainwaveReinitConflict`. In a web app, initialize in the lifespan/startup
|
|
76
|
+
hook, not per request.
|
|
77
|
+
- **Late imports need `mainwave.instrument()`.** If the LLM library is imported
|
|
78
|
+
lazily — inside a function, a Click subcommand, a FastAPI route — it wasn't
|
|
79
|
+
loaded when `init()` walked the registry. Call `mainwave.instrument("openai")`
|
|
80
|
+
after the import.
|
|
81
|
+
- **`service_name` is the deployable**, not the agent. `"support-triage"`, not
|
|
82
|
+
`"ClassifierAgent"`. Defaults to `mainwave-app`, which tells the operator
|
|
83
|
+
nothing — always set it.
|
|
84
|
+
- If `use_case_id` is missing, the SDK derives a stable one from the key and
|
|
85
|
+
service name so nothing crashes, but that telemetry lands in a use case the
|
|
86
|
+
operator never created. Set it explicitly.
|
|
87
|
+
|
|
88
|
+
## 4. Mark the unit of work
|
|
89
|
+
|
|
90
|
+
Wrap each unit of work in a run. This is what makes the trace legible as
|
|
91
|
+
business activity rather than a pile of LLM calls:
|
|
92
|
+
|
|
93
|
+
```python
|
|
94
|
+
with mainwave.run(f"triage-{ticket.id}", metadata={"ticket_id": ticket.id}) as r:
|
|
95
|
+
decision = classify(ticket) # instrumented calls land inside
|
|
96
|
+
r.end(reason="success", decision=decision, iterations=2)
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
`mainwave.arun(...)` is the async twin. `mainwave.start_run(...)` returns the
|
|
100
|
+
handle without a context manager, for a run that outlives one block.
|
|
101
|
+
|
|
102
|
+
Identity is **work-scoped and rides on the span**, so it applies to a block, not
|
|
103
|
+
to the process. When one deployable serves several use cases, override per run:
|
|
104
|
+
|
|
105
|
+
```python
|
|
106
|
+
with mainwave.run(run_id, use_case_id=UCID_FOR_THIS_TENANT, agent_name="triage"):
|
|
107
|
+
...
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Bind at the **root** of the unit of work. Spans created before the bind do not
|
|
111
|
+
inherit it. `mainwave.bind_identity(...)` does the same without opening a run.
|
|
112
|
+
|
|
113
|
+
## 5. Flush before the process dies
|
|
114
|
+
|
|
115
|
+
Short-lived processes — scripts, jobs, serverless handlers, CLI commands — must
|
|
116
|
+
flush or the last spans die with the process:
|
|
117
|
+
|
|
118
|
+
```python
|
|
119
|
+
mainwave.flush() # mainwave.aflush() in async code
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Long-running servers do not need this; the batch processor drains on its own.
|
|
123
|
+
|
|
124
|
+
## 6. Verify — do not skip this
|
|
125
|
+
|
|
126
|
+
Run the application so it does real work, then watch for it to land:
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
npx @mainwave/cli@latest verify --ucid <use-case-id> --no-sample
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
`--no-sample` is required here. Without it the CLI pushes its own synthetic
|
|
133
|
+
trace, which proves the network path but would pass even if your
|
|
134
|
+
instrumentation does nothing. The command reports the agent names it saw — check
|
|
135
|
+
that the application's own name is among them.
|
|
136
|
+
|
|
137
|
+
If nothing arrives, work `reference/troubleshooting.md`; the most common cause
|
|
138
|
+
is by design and is listed first.
|
|
139
|
+
|
|
140
|
+
## Guardrails
|
|
141
|
+
|
|
142
|
+
- **Never import anything underscore-prefixed** (`mainwave._config`,
|
|
143
|
+
`mainwave._runtime`). Those are internals and change without notice. If it is
|
|
144
|
+
not in `mainwave.__all__`, it is not public.
|
|
145
|
+
- **Never wire LangChain twice.** The auto-instrumentor and
|
|
146
|
+
`mainwave.langchain.CallbackHandler` each capture every call; both together
|
|
147
|
+
double-count tokens and cost. Pick one — see `reference/frameworks.md`.
|
|
148
|
+
- **Never let instrumentation change application behavior.** No swapped clients,
|
|
149
|
+
no altered control flow, no new required config. If the SDK cannot start, the
|
|
150
|
+
app must still run — that is why `MAINWAVE_DISABLED=1` exists.
|
|
151
|
+
- **Do not restructure the app to fit the SDK.** If the code has no clean unit
|
|
152
|
+
of work, add a run at the outermost sensible boundary and say so; do not
|
|
153
|
+
refactor their architecture as part of an instrumentation task.
|
|
154
|
+
|
|
155
|
+
## Reference
|
|
156
|
+
|
|
157
|
+
- `reference/api.md` — the exact public surface: signatures, env vars, defaults.
|
|
158
|
+
- `reference/frameworks.md` — per-framework wiring, including the LangChain fork
|
|
159
|
+
and frameworks with no working instrumentor.
|
|
160
|
+
- `reference/troubleshooting.md` — "no spans are showing up", in the order the
|
|
161
|
+
causes actually occur.
|
|
162
|
+
|
|
163
|
+
## Report at the end
|
|
164
|
+
|
|
165
|
+
Tell the user which files changed, which extras were installed, what the run
|
|
166
|
+
boundary is, and the verification result. If you had to guess at the unit of
|
|
167
|
+
work or the use case, say so plainly — that is the one decision they should
|
|
168
|
+
check.
|