@mainwave/cli 0.11.0 → 0.13.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 (43) hide show
  1. package/README.md +203 -16
  2. package/dist/adapters/claude-code.js +3 -3
  3. package/dist/adapters/claude-desktop.js +35 -1
  4. package/dist/adapters/codex-cli.js +16 -16
  5. package/dist/adapters/cursor.js +7 -2
  6. package/dist/adapters/kiro.js +13 -8
  7. package/dist/commands.js +219 -0
  8. package/dist/core/apply.js +47 -8
  9. package/dist/core/auth-commands.js +2 -1
  10. package/dist/core/codecs/kiro-hooks-json.js +1 -1
  11. package/dist/core/codex-trust.js +178 -0
  12. package/dist/core/doctor.js +144 -12
  13. package/dist/core/entry-script.js +2 -3
  14. package/dist/core/format.js +0 -1
  15. package/dist/core/hook-copies.js +157 -0
  16. package/dist/core/install-hooks.js +198 -15
  17. package/dist/core/interview.js +36 -16
  18. package/dist/core/markers.js +209 -44
  19. package/dist/core/redaction.js +188 -0
  20. package/dist/core/skills.js +3 -11
  21. package/dist/core/status.js +21 -1
  22. package/dist/core/store.js +254 -4
  23. package/dist/core/wizard.js +91 -6
  24. package/dist/main.js +173 -163
  25. package/hooks/codex-turns.mjs +584 -0
  26. package/hooks/kiro-otlp.mjs +10 -1
  27. package/hooks/mainwave-hook.mjs +27 -3
  28. package/hooks/marker-core.mjs +66 -8
  29. package/hooks/matchers.json +98 -1
  30. package/hooks/redaction-data.mjs +209 -0
  31. package/hooks/redaction-json.mjs +215 -0
  32. package/hooks/redaction-pattern.mjs +503 -0
  33. package/hooks/redaction.d.mts +84 -0
  34. package/hooks/redaction.mjs +701 -0
  35. package/hooks/vocabulary.mjs +41 -2
  36. package/package.json +3 -1
  37. package/skills/mainwave-instrument/SKILL.md +24 -6
  38. package/skills/mainwave-instrument/reference/frameworks.md +4 -2
  39. package/skills/mainwave-instrument/reference/troubleshooting.md +4 -0
  40. package/skills/mainwave-instrument-node/SKILL.md +83 -38
  41. package/skills/mainwave-instrument-node/reference/api.md +16 -16
  42. package/skills/mainwave-instrument-node/reference/frameworks.md +42 -27
  43. package/skills/mainwave-instrument-node/reference/troubleshooting.md +11 -7
@@ -68,8 +68,9 @@ export const ATTR_CALLER_SPAN_ID = 'mainwave.caller.span_id'
68
68
  // this key, so the marker joins its tool span on one key name. A marker is not
69
69
  // a tool span; readers that want tool spans select on `gen_ai.operation.name`.
70
70
  export const ATTR_TOOL_CALL_ID = 'gen_ai.tool.call.id'
71
- // Claude Code's per-spawn subagent id (its own spans carry it as a bare
72
- // `agent_id`). Not `gen_ai.agent.id`: upstream defines that as a stable agent
71
+ // The per-spawn subagent id. Claude Code's own spans carry it as a bare
72
+ // `agent_id`; the Codex turn hook and Codex-hosted markers emit the hook
73
+ // payload's `agent_id` (the child's conversation id) under this key too. Not `gen_ai.agent.id`: upstream defines that as a stable agent
73
74
  // identity, and this id is minted fresh for every spawn.
74
75
  export const ATTR_SUBAGENT_ID = 'mainwave.subagent.id'
75
76
 
@@ -347,6 +348,43 @@ export const ATTR_STOP_FAILURE_ERROR = 'mainwave.claude_code.stop_failure.error'
347
348
  // against the registry.
