@mainwave/cli 0.10.0 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. package/README.md +176 -13
  2. package/dist/adapters/claude-code.js +5 -4
  3. package/dist/adapters/claude-desktop.js +35 -1
  4. package/dist/adapters/copilot-chat.js +7 -13
  5. package/dist/adapters/copilot-cli.js +9 -12
  6. package/dist/adapters/cursor.js +7 -2
  7. package/dist/adapters/kiro.js +13 -8
  8. package/dist/commands.js +217 -0
  9. package/dist/core/apply.js +13 -5
  10. package/dist/core/auth-commands.js +2 -1
  11. package/dist/core/codecs/kiro-hooks-json.js +1 -1
  12. package/dist/core/doctor.js +71 -8
  13. package/dist/core/entry-script.js +9 -4
  14. package/dist/core/format.js +0 -1
  15. package/dist/core/hook-copies.js +157 -0
  16. package/dist/core/install-hooks.js +148 -10
  17. package/dist/core/interview.js +8 -2
  18. package/dist/core/markers.js +90 -24
  19. package/dist/core/post-setup.js +5 -22
  20. package/dist/core/redaction.js +179 -0
  21. package/dist/core/skills.js +6 -14
  22. package/dist/core/status.js +21 -1
  23. package/dist/core/store.js +255 -5
  24. package/dist/core/url.js +1 -0
  25. package/dist/core/wizard.js +101 -7
  26. package/dist/main.js +163 -162
  27. package/hooks/git-commit-marker.mjs +406 -0
  28. package/hooks/kiro-otlp.mjs +10 -1
  29. package/hooks/mainwave-hook.mjs +17 -5
  30. package/hooks/marker-core.mjs +56 -2
  31. package/hooks/matchers.json +20 -3
  32. package/hooks/redaction-data.mjs +201 -0
  33. package/hooks/redaction-json.mjs +215 -0
  34. package/hooks/redaction-pattern.mjs +503 -0
  35. package/hooks/redaction.d.mts +84 -0
  36. package/hooks/redaction.mjs +701 -0
  37. package/hooks/vocabulary.d.mts +13 -0
  38. package/hooks/vocabulary.mjs +42 -1
  39. package/package.json +9 -7
  40. package/skills/mainwave-instrument/SKILL.md +24 -6
  41. package/skills/mainwave-instrument/reference/frameworks.md +4 -2
  42. package/skills/mainwave-instrument/reference/troubleshooting.md +4 -0
  43. package/skills/mainwave-instrument-node/SKILL.md +81 -30
  44. package/skills/mainwave-instrument-node/reference/api.md +3 -3
  45. package/skills/mainwave-instrument-node/reference/frameworks.md +42 -25
  46. package/skills/mainwave-instrument-node/reference/troubleshooting.md +11 -7
@@ -40,6 +40,19 @@ export const VCS_PROVIDER_GITHUB: string
40
40
  export const VCS_PROVIDER_GITLAB: string
41
41
  export const VCS_MARKER_KEYS: readonly string[]
42
42
 
43
+ export const VCS_COMMIT_CREATED: string
44
+ export const ATTR_VCS_COMMIT_SHA: string
45
+ export const ATTR_VCS_COMMIT_PARENT_SHA: string
46
+ export const ATTR_VCS_COMMIT_PARENT_COUNT: string
47
+ export const ATTR_VCS_COMMIT_FILES_CHANGED: string
48
+ export const ATTR_VCS_COMMIT_LINES_ADDED: string
49
+ export const ATTR_VCS_COMMIT_LINES_REMOVED: string
50
+ export const ATTR_VCS_COMMIT_FILE_PATHS: string
51
+ export const ATTR_VCS_COMMIT_FILE_LINES_ADDED: string
52
+ export const ATTR_VCS_COMMIT_FILE_LINES_REMOVED: string
53
+ export const ATTR_VCS_COMMIT_FILE_IS_BINARY: string
54
+ export const VCS_COMMIT_KEYS: readonly string[]
55
+
43
56
  export const ATTR_CODE_FILE_PATH: string
44
57
  export const CODE_KEYS: readonly string[]
45
58
 
@@ -163,6 +163,46 @@ export const VCS_MARKER_KEYS = [
163
163
  ATTR_VCS_CHANGE_LINES_REMOVED,
164
164
  ]
165
165
 
