@mainwave/cli 0.8.0 → 0.10.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 (42) hide show
  1. package/README.md +169 -42
  2. package/dist/adapters/claude-code.js +23 -4
  3. package/dist/adapters/codex-cli.js +1 -1
  4. package/dist/adapters/cursor.js +4 -2
  5. package/dist/adapters/index.js +3 -0
  6. package/dist/adapters/kiro.js +361 -0
  7. package/dist/core/apply.js +161 -46
  8. package/dist/core/behaviour-hooks.js +7 -7
  9. package/dist/core/codecs/kiro-hooks-json.js +76 -0
  10. package/dist/core/doctor.js +27 -9
  11. package/dist/core/effective-settings.js +10 -0
  12. package/dist/core/entry-script.js +90 -0
  13. package/dist/core/git-bash.js +40 -0
  14. package/dist/core/install-hooks.js +126 -43
  15. package/dist/core/interview.js +114 -16
  16. package/dist/core/markers.js +678 -140
  17. package/dist/core/remove.js +67 -0
  18. package/dist/core/settings.js +32 -6
  19. package/dist/core/skills.js +47 -1
  20. package/dist/core/status.js +2 -1
  21. package/dist/core/wizard.js +64 -3
  22. package/dist/main.js +28 -9
  23. package/hooks/cursor-otlp.mjs +4 -27
  24. package/hooks/github-pr-marker.mjs +35 -22
  25. package/hooks/glab-mr-marker.mjs +795 -0
  26. package/hooks/jira-ticket-marker.mjs +27 -15
  27. package/hooks/kiro-otlp.mjs +570 -0
  28. package/hooks/linear-ticket-marker.mjs +27 -15
  29. package/hooks/mainwave-hook-node.mjs +42 -0
  30. package/hooks/mainwave-hook.mjs +301 -0
  31. package/hooks/marker-core.mjs +368 -41
  32. package/hooks/matchers.json +82 -6
  33. package/hooks/plan-snapshot.mjs +529 -0
  34. package/hooks/stop-failure.mjs +43 -0
  35. package/hooks/vocabulary.d.mts +49 -0
  36. package/hooks/vocabulary.mjs +188 -0
  37. package/package.json +5 -5
  38. package/skills/mainwave-instrument/SKILL.md +21 -7
  39. package/skills/mainwave-instrument/reference/api.md +29 -10
  40. package/skills/mainwave-instrument/reference/frameworks.md +3 -3
  41. package/skills/mainwave-instrument/reference/troubleshooting.md +12 -5
  42. package/skills/mainwave-setup/SKILL.md +47 -12
@@ -4,6 +4,7 @@
4
4
 
5
5
  export const ATTR_SCHEMA_VERSION: string
6
6
  export const SCHEMA_VERSION: string
7
+ export const ATTR_CLI_VERSION: string
7
8
  export const ATTR_HOST_SOURCE: string
8
9
  export const MARKER_HOST_SOURCES: Readonly<Record<string, string>>
9
10
 
@@ -31,13 +32,61 @@ export const ATTR_VCS_REPOSITORY_URL_FULL: string
31
32
  export const ATTR_VCS_CHANGE_ID: string
32
33
  export const ATTR_VCS_CHANGE_TITLE: string
33
34
  export const ATTR_VCS_PROVIDER_NAME: string
35
+ export const ATTR_VCS_REPOSITORY_ID: string
34
36
  export const ATTR_VCS_CHANGE_FILES_CHANGED: string
35
37
  export const ATTR_VCS_CHANGE_LINES_ADDED: string
36
38
  export const ATTR_VCS_CHANGE_LINES_REMOVED: string
37
39
  export const VCS_PROVIDER_GITHUB: string
40
+ export const VCS_PROVIDER_GITLAB: string
38
41
  export const VCS_MARKER_KEYS: readonly string[]
39
42
 
40
43
  export const ATTR_CODE_FILE_PATH: string
41
44
  export const CODE_KEYS: readonly string[]
