@mainwave/cli 0.6.0 → 0.7.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 (114) hide show
  1. package/README.md +94 -18
  2. package/dist/adapters/claude-code.js +258 -38
  3. package/dist/adapters/claude-code.js.map +1 -1
  4. package/dist/adapters/claude-desktop.js +0 -87
  5. package/dist/adapters/claude-desktop.js.map +1 -1
  6. package/dist/adapters/codex-cli.js +0 -65
  7. package/dist/adapters/codex-cli.js.map +1 -1
  8. package/dist/adapters/copilot-chat.js +7 -42
  9. package/dist/adapters/copilot-chat.js.map +1 -1
  10. package/dist/adapters/copilot-cli.js +7 -32
  11. package/dist/adapters/copilot-cli.js.map +1 -1
  12. package/dist/adapters/cursor-enterprise.js +4 -53
  13. package/dist/adapters/cursor-enterprise.js.map +1 -1
  14. package/dist/adapters/cursor.js +0 -62
  15. package/dist/adapters/cursor.js.map +1 -1
  16. package/dist/api/index.js +0 -1
  17. package/dist/api/index.js.map +1 -1
  18. package/dist/api/types.gen.js +0 -1
  19. package/dist/api/types.gen.js.map +1 -1
  20. package/dist/core/apply.js +73 -97
  21. package/dist/core/apply.js.map +1 -1
  22. package/dist/core/auth-commands.js +5 -20
  23. package/dist/core/auth-commands.js.map +1 -1
  24. package/dist/core/behaviour-hooks.js +0 -7
  25. package/dist/core/behaviour-hooks.js.map +1 -1
  26. package/dist/core/browser.js +0 -18
  27. package/dist/core/browser.js.map +1 -1
  28. package/dist/core/codecs/cursor-hooks-json.js +0 -8
  29. package/dist/core/codecs/cursor-hooks-json.js.map +1 -1
  30. package/dist/core/codecs/json-flat.js +0 -28
  31. package/dist/core/codecs/json-flat.js.map +1 -1
  32. package/dist/core/codecs/json-managed.js +0 -30
  33. package/dist/core/codecs/json-managed.js.map +1 -1
  34. package/dist/core/codecs/toml-otel.js +0 -39
  35. package/dist/core/codecs/toml-otel.js.map +1 -1
  36. package/dist/core/detect.js +0 -29
  37. package/dist/core/detect.js.map +1 -1
  38. package/dist/core/device-login.js +0 -22
  39. package/dist/core/device-login.js.map +1 -1
  40. package/dist/core/doctor.js +209 -48
  41. package/dist/core/doctor.js.map +1 -1
  42. package/dist/core/edit.js +18 -0
  43. package/dist/core/edit.js.map +1 -1
  44. package/dist/core/effective-settings.js +107 -10
  45. package/dist/core/effective-settings.js.map +1 -1
  46. package/dist/core/env-command.js +0 -9
  47. package/dist/core/env-command.js.map +1 -1
  48. package/dist/core/errors.js +0 -12
  49. package/dist/core/errors.js.map +1 -1
  50. package/dist/core/flags.js +0 -13
  51. package/dist/core/flags.js.map +1 -1
  52. package/dist/core/format.js +0 -56
  53. package/dist/core/format.js.map +1 -1
  54. package/dist/core/git.js +0 -9
  55. package/dist/core/git.js.map +1 -1
  56. package/dist/core/headers.js +4 -97
  57. package/dist/core/headers.js.map +1 -1
  58. package/dist/core/install-hooks.js +81 -0
  59. package/dist/core/install-hooks.js.map +1 -0
  60. package/dist/core/interview.js +25 -151
  61. package/dist/core/interview.js.map +1 -1
  62. package/dist/core/keys.js +0 -18
  63. package/dist/core/keys.js.map +1 -1
  64. package/dist/core/layer-policy.js +34 -0
  65. package/dist/core/layer-policy.js.map +1 -0
  66. package/dist/core/markers.js +219 -117
  67. package/dist/core/markers.js.map +1 -1
  68. package/dist/core/pinned-use-case.js +11 -0
  69. package/dist/core/pinned-use-case.js.map +1 -0
  70. package/dist/core/platform.js +5 -40
  71. package/dist/core/platform.js.map +1 -1
  72. package/dist/core/post-setup.js +7 -18
  73. package/dist/core/post-setup.js.map +1 -1
  74. package/dist/core/prompts.js +0 -59
  75. package/dist/core/prompts.js.map +1 -1
  76. package/dist/core/settings.js +20 -16
  77. package/dist/core/settings.js.map +1 -1
  78. package/dist/core/skills.js +0 -75
  79. package/dist/core/skills.js.map +1 -1
  80. package/dist/core/status.js +97 -45
  81. package/dist/core/status.js.map +1 -1
  82. package/dist/core/store.js +4 -34
  83. package/dist/core/store.js.map +1 -1
  84. package/dist/core/tty.js +0 -9
  85. package/dist/core/tty.js.map +1 -1
  86. package/dist/core/ucid.js +0 -13
  87. package/dist/core/ucid.js.map +1 -1
  88. package/dist/core/ui.js +0 -11
  89. package/dist/core/ui.js.map +1 -1
  90. package/dist/core/use-case.js +3 -50
  91. package/dist/core/use-case.js.map +1 -1
  92. package/dist/core/validate.js +0 -5
  93. package/dist/core/validate.js.map +1 -1
  94. package/dist/core/verify.js +51 -33
  95. package/dist/core/verify.js.map +1 -1
  96. package/dist/core/version.js +0 -3
  97. package/dist/core/version.js.map +1 -1
  98. package/dist/core/wizard.js +172 -128
  99. package/dist/core/wizard.js.map +1 -1
  100. package/dist/main.js +16 -38
  101. package/dist/main.js.map +1 -1
  102. package/hooks/cursor-otlp.mjs +4 -4
  103. package/hooks/github-pr-marker.mjs +31 -12
  104. package/hooks/jira-ticket-marker.mjs +46 -27
  105. package/hooks/linear-ticket-marker.mjs +58 -37
  106. package/hooks/marker-core.mjs +671 -59
  107. package/hooks/matchers.json +1 -1
  108. package/hooks/vocabulary.d.mts +9 -1
  109. package/hooks/vocabulary.mjs +73 -23
  110. package/package.json +3 -3
  111. package/skills/mainwave-instrument/SKILL.md +6 -5
  112. package/skills/mainwave-instrument/reference/frameworks.md +33 -22
  113. package/skills/mainwave-instrument/reference/troubleshooting.md +13 -4
  114. package/skills/mainwave-setup/SKILL.md +22 -6
