@mainwave/cli 0.9.0 → 0.11.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.
@@ -23,10 +23,12 @@ import {
23
23
  } from 'node:fs'
24
24
  import { homedir } from 'node:os'
25
25
  import { basename, dirname, isAbsolute, join, resolve } from 'node:path'
26
+ import { fileURLToPath } from 'node:url'
26
27
 
27
28
  import {
28
29
  ATTR_CALLER_SPAN_ID,
29
30
  ATTR_CALLER_TRACE_ID,
31
+ ATTR_CLI_VERSION,
30
32
  ATTR_HOST_SOURCE,
31
33
  ATTR_SCHEMA_VERSION,
32
34
  ATTR_SUBAGENT_ID,
@@ -140,6 +142,33 @@ export const parseKv = (raw) => {
140
142
  return out
141
143
  }
142
144
 
145
+ /** Reverse of the env-file codec's double-quoting (KEY="value" with \\ \" \n). */
146
+ const unquote = (raw) => {
147
+ const v = raw.trim()
148
+ if (v.startsWith('"') && v.endsWith('"') && v.length >= 2) {
149
+ return v.slice(1, -1).replace(/\\n/g, '\n').replace(/\\"/g, '"').replace(/\\\\/g, '\\')
150
+ }
151
+ if (v.startsWith("'") && v.endsWith("'") && v.length >= 2) return v.slice(1, -1)
152
+ return v
153
+ }
154
+
155
+ /** Parse a `KEY="value"` env file (the CLI's env-file codec output) into a flat record; {} on any error. */
156
+ export const parseEnvFile = (text) => {
157
+ const out = {}
158
+ for (const line of (text ?? '').split('\n')) {
159
+ const trimmed = line.trim()
160
+ if (trimmed === '' || trimmed.startsWith('#')) continue
161
+ let rest = trimmed
162
+ if (rest.startsWith('export ')) rest = rest.slice('export '.length).trimStart()
163
+ const eq = rest.indexOf('=')
164
+ if (eq < 0) continue
165
+ const key = rest.slice(0, eq).trim()
166
+ if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue
167
+ out[key] = unquote(rest.slice(eq + 1))
168
+ }
169
+ return out
170
+ }
171
+
143
172
  /** The Bearer value from an `Authorization=Bearer xyz` OTEL header string. */
144
173
  export const bearerFromHeaders = (raw) => {
145
174
  for (const [k, v] of Object.entries(parseKv(raw))) {
@@ -815,6 +844,59 @@ export const loadOtelConfig = (cwd, processEnv, tool = 'claude-code', managedDir
815
844
  processEnv,
816
845
  )
817
846
 
847
+ /** A staged release directory's name: `<version>-<12 hex content hash>`, as
848
+ * the CLI's installer names it under the managed `versions/` directory. */
849
+ const STAGED_RELEASE_RE = /^(.+)-[0-9a-f]{12}$/
850
+ /** The `--managed-by` value setup writes into a hook command it owns,
851
+ * `@mainwave/cli@<version>`. A concrete semver only: a payload that names a
852
+ * dist-tag (`@latest`) says nothing about which release is installed. */
853
+ const MANAGED_BY_RE = /^@mainwave\/cli@(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)$/
854
+
855
+ /**
856
+ * The `@mainwave/cli` release a hook script belongs to, or `undefined` when it
857
+ * can't tell, never a guess. Checked in order:
858
+ *
859
+ * 1. a release staged under the managed hooks directory: the directory's
860
+ * name, `…/versions/<version>-<hash>/`;
861
+ * 2. the package itself, `<package>/hooks/`: the package's own
862
+ * `package.json` one level up;
863
+ * 3. a flat copy (the Cursor and Kiro scripts under `~/.mainwave/hooks/`): the
864
+ * `--managed-by @mainwave/cli@<version>` flag on the hook command, which
865
+ * the setup run that copied the script wrote with the same version.
866
+ *
867
+ * The flag comes last: a first-generation managed command runs a staged
868
+ * release through `managed-entry.mjs` and still carries the version (or
869
+ * `@latest`) the payload was pasted with.
870
+ */
871
+ export const hookReleaseVersion = (dir, readFile = readFileSync, argv = []) => {
872
+ const staged = STAGED_RELEASE_RE.exec(basename(dir))
873
+ if (staged && basename(dirname(dir)) === 'versions') return staged[1]
874
+ try {
875
+ const pkg = JSON.parse(readFile(join(dir, '..', 'package.json'), 'utf8'))
876
+ if (pkg?.name === '@mainwave/cli' && typeof pkg.version === 'string' && pkg.version !== '') {
877
+ return pkg.version
878
+ }
879
+ } catch {
880
+ // no package beside it — not a release we can name from the files
881
+ }
882
+ return MANAGED_BY_RE.exec(hookFlag(argv, '--managed-by') ?? '')?.[1]
883
+ }
884
+
885
+ let ownVersionMemo
886
+ /** This script's own release (§ `hookReleaseVersion`), read once per process. */
887
+ const ownCliVersion = () => {
888
+ if (ownVersionMemo === undefined) {
889
+ ownVersionMemo = {
890
+ value: hookReleaseVersion(
891
+ dirname(fileURLToPath(import.meta.url)),
892
+ readFileSync,
893
+ process.argv,
894
+ ),
895
+ }
896
+ }
897
+ return ownVersionMemo.value
898
+ }
899
+
818
900
  /**
819
901
  * Keep the developer's identity attrs — above all `mainwave.ucid`, so the marker
820
902
  * attributes to the same use case as the session — but override the two the
@@ -830,15 +912,27 @@ export const loadOtelConfig = (cwd, processEnv, tool = 'claude-code', managedDir
830
912
  * — lands as `mainwave.host_source`. Absent → the key is omitted, and any value
831
913
  * inherited from the developer's `OTEL_RESOURCE_ATTRIBUTES` is dropped too, so
832
914
  * the attribute only ever carries what the hook itself resolved.
915
+ *
916
+ * `cliVersion` — the release this script belongs to, defaulting to its own
917
+ * (§ `hookReleaseVersion`) — lands as `mainwave.cli.version`, under the same
918
+ * rule: absent → omitted, and an inherited value is never forwarded.
833
919
  */
834
- export const markerResourceAttrs = (resourceAttrs, source, service, hostSource) => {
920
+ export const markerResourceAttrs = (
921
+ resourceAttrs,
922
+ source,
923
+ service,
924
+ hostSource,
925
+ cliVersion = ownCliVersion(),
926
+ ) => {
835
927
  const rest = { ...(resourceAttrs ?? {}) }
836
928
  delete rest[ATTR_HOST_SOURCE]
929
+ delete rest[ATTR_CLI_VERSION]
837
930
  return {
838
931
  ...rest,
839
932
  'mainwave.source': source,
840
933
  'service.name': service,
841
934
  ...(hostSource ? { [ATTR_HOST_SOURCE]: hostSource } : {}),
935
+ ...(cliVersion ? { [ATTR_CLI_VERSION]: cliVersion } : {}),
842
936
  // The v2 contract stamp on every hook emission (marker + cursor), so the
843
937
  // collector shim's lifetime can be measured against v1-vs-v2 traffic.
844
938
  [ATTR_SCHEMA_VERSION]: SCHEMA_VERSION,
@@ -43,11 +43,26 @@
43
43
  ],
44
44
  "why": "Built-in tool, exact name, narrowed by the handler's `if` to Bash commands that start with `glab`. The feature still returns immediately unless the command was 'glab mr create' or a POST of 'glab api' to a project's merge_requests endpoint. The feature's own detector also accepts env, sudo and exec wrappers and a path-qualified glab, which `glab *` doesn't match; that miss is accepted rather than widening the `if`."
45
45
  },
46
+ {
47
+ "event": "PostToolUse",
48
+ "route": "git",
49
+ "matcher": "Bash",
50
+ "if": "Bash(git *)",
51
+ "features": ["git-commit-marker"],
52
+ "optOut": "markers",
53
+ "hosts": ["claude-code"],
54
+ "dataClasses": [
55
+ "commit sha and first parent sha",
56
+ "changed-file, added-line and removed-line counts",
57
+ "repository-relative file paths with per-file added and removed line counts and a binary flag"
58
+ ],
59
+ "why": "Built-in tool, exact name, narrowed by the handler's `if` to Bash commands that start with `git`. The feature still returns immediately unless the command ran 'git commit' at a command position, and sends nothing unless the tool output carries git's new-commit summary line, so a failed commit sends nothing. Each commit is then read with `git show --numstat` under a 5 s budget. A commit that isn't the command's first word (`cd x && git commit`) is matched by the feature but not by `git *`; that miss is accepted rather than widening the `if` to every Bash command."
60
+ },
46
61
  {
47
62
  "event": "PostToolUse",
48
63
  "route": "bash",
49
64
  "matcher": "Bash",
50
- "features": ["github-pr-marker", "glab-mr-marker"],
65
+ "features": ["github-pr-marker", "glab-mr-marker", "git-commit-marker"],
51
66
  "optOut": "markers",
52
67
  "hosts": ["codex"],
53
68
  "dataClasses": [
@@ -55,9 +70,11 @@
55
70
  "changed-file, added-line and removed-line counts",
56
71
  "merge request url, iid and title",
57
72
  "instance-namespaced project id",
58
- "changed-file count"
73
+ "changed-file count",
74
+ "commit sha and first parent sha",
75
+ "repository-relative file paths with per-file added and removed line counts and a binary flag"
59
76
  ],
60
- "why": "Codex has no `if` filter, so one Bash group serves both pull-request markers: the shell entry reads the hook input and starts Node only when it contains `pr`…`create`, `mr`…`create`, `mr`…`new` or `merge_requests` — a superset of what the two features' own detectors accept."
77
+ "why": "Codex has no `if` filter, so one Bash group serves the pull-request markers and the commit marker: the shell entry reads the hook input and starts Node only when it contains `pr`…`create`, `mr`…`create`, `mr`…`new`, `merge_requests` or `git`…`commit` — a superset of what the three features' own detectors accept."
61
78
  },
62
79
  {
63
80
  "event": "PostToolUse",
@@ -4,6 +4,7 @@
4
4
 
5
5
  export const ATTR_SCHEMA_VERSION: string
6
6
  export const SCHEMA_VERSION: string
7
+ export const ATTR_CLI_VERSION: string
7
8
  export const ATTR_HOST_SOURCE: string
8
9
  export const MARKER_HOST_SOURCES: Readonly<Record<string, string>>
9
10
 
@@ -39,6 +40,19 @@ export const VCS_PROVIDER_GITHUB: string
39
40
  export const VCS_PROVIDER_GITLAB: string
40
41
  export const VCS_MARKER_KEYS: readonly string[]
41
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
+
42
56
  export const ATTR_CODE_FILE_PATH: string
43
57
  export const CODE_KEYS: readonly string[]
44
58
 
@@ -24,6 +24,13 @@
24
24
  export const ATTR_SCHEMA_VERSION = 'mainwave.schema.version'
25
25
  export const SCHEMA_VERSION = '2'
26
26
 
27
+ // ── The CLI release that sent it ────────────────────────────────────────────
28
+ // The `@mainwave/cli` version whose hook scripts produced the emission, on the
29
+ // resource — the sibling of the SDKs' `mainwave.sdk.version`, so a hook bug can
30
+ // be pinned to a release and an operator can see which installs lag. Omitted
31
+ // when the script can't tell which release it belongs to; never guessed.
32
+ export const ATTR_CLI_VERSION = 'mainwave.cli.version'
33
+
27
34
  // ── Host coding tool of a marker ────────────────────────────────────────────
28
35
  // A marker's `mainwave.source` is `hook.<vendor>` (the vendor the marker is
29
36
  // ABOUT), so on its own it doesn't say which coding tool the hook ran inside.
@@ -156,6 +163,46 @@ export const VCS_MARKER_KEYS = [
156
163
  ATTR_VCS_CHANGE_LINES_REMOVED,
157
164
  ]
158
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
+
159
206
  // ── File references — CLI cursor behaviour hook ──────────────────────────────
160
207
  // The standard OTel Code (Stable) key, replacing the hook's former
161
208
  // `cursor.file_path`.
@@ -277,7 +324,7 @@ export const SUBSCRIPTION_SNAPSHOT_KEYS = [
277
324
 
278
325
  // Every governed v2 event name the CLI hooks emit — checked against the
279
326
  // registry's events_v2 lists.
280
- 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]
281
328
 
282
329
  // ── Claude Code turn failures — CLI hook feature ─────────────────────────────
283
330
  // One more span under `mainwave.source = hook.anthropic`, beside the plan
@@ -322,6 +369,7 @@ export const FEATURE_EMITS = Object.freeze({
322
369
  },
323
370
  'github-pr-marker': { spans: [VCS_OPENED], keys: VCS_MARKER_KEYS, prefixes: [] },
324
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: [] },
325
373
  'linear-ticket-marker': {
326
374
  spans: [WI_CREATED, WI_UPDATED],
327
375
  keys: WORK_MARKER_KEYS,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mainwave/cli",
3
- "version": "0.9.0",
3
+ "version": "0.11.0",
4
4
  "description": "Setup wizard for connecting third-party coding tools to Mainwave AI.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -36,22 +36,22 @@
36
36
  "format:check": "prettier --check .",
37
37
  "test": "vitest",
38
38
  "test:run": "vitest run",
39
- "test:hooks": "node --test tests/hooks/*.test.mjs",
39
+ "test:hooks": "node tests/hooks/check-node.mjs && node --import ./tests/hooks/setup.mjs --test tests/hooks/*.test.mjs",
40
40
  "prepare": "lefthook install",
41
41
  "api:generate": "openapi-ts"
42
42
  },
43
43
  "dependencies": {
44
- "@inquirer/prompts": "8.7.2",
44
+ "@inquirer/prompts": "8.7.3",
45
45
  "picocolors": "1.1.1"
46
46
  },
47
47
  "devDependencies": {
48
48
  "@hey-api/openapi-ts": "^0.99.0",
49
49
  "@types/node": "22.20.5",
50
- "lefthook": "2.1.16",
51
- "oxlint": "1.86.0",
52
- "prettier": "3.9.9",
50
+ "lefthook": "2.2.1",
51
+ "oxlint": "1.87.0",
52
+ "prettier": "3.9.10",
53
53
  "typescript": "6.0.3",
54
- "vite": "8.3.2",
54
+ "vite": "8.3.4",
55
55
  "vitest": "5.0.3",
56
56
  "yaml": "2.9.1"
57
57
  },
@@ -25,8 +25,11 @@ 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.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.
30
33
  - **Does the app already register OpenTelemetry?** Search for `@vercel/otel`
31
34
  (`registerOTel`), `@opentelemetry/sdk-node` (`NodeSDK`),
32
35
  `NodeTracerProvider`, a Next.js `instrumentation.ts`, or an eve
@@ -280,10 +283,13 @@ instrument({ openai, anthropic })
280
283
  **Pass every module copy the app loads.** An ES module import and a
281
284
  `require()` result are two different copies, and a copy that was not passed is
282
285
  not traced: `instrument({ openai: [esm, required] })`. `instrument()` returns
283
- `{ openai: 'patched' }`, `'already'` (attached before), or `'unrecognized'`
284
- (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.
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.
287
293
 
288
294
  An ES module app that uses neither the flag nor `instrument()` gets no spans
289
295
  from these clients and one not-attached warning naming both options.
@@ -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'` 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, 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 |
22
22
 
23
23
  Before `init()` or `createSpanProcessor()`, `run()`, `startRun()`, `span()` and
24
24
  `bindIdentity()` run their callbacks without telemetry and log one warning.
@@ -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 |
13
-
14
- AI SDK v5 and v6 are not supported.
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 |
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.
15
17
 
16
18
  ## eve
17
19