166
+ // ── Commit events — CLI git-commit-marker hook ───────────────────────────────
167
+ // One span per commit a coding agent made with `git commit`, read from
168
+ // `git show --numstat` for that commit. OTel's vcs namespace has no commit
169
+ // entity (v1.44.0 names a revision only as `vcs.ref.head.revision`), so these
170
+ // are house keys under the pinned vcs namespace, worded like the change size
171
+ // keys above.
172
+ export const VCS_COMMIT_CREATED = 'vcs.commit.created'
173
+
174
+ // The commit's full object name, and its first parent's (absent on a root
175
+ // commit). A merge commit has more than one parent; `parent_count` says so.
176
+ export const ATTR_VCS_COMMIT_SHA = 'vcs.commit.sha'
177
+ export const ATTR_VCS_COMMIT_PARENT_SHA = 'vcs.commit.parent_sha'
178
+ export const ATTR_VCS_COMMIT_PARENT_COUNT = 'vcs.commit.parent_count'
179
+ // Totals over every file in the commit. A binary file counts as changed and
180
+ // adds 0 lines either way.
181
+ export const ATTR_VCS_COMMIT_FILES_CHANGED = 'vcs.commit.files_changed'
182
+ export const ATTR_VCS_COMMIT_LINES_ADDED = 'vcs.commit.lines_added'
183
+ export const ATTR_VCS_COMMIT_LINES_REMOVED = 'vcs.commit.lines_removed'
184
+ // Per file, as four parallel OTLP arrays: element i of each describes the same
185
+ // file. Paths are repository-relative, as git prints them; a rename carries
186
+ // its new path. The lists may hold fewer files than `files_changed` on a very
187
+ // large commit (the hook caps them); the totals always cover every file.
188
+ export const ATTR_VCS_COMMIT_FILE_PATHS = 'vcs.commit.file.paths'
189
+ export const ATTR_VCS_COMMIT_FILE_LINES_ADDED = 'vcs.commit.file.lines_added'
190
+ export const ATTR_VCS_COMMIT_FILE_LINES_REMOVED = 'vcs.commit.file.lines_removed'
191
+ export const ATTR_VCS_COMMIT_FILE_IS_BINARY = 'vcs.commit.file.is_binary'
192
+
193
+ export const VCS_COMMIT_KEYS = [
194
+ ATTR_VCS_COMMIT_SHA,
195
+ ATTR_VCS_COMMIT_PARENT_SHA,
196
+ ATTR_VCS_COMMIT_PARENT_COUNT,
197
+ ATTR_VCS_COMMIT_FILES_CHANGED,
198
+ ATTR_VCS_COMMIT_LINES_ADDED,
199
+ ATTR_VCS_COMMIT_LINES_REMOVED,
200
+ ATTR_VCS_COMMIT_FILE_PATHS,
201
+ ATTR_VCS_COMMIT_FILE_LINES_ADDED,
202
+ ATTR_VCS_COMMIT_FILE_LINES_REMOVED,
203
+ ATTR_VCS_COMMIT_FILE_IS_BINARY,
204
+ ]
205
+
166
206
  // ── File references — CLI cursor behaviour hook ──────────────────────────────
167
207
  // The standard OTel Code (Stable) key, replacing the hook's former
168
208
  // `cursor.file_path`.
