@mainwave/cli 0.7.1 → 0.9.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 (139) hide show
  1. package/README.md +141 -42
  2. package/dist/adapters/claude-code.js +33 -7
  3. package/dist/adapters/claude-desktop.js +0 -1
  4. package/dist/adapters/codex-cli.js +1 -2
  5. package/dist/adapters/copilot-chat.js +0 -1
  6. package/dist/adapters/copilot-cli.js +0 -1
  7. package/dist/adapters/cursor-enterprise.js +0 -1
  8. package/dist/adapters/cursor.js +15 -4
  9. package/dist/adapters/index.js +0 -1
  10. package/dist/adapters/types.js +0 -1
  11. package/dist/api/index.js +0 -1
  12. package/dist/api/types.gen.js +0 -1
  13. package/dist/cli.js +0 -1
  14. package/dist/core/apply.js +151 -42
  15. package/dist/core/auth-commands.js +0 -1
  16. package/dist/core/behaviour-hooks.js +0 -1
  17. package/dist/core/browser.js +0 -1
  18. package/dist/core/codecs/cursor-hooks-json.js +0 -1
  19. package/dist/core/codecs/env-file.js +0 -1
  20. package/dist/core/codecs/json-env.js +0 -1
  21. package/dist/core/codecs/json-flat.js +0 -1
  22. package/dist/core/codecs/json-managed.js +0 -1
  23. package/dist/core/codecs/toml-otel.js +0 -1
  24. package/dist/core/codecs/types.js +0 -1
  25. package/dist/core/detect.js +0 -1
  26. package/dist/core/device-login.js +0 -1
  27. package/dist/core/doctor.js +45 -9
  28. package/dist/core/edit.js +9 -5
  29. package/dist/core/effective-settings.js +71 -20
  30. package/dist/core/entry-script.js +90 -0
  31. package/dist/core/env-command.js +0 -1
  32. package/dist/core/errors.js +0 -1
  33. package/dist/core/flags.js +0 -1
  34. package/dist/core/format.js +0 -1
  35. package/dist/core/git-bash.js +40 -0
  36. package/dist/core/git.js +0 -1
  37. package/dist/core/headers.js +0 -1
  38. package/dist/core/install-hooks.js +127 -44
  39. package/dist/core/interview.js +53 -4
  40. package/dist/core/keys.js +0 -1
  41. package/dist/core/layer-policy.js +2 -1
  42. package/dist/core/markers.js +826 -133
  43. package/dist/core/pinned-use-case.js +0 -1
  44. package/dist/core/platform.js +0 -1
  45. package/dist/core/post-setup.js +0 -1
  46. package/dist/core/prompts.js +0 -1
  47. package/dist/core/settings.js +32 -8
  48. package/dist/core/skills.js +5 -2
  49. package/dist/core/status.js +7 -5
  50. package/dist/core/store.js +0 -1
  51. package/dist/core/tty.js +0 -1
  52. package/dist/core/ucid.js +0 -1
  53. package/dist/core/ui.js +0 -1
  54. package/dist/core/use-case.js +0 -1
  55. package/dist/core/validate.js +0 -1
  56. package/dist/core/verify.js +0 -1
  57. package/dist/core/version.js +0 -1
  58. package/dist/core/wizard.js +49 -8
  59. package/dist/main.js +16 -10
  60. package/hooks/cursor-otlp.mjs +13 -15
  61. package/hooks/github-pr-marker.mjs +55 -31
  62. package/hooks/glab-mr-marker.mjs +795 -0
  63. package/hooks/jira-ticket-marker.mjs +35 -23
  64. package/hooks/linear-ticket-marker.mjs +35 -21
  65. package/hooks/mainwave-hook-node.mjs +42 -0
  66. package/hooks/mainwave-hook.mjs +301 -0
  67. package/hooks/managed-entry.mjs +42 -0
  68. package/hooks/marker-core.mjs +389 -62
  69. package/hooks/matchers.json +82 -6
  70. package/hooks/plan-snapshot.mjs +529 -0
  71. package/hooks/stop-failure.mjs +43 -0
  72. package/hooks/vocabulary.d.mts +48 -0
  73. package/hooks/vocabulary.mjs +181 -0
  74. package/package.json +6 -5
  75. package/skills/mainwave-instrument/SKILL.md +21 -7
  76. package/skills/mainwave-instrument/reference/api.md +29 -10
  77. package/skills/mainwave-instrument/reference/frameworks.md +3 -3
  78. package/skills/mainwave-instrument/reference/troubleshooting.md +12 -5
  79. package/skills/mainwave-instrument-node/SKILL.md +420 -0
  80. package/skills/mainwave-instrument-node/reference/api.md +96 -0
  81. package/skills/mainwave-instrument-node/reference/frameworks.md +82 -0
  82. package/skills/mainwave-instrument-node/reference/troubleshooting.md +152 -0
  83. package/skills/mainwave-setup/SKILL.md +47 -12
  84. package/dist/adapters/claude-code.js.map +0 -1
  85. package/dist/adapters/claude-desktop.js.map +0 -1
  86. package/dist/adapters/codex-cli.js.map +0 -1
  87. package/dist/adapters/copilot-chat.js.map +0 -1
  88. package/dist/adapters/copilot-cli.js.map +0 -1
  89. package/dist/adapters/cursor-enterprise.js.map +0 -1
  90. package/dist/adapters/cursor.js.map +0 -1
  91. package/dist/adapters/index.js.map +0 -1
  92. package/dist/adapters/types.js.map +0 -1
  93. package/dist/api/index.js.map +0 -1
  94. package/dist/api/types.gen.js.map +0 -1
  95. package/dist/cli.js.map +0 -1
  96. package/dist/core/apply.js.map +0 -1
  97. package/dist/core/auth-commands.js.map +0 -1
  98. package/dist/core/behaviour-hooks.js.map +0 -1
  99. package/dist/core/browser.js.map +0 -1
  100. package/dist/core/codecs/cursor-hooks-json.js.map +0 -1
  101. package/dist/core/codecs/env-file.js.map +0 -1
  102. package/dist/core/codecs/json-env.js.map +0 -1
  103. package/dist/core/codecs/json-flat.js.map +0 -1
  104. package/dist/core/codecs/json-managed.js.map +0 -1
  105. package/dist/core/codecs/toml-otel.js.map +0 -1
  106. package/dist/core/codecs/types.js.map +0 -1
  107. package/dist/core/detect.js.map +0 -1
  108. package/dist/core/device-login.js.map +0 -1
  109. package/dist/core/doctor.js.map +0 -1
  110. package/dist/core/edit.js.map +0 -1
  111. package/dist/core/effective-settings.js.map +0 -1
  112. package/dist/core/env-command.js.map +0 -1
  113. package/dist/core/errors.js.map +0 -1
  114. package/dist/core/flags.js.map +0 -1
  115. package/dist/core/format.js.map +0 -1
  116. package/dist/core/git.js.map +0 -1
  117. package/dist/core/headers.js.map +0 -1
  118. package/dist/core/install-hooks.js.map +0 -1
  119. package/dist/core/interview.js.map +0 -1
  120. package/dist/core/keys.js.map +0 -1
  121. package/dist/core/layer-policy.js.map +0 -1
  122. package/dist/core/markers.js.map +0 -1
  123. package/dist/core/pinned-use-case.js.map +0 -1
  124. package/dist/core/platform.js.map +0 -1
  125. package/dist/core/post-setup.js.map +0 -1
  126. package/dist/core/prompts.js.map +0 -1
  127. package/dist/core/settings.js.map +0 -1
  128. package/dist/core/skills.js.map +0 -1
  129. package/dist/core/status.js.map +0 -1
  130. package/dist/core/store.js.map +0 -1
  131. package/dist/core/tty.js.map +0 -1
  132. package/dist/core/ucid.js.map +0 -1
  133. package/dist/core/ui.js.map +0 -1
  134. package/dist/core/use-case.js.map +0 -1
  135. package/dist/core/validate.js.map +0 -1
  136. package/dist/core/verify.js.map +0 -1
  137. package/dist/core/version.js.map +0 -1
  138. package/dist/core/wizard.js.map +0 -1
  139. package/dist/main.js.map +0 -1
