@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.
- package/README.md +176 -13
- package/dist/adapters/claude-code.js +5 -4
- package/dist/adapters/claude-desktop.js +35 -1
- package/dist/adapters/copilot-chat.js +7 -13
- package/dist/adapters/copilot-cli.js +9 -12
- package/dist/adapters/cursor.js +7 -2
- package/dist/adapters/kiro.js +13 -8
- package/dist/commands.js +217 -0
- package/dist/core/apply.js +13 -5
- package/dist/core/auth-commands.js +2 -1
- package/dist/core/codecs/kiro-hooks-json.js +1 -1
- package/dist/core/doctor.js +71 -8
- package/dist/core/entry-script.js +9 -4
- package/dist/core/format.js +0 -1
- package/dist/core/hook-copies.js +157 -0
- package/dist/core/install-hooks.js +148 -10
- package/dist/core/interview.js +8 -2
- package/dist/core/markers.js +90 -24
- package/dist/core/post-setup.js +5 -22
- package/dist/core/redaction.js +179 -0
- package/dist/core/skills.js +6 -14
- package/dist/core/status.js +21 -1
- package/dist/core/store.js +255 -5
- package/dist/core/url.js +1 -0
- package/dist/core/wizard.js +101 -7
- package/dist/main.js +163 -162
- package/hooks/git-commit-marker.mjs +406 -0
- package/hooks/kiro-otlp.mjs +10 -1
- package/hooks/mainwave-hook.mjs +17 -5
- package/hooks/marker-core.mjs +56 -2
- package/hooks/matchers.json +20 -3
- package/hooks/redaction-data.mjs +201 -0
- package/hooks/redaction-json.mjs +215 -0
- package/hooks/redaction-pattern.mjs +503 -0
- package/hooks/redaction.d.mts +84 -0
- package/hooks/redaction.mjs +701 -0
- package/hooks/vocabulary.d.mts +13 -0
- package/hooks/vocabulary.mjs +42 -1
- package/package.json +9 -7
- package/skills/mainwave-instrument/SKILL.md +24 -6
- package/skills/mainwave-instrument/reference/frameworks.md +4 -2
- package/skills/mainwave-instrument/reference/troubleshooting.md +4 -0
- package/skills/mainwave-instrument-node/SKILL.md +81 -30
- package/skills/mainwave-instrument-node/reference/api.md +3 -3
- package/skills/mainwave-instrument-node/reference/frameworks.md +42 -25
- package/skills/mainwave-instrument-node/reference/troubleshooting.md +11 -7
package/hooks/vocabulary.d.mts
CHANGED
|
@@ -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
|
|
package/hooks/vocabulary.mjs
CHANGED
|
@@ -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.
|
|
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.
|
|
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
|
-
"
|
|
51
|
-
"
|
|
52
|
-
"
|
|
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.
|
|
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?**
|
|
43
|
-
`TracerProvider`,
|
|
44
|
-
|
|
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 **
|
|
69
|
-
|
|
70
|
-
patch libraries
|
|
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
|
|
160
|
-
|
|
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.
|
|
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
|
|
33
|
-
`agent/instrumentation/` directory. If
|
|
34
|
-
provider, the app is a **host**: do not call
|
|
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
|
|
76
|
-
Anthropic
|
|
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
|
|
244
|
-
| A host that registers its own OpenTelemetry instrumentations | `new OpenAIInstrumentation()`
|
|
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
|
|
253
|
-
`
|
|
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)
|
|
257
|
-
|
|
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
|
|
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
|
|
297
|
+
instrument({ openai })
|
|
298
|
+
const anthropic = new Anthropic({ middleware: [mainwaveMiddleware()] })
|
|
266
299
|
```
|
|
267
300
|
|
|
268
|
-
Host mode (Next.js with `@vercel/otel`, `NodeSDK`)
|
|
269
|
-
|
|
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
|
|
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
|
|
311
|
+
instrument({ openai })
|
|
312
|
+
const anthropic = new Anthropic({ middleware: [mainwaveMiddleware()] })
|
|
278
313
|
```
|
|
279
314
|
|
|
280
|
-
|
|
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
|
-
|
|
287
|
-
|
|
288
|
-
An ES module app that uses neither the flag nor
|
|
289
|
-
from
|
|
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
|
|
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
|
|
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` | `
|
|
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.
|
|
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
|
-
|
|
50
|
-
|
|
51
|
-
`
|
|
52
|
-
`
|
|
53
|
-
|
|
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
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
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`
|
|
31
|
-
`--import @mainwave/sdk/register` nor `instrument()` gets no spans from
|
|
32
|
-
|
|
33
|
-
`
|
|
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
|
|
136
|
-
|
|
137
|
-
|
|
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
|
|