42
45
 
43
46
  export const CLI_EVENT_NAMES: readonly string[]
47
+
48
+ export const SUBSCRIPTION_SNAPSHOT: string
49
+ export const VENDOR_ANTHROPIC: string
50
+ export const ATTR_SUBSCRIPTION_TRIGGER: string
51
+ export const ATTR_PROMPT_ID: string
52
+ export const ATTR_SUBSCRIPTION_PROVIDER: string
53
+ export const ATTR_SUBSCRIPTION_ORGANIZATION_TYPE: string
54
+ export const ATTR_SUBSCRIPTION_SEAT_TIER: string
55
+ export const ATTR_SUBSCRIPTION_RATE_LIMIT_TIER: string
56
+ export const ATTR_SUBSCRIPTION_BILLING_TYPE: string
57
+ export const ATTR_SUBSCRIPTION_ORGANIZATION_ROLE: string
58
+ export const ATTR_SUBSCRIPTION_WORKSPACE_ROLE: string
59
+ export const ATTR_SUBSCRIPTION_CREATED_AT: string
60
+ export const ATTR_SUBSCRIPTION_TRIAL_ENDS_AT: string
61
+ export const ATTR_SUBSCRIPTION_TRIAL_DURATION_DAYS: string
62
+ export const ATTR_SUBSCRIPTION_PROFILE_OBSERVED_AT: string
63
+ export const ATTR_SUBSCRIPTION_FIRST_TOKEN_DATE: string
64
+ export const ATTR_USAGE_FIVE_HOUR_UTILIZATION: string
65
+ export const ATTR_USAGE_FIVE_HOUR_RESETS_AT: string
66
+ export const ATTR_USAGE_SEVEN_DAY_UTILIZATION: string
67
+ export const ATTR_USAGE_SEVEN_DAY_RESETS_AT: string
68
+ export const ATTR_EXTRA_USAGE_ENABLED: string
69
+ export const ATTR_EXTRA_USAGE_USED_MINOR: string
70
+ export const ATTR_EXTRA_USAGE_LIMIT_MINOR: string
71
+ export const ATTR_EXTRA_USAGE_CURRENCY: string
72
+ export const ATTR_EXTRA_USAGE_EXPONENT: string
73
+ export const ATTR_EXTRA_USAGE_SPEND_LIMIT_REACHED: string
74
+ export const ATTR_EXTRA_USAGE_DISABLED_REASON: string
75
+ export const ATTR_EXTRA_USAGE_USER_DISABLED: string
76
+ export const ATTR_EXTRA_USAGE_CACHED_DISABLED_REASON: string
77
+ export const ATTR_SUBSCRIPTION_OBSERVED_AT: string
78
+ export const SUBSCRIPTION_LIMIT_PREFIX: string
79
+ export const ATTR_ORGANIZATION_ID: string
80
+ export const SUBSCRIPTION_LIMIT_FIELDS: readonly string[]
81
+ export const SUBSCRIPTION_LIMIT_SCOPED_FIELDS: readonly string[]
82
+ export const subscriptionLimitKey: (kind: string, field: string, scope?: string) => string
83
+ export const SUBSCRIPTION_SNAPSHOT_KEYS: readonly string[]
84
+
85
+ export const CLAUDE_CODE_STOP_FAILURE: string
86
+ export const ATTR_STOP_FAILURE_ERROR: string
87
+ export const STOP_FAILURE_KEYS: readonly string[]
88
+ export const COMMON_SPAN_KEYS: readonly string[]
89
+ export const FEATURE_EMITS: Readonly<
90
+ Record<string, { spans: readonly string[]; keys: readonly string[]; prefixes: readonly string[] }>
91
+ >
92
+ export const ANTHROPIC_HOOK_SPANS: readonly string[]
@@ -24,6 +24,13 @@
24
24
  export const ATTR_SCHEMA_VERSION = 'mainwave.schema.version'