@@ -31,13 +31,61 @@ export const ATTR_VCS_REPOSITORY_URL_FULL: string
31
31
  export const ATTR_VCS_CHANGE_ID: string
32
32
  export const ATTR_VCS_CHANGE_TITLE: string
33
33
  export const ATTR_VCS_PROVIDER_NAME: string
34
+ export const ATTR_VCS_REPOSITORY_ID: string
34
35
  export const ATTR_VCS_CHANGE_FILES_CHANGED: string
35
36
  export const ATTR_VCS_CHANGE_LINES_ADDED: string
36
37
  export const ATTR_VCS_CHANGE_LINES_REMOVED: string
37
38
  export const VCS_PROVIDER_GITHUB: string
39
+ export const VCS_PROVIDER_GITLAB: string
38
40
  export const VCS_MARKER_KEYS: readonly string[]
39
41
 
40
42
  export const ATTR_CODE_FILE_PATH: string
41
43
  export const CODE_KEYS: readonly string[]
42
44
 
43
45
  export const CLI_EVENT_NAMES: readonly string[]
46
+
47
+ export const SUBSCRIPTION_SNAPSHOT: string
48
+ export const VENDOR_ANTHROPIC: string
49
+ export const ATTR_SUBSCRIPTION_TRIGGER: string
50
+ export const ATTR_PROMPT_ID: string
51
+ export const ATTR_SUBSCRIPTION_PROVIDER: string
52
+ export const ATTR_SUBSCRIPTION_ORGANIZATION_TYPE: string
53
+ export const ATTR_SUBSCRIPTION_SEAT_TIER: string
54
+ export const ATTR_SUBSCRIPTION_RATE_LIMIT_TIER: string
55
+ export const ATTR_SUBSCRIPTION_BILLING_TYPE: string
56
+ export const ATTR_SUBSCRIPTION_ORGANIZATION_ROLE: string
57
+ export const ATTR_SUBSCRIPTION_WORKSPACE_ROLE: string
58
+ export const ATTR_SUBSCRIPTION_CREATED_AT: string
59
+ export const ATTR_SUBSCRIPTION_TRIAL_ENDS_AT: string
60
+ export const ATTR_SUBSCRIPTION_TRIAL_DURATION_DAYS: string
61
+ export const ATTR_SUBSCRIPTION_PROFILE_OBSERVED_AT: string
62
+ export const ATTR_SUBSCRIPTION_FIRST_TOKEN_DATE: string
63
+ export const ATTR_USAGE_FIVE_HOUR_UTILIZATION: string
64
+ export const ATTR_USAGE_FIVE_HOUR_RESETS_AT: string
65
+ export const ATTR_USAGE_SEVEN_DAY_UTILIZATION: string
66
+ export const ATTR_USAGE_SEVEN_DAY_RESETS_AT: string
67
+ export const ATTR_EXTRA_USAGE_ENABLED: string
68
+ export const ATTR_EXTRA_USAGE_USED_MINOR: string
69
+ export const ATTR_EXTRA_USAGE_LIMIT_MINOR: string
70
+ export const ATTR_EXTRA_USAGE_CURRENCY: string
71
+ export const ATTR_EXTRA_USAGE_EXPONENT: string
72
+ export const ATTR_EXTRA_USAGE_SPEND_LIMIT_REACHED: string
73
+ export const ATTR_EXTRA_USAGE_DISABLED_REASON: string
74
+ export const ATTR_EXTRA_USAGE_USER_DISABLED: string
75
+ export const ATTR_EXTRA_USAGE_CACHED_DISABLED_REASON: string
76
+ export const ATTR_SUBSCRIPTION_OBSERVED_AT: string
77
+ export const SUBSCRIPTION_LIMIT_PREFIX: string
78
+ export const ATTR_ORGANIZATION_ID: string
79
+ export const SUBSCRIPTION_LIMIT_FIELDS: readonly string[]
80
+ export const SUBSCRIPTION_LIMIT_SCOPED_FIELDS: readonly string[]
81
+ export const subscriptionLimitKey: (kind: string, field: string, scope?: string) => string
82
+ export const SUBSCRIPTION_SNAPSHOT_KEYS: readonly string[]
83
+
84
+ export const CLAUDE_CODE_STOP_FAILURE: string
85
+ export const ATTR_STOP_FAILURE_ERROR: string
86
+ export const STOP_FAILURE_KEYS: readonly string[]
87
+ export const COMMON_SPAN_KEYS: readonly string[]
88
+ export const FEATURE_EMITS: Readonly<
89
+ Record<string, { spans: readonly string[]; keys: readonly string[]; prefixes: readonly string[] }>
90
+ >
91
+ export const ANTHROPIC_HOOK_SPANS: readonly string[]
@@ -130,6 +130,12 @@ export const ATTR_VCS_REPOSITORY_URL_FULL = 'vcs.repository.url.full'
130
130
  export const ATTR_VCS_CHANGE_ID = 'vcs.change.id'