348
349
  export const STOP_FAILURE_KEYS = [ATTR_STOP_FAILURE_ERROR, ATTR_PROMPT_ID]
349
350
 
351
+ // ── Codex turns — CLI hook feature ───────────────────────────────────────────
352
+ // Codex's own export has no turn-end signal, so the hook sends each turn,
353
+ // permission wait and subagent run as ONE closed span (start and end), when it
354
+ // ends. The resource carries the Codex export's own source tag, so the spans
355
+ // derive the export's ucid, and its own service name. `session.id` is the hook
356
+ // input's `session_id`, which equals the export's `conversation.id`. Ids only,
357
+ // the working directory and a tool name: never the prompt, the assistant
358
+ // message, a tool's input or output, or the transcript path.
359
+ export const CODEX_TURN_SOURCE = 'coding_agent.codex_cli'
360
+ export const CODEX_TURN_SERVICE = 'mainwave-codex-hook'
361
+
362
+ export const CODEX_TURN = 'mainwave.codex.turn'
363
+ export const CODEX_PERMISSION_WAIT = 'mainwave.codex.permission_wait'
364
+ export const CODEX_SUBAGENT_TURN = 'mainwave.codex.subagent_turn'
365
+
366
+ export const ATTR_CODEX_TURN_ID = 'mainwave.codex.turn_id'
367
+ export const ATTR_CODEX_END_REASON = 'mainwave.codex.turn.end_reason'
368
+ export const ATTR_CODEX_CWD = 'mainwave.codex.cwd'
369
+ export const ATTR_CODEX_AGENT_TYPE = 'mainwave.codex.agent_type'
370
+ export const ATTR_CODEX_PARENT_TURN_ID = 'mainwave.codex.parent_turn_id'
371
+ export const ATTR_CODEX_TOOL_NAME = 'mainwave.codex.tool_name'
372
+ export const ATTR_CODEX_WAIT_END_EVENT = 'mainwave.codex.wait.end_event'
373
+
374
+ export const CODEX_TURN_SPANS = [CODEX_TURN, CODEX_PERMISSION_WAIT, CODEX_SUBAGENT_TURN]
375
+
376
+ // The exact literal keys the three spans may emit beyond `session.id`.
377
+ export const CODEX_TURN_KEYS = [
378
+ ATTR_CODEX_TURN_ID,
379
+ ATTR_CODEX_END_REASON,
380
+ ATTR_CODEX_CWD,
381
+ ATTR_SUBAGENT_ID,
382
+ ATTR_CODEX_AGENT_TYPE,
383
+ ATTR_CODEX_PARENT_TURN_ID,
384
+ ATTR_CODEX_TOOL_NAME,
385
+ ATTR_CODEX_WAIT_END_EVENT,
386
+ ]
387
+
350
388
  // ── What each hook feature may send ─────────────────────────────────────────
351
389
  // The dispatcher drops every span attribute a feature's entry here doesn't
352
390
  // bind, and every span whose name isn't the feature's, before anything is
@@ -381,6 +419,7 @@ export const FEATURE_EMITS = Object.freeze({
381
419
  prefixes: [],
382
420
  },
383
421
  'stop-failure': { spans: [CLAUDE_CODE_STOP_FAILURE], keys: STOP_FAILURE_KEYS, prefixes: [] },
422
+ 'codex-turns': { spans: CODEX_TURN_SPANS, keys: CODEX_TURN_KEYS, prefixes: [] },
384
423
  })
385
424
 
386
425
  // The hook spans outside the work / vcs families, each under `hook.anthropic`
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mainwave/cli",
3
- "version": "0.11.0",
3
+ "version": "0.13.0",
4
4
  "description": "Setup wizard for connecting third-party coding tools to Mainwave AI.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -34,6 +34,7 @@
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
40
  "test:hooks": "node tests/hooks/check-node.mjs && node --import ./tests/hooks/setup.mjs --test tests/hooks/*.test.mjs",
