@mainwave/cli 0.8.0 → 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.
- package/README.md +137 -41
- package/dist/adapters/claude-code.js +23 -4
- package/dist/adapters/codex-cli.js +1 -1
- package/dist/adapters/cursor.js +2 -2
- package/dist/core/apply.js +151 -41
- package/dist/core/doctor.js +26 -8
- package/dist/core/effective-settings.js +10 -0
- package/dist/core/entry-script.js +90 -0
- package/dist/core/git-bash.js +40 -0
- package/dist/core/install-hooks.js +126 -43
- package/dist/core/interview.js +53 -3
- package/dist/core/markers.js +678 -140
- package/dist/core/settings.js +16 -5
- package/dist/core/status.js +2 -1
- package/dist/core/wizard.js +46 -1
- package/dist/main.js +16 -9
- package/hooks/cursor-otlp.mjs +1 -1
- package/hooks/github-pr-marker.mjs +35 -22
- package/hooks/glab-mr-marker.mjs +795 -0
- package/hooks/jira-ticket-marker.mjs +27 -15
- package/hooks/linear-ticket-marker.mjs +27 -15
- package/hooks/mainwave-hook-node.mjs +42 -0
- package/hooks/mainwave-hook.mjs +301 -0
- package/hooks/marker-core.mjs +273 -40
- package/hooks/matchers.json +82 -6
- package/hooks/plan-snapshot.mjs +529 -0
- package/hooks/stop-failure.mjs +43 -0
- package/hooks/vocabulary.d.mts +48 -0
- package/hooks/vocabulary.mjs +181 -0
- package/package.json +5 -5
- package/skills/mainwave-instrument/SKILL.md +21 -7
- package/skills/mainwave-instrument/reference/api.md +29 -10
- package/skills/mainwave-instrument/reference/frameworks.md +3 -3
- package/skills/mainwave-instrument/reference/troubleshooting.md +12 -5
- package/skills/mainwave-setup/SKILL.md +47 -12
package/hooks/vocabulary.mjs
CHANGED
|
@@ -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.
|
|
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,13 +46,13 @@
|
|
|
46
46
|
},
|
|
47
47
|
"devDependencies": {
|
|
48
48
|
"@hey-api/openapi-ts": "^0.99.0",
|
|
49
|
-
"@types/node": "22.20.
|
|
50
|
-
"lefthook": "2.1.
|
|
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.
|
|
55
|
-
"vitest": "5.0.
|
|
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
|
-
-
|
|
85
|
-
|
|
86
|
-
|
|
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
|
-
|
|
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
|
|
135
|
-
|
|
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
|
-
|
|
87
|
-
|
|
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
|
|
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
|
|
74
|
-
per-agent default (
|
|
75
|
-
|
|
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
|
|
59
|
-
|
|
60
|
-
case nobody created. Set
|
|
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`.
|
|
48
|
-
|
|
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
|
|
75
|
-
prompted for. `--opt-in none` sends
|
|
76
|
-
(`--opt-in tool-details
|
|
77
|
-
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
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`,
|
|
138
|
-
|
|
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
|