@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.
Files changed (88) hide show
  1. package/README.md +133 -10
  2. package/dist/adapters/claude-code.js +22 -2
  3. package/dist/adapters/claude-code.js.map +1 -1
  4. package/dist/adapters/claude-desktop.js +3 -0
  5. package/dist/adapters/claude-desktop.js.map +1 -1
  6. package/dist/adapters/codex-cli.js +18 -1
  7. package/dist/adapters/codex-cli.js.map +1 -1
  8. package/dist/adapters/copilot-chat.js +22 -0
  9. package/dist/adapters/copilot-chat.js.map +1 -1
  10. package/dist/adapters/copilot-cli.js +10 -0
  11. package/dist/adapters/copilot-cli.js.map +1 -1
  12. package/dist/adapters/cursor-enterprise.js +155 -0
  13. package/dist/adapters/cursor-enterprise.js.map +1 -0
  14. package/dist/adapters/cursor.js +205 -0
  15. package/dist/adapters/cursor.js.map +1 -0
  16. package/dist/adapters/index.js +4 -0
  17. package/dist/adapters/index.js.map +1 -1
  18. package/dist/api/index.js +3 -0
  19. package/dist/api/index.js.map +1 -0
  20. package/dist/api/types.gen.js +3 -0
  21. package/dist/api/types.gen.js.map +1 -0
  22. package/dist/core/apply.js +269 -0
  23. package/dist/core/apply.js.map +1 -0
  24. package/dist/core/auth-commands.js +167 -0
  25. package/dist/core/auth-commands.js.map +1 -0
  26. package/dist/core/behaviour-hooks.js +101 -0
  27. package/dist/core/behaviour-hooks.js.map +1 -0
  28. package/dist/core/browser.js +41 -0
  29. package/dist/core/browser.js.map +1 -0
  30. package/dist/core/codecs/cursor-hooks-json.js +90 -0
  31. package/dist/core/codecs/cursor-hooks-json.js.map +1 -0
  32. package/dist/core/detect.js +52 -0
  33. package/dist/core/detect.js.map +1 -0
  34. package/dist/core/device-login.js +76 -0
  35. package/dist/core/device-login.js.map +1 -0
  36. package/dist/core/doctor.js +51 -2
  37. package/dist/core/doctor.js.map +1 -1
  38. package/dist/core/errors.js +23 -0
  39. package/dist/core/errors.js.map +1 -1
  40. package/dist/core/flags.js +57 -0
  41. package/dist/core/flags.js.map +1 -0
  42. package/dist/core/headers.js +15 -1
  43. package/dist/core/headers.js.map +1 -1
  44. package/dist/core/interview.js +199 -0
  45. package/dist/core/interview.js.map +1 -0
  46. package/dist/core/keys.js +41 -0
  47. package/dist/core/keys.js.map +1 -0
  48. package/dist/core/markers.js +5 -1
  49. package/dist/core/markers.js.map +1 -1
  50. package/dist/core/platform.js +155 -0
  51. package/dist/core/platform.js.map +1 -0
  52. package/dist/core/prompts.js +73 -22
  53. package/dist/core/prompts.js.map +1 -1
  54. package/dist/core/skills.js +203 -0
  55. package/dist/core/skills.js.map +1 -0
  56. package/dist/core/status.js +25 -1
  57. package/dist/core/status.js.map +1 -1
  58. package/dist/core/store.js +118 -0
  59. package/dist/core/store.js.map +1 -0
  60. package/dist/core/tty.js +6 -0
  61. package/dist/core/tty.js.map +1 -1
  62. package/dist/core/ucid.js +25 -0
  63. package/dist/core/ucid.js.map +1 -0
  64. package/dist/core/ui.js +26 -0
  65. package/dist/core/ui.js.map +1 -0
  66. package/dist/core/use-case.js +75 -0
  67. package/dist/core/use-case.js.map +1 -0
  68. package/dist/core/validate.js +22 -0
  69. package/dist/core/validate.js.map +1 -1
  70. package/dist/core/verify.js +154 -0
  71. package/dist/core/verify.js.map +1 -0
  72. package/dist/core/wizard.js +236 -266
  73. package/dist/core/wizard.js.map +1 -1
  74. package/dist/main.js +215 -29
  75. package/dist/main.js.map +1 -1
  76. package/hooks/cursor-otlp.mjs +244 -0
  77. package/hooks/github-pr-marker.mjs +30 -10
  78. package/hooks/jira-ticket-marker.mjs +69 -17
  79. package/hooks/linear-ticket-marker.mjs +68 -12
  80. package/hooks/marker-core.mjs +5 -0
  81. package/hooks/vocabulary.d.mts +35 -0
  82. package/hooks/vocabulary.mjs +109 -0
  83. package/package.json +7 -3
  84. package/skills/mainwave-instrument/SKILL.md +168 -0
  85. package/skills/mainwave-instrument/reference/api.md +142 -0
  86. package/skills/mainwave-instrument/reference/frameworks.md +170 -0
  87. package/skills/mainwave-instrument/reference/troubleshooting.md +131 -0
  88. 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
- // Crucially it emits the SAME `mainwave.ticket_marker` span and the SAME
12
- // `linear.issue_id` / `linear.op` / `linear.issue_url` attribute keys the Linear
13
- // hook does, because the read side (app/read/activity_rollup.py) matches on those
14
- // exact keys. The `linear.*` names are a deliberate misnomer here — they are the
15
- // storage-agnostic "tickets filed" contract, not a Linear-specific field — so
16
- // Jira tickets count with no backend change. A future rename to `ticket.*` would
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(). Privacy: emits the issue key (e.g.
22
- // "KAN-4"), the operation, and the issue url only — never the summary or body.
23
- // Fails open and fast so a telemetry hiccup can never block or slow the session.
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 = 'mainwave.ticket_marker'
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') ? 'create' : 'update'
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
- * span name and `linear.*` attribute contract as the Linear hook so the reader
124
- * counts it unchanged. `issueUrl` is dropped by `buildMarkerPayload` when absent. */
125
- export const buildTracePayload = ({ issueKey, issueUrl, op, sessionId, resourceAttrs, nowNs }) =>
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: 'mainwave.ticket_marker',
171
+ spanName: op === WORK_OP_CREATED ? WI_CREATED : WI_UPDATED,
128
172
  scopeName: 'mainwave.jira-ticket-marker',
129
- attributes: { 'linear.issue_id': issueKey, 'linear.op': op, 'linear.issue_url': issueUrl },
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(). Privacy: emits the issue key
21
- // (e.g. "MAI-930") and the operation only — never the ticket title or body.
22
- // Fails open and fast so a telemetry hiccup can never block or slow the session.
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 = 'mainwave.ticket_marker'
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 'create'
152
- if (toolName.endsWith('update_issue')) return 'update'
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 ? 'update' : 'create'
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. `issueUrl` is dropped
162
- * by `buildMarkerPayload` when absent (an older result, or no issue url). */
163
- export const buildTracePayload = ({ issueKey, issueUrl, op, sessionId, resourceAttrs, nowNs }) =>
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: 'mainwave.ticket_marker',
213
+ spanName: op === WORK_OP_CREATED ? WI_CREATED : WI_UPDATED,
166
214
  scopeName: 'mainwave.linear-ticket-marker',
167
- attributes: { 'linear.issue_id': issueKey, 'linear.op': op, 'linear.issue_url': issueUrl },
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,
@@ -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.2",
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.