@@ -47,6 +48,7 @@
47
48
  "devDependencies": {
48
49
  "@hey-api/openapi-ts": "^0.99.0",
49
50
  "@types/node": "22.20.5",
51
+ "knip": "6.41.0",
50
52
  "lefthook": "2.2.1",
51
53
  "oxlint": "1.87.0",
52
54
  "prettier": "3.9.10",
@@ -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,19 +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 <0.134.0`. A version outside its range is not instrumented: report it, do
29
- not wire around it. `@anthropic-ai/sdk` 0.134.0 and later emit their own
30
- OpenTelemetry spans, so the SDK leaves them unpatched with one warning and
31
- exports the client's own spans as they are; to get the SDK's Anthropic spans,
32
- the app pins `@anthropic-ai/sdk` below 0.134.0.
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).
33
32
  - **Does the app already register OpenTelemetry?** Search for `@vercel/otel`
34
33
  (`registerOTel`), `@opentelemetry/sdk-node` (`NodeSDK`),
35
- `NodeTracerProvider`, a Next.js `instrumentation.ts`, or an eve
36
- `agent/instrumentation/` directory. If something registers the tracer
37
- 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.
38
39
  - **Where does the process start?** The server entry, the worker bootstrap, the
39
40
  script's first file, the Next.js `instrumentation.ts` `register()`. That is
40
- 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.
41
45
  - **ESM or CommonJS, bundled or not, and what runtime?** This picks the attach
42
46
  path in section 6. Plain `node app.mjs` is not bundled; Vercel Functions,
43
47
  Next.js, and anything built by a bundler are.
@@ -75,8 +79,9 @@ npm install @mainwave/sdk # or: pnpm add @mainwave/sdk / yarn add @mainwave
75
79
  app already depends on another version of it, stop and report the conflict.
76
80
  The framework and provider packages are optional peers the application already
77
81
  installs; **install none of them for the user, and never install an
78
- OpenInference or Traceloop package**: the SDK carries its own OpenAI and
79
- 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.
80
85
 
81
86
  If the install fails with "package not found", report that
82
87
  `@mainwave/sdk` is not yet published to npm and stop. Do not substitute another
@@ -171,10 +176,26 @@ A plain `NodeTracerProvider` takes
171
176
  - An `init()` call that finds another provider registered, with no
172
177
  `createSpanProcessor()` wired in, exports nothing and logs one warning.
173
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()`.
174
193
 
175
194
  ## 5c. Owned mode: `init()` at process start
176
195
 
177
- 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.
178
199
 
179
200
  ```ts
180
201
  import { init } from '@mainwave/sdk'
@@ -240,11 +261,11 @@ passes `mainwaveTelemetry({ tracer })`.
240
261
  **OpenAI (`openai`) and Anthropic (`@anthropic-ai/sdk`) called directly:** choose
241
262
  by how the app starts.
242
263
 
243
- | The app is | Attach |
244
- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
245
- | A plain Node process you start (`node app.mjs`, a worker, a script) | `node --import @mainwave/sdk/register app.mjs` |
246
- | 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) |
247
- | 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 |
248
269
 
249
270
  The loader flag covers static imports, dynamic `import()`, and `require()`,
250
271
  for both clients in one process. Put it where the process starts (the
@@ -252,47 +273,71 @@ for both clients in one process. Put it where the process starts (the
252
273
  @mainwave/sdk/register'`), and still initialize in the app: `init()` in owned
253
274
  mode, or the `createSpanProcessor()` wiring from section 5b in host mode (no
254
275
  `init()`). In owned mode, a CommonJS app that calls `init()` before its first
255
- `require()` of the client needs no flag; a host-mode app needs the flag or
256
- `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.
257
283
 
258
284
  The explicit path, for bundled and serverless hosts (on Vercel Functions and in
259
- bundled apps this is the supported way; do not use the flag there). Owned mode
260
- 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:
261
289
 
262
290
  ```ts