@@ -284,7 +324,7 @@ export const SUBSCRIPTION_SNAPSHOT_KEYS = [
284
324
 
285
325
  // Every governed v2 event name the CLI hooks emit — checked against the
286
326
  // registry's events_v2 lists.
287
- export const CLI_EVENT_NAMES = [WI_CREATED, WI_UPDATED, VCS_OPENED]
327
+ export const CLI_EVENT_NAMES = [WI_CREATED, WI_UPDATED, VCS_OPENED, VCS_COMMIT_CREATED]
288
328
 
289
329
  // ── Claude Code turn failures — CLI hook feature ─────────────────────────────
290
330
  // One more span under `mainwave.source = hook.anthropic`, beside the plan
@@ -329,6 +369,7 @@ export const FEATURE_EMITS = Object.freeze({
329
369
  },
330
370
  'github-pr-marker': { spans: [VCS_OPENED], keys: VCS_MARKER_KEYS, prefixes: [] },
331
371
  'glab-mr-marker': { spans: [VCS_OPENED], keys: VCS_MARKER_KEYS, prefixes: [] },
372
+ 'git-commit-marker': { spans: [VCS_COMMIT_CREATED], keys: VCS_COMMIT_KEYS, prefixes: [] },
332
373
  'linear-ticket-marker': {
333
374
  spans: [WI_CREATED, WI_UPDATED],
334
375
  keys: WORK_MARKER_KEYS,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mainwave/cli",
3
- "version": "0.10.0",
3
+ "version": "0.12.0",
4
4
  "description": "Setup wizard for connecting third-party coding tools to Mainwave AI.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -34,24 +34,26 @@
34
34
  "lint:fix": "oxlint --fix .",
35
35
  "format": "prettier --write .",
36
36
  "format:check": "prettier --check .",
37
+ "knip": "knip",
37
38
  "test": "vitest",
38
39
  "test:run": "vitest run",
39
- "test:hooks": "node --test tests/hooks/*.test.mjs",
40
+ "test:hooks": "node tests/hooks/check-node.mjs && node --import ./tests/hooks/setup.mjs --test tests/hooks/*.test.mjs",
40
41
  "prepare": "lefthook install",
41
42
  "api:generate": "openapi-ts"
42
43
  },
43
44
  "dependencies": {
44
- "@inquirer/prompts": "8.7.2",
45
+ "@inquirer/prompts": "8.7.3",
45
46
  "picocolors": "1.1.1"
46
47
  },
47
48
  "devDependencies": {
48
49
  "@hey-api/openapi-ts": "^0.99.0",
49
50
  "@types/node": "22.20.5",
50
- "lefthook": "2.1.16",
51
- "oxlint": "1.86.0",
52
- "prettier": "3.9.9",
51
+ "knip": "6.41.0",
52
+ "lefthook": "2.2.1",
53
+ "oxlint": "1.87.0",
54
+ "prettier": "3.9.10",
53
55
  "typescript": "6.0.3",
54
- "vite": "8.3.2",
56
+ "vite": "8.3.4",
55
57
  "vitest": "5.0.3",
56
58
  "yaml": "2.9.1"
57
59
  },
@@ -39,9 +39,14 @@ Answer these from the codebase, not from assumption:
39
39
  - **What is one "unit of work"?** A ticket triaged, a question answered, a
40
40
  document processed. This becomes a run, and it is the level a business
41
41
  operator reads results at — not one HTTP request, not one LLM call.
42
- - **Is OpenTelemetry already set up?** If the app builds its own
43
- `TracerProvider`, the SDK detects it and runs in coexist mode. Do not remove
44
- their setup; `init()` attaches to it.
42
+ - **Is OpenTelemetry already set up?** Search for `set_tracer_provider`,
43
+ `TracerProvider`, `opentelemetry-instrument` in the start command,
44
+ Dockerfile, or Procfile, and `sentry_sdk.init` when Sentry runs on
45
+ OpenTelemetry. If the app registers its own provider, the SDK detects it and
46
+ runs in coexist mode. Do not remove their setup. Note where it runs, because
47
+ `init()` goes after it, as section 3 describes. The `opentelemetry-instrument`
48
+ launcher registers its provider before any app code runs, so an `init()` in
49
+ the app already comes after it.
45
50
 
46
51
  ## 2. Install with narrow extras
47
52
 
@@ -65,9 +70,22 @@ mainwave.init(service_name="support-triage")
65
70
  ```
66
71
 
67
72
  `api_key` and `use_case_id` come from `MAINWAVE_API_KEY` and
68
- `MAINWAVE_USE_CASE_ID` when not passed. Call it **before** the framework does
69
- its work, and prefer placing it before the framework imports — instrumentors
70
- patch libraries at wire time.
73
+ `MAINWAVE_USE_CASE_ID` when not passed. Call it **after** the app's own
74
+ OpenTelemetry setup and **before** the framework does its work. Instrumentors
75
+ patch libraries when `init()` wires them, so a framework that has already done
76
+ its work is not captured. With no OpenTelemetry setup in the app, that means
77
+ the top of the entry point, before the framework imports.
78
+
79
+ ```python
80
+ trace.set_tracer_provider(provider) # the app's own setup, if it has one
81
+ mainwave.init(service_name="support-triage") # then Mainwave
82
+ ```
83
+
84
+ Never put `init()` before the app's own provider is registered. `init()` would
85
+ install the SDK's provider as the global one, OpenTelemetry would refuse the
86
+ app's provider, and the app's own backend would stop receiving spans. The
87
+ only sign is an `Overriding of current TracerProvider is not allowed`
88
+ warning, which OpenTelemetry logs.
71
89
 
72
90
  Rules that bite:
73
91
 
@@ -156,8 +156,10 @@ instead of installing one, and forwards spans under the host's resource
156
156
  untouched.
157
157
 
158
158
  Leave their setup alone. Do not remove their exporter, do not replace their
159
- provider, do not move their `TracerProvider` construction after `init()`. Their
160
- existing backend keeps receiving everything it received before.
159
+ provider, and do not call `init()` before their `TracerProvider` is registered.
160
+ In that order OpenTelemetry keeps the SDK's provider and refuses theirs, and
161
+ their backend stops receiving spans. Called after their setup, `init()` leaves
162
+ their existing backend receiving everything it received before.
161
163
 
162
164
  Only LLM-bearing traces are forwarded to Mainwave — the host's HTTP, database,
163
165
  and background-job traces stay out. That filtering is what makes sharing a
@@ -34,6 +34,10 @@ the span.
34
34
  a no-op that logs and returns. Check the deployment's env, not just the shell.
35
35
  - In a web app, confirm `init()` is in the startup hook and that the hook
36
36
  actually runs under the process manager in use.
37
+ - If the app has its own OpenTelemetry setup and its own backend stopped
38
+ receiving spans, `init()` ran before that setup. Look for an
39
+ `Overriding of current TracerProvider is not allowed` warning. Move `init()`
40
+ after the code that calls `trace.set_tracer_provider(...)`.
37
41
 
38
42
  ## 3. The process exited before the batch drained
39
43
 
@@ -25,16 +25,23 @@ Answer these from the codebase, not from assumption:
25
25
  `ai` (with `@ai-sdk/otel`), `openai`, `@anthropic-ai/sdk`. More than one can
26
26
  apply. Note the installed versions: eve `>=0.66.3 <0.70.0`, `ai` `^7` with
27
27
  `@ai-sdk/otel` `^1`, `openai` `>=4.19.0 <8`, `@anthropic-ai/sdk`
28
- `>=0.51.0 <1`. A version outside its range is not instrumented: report it, do
29
- not wire around it.
28
+ `>=0.134.0`. A version outside its range is not instrumented: report it, do
29
+ not wire around it. An `@anthropic-ai/sdk` below 0.134.0 records no spans
30
+ at all: tell the user to upgrade it. From 0.134.0 the client records its own
31
+ spans, and Mainwave's middleware adds what they leave out (section 6).
30
32
  - **Does the app already register OpenTelemetry?** Search for `@vercel/otel`
31
33
  (`registerOTel`), `@opentelemetry/sdk-node` (`NodeSDK`),
32
- `NodeTracerProvider`, a Next.js `instrumentation.ts`, or an eve
33
- `agent/instrumentation/` directory. If something registers the tracer
34
- provider, the app is a **host**: do not call `init()` into it.
34
+ `NodeTracerProvider`, `@sentry/node` (`Sentry.init`), a Next.js
35
+ `instrumentation.ts`, or an eve `agent/instrumentation/` directory. If
36
+ something registers the tracer provider, the app is a **host**: do not call
37
+ `init()` into it. Note where that setup runs, because Mainwave joins it
38
+ through `createSpanProcessor()`, as section 5b describes.
35
39
  - **Where does the process start?** The server entry, the worker bootstrap, the
36
40
  script's first file, the Next.js `instrumentation.ts` `register()`. That is
37
- where `init()` or the host wiring goes.
41
+ where `init()` or the host wiring goes. `init()` goes before the framework
42
+ does its work, because it patches libraries when it runs. Host wiring is
43
+ different: `createSpanProcessor()` installs no hooks, and section 6 says how
44
+ the clients attach.
38
45
  - **ESM or CommonJS, bundled or not, and what runtime?** This picks the attach
39
46
  path in section 6. Plain `node app.mjs` is not bundled; Vercel Functions,
40
47
  Next.js, and anything built by a bundler are.
@@ -72,8 +79,9 @@ npm install @mainwave/sdk # or: pnpm add @mainwave/sdk / yarn add @mainwave
72
79
  app already depends on another version of it, stop and report the conflict.
73
80
  The framework and provider packages are optional peers the application already
74
81
  installs; **install none of them for the user, and never install an
75
- OpenInference or Traceloop package**: the SDK carries its own OpenAI and
76
- Anthropic instrumentation, and a second one traces every call twice.
82
+ OpenInference or Traceloop package**: the SDK carries its own OpenAI
83
+ instrumentation and Anthropic middleware, and a second instrumentation traces
84
+ every call twice.
77
85
 
78
86
  If the install fails with "package not found", report that
79
87
  `@mainwave/sdk` is not yet published to npm and stop. Do not substitute another
@@ -168,10 +176,26 @@ A plain `NodeTracerProvider` takes
168
176
  - An `init()` call that finds another provider registered, with no
169
177
  `createSpanProcessor()` wired in, exports nothing and logs one warning.
170
178
  Do not "fix" that by removing the host's provider.
179
+ - Mainwave joins the host's setup through `createSpanProcessor()` and never
180
+ registers ahead of it. An `init()` that runs first registers Mainwave's
181
+ provider as the global one. OpenTelemetry keeps the first global provider
182
+ and refuses the host's, so the host's own backend silently stops receiving
183
+ spans. The only sign is an
184
+ `@opentelemetry/api: Attempted duplicate registration of API: trace` error on
185
+ OpenTelemetry's diagnostic channel, and it prints only when the app has set a
186
+ diagnostic logger. Remove an `init()` that sits ahead of the host's setup and
187
+ wire `createSpanProcessor()` into the host instead.
188
+ - For a setup not shown above, such as `@sentry/node` or another monitoring
189
+ SDK that registers OpenTelemetry for you, pass `createSpanProcessor()`
190
+ wherever that setup accepts span processors. Check that setup's own
191
+ documentation for the option. If it accepts none, report that to the user
192
+ and do not call `init()`.
171
193
 
172
194
  ## 5c. Owned mode: `init()` at process start
173
195
 
174
- For an application with no OpenTelemetry setup of its own:
196
+ For an application with no OpenTelemetry setup of its own. If the survey
197
+ found one, use section 5b instead. `init()` here would register the global
198
+ provider ahead of it.
175
199
 
176
200
  ```ts
177
201
  import { init } from '@mainwave/sdk'
@@ -237,11 +261,11 @@ passes `mainwaveTelemetry({ tracer })`.
237
261
  **OpenAI (`openai`) and Anthropic (`@anthropic-ai/sdk`) called directly:** choose
238
262
  by how the app starts.
239
263
 
240
- | The app is | Attach |
241
- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
242
- | A plain Node process you start (`node app.mjs`, a worker, a script) | `node --import @mainwave/sdk/register app.mjs` |
243
- | Bundled, or on Vercel Functions or Next.js, or the flag cannot be set | `instrument({ openai, anthropic })` after the host wiring (host mode, no `init()`), or after `init()` (owned mode) |
244
- | A host that registers its own OpenTelemetry instrumentations | `new OpenAIInstrumentation()` / `new AnthropicInstrumentation()` from `@mainwave/sdk/openai` / `@mainwave/sdk/anthropic` via `registerInstrumentations` |
264
+ | The app is | Attach |
265
+ | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
266
+ | A plain Node process you start (`node app.mjs`, a worker, a script) | `node --import @mainwave/sdk/register app.mjs` |
267
+ | Bundled, or on Vercel Functions or Next.js, or the flag cannot be set | `instrument({ openai })`, and `mainwaveMiddleware()` in every Anthropic client, after the host wiring (host mode, no `init()`), or after `init()` (owned mode) |
268
+ | A host that registers its own OpenTelemetry instrumentations | `new OpenAIInstrumentation()` from `@mainwave/sdk/openai` via `registerInstrumentations`; `mainwaveMiddleware()` in every Anthropic client |
245
269
 
246
270
  The loader flag covers static imports, dynamic `import()`, and `require()`,
247
271
  for both clients in one process. Put it where the process starts (the
@@ -249,44 +273,71 @@ for both clients in one process. Put it where the process starts (the
249
273
  @mainwave/sdk/register'`), and still initialize in the app: `init()` in owned
250
274
  mode, or the `createSpanProcessor()` wiring from section 5b in host mode (no
251
275
  `init()`). In owned mode, a CommonJS app that calls `init()` before its first
252
- `require()` of the client needs no flag; a host-mode app needs the flag or
253
- `instrument()`.
276
+ `require()` of `openai` needs no flag, and `init()` itself adds Mainwave's
277
+ middleware, last in the list, to every `Anthropic`, `AnthropicBedrock` and
278
+ `AnthropicVertex` client the app constructs after it, in ES module and
279
+ CommonJS apps alike. The flag also covers an Anthropic client constructed
280
+ before `init()`, such as one at the top level of a module the entry imports;
281
+ without it, give that client `mainwaveMiddleware()`. A host-mode app needs the
282
+ flag or the explicit path.
254
283
 
255
284
  The explicit path, for bundled and serverless hosts (on Vercel Functions and in
256
- bundled apps this is the supported way; do not use the flag there). Owned mode
257
- calls `init()` first:
285
+ bundled apps this is the supported way; do not use the flag there): pass the
286
+ `openai` module to `instrument()`, and add `mainwaveMiddleware()` to the
287
+ `middleware` option of every `@anthropic-ai/sdk` client the app constructs.
288
+ Owned mode calls `init()` first:
258
289
 
259
290
  ```ts
260
- import * as anthropic from '@anthropic-ai/sdk'
291
+ import Anthropic from '@anthropic-ai/sdk'
261
292
  import * as openai from 'openai'
262
293
  import { init, instrument } from '@mainwave/sdk'
294
+ import { mainwaveMiddleware } from '@mainwave/sdk/anthropic'
263
295
 
264
296
  init()
265
- instrument({ openai, anthropic })
297
+ instrument({ openai })
298
+ const anthropic = new Anthropic({ middleware: [mainwaveMiddleware()] })
266
299
  ```
267
300
 
268
- Host mode (Next.js with `@vercel/otel`, `NodeSDK`) calls `instrument()` after
269
- the section 5b wiring and never calls `init()`:
301
+ Host mode (Next.js with `@vercel/otel`, `NodeSDK`) attaches after the section
302
+ 5b wiring and never calls `init()`:
270
303
 
271
304
  ```ts
272
- import * as anthropic from '@anthropic-ai/sdk'
305
+ import Anthropic from '@anthropic-ai/sdk'
273
306
  import * as openai from 'openai'
274
307
  import { instrument } from '@mainwave/sdk'
308
+ import { mainwaveMiddleware } from '@mainwave/sdk/anthropic'
275
309
 
276
310
  // Runs after registerOTel(...) or sdk.start() has received createSpanProcessor().
277
- instrument({ openai, anthropic })
311
+ instrument({ openai })
312
+ const anthropic = new Anthropic({ middleware: [mainwaveMiddleware()] })
278
313
  ```
279
314
 
280
- **Pass every module copy the app loads.** An ES module import and a
315
+ If the app already passes its own `middleware` to an Anthropic client, put
316
+ `mainwaveMiddleware()` last in that list, so it records what the app's own
317
+ client-level middleware sends. Middleware passed to a single call
318
+ (`messages.create(body, { middleware })`) runs after Mainwave's has recorded:
319
+ if the app scrubs data there, move the scrubber to client level
320
+ (`new Anthropic({ middleware })` or `client.withOptions({ middleware })`) or
321
+ tell the user to use the SDK's redaction rules. Edit every place the app constructs
322
+ a client (`new Anthropic(...)`, `new AnthropicBedrock(...)`,
323
+ `new AnthropicVertex(...)`); a `withOptions()` copy keeps the middleware of the
324
+ client it copies. `instrument({ anthropic })` no longer exists: replace it with
325
+ the middleware when the app has it.
326
+
327
+ **Pass every `openai` module copy the app loads.** An ES module import and a
281
328
  `require()` result are two different copies, and a copy that was not passed is
282
329
  not traced: `instrument({ openai: [esm, required] })`. `instrument()` returns
283
330
  `{ openai: 'patched' }`, `'already'` (attached before), or `'unrecognized'`
284
331
  (what it was given is not the module), and never throws. Read the result: an
285
- `'unrecognized'` means the wiring is wrong, and a client missing from the
286
- spans usually means the code calls a copy you did not pass.
287
-
288
- An ES module app that uses neither the flag nor `instrument()` gets no spans
289
- from these clients and one not-attached warning naming both options.
332
+ `'unrecognized'` means the wiring is wrong, and a client missing from the spans
333
+ usually means the code calls a copy you did not pass.
334
+
335
+ An ES module app that uses neither the flag nor the explicit path gets no
336
+ spans from `openai`, and one not-attached warning naming both options. Its
337
+ `@anthropic-ai/sdk` clients constructed after `init()` get the middleware all
338
+ the same; one constructed before `init()` sends spans without the request
339
+ content, tool definitions and raw stream output, and the SDK logs one warning
340
+ when they arrive.
290
341
  `init({ skipInstrumentations: ['openai'] })` turns the SDK's hooks off when
291
342
  another instrumentation for that client is already running (it would trace
292
343
  every call twice).
@@ -13,7 +13,7 @@ the package is internal: do not import from `dist/` paths.
13
13
  | `startRun(runId, [options])` | A run you end yourself; bind a block with `handle.with(fn)`; `handle.end({ status, description, reason, decision, iterations, cost })` |
14
14
  | `span(name, [{ attributes }], fn)` | A custom span; `fn` gets the OpenTelemetry `Span` |
15
15
  | `bindIdentity({ useCaseId, useCaseKey, agentName }, fn)` | Bind a use case and agent name to every span started inside `fn` |
16
- | `instrument({ openai, anthropic })` | Attach to the module(s) passed; returns `'patched'`, `'already'` or `'unrecognized'` per client; never throws |
16
+ | `instrument({ openai })` | Attach to the module(s) passed; returns `'patched'`, `'already'` or `'unrecognized'`; never throws |
17
17
  | `flush({ timeoutMs })` | Send everything buffered; resolves `true` when accepted, `false` otherwise; never rejects. Default 30,000 ms |
18
18
  | `shutdown()` | Flush, shut the provider or processor down, remove the SDK's listeners; safe to call twice |
19
19
  | `useCaseIdFor(key)` | The UUID a key derives to; throws `MainwaveConfigError` before `init()` or `createSpanProcessor()`, or when disabled |
@@ -27,11 +27,11 @@ Before `init()` or `createSpanProcessor()`, `run()`, `startRun()`, `span()` and
27
27
 
28
28
  | Import | Provides |
29
29
  | ------------------------- | --------------------------------------------------------------------------------- |
30
- | `@mainwave/sdk/register` | Loader hooks for `node --import`; patches `openai` and `@anthropic-ai/sdk` |
30
+ | `@mainwave/sdk/register` | Loader hooks for `node --import`; patches `openai`, adds the Anthropic middleware |
31
31
  | `@mainwave/sdk/eve` | `mainwave(options)`: the eve instrumentation destination |
32
32
  | `@mainwave/sdk/ai-sdk` | `mainwaveTelemetry(options)`: the AI SDK v7 integration for `registerTelemetry` |
33
33
  | `@mainwave/sdk/openai` | `OpenAIInstrumentation` class, for hosts that register their own instrumentations |
34
- | `@mainwave/sdk/anthropic` | `AnthropicInstrumentation` class, same |
34
+ | `@mainwave/sdk/anthropic` | `mainwaveMiddleware()`, for `new Anthropic({ middleware: [...] })` |
35
35
  | `@mainwave/sdk/testing` | `installInMemoryProvider(options)`, `reset()`: in-process span assertions |
36
36
 
37
37
  ## `init()` options
@@ -4,14 +4,16 @@ Supported ranges are the optional peer dependencies the application installs.
4
4
  A version outside its range is not instrumented and logs one warning with the
5
5
  package, version, and range: report it to the user instead of wiring around it.
6
6
 
7
- | Framework | Range | Wiring |
8
- | ------------- | ---------------------------------- | ------------------------------------------------------ |
9
- | eve | `>=0.66.3 <0.70.0`, Node 24+ | `mainwave()` from `@mainwave/sdk/eve`; no `init()` |
10
- | Vercel AI SDK | `ai` `^7` with `@ai-sdk/otel` `^1` | `registerTelemetry(mainwaveTelemetry())` |
11
- | OpenAI | `openai` `>=4.19.0 <8` | loader flag, `instrument({ openai })`, or the class |
12
- | Anthropic | `@anthropic-ai/sdk` `>=0.51.0 <1` | loader flag, `instrument({ anthropic })`, or the class |
7
+ | Framework | Range | Wiring |
8
+ | ------------- | ---------------------------------- | ---------------------------------------------------- |
9
+ | eve | `>=0.66.3 <0.70.0`, Node 24+ | `mainwave()` from `@mainwave/sdk/eve`; no `init()` |
10
+ | Vercel AI SDK | `ai` `^7` with `@ai-sdk/otel` `^1` | `registerTelemetry(mainwaveTelemetry())` |
11
+ | OpenAI | `openai` `>=4.19.0 <8` | loader flag, `instrument({ openai })`, or the class |
12
+ | Anthropic | `@anthropic-ai/sdk` `>=0.134.0` | `init()`, the loader flag, or `mainwaveMiddleware()` |
13
13
 
14
- AI SDK v5 and v6 are not supported.
14
+ AI SDK v5 and v6 are not supported. An `@anthropic-ai/sdk` below 0.134.0
15
+ records no spans, so its calls reach Mainwave not at all; the SDK logs one
16
+ warning with its version and the range.
15
17
 
16
18
  ## eve
17
19
 
@@ -46,28 +48,43 @@ process restarts.
46
48
 
47
49
  ## Anthropic
48
50
 
49
- Traces every Messages API call: `messages.create()` with or without
50
- `stream: true`, `messages.stream()`, `messages.parse()`, `beta.messages.create()`,
51
- `beta.messages.stream()`, and each model turn of `beta.messages.toolRunner()`.
52
- `countTokens()`, batches, models, and files make no span. A redacted thinking
53
- block is recorded as `[redacted thinking]`.
51
+ The client records its own spans: one `anthropic.messages.create` span per
52
+ Messages API call (`messages.create()` with or without `stream: true`,
53
+ `messages.stream()`, `messages.parse()`, the beta methods, and each model turn
54
+ of `beta.messages.toolRunner()`, which also records an agent span and one span
55
+ per tool run). A trace of only `countTokens()`, batches, models or files spans
56
+ is not sent. Mainwave's middleware adds what those spans leave out, to
57
+ Mainwave's copy only: the request's messages, system prompt and tool
58
+ definitions, and the response, including a stream the app reads raw. A
59
+ redacted thinking block reaches Mainwave as `[redacted thinking]`. The app's
60
+ own exporters receive the client's spans unchanged. The Bedrock and Vertex
61
+ clients (`@anthropic-ai/bedrock-sdk`, `@anthropic-ai/vertex-sdk`) are covered
62
+ the same way, with the providers `aws.bedrock` and `gcp.vertex_ai`.
54
63
 
55
64
  ## Attach paths for OpenAI and Anthropic
56
65
 
57
66
  1. `node --import @mainwave/sdk/register app.mjs` (or `NODE_OPTIONS`): static
58
- imports, dynamic `import()`, and `require()`. For plain Node processes.
59
- 2. `instrument({ openai, anthropic })`: bundled apps and serverless functions
60
- (Vercel Functions, Next.js). Call it after `init()` in owned mode, or after
61
- the host wiring in host mode, where `createSpanProcessor()` is the
62
- initialization and `init()` is not called (a bare `init()` after it throws
63
- `MainwaveReinitConflict`). Pass every copy the app loads; an ES module import
64
- and a `require()` result are different copies.
65
- 3. The `OpenAIInstrumentation` / `AnthropicInstrumentation` classes, for a host
66
- that calls `registerInstrumentations`. ES module imports are then
67
- intercepted by the host's own OpenTelemetry loader, registered before the
68
- application starts.
69
-
70
- A copy attached by two of these ways is instrumented once. Do not add an
67
+ imports, dynamic `import()`, and `require()`. For plain Node processes. For
68
+ `@anthropic-ai/sdk` it adds Mainwave's middleware to every client the app
69
+ constructs. Without it, `init()` adds the middleware to every
70
+ `@anthropic-ai/sdk` client constructed after `init()`, in ES module and
71
+ CommonJS apps.
72
+ 2. The explicit path, for bundled apps and serverless functions (Vercel
73
+ Functions, Next.js): `instrument({ openai })`, and
74
+ `new Anthropic({ middleware: [mainwaveMiddleware()] })` with
75
+ `mainwaveMiddleware` from `@mainwave/sdk/anthropic`. Attach after `init()`
76
+ in owned mode, or after the host wiring in host mode, where
77
+ `createSpanProcessor()` is the initialization and `init()` is not called (a
78
+ bare `init()` after it throws `MainwaveReinitConflict`). Pass every
79
+ `openai` copy the app loads; an ES module import and a `require()` result
80
+ are different copies.
81
+ 3. The `OpenAIInstrumentation` class, for a host that calls
82
+ `registerInstrumentations`. ES module imports are then intercepted by the
83
+ host's own OpenTelemetry loader, registered before the application starts.
84
+ Anthropic clients there take the middleware as in 2.
85
+
86
+ A copy attached by two of these ways is instrumented once, and a client that
87
+ gets the Anthropic middleware both ways runs it once. Do not add an
71
88
  OpenInference or Traceloop instrumentation for these clients: the SDK has its
72
89
  own, and a second one traces every call twice. Where one is already installed
73
90
  by the app, set `init({ skipInstrumentations: [...] })` for that client instead
@@ -27,10 +27,12 @@ the trace.
27
27
 
28
28
  ## 2. Nothing was attached for the provider client
29
29
 
30
- An ES module app with `openai` or `@anthropic-ai/sdk` installed and neither
31
- `--import @mainwave/sdk/register` nor `instrument()` gets no spans from that
32
- client and one warning naming both options. Fix per the attach table in
33
- `SKILL.md` section 6. If `instrument()` returned `'unrecognized'`, it was not
30
+ An ES module app with `openai` installed and neither
31
+ `--import @mainwave/sdk/register` nor `instrument()` gets no spans from it and
32
+ one warning naming both options. An `@anthropic-ai/sdk` client constructed
33
+ before `init()` without the flag or `mainwaveMiddleware()` sends its own spans
34
+ without the request content, tool definitions and raw stream output, with one
35
+ warning when they arrive; one constructed after `init()` gets the middleware. Fix per the attach table in `SKILL.md` section 6. If `instrument()` returned `'unrecognized'`, it was not
34
36
  given the module itself (`import * as openai from 'openai'`). If a client is
35
37
  traced in one file and not another, the second file loads a different copy:
36
38
  pass every copy.
@@ -132,9 +134,11 @@ runtime`. Move the route to the Node.js runtime.
132
134
  ## 10. Every call appears twice
133
135
 
134
136
  Another OpenAI or Anthropic instrumentation (OpenInference, Traceloop, a
135
- host's own) is running beside the SDK's. Set
136
- `init({ skipInstrumentations: ['openai'] })` (or `'anthropic'`) for the client
137
- that is doubled, or remove the other instrumentation if the user agrees.
137
+ host's own) is running beside the SDK's OpenAI instrumentation or the
138
+ Anthropic client's own spans. For `openai`, set
139
+ `init({ skipInstrumentations: ['openai'] })`; for `@anthropic-ai/sdk`, remove
140
+ the other instrumentation if the user agrees, since the client always records
141
+ its own spans.
138
142
 
139
143
  ## Proving instrumentation works without the network
140
144