131
131
  export const ATTR_VCS_CHANGE_TITLE = 'vcs.change.title'
132
132
  export const ATTR_VCS_PROVIDER_NAME = 'vcs.provider.name'
133
+ // The instance-namespaced id of the repository, `<instance>:<id>`, where the
134
+ // instance is the host (and any non-default port) of the vendor's own URL. GitLab
135
+ // ids are per instance, so two instances share one integer space; the namespace
136
+ // keeps their repositories apart. The id survives a rename or a move, which the
137
+ // URL does not. Only vendors whose repository has a stable id carry it.
138
+ export const ATTR_VCS_REPOSITORY_ID = 'vcs.repository.id'
133
139
  export const ATTR_VCS_CHANGE_FILES_CHANGED = 'vcs.change.files_changed'
134
140
  export const ATTR_VCS_CHANGE_LINES_ADDED = 'vcs.change.lines_added'
135
141
  export const ATTR_VCS_CHANGE_LINES_REMOVED = 'vcs.change.lines_removed'
@@ -137,12 +143,14 @@ export const ATTR_VCS_CHANGE_LINES_REMOVED = 'vcs.change.lines_removed'
137
143
  // `vcs.provider.name` value — vendor-as-value, replacing the implicit vendor in
138
144
  // the old `github.pr_*` key prefix.
139
145
  export const VCS_PROVIDER_GITHUB = 'github'
146
+ export const VCS_PROVIDER_GITLAB = 'gitlab'
140
147
 