263
- import * as anthropic from '@anthropic-ai/sdk'
291
+ import Anthropic from '@anthropic-ai/sdk'
264
292
  import * as openai from 'openai'
265
293
  import { init, instrument } from '@mainwave/sdk'
294
+ import { mainwaveMiddleware } from '@mainwave/sdk/anthropic'
266
295
 
267
296
  init()
268
- instrument({ openai, anthropic })
297
+ instrument({ openai })
298
+ const anthropic = new Anthropic({ middleware: [mainwaveMiddleware()] })
269
299
  ```
270
300
 
271
- Host mode (Next.js with `@vercel/otel`, `NodeSDK`) calls `instrument()` after
272
- 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()`:
273
303
 
274
304
  ```ts
275
- import * as anthropic from '@anthropic-ai/sdk'
305
+ import Anthropic from '@anthropic-ai/sdk'
276
306
  import * as openai from 'openai'
277
307
  import { instrument } from '@mainwave/sdk'
308
+ import { mainwaveMiddleware } from '@mainwave/sdk/anthropic'
278
309
 
279
310
  // Runs after registerOTel(...) or sdk.start() has received createSpanProcessor().
280
- instrument({ openai, anthropic })
311
+ instrument({ openai })
312
+ const anthropic = new Anthropic({ middleware: [mainwaveMiddleware()] })
281
313
  ```
282
314
 
283
- **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
284
328
  `require()` result are two different copies, and a copy that was not passed is
285
329
  not traced: `instrument({ openai: [esm, required] })`. `instrument()` returns
286
- `{ openai: 'patched' }`, `'already'` (attached before), `'unsupported'`
287
- (Anthropic only: an `@anthropic-ai/sdk` 0.134.0 or later client, which emits
288
- its own spans), or `'unrecognized'` (what it was given is not the module), and
289
- never throws. Read the result: an `'unrecognized'` means the wiring is wrong,
290
- an `'unsupported'` means the app's Anthropic client is above the supported
291
- range, and a client missing from the spans usually means the code calls a copy
292
- you did not pass.
293
-
294
- An ES module app that uses neither the flag nor `instrument()` gets no spans
295
- from these clients and one not-attached warning naming both options.
330
+ `{ openai: 'patched' }`, `'already'` (attached before), or `'unrecognized'`
331
+ (what it was given is not the module), and never throws. Read the result: an
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.
296
341
  `init({ skipInstrumentations: ['openai'] })` turns the SDK's hooks off when
297
342
  another instrumentation for that client is already running (it would trace
298
343
  every call twice).
@@ -5,20 +5,20 @@ the package is internal: do not import from `dist/` paths.
5
5
 
6
6
  ## Root exports (`@mainwave/sdk`)
7
7
 
