@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.
- package/README.md +94 -18
- package/dist/adapters/claude-code.js +258 -38
- package/dist/adapters/claude-code.js.map +1 -1
- package/dist/adapters/claude-desktop.js +0 -87
- package/dist/adapters/claude-desktop.js.map +1 -1
- package/dist/adapters/codex-cli.js +0 -65
- package/dist/adapters/codex-cli.js.map +1 -1
- package/dist/adapters/copilot-chat.js +7 -42
- package/dist/adapters/copilot-chat.js.map +1 -1
- package/dist/adapters/copilot-cli.js +7 -32
- package/dist/adapters/copilot-cli.js.map +1 -1
- package/dist/adapters/cursor-enterprise.js +4 -53
- package/dist/adapters/cursor-enterprise.js.map +1 -1
- package/dist/adapters/cursor.js +0 -62
- package/dist/adapters/cursor.js.map +1 -1
- package/dist/api/index.js +0 -1
- package/dist/api/index.js.map +1 -1
- package/dist/api/types.gen.js +0 -1
- package/dist/api/types.gen.js.map +1 -1
- package/dist/core/apply.js +73 -97
- package/dist/core/apply.js.map +1 -1
- package/dist/core/auth-commands.js +5 -20
- package/dist/core/auth-commands.js.map +1 -1
- package/dist/core/behaviour-hooks.js +0 -7
- package/dist/core/behaviour-hooks.js.map +1 -1
- package/dist/core/browser.js +0 -18
- package/dist/core/browser.js.map +1 -1
- package/dist/core/codecs/cursor-hooks-json.js +0 -8
- package/dist/core/codecs/cursor-hooks-json.js.map +1 -1
- package/dist/core/codecs/json-flat.js +0 -28
- package/dist/core/codecs/json-flat.js.map +1 -1
- package/dist/core/codecs/json-managed.js +0 -30
- package/dist/core/codecs/json-managed.js.map +1 -1
- package/dist/core/codecs/toml-otel.js +0 -39
- package/dist/core/codecs/toml-otel.js.map +1 -1
- package/dist/core/detect.js +0 -29
- package/dist/core/detect.js.map +1 -1
- package/dist/core/device-login.js +0 -22
- package/dist/core/device-login.js.map +1 -1
- package/dist/core/doctor.js +209 -48
- package/dist/core/doctor.js.map +1 -1
- package/dist/core/edit.js +18 -0
- package/dist/core/edit.js.map +1 -1
- package/dist/core/effective-settings.js +107 -10
- package/dist/core/effective-settings.js.map +1 -1
- package/dist/core/env-command.js +0 -9
- package/dist/core/env-command.js.map +1 -1
- package/dist/core/errors.js +0 -12
- package/dist/core/errors.js.map +1 -1
- package/dist/core/flags.js +0 -13
- package/dist/core/flags.js.map +1 -1
- package/dist/core/format.js +0 -56
- package/dist/core/format.js.map +1 -1
- package/dist/core/git.js +0 -9
- package/dist/core/git.js.map +1 -1
- package/dist/core/headers.js +4 -97
- package/dist/core/headers.js.map +1 -1
- package/dist/core/install-hooks.js +81 -0
- package/dist/core/install-hooks.js.map +1 -0
- package/dist/core/interview.js +25 -151
- package/dist/core/interview.js.map +1 -1
- package/dist/core/keys.js +0 -18
- package/dist/core/keys.js.map +1 -1
- package/dist/core/layer-policy.js +34 -0
- package/dist/core/layer-policy.js.map +1 -0
- package/dist/core/markers.js +219 -117
- package/dist/core/markers.js.map +1 -1
- package/dist/core/pinned-use-case.js +11 -0
- package/dist/core/pinned-use-case.js.map +1 -0
- package/dist/core/platform.js +5 -40
- package/dist/core/platform.js.map +1 -1
- package/dist/core/post-setup.js +7 -18
- package/dist/core/post-setup.js.map +1 -1
- package/dist/core/prompts.js +0 -59
- package/dist/core/prompts.js.map +1 -1
- package/dist/core/settings.js +20 -16
- package/dist/core/settings.js.map +1 -1
- package/dist/core/skills.js +0 -75
- package/dist/core/skills.js.map +1 -1
- package/dist/core/status.js +97 -45
- package/dist/core/status.js.map +1 -1
- package/dist/core/store.js +4 -34
- package/dist/core/store.js.map +1 -1
- package/dist/core/tty.js +0 -9
- package/dist/core/tty.js.map +1 -1
- package/dist/core/ucid.js +0 -13
- package/dist/core/ucid.js.map +1 -1
- package/dist/core/ui.js +0 -11
- package/dist/core/ui.js.map +1 -1
- package/dist/core/use-case.js +3 -50
- package/dist/core/use-case.js.map +1 -1
- package/dist/core/validate.js +0 -5
- package/dist/core/validate.js.map +1 -1
- package/dist/core/verify.js +51 -33
- package/dist/core/verify.js.map +1 -1
- package/dist/core/version.js +0 -3
- package/dist/core/version.js.map +1 -1
- package/dist/core/wizard.js +172 -128
- package/dist/core/wizard.js.map +1 -1
- package/dist/main.js +16 -38
- package/dist/main.js.map +1 -1
- package/hooks/cursor-otlp.mjs +4 -4
- package/hooks/github-pr-marker.mjs +31 -12
- package/hooks/jira-ticket-marker.mjs +46 -27
- package/hooks/linear-ticket-marker.mjs +58 -37
- package/hooks/marker-core.mjs +671 -59
- package/hooks/matchers.json +1 -1
- package/hooks/vocabulary.d.mts +9 -1
- package/hooks/vocabulary.mjs +73 -23
- package/package.json +3 -3
- package/skills/mainwave-instrument/SKILL.md +6 -5
- package/skills/mainwave-instrument/reference/frameworks.md +33 -22
- package/skills/mainwave-instrument/reference/troubleshooting.md +13 -4
- package/skills/mainwave-setup/SKILL.md +22 -6
package/hooks/matchers.json
CHANGED
|
@@ -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
|
|
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",
|
package/hooks/vocabulary.d.mts
CHANGED
|
@@ -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
|
|
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
|
package/hooks/vocabulary.mjs
CHANGED
|
@@ -1,30 +1,80 @@
|
|
|
1
|
-
// The v2 telemetry vocabulary the CLI marker + cursor hooks emit
|
|
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
|
|
5
|
-
//
|
|
6
|
-
// `
|
|
7
|
-
//
|
|
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
|
|
15
|
-
//
|
|
16
|
-
//
|
|
17
|
-
//
|
|
18
|
-
//
|
|
19
|
-
//
|
|
20
|
-
//
|
|
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
|
|
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
|
|
44
|
-
// can reconcile
|
|
45
|
-
//
|
|
46
|
-
//
|
|
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
|
|
50
|
-
// tense, matching the connector
|
|
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
|
|
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 —
|
|
78
|
-
//
|
|
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.
|
|
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.
|
|
52
|
-
"prettier": "3.9.
|
|
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
|
|
146
|
-
|
|
147
|
-
|
|
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
|
|
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`,
|
|
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 —
|
|
42
|
+
## LangChain — auto-instrumented, identity bound in context
|
|
43
43
|
|
|
44
|
-
|
|
45
|
-
`
|
|
46
|
-
|
|
47
|
-
|
|
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
|
-
|
|
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"]`
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
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
|
-
|
|
64
|
-
|
|
68
|
+
```python
|
|
69
|
+
with mainwave.bind_identity(use_case_id=tenant_ucid, agent_name="research"):
|
|
70
|
+
chain.invoke(input)
|
|
71
|
+
```
|
|
65
72
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
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
|
-
|
|
71
|
-
|
|
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.
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
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,
|
|
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
|
-
-
|
|
60
|
-
|
|
61
|
-
|
|
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
|
|
96
|
-
|
|
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
|
|