@@ -2,7 +2,7 @@
2
2
  {
3
3
  "hook": "linear-ticket-marker.mjs",
4
4
  "matcher": "^mcp__.*[Ll]inear.*_(save|create|update)_issue$",
5
- "why": "The server PREFIX and the separator both vary. Prefix: this workspace connects Linear as mcp__linear-server__save_issue, the older integration as mcp__linear__save_issue, and Codex exposes it as mcp__codex_apps__linear_save_issue — a SINGLE underscore before save_issue (MAI-1218). So the separator is `.*_` (one-or-more via the greedy `.*`, which absorbs the extra underscore in the __ forms) rather than a literal `__`. create_issue / update_issue are covered defensively in case an integration splits the save; detectOp reads the op off the tool name and falls back to the input's id. Anchored (`$`) because linear-server really does expose create_issue_label — the trailing `_issue$` excludes it."
5
+ "why": "The server PREFIX and the separator both vary. Prefix: this workspace connects Linear as mcp__linear-server__save_issue, the older integration as mcp__linear__save_issue, and Codex exposes it as mcp__codex_apps__linear_save_issue — a SINGLE underscore before save_issue. So the separator is `.*_` (one-or-more via the greedy `.*`, which absorbs the extra underscore in the __ forms) rather than a literal `__`. create_issue / update_issue are covered defensively in case an integration splits the save; detectOp reads the op off the tool name and falls back to the input's id. Anchored (`$`) because linear-server really does expose create_issue_label — the trailing `_issue$` excludes it."
6
6
  },