25
25
  export const SCHEMA_VERSION = '2'
26
26
 
27
+ // ── The CLI release that sent it ────────────────────────────────────────────
28
+ // The `@mainwave/cli` version whose hook scripts produced the emission, on the
29
+ // resource — the sibling of the SDKs' `mainwave.sdk.version`, so a hook bug can
30
+ // be pinned to a release and an operator can see which installs lag. Omitted
31
+ // when the script can't tell which release it belongs to; never guessed.
32
+ export const ATTR_CLI_VERSION = 'mainwave.cli.version'
33
+
27
34
  // ── Host coding tool of a marker ────────────────────────────────────────────
28
35
  // A marker's `mainwave.source` is `hook.<vendor>` (the vendor the marker is
29
36
  // ABOUT), so on its own it doesn't say which coding tool the hook ran inside.
@@ -130,6 +137,12 @@ export const ATTR_VCS_REPOSITORY_URL_FULL = 'vcs.repository.url.full'
130
137
  export const ATTR_VCS_CHANGE_ID = 'vcs.change.id'
131
138
  export const ATTR_VCS_CHANGE_TITLE = 'vcs.change.title'
132
139
  export const ATTR_VCS_PROVIDER_NAME = 'vcs.provider.name'
140
+ // The instance-namespaced id of the repository, `<instance>:<id>`, where the
141
+ // instance is the host (and any non-default port) of the vendor's own URL. GitLab
142
+ // ids are per instance, so two instances share one integer space; the namespace
143
+ // keeps their repositories apart. The id survives a rename or a move, which the
144
+ // URL does not. Only vendors whose repository has a stable id carry it.
145
+ export const ATTR_VCS_REPOSITORY_ID = 'vcs.repository.id'
133
146
  export const ATTR_VCS_CHANGE_FILES_CHANGED = 'vcs.change.files_changed'
134
147
  export const ATTR_VCS_CHANGE_LINES_ADDED = 'vcs.change.lines_added'
135
148
  export const ATTR_VCS_CHANGE_LINES_REMOVED = 'vcs.change.lines_removed'
@@ -137,12 +150,14 @@ export const ATTR_VCS_CHANGE_LINES_REMOVED = 'vcs.change.lines_removed'
137
150
  // `vcs.provider.name` value — vendor-as-value, replacing the implicit vendor in
138
151
  // the old `github.pr_*` key prefix.
139
152
  export const VCS_PROVIDER_GITHUB = 'github'
153
+ export const VCS_PROVIDER_GITLAB = 'gitlab'
140
154
 