141
148
  export const VCS_MARKER_KEYS = [
142
149
  ATTR_VCS_REPOSITORY_URL_FULL,
143
150
  ATTR_VCS_CHANGE_ID,
144
151
  ATTR_VCS_CHANGE_TITLE,
145
152
  ATTR_VCS_PROVIDER_NAME,
153
+ ATTR_VCS_REPOSITORY_ID,
146
154
  ATTR_VCS_CHANGE_FILES_CHANGED,
147
155
  ATTR_VCS_CHANGE_LINES_ADDED,
148
156
  ATTR_VCS_CHANGE_LINES_REMOVED,
@@ -154,6 +162,179 @@ export const VCS_MARKER_KEYS = [
154
162
  export const ATTR_CODE_FILE_PATH = 'code.file.path'
155
163
  export const CODE_KEYS = [ATTR_CODE_FILE_PATH]
156
164
 
165
+ // ── Subscription snapshot — the CLI hook's plan-snapshot feature ─────────────
166
+ // Claude Code's own telemetry carries neither the account's plan, its usage
167
+ // against its rate limits, nor its overage ("extra usage") spend; Claude Code
168
+ // keeps them in its local account record. This hook sends them as one span on
169
+ // every submitted prompt (UserPromptSubmit), under `mainwave.source = hook.anthropic` (the vendor the
170
+ // snapshot is about). Strings are sent exactly as Claude Code stores them — no
171
+ // mapping, normalizing or display names; readers interpret them. Money is in
172
+ // the currency's minor unit: `used_minor / 10^exponent` is the amount.
173
+ //
174
+ // Claude Code refreshes these figures on its own schedule, not per prompt, so
175
+ // each group travels with the time Claude Code fetched it: the plan / profile
176
+ // fields with `profile_observed_at`, the usage cache's fields with
177
+ // `observed_at`. A key is absent when its source is — absent means "not
178
+ // reported", never zero.
179
+ export const SUBSCRIPTION_SNAPSHOT = 'mainwave.subscription.snapshot'
180
+ export const VENDOR_ANTHROPIC = 'anthropic'
181
+
182
+ // Which hook event sent the snapshot.
183
+ export const ATTR_SUBSCRIPTION_TRIGGER = 'mainwave.subscription.trigger'
184
+ // The prompt the snapshot was taken at — Claude Code's own key for it (its
185
+ // api_request logs carry `prompt.id`), so the snapshot joins the prompt on one name.
186
+ export const ATTR_PROMPT_ID = 'prompt.id'
187
+
188
+ // Plan / profile — from `oauthAccount`.
189
+ export const ATTR_SUBSCRIPTION_PROVIDER = 'mainwave.subscription.provider'
190
+ export const ATTR_SUBSCRIPTION_ORGANIZATION_TYPE = 'mainwave.subscription.organization_type'
191
+ export const ATTR_SUBSCRIPTION_SEAT_TIER = 'mainwave.subscription.seat_tier'
192
+ export const ATTR_SUBSCRIPTION_RATE_LIMIT_TIER = 'mainwave.subscription.rate_limit_tier'
193
+ export const ATTR_SUBSCRIPTION_BILLING_TYPE = 'mainwave.subscription.billing_type'
194
+ export const ATTR_SUBSCRIPTION_ORGANIZATION_ROLE = 'mainwave.subscription.organization_role'
195
+ export const ATTR_SUBSCRIPTION_WORKSPACE_ROLE = 'mainwave.subscription.workspace_role'
196
+ export const ATTR_SUBSCRIPTION_CREATED_AT = 'mainwave.subscription.created_at'
197
+ export const ATTR_SUBSCRIPTION_TRIAL_ENDS_AT = 'mainwave.subscription.trial.ends_at'
198
+ export const ATTR_SUBSCRIPTION_TRIAL_DURATION_DAYS = 'mainwave.subscription.trial.duration_days'
199
+ export const ATTR_SUBSCRIPTION_PROFILE_OBSERVED_AT = 'mainwave.subscription.profile_observed_at'
200
+ // Top-level in the record, not under `oauthAccount`.
201
+ export const ATTR_SUBSCRIPTION_FIRST_TOKEN_DATE = 'mainwave.subscription.first_token_date'
202
+
203
+ // Usage — from `cachedUsageUtilization`, only when it names the same account.
204
+ export const ATTR_USAGE_FIVE_HOUR_UTILIZATION = 'mainwave.subscription.usage.five_hour.utilization'
205
+ export const ATTR_USAGE_FIVE_HOUR_RESETS_AT = 'mainwave.subscription.usage.five_hour.resets_at'
206
+ export const ATTR_USAGE_SEVEN_DAY_UTILIZATION = 'mainwave.subscription.usage.seven_day.utilization'
207
+ export const ATTR_USAGE_SEVEN_DAY_RESETS_AT = 'mainwave.subscription.usage.seven_day.resets_at'
208
+ export const ATTR_EXTRA_USAGE_ENABLED = 'mainwave.subscription.extra_usage.enabled'
209
+ export const ATTR_EXTRA_USAGE_USED_MINOR = 'mainwave.subscription.extra_usage.used_minor'
210
+ export const ATTR_EXTRA_USAGE_LIMIT_MINOR = 'mainwave.subscription.extra_usage.limit_minor'
211
+ export const ATTR_EXTRA_USAGE_CURRENCY = 'mainwave.subscription.extra_usage.currency'
212
+ export const ATTR_EXTRA_USAGE_EXPONENT = 'mainwave.subscription.extra_usage.exponent'
213
+ export const ATTR_EXTRA_USAGE_SPEND_LIMIT_REACHED =
214
+ 'mainwave.subscription.extra_usage.spend_limit_reached'
215
+ export const ATTR_EXTRA_USAGE_DISABLED_REASON = 'mainwave.subscription.extra_usage.disabled_reason'
216
+ export const ATTR_EXTRA_USAGE_USER_DISABLED = 'mainwave.subscription.extra_usage.user_disabled'
217
+ // Top-level `cachedExtraUsageDisabledReason`.
218
+ export const ATTR_EXTRA_USAGE_CACHED_DISABLED_REASON =
219
+ 'mainwave.subscription.extra_usage.cached_disabled_reason'
220
+ export const ATTR_SUBSCRIPTION_OBSERVED_AT = 'mainwave.subscription.observed_at'
221
+
222
+ // Rate limits — `utilization.limits[]`, one key group per entry, keyed by its
223
+ // `kind` (seen: `session`, `weekly_all`, `weekly_scoped`; an open set) and,
224
+ // for a scoped entry, its scope (`weekly_scoped` comes once per model):
225
+ // `limit.<kind>.<field>` unscoped, `limit.<kind>.<scope>.<field>` scoped, the
226
+ // scope being `scope.model.id`, else `scope.model.display_name`, else
227
+ // `scope.surface`. Both segments are reduced to `[a-z0-9_]`; a scoped group
228
+ // also carries the raw label as `scope_label`.
229
+ export const SUBSCRIPTION_LIMIT_PREFIX = 'mainwave.subscription.limit.'
230
+ export const SUBSCRIPTION_LIMIT_FIELDS = ['group', 'percent', 'severity', 'is_active', 'resets_at']
231
+ export const SUBSCRIPTION_LIMIT_SCOPED_FIELDS = [...SUBSCRIPTION_LIMIT_FIELDS, 'scope_label']
232
+ /** `mainwave.subscription.limit.<kind>[.<scope>].<field>`. */
233
+ export const subscriptionLimitKey = (kind, field, scope) =>
234
+ `${SUBSCRIPTION_LIMIT_PREFIX}${kind}.${scope === undefined ? '' : `${scope}.`}${field}`
235
+
236
+ // The provider's organization id, under the key Claude Code's own spans carry
237
+ // it, so the snapshot joins the session's native telemetry on the same names
238
+ // (`user.account_uuid`, `user.email`, `organization.id`).
239
+ export const ATTR_ORGANIZATION_ID = 'organization.id'
240
+
241
+ // The exact literal keys the snapshot may emit beyond the identity pair,
242
+ // `session.id` and the calling-span keys marker-core stamps — what the
243
+ // conformance test checks against the registry. The per-kind limit keys are a
244
+ // pattern (§ SUBSCRIPTION_LIMIT_FIELDS / SUBSCRIPTION_LIMIT_SCOPED_FIELDS),
245
+ // checked separately.
246
+ export const SUBSCRIPTION_SNAPSHOT_KEYS = [
247
+ ATTR_SUBSCRIPTION_TRIGGER,
248
+ ATTR_PROMPT_ID,
249
+ ATTR_SUBSCRIPTION_PROVIDER,
250
+ ATTR_SUBSCRIPTION_ORGANIZATION_TYPE,
251
+ ATTR_SUBSCRIPTION_SEAT_TIER,
252
+ ATTR_SUBSCRIPTION_RATE_LIMIT_TIER,
253
+ ATTR_SUBSCRIPTION_BILLING_TYPE,
254
+ ATTR_SUBSCRIPTION_ORGANIZATION_ROLE,
255
+ ATTR_SUBSCRIPTION_WORKSPACE_ROLE,
256
+ ATTR_SUBSCRIPTION_CREATED_AT,
257
+ ATTR_SUBSCRIPTION_TRIAL_ENDS_AT,
258
+ ATTR_SUBSCRIPTION_TRIAL_DURATION_DAYS,
259
+ ATTR_SUBSCRIPTION_PROFILE_OBSERVED_AT,
260
+ ATTR_SUBSCRIPTION_FIRST_TOKEN_DATE,
261
+ ATTR_USAGE_FIVE_HOUR_UTILIZATION,
262
+ ATTR_USAGE_FIVE_HOUR_RESETS_AT,
263
+ ATTR_USAGE_SEVEN_DAY_UTILIZATION,
264
+ ATTR_USAGE_SEVEN_DAY_RESETS_AT,
265
+ ATTR_EXTRA_USAGE_ENABLED,
266
+ ATTR_EXTRA_USAGE_USED_MINOR,
267
+ ATTR_EXTRA_USAGE_LIMIT_MINOR,
268
+ ATTR_EXTRA_USAGE_CURRENCY,
269
+ ATTR_EXTRA_USAGE_EXPONENT,
270
+ ATTR_EXTRA_USAGE_SPEND_LIMIT_REACHED,
271
+ ATTR_EXTRA_USAGE_DISABLED_REASON,
272
+ ATTR_EXTRA_USAGE_USER_DISABLED,
273
+ ATTR_EXTRA_USAGE_CACHED_DISABLED_REASON,
274
+ ATTR_SUBSCRIPTION_OBSERVED_AT,
275
+ ATTR_ORGANIZATION_ID,
276
+ ]
277
+
157
278
  // Every governed v2 event name the CLI hooks emit — checked against the
158
279
  // registry's events_v2 lists.
159
280
  export const CLI_EVENT_NAMES = [WI_CREATED, WI_UPDATED, VCS_OPENED]
281
+
282
+ // ── Claude Code turn failures — CLI hook feature ─────────────────────────────
283
+ // One more span under `mainwave.source = hook.anthropic`, beside the plan
284
+ // snapshot and joinable to it on the same identity and session keys
285
+ // (`user.account_uuid`, `user.email`, `session.id`, `prompt.id`). It carries
286
+ // ONE enumerated value from the hook input and nothing else from it: never the
287
+ // error details or the rendered error message.
288
+ //
289
+ // `stop-failure` runs on Claude Code's StopFailure event, which fires instead
290
+ // of Stop when a turn ends on an API error. Its key is the input's `error`
291
+ // enum (seen: rate_limit, overloaded, authentication_failed,
292
+ // oauth_org_not_allowed, account_on_hold, billing_error, invalid_request,
293
+ // model_not_found, server_error, max_output_tokens, cloud_credential_error,
294
+ // unknown — an open set; any `[a-z_]` token is sent as is).
295
+ export const CLAUDE_CODE_STOP_FAILURE = 'mainwave.claude_code.stop_failure'
296
+ export const ATTR_STOP_FAILURE_ERROR = 'mainwave.claude_code.stop_failure.error'
297
+
298
+ // The exact literal keys the span may emit beyond the identity pair,
299
+ // `session.id` and the calling-span keys — what the conformance test checks
300
+ // against the registry.
301
+ export const STOP_FAILURE_KEYS = [ATTR_STOP_FAILURE_ERROR, ATTR_PROMPT_ID]
302
+
303
+ // ── What each hook feature may send ─────────────────────────────────────────
304
+ // The dispatcher drops every span attribute a feature's entry here doesn't
305
+ // bind, and every span whose name isn't the feature's, before anything is
306
+ // posted: a key added to a feature without a registered name here never
307
+ // leaves the machine. `prefixes` covers the snapshot's per-kind limit keys,
308
+ // a registered pattern. Every feature may also send the identity pair, the
309
+ // session id and the calling-span keys (§ COMMON_SPAN_KEYS).
310
+ export const COMMON_SPAN_KEYS = Object.freeze([
311
+ 'session.id',
312
+ 'user.email',
313
+ 'user.account_uuid',
314
+ ...MARKER_CALL_CONTEXT_KEYS,
315
+ ])
316
+
317
+ export const FEATURE_EMITS = Object.freeze({
318
+ 'plan-snapshot': {
319
+ spans: [SUBSCRIPTION_SNAPSHOT],
320
+ keys: SUBSCRIPTION_SNAPSHOT_KEYS,
321
+ prefixes: [SUBSCRIPTION_LIMIT_PREFIX],
322
+ },
323
+ 'github-pr-marker': { spans: [VCS_OPENED], keys: VCS_MARKER_KEYS, prefixes: [] },
324
+ 'glab-mr-marker': { spans: [VCS_OPENED], keys: VCS_MARKER_KEYS, prefixes: [] },
325
+ 'linear-ticket-marker': {
326
+ spans: [WI_CREATED, WI_UPDATED],
327
+ keys: WORK_MARKER_KEYS,
328
+ prefixes: [],
329
+ },
330
+ 'jira-ticket-marker': {
331
+ spans: [WI_CREATED, WI_UPDATED],
332
+ keys: WORK_MARKER_KEYS,
333
+ prefixes: [],
334
+ },
335
+ 'stop-failure': { spans: [CLAUDE_CODE_STOP_FAILURE], keys: STOP_FAILURE_KEYS, prefixes: [] },
336
+ })
337
+
338
+ // The hook spans outside the work / vcs families, each under `hook.anthropic`
339
+ // — checked against the registry's `hook_events`.
340
+ export const ANTHROPIC_HOOK_SPANS = [SUBSCRIPTION_SNAPSHOT, CLAUDE_CODE_STOP_FAILURE]
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mainwave/cli",
3
- "version": "0.7.1",
3
+ "version": "0.9.0",
4
4
  "description": "Setup wizard for connecting third-party coding tools to Mainwave AI.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -46,12 +46,13 @@
46
46
  },
47
47
  "devDependencies": {
48
48
  "@hey-api/openapi-ts": "^0.99.0",
49
- "@types/node": "22.20.4",
50
- "lefthook": "2.1.14",
51
- "oxlint": "1.85.0",
49
+ "@types/node": "22.20.5",
50
+ "lefthook": "2.1.16",
51
+ "oxlint": "1.86.0",
52
52
  "prettier": "3.9.9",
53
53
  "typescript": "6.0.3",
54
- "vitest": "5.0.1",
54
+ "vite": "8.3.2",
55
+ "vitest": "5.0.3",
55
56
  "yaml": "2.9.1"
56
57
  },
57
58
  "keywords": [
@@ -81,9 +81,15 @@ Rules that bite:
81
81
  - **`service_name` is the deployable**, not the agent. `"support-triage"`, not
82
82
  `"ClassifierAgent"`. Defaults to `mainwave-app`, which tells the operator
83
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.
84
+ - Bind a use case with **one** of `use_case_id` (`MAINWAVE_USE_CASE_ID`, a UUID
85
+ from the app) or `use_case_key` (`MAINWAVE_USE_CASE_KEY`, a stable name the
86
+ SDK derives the UUID from). Passing both as arguments raises
87
+ `MainwaveConfigError`; if both env vars are set, `MAINWAVE_USE_CASE_ID` wins.
88
+ With neither, the SDK derives an id from `service_name` and logs it at INFO;
89
+ that telemetry lands in a use case the operator never created. Derived ids
90
+ (from a `use_case_key` too) seed on the API key unless `ucid_namespace`
91
+ (`MAINWAVE_UCID_NAMESPACE`) is set, so a key rotation changes them; the SDK
92
+ logs a WARNING while it is unset.
87
93
 
88
94
  ## 4. Mark the unit of work
89
95
 
@@ -123,16 +129,21 @@ Long-running servers do not need this; the batch processor drains on its own.
123
129
 
124
130
  ## 6. Verify — do not skip this
125
131
 
126
- Run the application so it does real work, then watch for it to land:
132
+ Start the watcher **before** the application does its work, in the background
133
+ or a second terminal, with the id the code actually sends:
127
134
 
128
135
  ```bash
129
- npx @mainwave/cli@latest verify --ucid <use-case-id> --no-sample
136
+ npx @mainwave/cli@latest verify --ucid <use-case-id> --no-sample --timeout 300
130
137
  ```
131
138
 
139
+ While it is watching, run the application so it does real work.
140
+
132
141
  `--no-sample` is required here. Without it the CLI pushes its own synthetic
133
142
  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.
143
+ instrumentation does nothing. The command counts only spans that start after
144
+ it starts, so a run made before it began is not seen, and it gives up after
145
+ 60 s unless `--timeout <seconds>` is given. It reports the agent names it saw —
146
+ check that the application's own name is among them.
136
147
 
137
148
  If nothing arrives, work `reference/troubleshooting.md`; the most common cause
138
149
  is by design and is listed first.
@@ -152,6 +163,9 @@ is by design and is listed first.
152
163
  - **Do not restructure the app to fit the SDK.** If the code has no clean unit
153
164
  of work, add a run at the outermost sensible boundary and say so; do not
154
165
  refactor their architecture as part of an instrumentation task.
166
+ - Content (prompts, completions, tool bodies, reasoning) is captured by default.
167
+ If the user handles sensitive data, say so and offer
168
+ `init(capture_content=False)`; do not decide for them.
155
169
 
156
170
  ## Reference
157
171
 
@@ -11,14 +11,30 @@ mainwave.init(
11
11
  *,
12
12
  api_key: str | None = None, # env: MAINWAVE_API_KEY (required)
13
13
  use_case_id: str | None = None, # env: MAINWAVE_USE_CASE_ID
14
+ use_case_key: str | None = None, # env: MAINWAVE_USE_CASE_KEY
15
+ ucid_namespace: str | None = None, # env: MAINWAVE_UCID_NAMESPACE
14
16
  collector_url: str | None = None, # env: MAINWAVE_COLLECTOR_URL
15
17
  service_name: str | None = None, # env: OTEL_SERVICE_NAME
16
18
  deployment_environment: str | None = None,# env: MAINWAVE_ENVIRONMENT
17
19
  disabled: bool | None = None, # env: MAINWAVE_DISABLED
18
20
  skip_instrumentors: list[str] | None = None,
21
+ capture_content: bool | str | None = None,# env: OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT
19
22
  ) -> None
20
23
  ```
21
24
 
25
+ `use_case_id` is a UUID from the app; `use_case_key` is a stable name the SDK
26
+ derives the UUID from. Passing both as arguments raises
27
+ `MainwaveConfigError`; if both env vars are set, `MAINWAVE_USE_CASE_ID` wins.
28
+ With neither, the key defaults to `service_name`. `capture_content` defaults to
29
+ `SPAN_ONLY` (content on); `False` sends no message, tool or reasoning bodies.
30
+
31
+ ```python
32
+ mainwave.use_case_id_for(key: str | None = None, *, agent_name: str | None = None) -> str
33
+ ```
34
+
35
+ Returns the UUID the SDK derives for a key, for an agent name under the
36
+ configured `service_name`, or, with no argument, the process default.
37
+
22
38
  Idempotent when called again with identical config; raises
23
39
  `MainwaveReinitConflict` when the config differs. Bad config raises
24
40
  `MainwaveConfigError`. After a successful init, runtime errors are swallowed —
@@ -49,11 +65,11 @@ in telemetry.
49
65
  ## Runs and spans
50
66
 
51
67
  ```python
52
- with mainwave.run(run_id, *, metadata=None, use_case_id=None, agent_name=None) as r: ...
68
+ with mainwave.run(run_id, *, metadata=None, use_case_id=None, use_case_key=None, agent_name=None) as r: ...
53
69
  async with mainwave.arun(...) as r: ...
54
70
  r = mainwave.start_run(...) # same args, no context manager
55
71
  with mainwave.span(name, *, attrs=None) as s: ...
56
- with mainwave.bind_identity(*, use_case_id=None, agent_name=None): ...
72
+ with mainwave.bind_identity(*, use_case_id=None, use_case_key=None, agent_name=None): ...
57
73
  ```
58
74
 
59
75
  `span()` is the escape hatch for a manual span; it inherits the active run's id
@@ -83,8 +99,11 @@ mainwave.flush(timeout: float = 30.0) -> bool
83
99
  await mainwave.aflush(timeout: float = 30.0) -> bool
84
100
  ```
85
101
 
86
- An `atexit` handler is registered automatically, but call `flush()` explicitly
87
- in scripts and job handlers — an abrupt exit path can outrun `atexit`.
102
+ `init()` registers an `atexit` flush and a SIGTERM handler that flushes, then
103
+ calls the handler the app had installed before it (or exits, if there was
104
+ none). `MAINWAVE_DISABLE_SIGNAL_HANDLER=1` keeps the app's SIGTERM handling
105
+ untouched and leaves only `atexit`. Call `flush()` explicitly in scripts and
106
+ job handlers — an abrupt exit path can outrun `atexit`.
88
107
 
89
108
  ## Errors
90
109
 
@@ -114,12 +133,12 @@ the SDK _inside_ fixtures rather than importing it at module level in
114
133
 
115
134
  ## Defaults
116
135
 
117
- | Setting | Default |
118
- | ------------------------ | -------------------------------------------------------- |
119
- | `collector_url` | `https://collector.mainwave.com` |
120
- | `service_name` | `mainwave-app` — always override |
121
- | `deployment_environment` | `production` |
122
- | `use_case_id` | derived (stable UUIDv5 of key + service name) when unset |
136
+ | Setting | Default |
137
+ | ------------------------ | -------------------------------------------------------------------------------------------------------- |
138
+ | `collector_url` | `https://collector.mainwave.com` |
139
+ | `service_name` | `mainwave-app` — always override |
140
+ | `deployment_environment` | `production` |
141
+ | `use_case_id` | derived when unset: UUIDv5 of `ucid_namespace` (else the API key) + `use_case_key` (else `service_name`) |
123
142
 
124
143
  ## Optional dependency extras
125
144
 
@@ -70,9 +70,9 @@ with mainwave.bind_identity(use_case_id=tenant_ucid, agent_name="research"):
70
70
  chain.invoke(input)
71
71
  ```
72
72
 
73
- An agent name bound in context when a LangChain ROOT run starts derives the
74
- per-agent default (the same UCID the removed `CallbackHandler(agent_name=...)`
75
- used to produce); an explicit identity already bound in context wins over it.
73
+ An agent name bound in context when a LangChain root run starts derives the
74
+ per-agent default (key `<service_name>/<agent_name>`); an explicit identity
75
+ already bound in context wins over it.
76
76
  `mainwave.run()` establishes the same OTel context, so a turn comes out as one
77
77
  connected trace rather than a scatter of roots.
78
78
 
@@ -55,16 +55,23 @@ importable or its version conflicts with the instrumentor.
55
55
 
56
56
  ## 5. Spans are landing, but not in the use case you're watching
57
57
 
58
- - If `MAINWAVE_USE_CASE_ID` was unset, the SDK derived a stable id from the API
59
- key and service name and logged it at INFO. Telemetry is arriving — into a use
60
- case nobody created. Set the id explicitly.
58
+ - If neither `MAINWAVE_USE_CASE_ID` nor `MAINWAVE_USE_CASE_KEY` was set, the SDK
59
+ derived an id from `service_name` and logged it at INFO. Telemetry is
60
+ arriving — into a use case nobody created. Set `use_case_id` or
61
+ `use_case_key`.
62
+ - A run that binds `agent_name` with no use case set derives its id from
63
+ `<service_name>/<agent_name>`; `mainwave.use_case_id_for(agent_name=...)`
64
+ returns it.
61
65
  - Identity binds at the root of a unit of work. **Spans created before the bind
62
66
  do not inherit it**, so work started outside `mainwave.run(...)` /
63
67
  `bind_identity(...)` carries the process default instead of the override.
64
- - Verify against the id the code is actually sending, not the one you expected:
68
+ - Verify against the id the code is actually sending, not the one you expected.
69
+ Start the command first and run the application while it watches: it counts
70
+ only spans that start after it starts, and gives up after 60 s unless
71
+ `--timeout <seconds>` is given.
65
72
 
66
73
  ```bash
67
- npx @mainwave/cli@latest verify --ucid <use-case-id> --no-sample
74
+ npx @mainwave/cli@latest verify --ucid <use-case-id> --no-sample --timeout 300
68
75
  ```
69
76
 
70
77
  ## 6. One span per run, and no tokens or cost