8
- | Export | Use |
9
- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
10
- | `init(options)` | Owned mode: build a tracer provider and export every LLM trace. Once per process. Throws `MainwaveConfigError` for a missing key |
11
- | `createSpanProcessor(options)` | Host mode: one processor to pass to the host's provider. Same options as `init()` except `mode` |
12
- | `run(runId, [options], fn)` | A run around a block; resolves with what `fn` returns |
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
- | `span(name, [{ attributes }], fn)` | A custom span; `fn` gets the OpenTelemetry `Span` |
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'`, `'unsupported'` (Anthropic 0.134.0+) or `'unrecognized'` per client; never throws |
17
- | `flush({ timeoutMs })` | Send everything buffered; resolves `true` when accepted, `false` otherwise; never rejects. Default 30,000 ms |
18
- | `shutdown()` | Flush, shut the provider or processor down, remove the SDK's listeners; safe to call twice |
19
- | `useCaseIdFor(key)` | The UUID a key derives to; throws `MainwaveConfigError` before `init()` or `createSpanProcessor()`, or when disabled |
20
- | `registerFramework(name, [version])`, `VERSION` | Record a framework name on exported spans (for a custom integration); package version |
21
- | `MainwaveError`, `MainwaveConfigError`, `MainwaveReinitConflict` | Error classes. Config errors are invalid caller input; reinit conflict is a second `init()` with a different configuration |
8
+ | Export | Use |
9
+ | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
10
+ | `init(options)` | Owned mode: build a tracer provider and export every LLM trace. Once per process. Throws `MainwaveConfigError` for a missing key |
11
+ | `createSpanProcessor(options)` | Host mode: one processor to pass to the host's provider. Same options as `init()` except `mode` |
12
+ | `run(runId, [options], fn)` | A run around a block; resolves with what `fn` returns |
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
+ | `span(name, [{ attributes }], fn)` | A custom span; `fn` gets the OpenTelemetry `Span` |
15
+ | `bindIdentity({ useCaseId, useCaseKey, agentName }, fn)` | Bind a use case and agent name to every span started inside `fn` |
16
+ | `instrument({ openai })` | Attach to the module(s) passed; returns `'patched'`, `'already'` or `'unrecognized'`; never throws |
17
+ | `flush({ timeoutMs })` | Send everything buffered; resolves `true` when accepted, `false` otherwise; never rejects. Default 30,000 ms |
18
+ | `shutdown()` | Flush, shut the provider or processor down, remove the SDK's listeners; safe to call twice |
19
+ | `useCaseIdFor(key)` | The UUID a key derives to; throws `MainwaveConfigError` before `init()` or `createSpanProcessor()`, or when disabled |
20
+ | `registerFramework(name, [version])`, `VERSION` | Record a framework name on exported spans (for a custom integration); package version |
21
+ | `MainwaveError`, `MainwaveConfigError`, `MainwaveReinitConflict` | Error classes. Config errors are invalid caller input; reinit conflict is a second `init()` with a different configuration |
22
22
 
23
23
  Before `init()` or `createSpanProcessor()`, `run()`, `startRun()`, `span()` and
24
24
  `bindIdentity()` run their callbacks without telemetry and log one warning.
@@ -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,16 +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 <0.134.0` | 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. `@anthropic-ai/sdk` 0.134.0 and later emit
15
- their own OpenTelemetry spans: the SDK leaves them unpatched with one warning,
16
- and their own spans export as they are.
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.
17
17
 
18
18
  ## eve
19
19
 
@@ -48,28 +48,43 @@ process restarts.
48
48
 
49
49
  ## Anthropic
50
50
 
51
- Traces every Messages API call: `messages.create()` with or without
52
- `stream: true`, `messages.stream()`, `messages.parse()`, `beta.messages.create()`,
53
- `beta.messages.stream()`, and each model turn of `beta.messages.toolRunner()`.
54
- `countTokens()`, batches, models, and files make no span. A redacted thinking
55
- 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`.
56
63
 
57
64
  ## Attach paths for OpenAI and Anthropic
58
65
 
59
66
  1. `node --import @mainwave/sdk/register app.mjs` (or `NODE_OPTIONS`): static
60
- imports, dynamic `import()`, and `require()`. For plain Node processes.
61
- 2. `instrument({ openai, anthropic })`: bundled apps and serverless functions
62
- (Vercel Functions, Next.js). Call it after `init()` in owned mode, or after
63
- the host wiring in host mode, where `createSpanProcessor()` is the
64
- initialization and `init()` is not called (a bare `init()` after it throws
65
- `MainwaveReinitConflict`). Pass every copy the app loads; an ES module import
66
- and a `require()` result are different copies.
67
- 3. The `OpenAIInstrumentation` / `AnthropicInstrumentation` classes, for a host
68
- that calls `registerInstrumentations`. ES module imports are then
69
- intercepted by the host's own OpenTelemetry loader, registered before the
70
- application starts.
71
-
72
- 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
73
88
  OpenInference or Traceloop instrumentation for these clients: the SDK has its
74
89
  own, and a second one traces every call twice. Where one is already installed
75
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