141
155
  export const VCS_MARKER_KEYS = [
142
156
  ATTR_VCS_REPOSITORY_URL_FULL,
143
157
  ATTR_VCS_CHANGE_ID,
144
158
  ATTR_VCS_CHANGE_TITLE,
145
159
  ATTR_VCS_PROVIDER_NAME,
160
+ ATTR_VCS_REPOSITORY_ID,
146
161
  ATTR_VCS_CHANGE_FILES_CHANGED,
147
162
  ATTR_VCS_CHANGE_LINES_ADDED,
148
163
  ATTR_VCS_CHANGE_LINES_REMOVED,
@@ -154,6 +169,179 @@ export const VCS_MARKER_KEYS = [
154
169
  export const ATTR_CODE_FILE_PATH = 'code.file.path'
155
170
  export const CODE_KEYS = [ATTR_CODE_FILE_PATH]
156
171
 
172
+ // ── Subscription snapshot — the CLI hook's plan-snapshot feature ─────────────
173
+ // Claude Code's own telemetry carries neither the account's plan, its usage
174
+ // against its rate limits, nor its overage ("extra usage") spend; Claude Code
175
+ // keeps them in its local account record. This hook sends them as one span on
176
+ // every submitted prompt (UserPromptSubmit), under `mainwave.source = hook.anthropic` (the vendor the
177
+ // snapshot is about). Strings are sent exactly as Claude Code stores them — no
178
+ // mapping, normalizing or display names; readers interpret them. Money is in
179
+ // the currency's minor unit: `used_minor / 10^exponent` is the amount.
180
+ //
181
+ // Claude Code refreshes these figures on its own schedule, not per prompt, so
182
+ // each group travels with the time Claude Code fetched it: the plan / profile
183
+ // fields with `profile_observed_at`, the usage cache's fields with
184
+ // `observed_at`. A key is absent when its source is — absent means "not
185
+ // reported", never zero.
186
+ export const SUBSCRIPTION_SNAPSHOT = 'mainwave.subscription.snapshot'
187
+ export const VENDOR_ANTHROPIC = 'anthropic'
188
+
189
+ // Which hook event sent the snapshot.
190
+ export const ATTR_SUBSCRIPTION_TRIGGER = 'mainwave.subscription.trigger'
191
+ // The prompt the snapshot was taken at — Claude Code's own key for it (its
192
+ // api_request logs carry `prompt.id`), so the snapshot joins the prompt on one name.
193
+ export const ATTR_PROMPT_ID = 'prompt.id'
194
+
195
+ // Plan / profile — from `oauthAccount`.
196
+ export const ATTR_SUBSCRIPTION_PROVIDER = 'mainwave.subscription.provider'
197
+ export const ATTR_SUBSCRIPTION_ORGANIZATION_TYPE = 'mainwave.subscription.organization_type'
198
+ export const ATTR_SUBSCRIPTION_SEAT_TIER = 'mainwave.subscription.seat_tier'
199
+ export const ATTR_SUBSCRIPTION_RATE_LIMIT_TIER = 'mainwave.subscription.rate_limit_tier'
200
+ export const ATTR_SUBSCRIPTION_BILLING_TYPE = 'mainwave.subscription.billing_type'
201
+ export const ATTR_SUBSCRIPTION_ORGANIZATION_ROLE = 'mainwave.subscription.organization_role'
202
+ export const ATTR_SUBSCRIPTION_WORKSPACE_ROLE = 'mainwave.subscription.workspace_role'
203
+ export const ATTR_SUBSCRIPTION_CREATED_AT = 'mainwave.subscription.created_at'
204
+ export const ATTR_SUBSCRIPTION_TRIAL_ENDS_AT = 'mainwave.subscription.trial.ends_at'
205
+ export const ATTR_SUBSCRIPTION_TRIAL_DURATION_DAYS = 'mainwave.subscription.trial.duration_days'
206
+ export const ATTR_SUBSCRIPTION_PROFILE_OBSERVED_AT = 'mainwave.subscription.profile_observed_at'
207
+ // Top-level in the record, not under `oauthAccount`.
208
+ export const ATTR_SUBSCRIPTION_FIRST_TOKEN_DATE = 'mainwave.subscription.first_token_date'
209
+
210
+ // Usage — from `cachedUsageUtilization`, only when it names the same account.
211
+ export const ATTR_USAGE_FIVE_HOUR_UTILIZATION = 'mainwave.subscription.usage.five_hour.utilization'
212
+ export const ATTR_USAGE_FIVE_HOUR_RESETS_AT = 'mainwave.subscription.usage.five_hour.resets_at'
213
+ export const ATTR_USAGE_SEVEN_DAY_UTILIZATION = 'mainwave.subscription.usage.seven_day.utilization'
214
+ export const ATTR_USAGE_SEVEN_DAY_RESETS_AT = 'mainwave.subscription.usage.seven_day.resets_at'
215
+ export const ATTR_EXTRA_USAGE_ENABLED = 'mainwave.subscription.extra_usage.enabled'
216
+ export const ATTR_EXTRA_USAGE_USED_MINOR = 'mainwave.subscription.extra_usage.used_minor'
217
+ export const ATTR_EXTRA_USAGE_LIMIT_MINOR = 'mainwave.subscription.extra_usage.limit_minor'
218
+ export const ATTR_EXTRA_USAGE_CURRENCY = 'mainwave.subscription.extra_usage.currency'
219
+ export const ATTR_EXTRA_USAGE_EXPONENT = 'mainwave.subscription.extra_usage.exponent'
220
+ export const ATTR_EXTRA_USAGE_SPEND_LIMIT_REACHED =
221
+ 'mainwave.subscription.extra_usage.spend_limit_reached'
222
+ export const ATTR_EXTRA_USAGE_DISABLED_REASON = 'mainwave.subscription.extra_usage.disabled_reason'
223
+ export const ATTR_EXTRA_USAGE_USER_DISABLED = 'mainwave.subscription.extra_usage.user_disabled'
224
+ // Top-level `cachedExtraUsageDisabledReason`.
225
+ export const ATTR_EXTRA_USAGE_CACHED_DISABLED_REASON =
226
+ 'mainwave.subscription.extra_usage.cached_disabled_reason'
227
+ export const ATTR_SUBSCRIPTION_OBSERVED_AT = 'mainwave.subscription.observed_at'
228
+
229
+ // Rate limits — `utilization.limits[]`, one key group per entry, keyed by its
230
+ // `kind` (seen: `session`, `weekly_all`, `weekly_scoped`; an open set) and,
231
+ // for a scoped entry, its scope (`weekly_scoped` comes once per model):
232
+ // `limit.<kind>.<field>` unscoped, `limit.<kind>.<scope>.<field>` scoped, the
233
+ // scope being `scope.model.id`, else `scope.model.display_name`, else
234
+ // `scope.surface`. Both segments are reduced to `[a-z0-9_]`; a scoped group
235
+ // also carries the raw label as `scope_label`.
236
+ export const SUBSCRIPTION_LIMIT_PREFIX = 'mainwave.subscription.limit.'
237
+ export const SUBSCRIPTION_LIMIT_FIELDS = ['group', 'percent', 'severity', 'is_active', 'resets_at']
238
+ export const SUBSCRIPTION_LIMIT_SCOPED_FIELDS = [...SUBSCRIPTION_LIMIT_FIELDS, 'scope_label']
239
+ /** `mainwave.subscription.limit.<kind>[.<scope>].<field>`. */
240
+ export const subscriptionLimitKey = (kind, field, scope) =>
241
+ `${SUBSCRIPTION_LIMIT_PREFIX}${kind}.${scope === undefined ? '' : `${scope}.`}${field}`
242
+
243
+ // The provider's organization id, under the key Claude Code's own spans carry
244
+ // it, so the snapshot joins the session's native telemetry on the same names
245
+ // (`user.account_uuid`, `user.email`, `organization.id`).
246
+ export const ATTR_ORGANIZATION_ID = 'organization.id'
247
+
248
+ // The exact literal keys the snapshot may emit beyond the identity pair,
249
+ // `session.id` and the calling-span keys marker-core stamps — what the
250
+ // conformance test checks against the registry. The per-kind limit keys are a
251
+ // pattern (§ SUBSCRIPTION_LIMIT_FIELDS / SUBSCRIPTION_LIMIT_SCOPED_FIELDS),
252
+ // checked separately.
253
+ export const SUBSCRIPTION_SNAPSHOT_KEYS = [
254
+ ATTR_SUBSCRIPTION_TRIGGER,
255
+ ATTR_PROMPT_ID,
256
+ ATTR_SUBSCRIPTION_PROVIDER,
257
+ ATTR_SUBSCRIPTION_ORGANIZATION_TYPE,
258
+ ATTR_SUBSCRIPTION_SEAT_TIER,
259
+ ATTR_SUBSCRIPTION_RATE_LIMIT_TIER,
260
+ ATTR_SUBSCRIPTION_BILLING_TYPE,
261
+ ATTR_SUBSCRIPTION_ORGANIZATION_ROLE,
262
+ ATTR_SUBSCRIPTION_WORKSPACE_ROLE,
263
+ ATTR_SUBSCRIPTION_CREATED_AT,
264
+ ATTR_SUBSCRIPTION_TRIAL_ENDS_AT,
265
+ ATTR_SUBSCRIPTION_TRIAL_DURATION_DAYS,
266
+ ATTR_SUBSCRIPTION_PROFILE_OBSERVED_AT,
267
+ ATTR_SUBSCRIPTION_FIRST_TOKEN_DATE,
268
+ ATTR_USAGE_FIVE_HOUR_UTILIZATION,
269
+ ATTR_USAGE_FIVE_HOUR_RESETS_AT,
270
+ ATTR_USAGE_SEVEN_DAY_UTILIZATION,
271
+ ATTR_USAGE_SEVEN_DAY_RESETS_AT,
272
+ ATTR_EXTRA_USAGE_ENABLED,
273
+ ATTR_EXTRA_USAGE_USED_MINOR,
274
+ ATTR_EXTRA_USAGE_LIMIT_MINOR,
275
+ ATTR_EXTRA_USAGE_CURRENCY,
276
+ ATTR_EXTRA_USAGE_EXPONENT,
277
+ ATTR_EXTRA_USAGE_SPEND_LIMIT_REACHED,
278
+ ATTR_EXTRA_USAGE_DISABLED_REASON,
279
+ ATTR_EXTRA_USAGE_USER_DISABLED,
280
+ ATTR_EXTRA_USAGE_CACHED_DISABLED_REASON,
281
+ ATTR_SUBSCRIPTION_OBSERVED_AT,
282
+ ATTR_ORGANIZATION_ID,
283
+ ]
284
+
157
285
  // Every governed v2 event name the CLI hooks emit — checked against the
158
286
  // registry's events_v2 lists.
159
287
  export const CLI_EVENT_NAMES = [WI_CREATED, WI_UPDATED, VCS_OPENED]
288
+
289
+ // ── Claude Code turn failures — CLI hook feature ─────────────────────────────
290
+ // One more span under `mainwave.source = hook.anthropic`, beside the plan
291
+ // snapshot and joinable to it on the same identity and session keys
292
+ // (`user.account_uuid`, `user.email`, `session.id`, `prompt.id`). It carries
293
+ // ONE enumerated value from the hook input and nothing else from it: never the
294
+ // error details or the rendered error message.
295
+ //
296
+ // `stop-failure` runs on Claude Code's StopFailure event, which fires instead
297
+ // of Stop when a turn ends on an API error. Its key is the input's `error`
298
+ // enum (seen: rate_limit, overloaded, authentication_failed,
299
+ // oauth_org_not_allowed, account_on_hold, billing_error, invalid_request,
300
+ // model_not_found, server_error, max_output_tokens, cloud_credential_error,
301
+ // unknown — an open set; any `[a-z_]` token is sent as is).
302
+ export const CLAUDE_CODE_STOP_FAILURE = 'mainwave.claude_code.stop_failure'
303
+ export const ATTR_STOP_FAILURE_ERROR = 'mainwave.claude_code.stop_failure.error'
304
+
305
+ // The exact literal keys the span may emit beyond the identity pair,
306
+ // `session.id` and the calling-span keys — what the conformance test checks
307
+ // against the registry.
308
+ export const STOP_FAILURE_KEYS = [ATTR_STOP_FAILURE_ERROR, ATTR_PROMPT_ID]
309
+
310
+ // ── What each hook feature may send ─────────────────────────────────────────
311
+ // The dispatcher drops every span attribute a feature's entry here doesn't
312
+ // bind, and every span whose name isn't the feature's, before anything is
313
+ // posted: a key added to a feature without a registered name here never
314
+ // leaves the machine. `prefixes` covers the snapshot's per-kind limit keys,
315
+ // a registered pattern. Every feature may also send the identity pair, the
316
+ // session id and the calling-span keys (§ COMMON_SPAN_KEYS).
317
+ export const COMMON_SPAN_KEYS = Object.freeze([
318
+ 'session.id',
319
+ 'user.email',
320
+ 'user.account_uuid',
321
+ ...MARKER_CALL_CONTEXT_KEYS,
322
+ ])
323
+
324
+ export const FEATURE_EMITS = Object.freeze({
325
+ 'plan-snapshot': {
326
+ spans: [SUBSCRIPTION_SNAPSHOT],
327
+ keys: SUBSCRIPTION_SNAPSHOT_KEYS,
328
+ prefixes: [SUBSCRIPTION_LIMIT_PREFIX],
329
+ },
330
+ 'github-pr-marker': { spans: [VCS_OPENED], keys: VCS_MARKER_KEYS, prefixes: [] },
331
+ 'glab-mr-marker': { spans: [VCS_OPENED], keys: VCS_MARKER_KEYS, prefixes: [] },
332
+ 'linear-ticket-marker': {
333
+ spans: [WI_CREATED, WI_UPDATED],
334
+ keys: WORK_MARKER_KEYS,
335
+ prefixes: [],
336
+ },
337
+ 'jira-ticket-marker': {
338
+ spans: [WI_CREATED, WI_UPDATED],
339
+ keys: WORK_MARKER_KEYS,
340
+ prefixes: [],
341
+ },
342
+ 'stop-failure': { spans: [CLAUDE_CODE_STOP_FAILURE], keys: STOP_FAILURE_KEYS, prefixes: [] },
343
+ })
344
+
345
+ // The hook spans outside the work / vcs families, each under `hook.anthropic`
346
+ // — checked against the registry's `hook_events`.
347
+ 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.8.0",
3
+ "version": "0.10.0",
4
4
  "description": "Setup wizard for connecting third-party coding tools to Mainwave AI.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -46,13 +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",
49
+ "@types/node": "22.20.5",
50
+ "lefthook": "2.1.16",
51
51
  "oxlint": "1.86.0",
52
52
  "prettier": "3.9.9",
53
53
  "typescript": "6.0.3",
54
- "vite": "8.3.1",
55
- "vitest": "5.0.2",
54
+ "vite": "8.3.2",
55
+ "vitest": "5.0.3",
56
56
  "yaml": "2.9.1"
57
57
  },
58
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
@@ -44,8 +44,10 @@ npx @mainwave/cli@latest setup <adapter> --yes --json
44
44
  ```
45
45
 
46
46
  Use the adapter for the tool you are running inside — `claude-code`, `codex`,
47
- `copilot-cli`, `copilot-chat`, `cursor`, `claude-desktop`. Run `setup` with no
48
- adapter to see what the CLI detects on this machine.
47
+ `copilot-cli`, `copilot-chat`, `cursor`, `cursor-enterprise`, `claude-desktop`.
48
+ Without a terminal, `setup` needs the adapter named: with none it stops with
49
+ "requires an interactive terminal". If you cannot tell which tool you are
50
+ running in, ask the user.
49
51
 
50
52
  Config always lands in the user's home directory; there is no repo-local option,
51
53
  so nothing setup writes can end up committed.
@@ -71,14 +73,31 @@ Flags worth knowing, all optional:
71
73
  no email — don't pass `--ucid` for it unless the user names a use case. If setup warns that a tool has no email, its activity lands
72
74
  unattributed until you re-run with `--email`.
73
75
  - `--opt-in` selects content capture. The default is **everything on** — prompt
74
- text, shell commands and file paths, tool result bodies — and it is never
75
- prompted for. `--opt-in none` sends metadata only; a named list
76
- (`--opt-in tool-details`) selects exactly those.
77
- - `--no-markers` skips the ticket & PR marker hooks, which are installed by
78
- default. They emit issue keys and PR numbers/urls only — no bodies, no diffs —
79
- and they are the only source of the "Tickets filed" / "PRs created" counts.
80
-
81
- **Tell the user what the default captures, before you run setup.** Prompt text
76
+ text, shell commands and file paths, tool result bodies, and for Claude Code
77
+ repository names — and it is never prompted for. `--opt-in none` sends
78
+ metadata only; a named list (`--opt-in tool-details`,
79
+ `--opt-in tool-details,repository`) selects exactly those.
80
+ - `--no-markers` installs no Mainwave hooks at all, which are installed by
81
+ default: the ticket & PR markers and, for Claude Code, the plan snapshot
82
+ below. The markers emit issue keys and PR / MR numbers and urls only — no
83
+ bodies, no diffs — and they are the only source of the "Tickets filed" /
84
+ "PRs created" counts.
85
+ - The Claude plan snapshot (Claude Code) installs with the Mainwave hooks and
86
+ has no flag of its own; only `--no-markers` leaves it out. On every prompt
87
+ it sends the user's Claude plan and tier names, roles, subscription and
88
+ trial dates, usage against rate limits and extra-usage spend, with their
89
+ Claude email, account id and organization id and the session, prompt, trace
90
+ and span ids. It never includes prompt text; prompt text reaches Mainwave
91
+ only through Claude Code's own telemetry, when prompt capture is on (it is
92
+ by default) or raw API body logging is enabled. Only sessions signed in
93
+ with a Claude account send it. With it comes the error type when a turn
94
+ ends on an API error (never its text).
95
+ - With any hook on, Claude Code setup also adds a session-start hook that runs
96
+ `npx @mainwave/cli@latest install-hooks` in the background to keep the hook
97
+ scripts current. Mention it when you list what setup installs.
98
+
99
+ **Tell the user what the default captures, before you run setup.** For Claude
100
+ Code, also say that the plan snapshot is on and what it sends. Prompt text
82
101
  and tool result bodies leave the machine under the default. If they want less:
83
102
 
84
103
  - **Claude Code:** `--opt-in none` still gives them every activity view —
@@ -91,6 +110,20 @@ and tool result bodies leave the machine under the default. If they want less:
91
110
 
92
111
  Never talk someone out of less capture because it makes a demo better.
93
112
 
113
+ Read the plan snapshot fields in the JSON before you report the result.
114
+ `planSnapshot` says whether the snapshot is sent; `planSnapshotReason`, when
115
+ present, says why:
116
+
117
+ - `"no-markers"` (`planSnapshot: false`): `--no-markers` installed no hooks.
118
+ - `"org-delivered"` (`planSnapshot: true`): `--no-markers` installed no hooks,
119
+ but the organization's managed settings send the snapshot anyway; only their
120
+ Claude admin can remove it.
121
+ - `"not-hosted"` (`planSnapshot: false`): no tool in this run hosts the
122
+ snapshot (only Claude Code does).
123
+ - `"blocked"` (`planSnapshot: false`): Claude Code won't run the user's own
124
+ hooks on this machine, and `planSnapshotBlockedBy` names the setting per
125
+ tool. Report it and do not retry.
126
+
94
127
  ## 3. Prove it works
95
128
 
96
129
  ```bash
@@ -134,8 +167,10 @@ rather than duplicating.
134
167
  - **Never print an API key, a token, or the contents of `~/.mainwave/credentials.json`.**
135
168
  The CLI masks secrets in its own output; don't undo that by `cat`-ing files.
136
169
  - **Say what the default captures; honour a request for less.** If the user asks
137
- for minimal capture, give it to them — `--opt-in none`, or `--opt-in
138
- tool-details` for Codex once they know what `none` costs there. Don't negotiate.
170
+ for minimal capture, give it to them — `--opt-in none`, `--no-markers` (no
171
+ hooks: no plan snapshot, but no ticket or PR counts either), or
172
+ `--opt-in tool-details` for Codex once they know what `none` costs there.
173
+ Don't negotiate.
139
174
  - **Never commit a settings file containing a key.** Setup writes only to the
140
175
  home directory, but an older CLI or a colleague may have left a repo-local
141
176
  file — `doctor <adapter>` lists every layer, so check before suggesting a