@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.
- package/README.md +141 -42
- package/dist/adapters/claude-code.js +33 -7
- package/dist/adapters/claude-desktop.js +0 -1
- package/dist/adapters/codex-cli.js +1 -2
- package/dist/adapters/copilot-chat.js +0 -1
- package/dist/adapters/copilot-cli.js +0 -1
- package/dist/adapters/cursor-enterprise.js +0 -1
- package/dist/adapters/cursor.js +15 -4
- package/dist/adapters/index.js +0 -1
- package/dist/adapters/types.js +0 -1
- package/dist/api/index.js +0 -1
- package/dist/api/types.gen.js +0 -1
- package/dist/cli.js +0 -1
- package/dist/core/apply.js +151 -42
- package/dist/core/auth-commands.js +0 -1
- package/dist/core/behaviour-hooks.js +0 -1
- package/dist/core/browser.js +0 -1
- package/dist/core/codecs/cursor-hooks-json.js +0 -1
- package/dist/core/codecs/env-file.js +0 -1
- package/dist/core/codecs/json-env.js +0 -1
- package/dist/core/codecs/json-flat.js +0 -1
- package/dist/core/codecs/json-managed.js +0 -1
- package/dist/core/codecs/toml-otel.js +0 -1
- package/dist/core/codecs/types.js +0 -1
- package/dist/core/detect.js +0 -1
- package/dist/core/device-login.js +0 -1
- package/dist/core/doctor.js +45 -9
- package/dist/core/edit.js +9 -5
- package/dist/core/effective-settings.js +71 -20
- package/dist/core/entry-script.js +90 -0
- package/dist/core/env-command.js +0 -1
- package/dist/core/errors.js +0 -1
- package/dist/core/flags.js +0 -1
- package/dist/core/format.js +0 -1
- package/dist/core/git-bash.js +40 -0
- package/dist/core/git.js +0 -1
- package/dist/core/headers.js +0 -1
- package/dist/core/install-hooks.js +127 -44
- package/dist/core/interview.js +53 -4
- package/dist/core/keys.js +0 -1
- package/dist/core/layer-policy.js +2 -1
- package/dist/core/markers.js +826 -133
- package/dist/core/pinned-use-case.js +0 -1
- package/dist/core/platform.js +0 -1
- package/dist/core/post-setup.js +0 -1
- package/dist/core/prompts.js +0 -1
- package/dist/core/settings.js +32 -8
- package/dist/core/skills.js +5 -2
- package/dist/core/status.js +7 -5
- package/dist/core/store.js +0 -1
- package/dist/core/tty.js +0 -1
- package/dist/core/ucid.js +0 -1
- package/dist/core/ui.js +0 -1
- package/dist/core/use-case.js +0 -1
- package/dist/core/validate.js +0 -1
- package/dist/core/verify.js +0 -1
- package/dist/core/version.js +0 -1
- package/dist/core/wizard.js +49 -8
- package/dist/main.js +16 -10
- package/hooks/cursor-otlp.mjs +13 -15
- package/hooks/github-pr-marker.mjs +55 -31
- package/hooks/glab-mr-marker.mjs +795 -0
- package/hooks/jira-ticket-marker.mjs +35 -23
- package/hooks/linear-ticket-marker.mjs +35 -21
- package/hooks/mainwave-hook-node.mjs +42 -0
- package/hooks/mainwave-hook.mjs +301 -0
- package/hooks/managed-entry.mjs +42 -0
- package/hooks/marker-core.mjs +389 -62
- 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 +6 -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-instrument-node/SKILL.md +420 -0
- package/skills/mainwave-instrument-node/reference/api.md +96 -0
- package/skills/mainwave-instrument-node/reference/frameworks.md +82 -0
- package/skills/mainwave-instrument-node/reference/troubleshooting.md +152 -0
- package/skills/mainwave-setup/SKILL.md +47 -12
- package/dist/adapters/claude-code.js.map +0 -1
- package/dist/adapters/claude-desktop.js.map +0 -1
- package/dist/adapters/codex-cli.js.map +0 -1
- package/dist/adapters/copilot-chat.js.map +0 -1
- package/dist/adapters/copilot-cli.js.map +0 -1
- package/dist/adapters/cursor-enterprise.js.map +0 -1
- package/dist/adapters/cursor.js.map +0 -1
- package/dist/adapters/index.js.map +0 -1
- package/dist/adapters/types.js.map +0 -1
- package/dist/api/index.js.map +0 -1
- package/dist/api/types.gen.js.map +0 -1
- package/dist/cli.js.map +0 -1
- package/dist/core/apply.js.map +0 -1
- package/dist/core/auth-commands.js.map +0 -1
- package/dist/core/behaviour-hooks.js.map +0 -1
- package/dist/core/browser.js.map +0 -1
- package/dist/core/codecs/cursor-hooks-json.js.map +0 -1
- package/dist/core/codecs/env-file.js.map +0 -1
- package/dist/core/codecs/json-env.js.map +0 -1
- package/dist/core/codecs/json-flat.js.map +0 -1
- package/dist/core/codecs/json-managed.js.map +0 -1
- package/dist/core/codecs/toml-otel.js.map +0 -1
- package/dist/core/codecs/types.js.map +0 -1
- package/dist/core/detect.js.map +0 -1
- package/dist/core/device-login.js.map +0 -1
- package/dist/core/doctor.js.map +0 -1
- package/dist/core/edit.js.map +0 -1
- package/dist/core/effective-settings.js.map +0 -1
- package/dist/core/env-command.js.map +0 -1
- package/dist/core/errors.js.map +0 -1
- package/dist/core/flags.js.map +0 -1
- package/dist/core/format.js.map +0 -1
- package/dist/core/git.js.map +0 -1
- package/dist/core/headers.js.map +0 -1
- package/dist/core/install-hooks.js.map +0 -1
- package/dist/core/interview.js.map +0 -1
- package/dist/core/keys.js.map +0 -1
- package/dist/core/layer-policy.js.map +0 -1
- package/dist/core/markers.js.map +0 -1
- package/dist/core/pinned-use-case.js.map +0 -1
- package/dist/core/platform.js.map +0 -1
- package/dist/core/post-setup.js.map +0 -1
- package/dist/core/prompts.js.map +0 -1
- package/dist/core/settings.js.map +0 -1
- package/dist/core/skills.js.map +0 -1
- package/dist/core/status.js.map +0 -1
- package/dist/core/store.js.map +0 -1
- package/dist/core/tty.js.map +0 -1
- package/dist/core/ucid.js.map +0 -1
- package/dist/core/ui.js.map +0 -1
- package/dist/core/use-case.js.map +0 -1
- package/dist/core/validate.js.map +0 -1
- package/dist/core/verify.js.map +0 -1
- package/dist/core/version.js.map +0 -1
- package/dist/core/wizard.js.map +0 -1
- package/dist/main.js.map +0 -1
package/hooks/vocabulary.d.mts
CHANGED
|
@@ -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[]
|
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,12 +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.
|
|
51
|
-
"oxlint": "1.
|
|
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
|
-
"
|
|
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
|
-
-
|
|
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
|