@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.
@@ -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.8.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.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