7
7
  {
8
8
  "hook": "github-pr-marker.mjs",
@@ -1,9 +1,17 @@
1
1
  // Type declarations for vocabulary.mjs — the hooks are runtime-dep-free .mjs and
2
2
  // aren't compiled by tsc, but the vitest registry-conformance test (.ts) imports
3
- // this module, so NodeNext needs a .d.mts sibling to type it (MAI-1480).
3
+ // this module, so NodeNext needs a .d.mts sibling to type it.
4
4
 
5
5
  export const ATTR_SCHEMA_VERSION: string
6
6
  export const SCHEMA_VERSION: string
7
+ export const ATTR_HOST_SOURCE: string
8
+ export const MARKER_HOST_SOURCES: Readonly<Record<string, string>>
9
+
10
+ export const ATTR_CALLER_TRACE_ID: string
11
+ export const ATTR_CALLER_SPAN_ID: string
12
+ export const ATTR_TOOL_CALL_ID: string
13
+ export const ATTR_SUBAGENT_ID: string
14
+ export const MARKER_CALL_CONTEXT_KEYS: readonly string[]
7
15
 
8
16
  export const WI_CREATED: string
9
17
  export const WI_UPDATED: string
@@ -1,30 +1,80 @@
1
- // The v2 telemetry vocabulary the CLI marker + cursor hooks emit (MAI-1480).
1
+ // The v2 telemetry vocabulary the CLI marker + cursor hooks emit.
2
2
  //
3
3
  // This is the CLI's checkable copy of the work.item.* / vcs.change.* / code.*
4
- // contract in the repo-root `telemetry/registry.yaml` — the .mjs twin of the
5
- // backend's `app/devtool/vocabulary.py`. The conformance test
6
- // `tests/registry-conformance.test.ts` asserts every name and key declared here
7
- // is a registered `emitted` entry, so a name changed on one side without the
8
- // other fails the build (telemetry/README.md § Enforcement coverage).
4
+ // vocabulary contract also used by the platform side. A conformance test in the
5
+ // CLI's own repository asserts every name and key declared here is a registered
6
+ // `emitted` entry, so a name changed on one side without the other fails the
7
+ // build.
9
8
  //
10
9
  // Unlike the poller connector, a marker hook mints a RANDOM span id per emit
11
10
  // (marker-core `randomBytes`), and the read side counts distinct entity ids
12
11
  // (`uniqExact(work.item.id)`), not span ids. So there is no frozen `id_seed`
13
12
  // concern here — renaming a marker event name never re-mints history the way it
14
- // would for the connector's deterministic span ids (see vocabulary.py). The
15
- // marker self-declares `mainwave.source = hook.<vendor>` (MAI-1539), honored
16
- // verbatim by the collector's Generic processor. It stays out of coding-activity
17
- // segmentation because `hook.*` is outside the CODING_TOOL_SOURCES allowlist and
18
- // markers are admitted by span NAME (MAI-936) — NOT because of the old `other`
19
- // fallback (before MAI-1539 the hooks stamped `mainwave.ticket_marker` /
20
- // `mainwave.pr_marker`, which the collector ignored and mapped to `other`).
13
+ // would for the connector's deterministic span ids. The marker self-declares
14
+ // `mainwave.source = hook.<vendor>`, honored verbatim by the collector's Generic
15
+ // processor. It stays out of coding-activity segmentation because `hook.*` is
16
+ // outside the CODING_TOOL_SOURCES allowlist and markers are admitted by span
17
+ // NAME — NOT because of the old `other` fallback (before this, the hooks
18
+ // stamped `mainwave.ticket_marker` / `mainwave.pr_marker`, which the collector
19
+ // ignored and mapped to `other`).
21
20
 
22
21
  // ── The v2 contract stamp ───────────────────────────────────────────────────
23
22
  // Every v2 emission stamps this on its resource; v1 traffic carries no stamp,
24
- // and the collector shim's lifetime is measured against it (registry header).
23
+ // and the collector shim's lifetime is measured against it.
25
24
  export const ATTR_SCHEMA_VERSION = 'mainwave.schema.version'
26
25
  export const SCHEMA_VERSION = '2'
27
26
 
27
+ // ── Host coding tool of a marker ────────────────────────────────────────────
28
+ // A marker's `mainwave.source` is `hook.<vendor>` (the vendor the marker is
29
+ // ABOUT), so on its own it doesn't say which coding tool the hook ran inside.
30
+ // The marker stamps that tool's registered `coding_agent.*` source tag on the
31
+ // resource under this key. Named as the sibling of `mainwave.source`: its value
32
+ // is drawn from the same tag vocabulary, but names the HOSTING tool rather than
33
+ // the row's own producer — a `host_` qualifier, not a second `source`.
34
+ export const ATTR_HOST_SOURCE = 'mainwave.host_source'
35
+
36
+ // `--tool <name>` (the selector the CLI bakes into the installed hook command)
37
+ // → the host's registered source tag. Only the tools the CLI installs marker
38
+ // hooks for appear: `claude-code` (no `--tool`; the default) and `codex`. A
39
+ // tool not listed here gets no host attribute — the hook never guesses. The
40
+ // conformance test pins every value to `sources.coding_agents` in the registry.
41
+ export const MARKER_HOST_SOURCES = Object.freeze({
42
+ 'claude-code': 'coding_agent.claude_code',
43
+ codex: 'coding_agent.codex_cli',
44
+ })
45
+
46
+ // ── Calling-span context of a marker ────────────────────────────────────────
47
+ // Span attributes that tie a marker to the Claude Code tool call that produced
48
+ // it, so a reader can place it in its turn (and subagent) without a timestamp
49
+ // window. All opaque ids, each emitted only when the hook received it.
50
+ //
51
+ // The marker stays in its own random trace: its trace id is what a marker row's
52
+ // run is keyed on, so sharing the turn's trace would fold that turn's markers
53
+ // into one run and change run counts. The calling span is REFERENCED instead —
54
+ // `mainwave.caller.trace_id` / `mainwave.caller.span_id`, from the TRACEPARENT
55
+ // Claude Code gives the hook (the interaction span on the main thread, the
56
+ // spawning Agent tool span inside a subagent). An OTLP span link would be the
57
+ // standard shape for this, but links are not stored, so it would be dropped.
58
+ export const ATTR_CALLER_TRACE_ID = 'mainwave.caller.trace_id'
59
+ export const ATTR_CALLER_SPAN_ID = 'mainwave.caller.span_id'
60
+ // The tool-use id — the same value Claude Code's own tool span carries under
61
+ // this key, so the marker joins its tool span on one key name. A marker is not
62
+ // a tool span; readers that want tool spans select on `gen_ai.operation.name`.
63
+ export const ATTR_TOOL_CALL_ID = 'gen_ai.tool.call.id'
64
+ // Claude Code's per-spawn subagent id (its own spans carry it as a bare
65
+ // `agent_id`). Not `gen_ai.agent.id`: upstream defines that as a stable agent
66
+ // identity, and this id is minted fresh for every spawn.
67
+ export const ATTR_SUBAGENT_ID = 'mainwave.subagent.id'
68
+
69
+ // The exact calling-span keys a marker may emit — what the conformance test
70
+ // checks against the registry (ids-only, emitted by the CLI).
71
+ export const MARKER_CALL_CONTEXT_KEYS = [
72
+ ATTR_CALLER_TRACE_ID,
73
+ ATTR_CALLER_SPAN_ID,
74
+ ATTR_TOOL_CALL_ID,
75
+ ATTR_SUBAGENT_ID,
76
+ ]
77
+
28
78
  // ── Work-item events (tickets) — CLI ticket-marker hooks ─────────────────────
29
79
  // The event NAME encodes the operation (a v2 event's name IS its op), so create
30
80
  // and update are distinct span names rather than one span discriminated by an
@@ -40,20 +90,20 @@ export const ATTR_WORK_VENDOR = 'work.vendor'
40
90
  // emits as work.instance (Linear team UUID, Jira site cloudId). A marker CAN
41
91
  // produce it after all: it sits in the MCP save result the hook already parses
42
92
  // (Linear's top-level teamId, Jira's context.cloudId). Emitted best-effort —
43
- // present when the result supplies it, cleanly omitted otherwise — so MAI-1483
44
- // can reconcile marker spans against connector events on a shared instance id.
45
- // (MAI-1480 first deferred this on the assumption a hook couldn't produce the
46
- // global id; live MCP probes disproved that — MAI-1481 follow-up.)
93
+ // present when the result supplies it, cleanly omitted otherwise — so a marker
94
+ // span can reconcile against connector events on a shared instance id. (Earlier
95
+ // work deferred this on the assumption a hook couldn't produce the global id;
96
+ // live MCP probes disproved that.)
47
97
  export const ATTR_WORK_INSTANCE = 'work.instance'
48
98
 
49
- // `work.item.op` values — the registry's entities.item.operations axis. Past
50
- // tense, matching the connector (vocabulary.py WORK_ITEM_OP_*), not the v1
99
+ // `work.item.op` values — the vocabulary's entities.item.operations axis. Past
100
+ // tense, matching the connector's own `WORK_ITEM_OP_*` naming, not the v1
51
101
  // `linear.op` present-tense create/update.
52
102
  export const WORK_OP_CREATED = 'created'
53
103
  export const WORK_OP_UPDATED = 'updated'
54
104
 
55
105
  // `work.vendor` values a ticket marker stamps — the fix for the vendor-blind
56
- // `linear.*`-on-Jira misnomer (MAI-1469): a Jira and a Linear ticket are now
106
+ // `linear.*`-on-Jira misnomer: a Jira and a Linear ticket are now
57
107
  // distinguishable end to end.
58
108
  export const VENDOR_LINEAR = 'linear'
59
109
  export const VENDOR_JIRA = 'jira'
@@ -74,8 +124,8 @@ export const WORK_MARKER_KEYS = [
74
124
  export const VCS_OPENED = 'vcs.change.opened'
75
125
 
76
126
  // The PR URL lands under vcs.repository.url.full and the PR number under
77
- // vcs.change.id — the registry alias map for github.pr_url / github.pr_number
78
- // (a house mapping the read side already coalesces on; app/read/_vocab.py).
127
+ // vcs.change.id — an alias map for github.pr_url / github.pr_number (a house
128
+ // mapping the platform's read side already coalesces on).
79
129
  export const ATTR_VCS_REPOSITORY_URL_FULL = 'vcs.repository.url.full'
80
130
  export const ATTR_VCS_CHANGE_ID = 'vcs.change.id'
81
131
  export const ATTR_VCS_CHANGE_TITLE = 'vcs.change.title'
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mainwave/cli",
3
- "version": "0.6.0",
3
+ "version": "0.7.0",
4
4
  "description": "Setup wizard for connecting third-party coding tools to Mainwave AI.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -48,8 +48,8 @@
48
48
  "@hey-api/openapi-ts": "^0.99.0",
49
49
  "@types/node": "22.20.4",
50
50
  "lefthook": "2.1.14",
51
- "oxlint": "1.83.0",
52
- "prettier": "3.9.8",
51
+ "oxlint": "1.85.0",
52
+ "prettier": "3.9.9",
53
53
  "typescript": "6.0.3",
54
54
  "vitest": "5.0.1",
55
55
  "yaml": "2.9.1"
@@ -142,9 +142,10 @@ is by design and is listed first.
142
142
  - **Never import anything underscore-prefixed** (`mainwave._config`,
143
143
  `mainwave._runtime`). Those are internals and change without notice. If it is
144
144
  not in `mainwave.__all__`, it is not public.
145
- - **LangChain has one path: the handler.** There is no LangChain
146
- auto-instrumentor (ADR 0018), so `init()` alone captures no LangChain calls —
147
- attach `mainwave.langchain.CallbackHandler`. See `reference/frameworks.md`.
145
+ - **LangChain wires automatically, like the other frameworks.** `init()`
146
+ alone captures every LangChain / LangGraph call once `mainwave[langchain]`
147
+ is installed — no callback to construct, nothing passed to `.invoke()` /
148
+ `.stream()`. See `reference/frameworks.md`.
148
149
  - **Never let instrumentation change application behavior.** No swapped clients,
149
150
  no altered control flow, no new required config. If the SDK cannot start, the
150
151
  app must still run — that is why `MAINWAVE_DISABLED=1` exists.
@@ -155,8 +156,8 @@ is by design and is listed first.
155
156
  ## Reference
156
157
 
157
158
  - `reference/api.md` — the exact public surface: signatures, env vars, defaults.
158
- - `reference/frameworks.md` — per-framework wiring, including the LangChain fork
159
- and frameworks with no working instrumentor.
159
+ - `reference/frameworks.md` — per-framework wiring, including LangChain's
160
+ degraded case and frameworks with no working instrumentor.
160
161
  - `reference/troubleshooting.md` — "no spans are showing up", in the order the
161
162
  causes actually occur.
162
163
 
@@ -3,8 +3,8 @@
3
3
  ## The default: do nothing
4
4
 
5
5
  For `openai`, `anthropic`, `mistralai`, `google-genai`, `groq`, `bedrock`,
6
- `vertexai`, `litellm`, and `llama-index`, `mainwave.init()` wires the
7
- instrumentor at startup. Install the extra, call `init()` early, and the
6
+ `vertexai`, `litellm`, `llama-index`, and `langchain`, `mainwave.init()` wires
7
+ the instrumentor at startup. Install the extra, call `init()` early, and the
8
8
  framework's calls are captured — no callbacks, no wrappers, no changes at the
9
9
  call sites.
10
10
 
@@ -39,36 +39,47 @@ def handler():
39
39
 
40
40
  `instrument()` is safe to call repeatedly; it only wires what isn't wired.
41
41
 
42
- ## LangChain — one path, the explicit handler
42
+ ## LangChain — auto-instrumented, identity bound in context
43
43
 
44
- There is no LangChain auto-instrumentor. ADR 0018 removed the registry entry;
45
- `mainwave.langchain.CallbackHandler` emits the OTel GenAI conventions directly
46
- and is the only LangChain capture. `init()` alone produces no LangChain spans —
47
- attach the handler:
44
+ `mainwave[langchain]` installs the official OTel GenAI package
45
+ (`opentelemetry-instrumentation-genai-langchain`); the registry entry
46
+ `langchain` points at `mainwave.langchain.LangChainInstrumentor`, the SDK's
47
+ subclass of it. `init()` alone captures every LangChain / LangGraph call — no
48
+ callback to construct, nothing passed to `.invoke()` / `.stream()`:
48
49
 
49
50
  ```python
50
51
  mainwave.init(service_name="research-agent")
51
52
 
52
- from mainwave.langchain import CallbackHandler
53
-
54
- handler = CallbackHandler(use_case_id=tenant_ucid, agent_name="research")
55
- chain.invoke(input, config={"callbacks": [handler]})
53
+ chain.invoke(input)
56
54
  ```
57
55
 
58
- `skip_instrumentors=["langchain"]` is a no-op — harmless, but it names nothing.
59
- The SDK still defends the "pick one" contract by construction: building a
60
- `CallbackHandler` uninstruments a LangChain auto-instrumentor if a future
61
- release registers one.
56
+ `init(skip_instrumentors=["langchain"])` opts out.
57
+
58
+ Upstream owns span lifecycle and opens `invoke_agent` / `invoke_workflow` /
59
+ `chat {model}` / `execute_tool` / retrieval spans parented through its own
60
+ record of LangChain runs, so a LangGraph worker thread that loses contextvars
61
+ still lands in the right trace. The subclass adds graph-node spans (named
62
+ after the LangGraph node), corrected chat content and tokens, and reasoning on
63
+ `mainwave.reasoning.*`.
64
+
65
+ When one deployable serves several tenants or use cases, bind identity in
66
+ context around the call instead of passing it to a handler:
62
67
 
63
- Pass `use_case_id` / `agent_name` on the handler when one deployable serves
64
- several tenants or use cases.
68
+ ```python
69
+ with mainwave.bind_identity(use_case_id=tenant_ucid, agent_name="research"):
70
+ chain.invoke(input)
71
+ ```
65
72
 
66
- The handler parents its spans via LangChain's `parent_run_id`, and
67
- `mainwave.run()` establishes OTel context, so a turn comes out as one connected
68
- trace rather than a scatter of roots.
73
+ An agent name bound in context when a LangChain ROOT run starts derives the
74
+ per-agent default (the same UCID the removed `CallbackHandler(agent_name=...)`
75
+ used to produce); an explicit identity already bound in context wins over it.
76
+ `mainwave.run()` establishes the same OTel context, so a turn comes out as one
77
+ connected trace rather than a scatter of roots.
69
78
 
70
- `service_name=` on the handler is a deprecated alias for `agent_name=`. In new
71
- code use `agent_name`.
79
+ **Known degraded case:** upstream opens no `chat {model}` span for a model
80
+ whose name it cannot resolve (from `ls_model_name` metadata or the invocation
81
+ params) — a real LangChain chat model reports one, so this only bites a
82
+ hand-built or mocked chat model that omits both.
72
83
 
73
84
  ## CrewAI — two instrumentors, and the provider must match
74
85
 
@@ -96,10 +96,19 @@ at import and once in a startup hook, or once per worker in a pre-fork server.
96
96
  Initialize in exactly one place. Calling it again with _identical_ config is
97
97
  fine and does nothing.
98
98
 
99
- ## 9. Tokens and cost are roughly double
100
-
101
- LangChain wired both ways: the auto-instrumentor and a `CallbackHandler`. Pick
102
- one path — see `frameworks.md`.
99
+ ## 9. No LangChain spans at all
100
+
101
+ - `mainwave[langchain]` isn't installed — the extra pulls in
102
+ `opentelemetry-instrumentation-genai-langchain`, and without it `init()` has
103
+ nothing to wire.
104
+ - `skip_instrumentors=["langchain"]` is set somewhere the app doesn't expect
105
+ (a shared `init()` call, a config default). Check the `mainwave: instrumented
106
+ ...` log line for `langchain` in the list.
107
+ - The model's name is unresolvable — upstream opens no `chat {model}` span
108
+ for a chat model it can't identify from `ls_model_name` metadata or the
109
+ invocation params. A hand-built or mocked chat model that sets neither will
110
+ produce no chat span while everything else (graph-node, tool) still traces.
111
+ See `frameworks.md` § LangChain.
103
112
 
104
113
  ## 10. Nothing is wrong locally, so check the wire
105
114
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: mainwave-setup
3
- description: Connect this coding tool to Mainwave so its sessions produce telemetry — sign in, pick a use case, mint a per-developer key, write the config, and prove a span arrived. Use when asked to set up Mainwave, connect to Mainwave, fix a broken or stale Mainwave config, or check whether telemetry is actually flowing. Drives the mainwave-cli; never edit the tool's settings by hand.
3
+ description: Connect this coding tool to Mainwave so its sessions produce telemetry — sign in, mint a per-developer key, write the config, and prove a span arrived. Use when asked to set up Mainwave, connect to Mainwave, fix a broken or stale Mainwave config, or check whether telemetry is actually flowing. Drives the mainwave-cli; never edit the tool's settings by hand.
4
4
  ---
5
5
 
6
6
  # Connecting a coding tool to Mainwave
@@ -56,9 +56,20 @@ rather than showing a diff nobody confirms.
56
56
 
57
57
  Flags worth knowing, all optional:
58
58
 
59
- - `--use-case "<name>"` creates a use case by name, `--ucid <id|url>` binds an
60
- existing one, `--no-use-case` skips. Left alone, the CLI asks — which it
61
- cannot do without a terminal, so pass one of these.
59
+ - You do not need a use case. By default setup writes none: Mainwave attributes
60
+ each tool's activity to the developer from the identity its telemetry carries
61
+ (their Claude account, or their email), and it appears under **Development**.
62
+ Only pass `--use-case "<name>"` (create or reuse by name) or `--ucid <id|url>`
63
+ (bind an existing one) when the user explicitly wants every tool pinned to a
64
+ specific use case. A pin survives later default runs in the tools that
65
+ carry it; `--no-use-case` removes it.
66
+ - `--email <address>` gives Codex and Copilot an identity; their telemetry
67
+ carries none of its own. Claude Code needs it too when it runs on an API key,
68
+ Bedrock or Vertex instead of a Claude account. Signed in, setup uses the
69
+ account's email. `cursor-enterprise` is the exception: its export is
70
+ team-wide, so setup gives it a team use-case id (minted once, then kept) and
71
+ no email — don't pass `--ucid` for it unless the user names a use case. If setup warns that a tool has no email, its activity lands
72
+ unattributed until you re-run with `--email`.
62
73
  - `--opt-in` selects content capture. The default is **everything on** — prompt
63
74
  text, shell commands and file paths, tool result bodies — and it is never
64
75
  prompted for. `--opt-in none` sends metadata only; a named list
@@ -92,8 +103,13 @@ has to run first, and most tools only read the new config at launch.
92
103
 
93
104
  So: **tell the user to restart the tool** — every session that was already open,
94
105
  including the one you are running in, since the config is read at startup — have
95
- them do some work in it, then run `verify --no-sample` to watch for the tool's
96
- own spans without the synthetic one. Report the link it prints.
106
+ them do some work in it, then point them at the link `verify` printed: their
107
+ activity appears under Development once the first session arrives, within about
108
+ 10 minutes. If a use case is pinned (`--ucid`, or one a `setup --ucid` run
109
+ pinned that a tool still carries), `verify` watches that use case instead and
110
+ links to it, and `verify --no-sample` watches for the tool's own spans there;
111
+ without a pinned use case `--no-sample` refuses, because there is no id to
112
+ watch.
97
113
 
98
114
  ## When something is already there
99
115