@mainwave/cli 0.3.2 → 0.4.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 (88) hide show
  1. package/README.md +133 -10
  2. package/dist/adapters/claude-code.js +22 -2
  3. package/dist/adapters/claude-code.js.map +1 -1
  4. package/dist/adapters/claude-desktop.js +3 -0
  5. package/dist/adapters/claude-desktop.js.map +1 -1
  6. package/dist/adapters/codex-cli.js +18 -1
  7. package/dist/adapters/codex-cli.js.map +1 -1
  8. package/dist/adapters/copilot-chat.js +22 -0
  9. package/dist/adapters/copilot-chat.js.map +1 -1
  10. package/dist/adapters/copilot-cli.js +10 -0
  11. package/dist/adapters/copilot-cli.js.map +1 -1
  12. package/dist/adapters/cursor-enterprise.js +155 -0
  13. package/dist/adapters/cursor-enterprise.js.map +1 -0
  14. package/dist/adapters/cursor.js +205 -0
  15. package/dist/adapters/cursor.js.map +1 -0
  16. package/dist/adapters/index.js +4 -0
  17. package/dist/adapters/index.js.map +1 -1
  18. package/dist/api/index.js +3 -0
  19. package/dist/api/index.js.map +1 -0
  20. package/dist/api/types.gen.js +3 -0
  21. package/dist/api/types.gen.js.map +1 -0
  22. package/dist/core/apply.js +269 -0
  23. package/dist/core/apply.js.map +1 -0
  24. package/dist/core/auth-commands.js +167 -0
  25. package/dist/core/auth-commands.js.map +1 -0
  26. package/dist/core/behaviour-hooks.js +101 -0
  27. package/dist/core/behaviour-hooks.js.map +1 -0
  28. package/dist/core/browser.js +41 -0
  29. package/dist/core/browser.js.map +1 -0
  30. package/dist/core/codecs/cursor-hooks-json.js +90 -0
  31. package/dist/core/codecs/cursor-hooks-json.js.map +1 -0
  32. package/dist/core/detect.js +52 -0
  33. package/dist/core/detect.js.map +1 -0
  34. package/dist/core/device-login.js +76 -0
  35. package/dist/core/device-login.js.map +1 -0
  36. package/dist/core/doctor.js +51 -2
  37. package/dist/core/doctor.js.map +1 -1
  38. package/dist/core/errors.js +23 -0
  39. package/dist/core/errors.js.map +1 -1
  40. package/dist/core/flags.js +57 -0
  41. package/dist/core/flags.js.map +1 -0
  42. package/dist/core/headers.js +15 -1
  43. package/dist/core/headers.js.map +1 -1
  44. package/dist/core/interview.js +199 -0
  45. package/dist/core/interview.js.map +1 -0
  46. package/dist/core/keys.js +41 -0
  47. package/dist/core/keys.js.map +1 -0
  48. package/dist/core/markers.js +5 -1
  49. package/dist/core/markers.js.map +1 -1
  50. package/dist/core/platform.js +155 -0
  51. package/dist/core/platform.js.map +1 -0
  52. package/dist/core/prompts.js +73 -22
  53. package/dist/core/prompts.js.map +1 -1
  54. package/dist/core/skills.js +203 -0
  55. package/dist/core/skills.js.map +1 -0
  56. package/dist/core/status.js +25 -1
  57. package/dist/core/status.js.map +1 -1
  58. package/dist/core/store.js +118 -0
  59. package/dist/core/store.js.map +1 -0
  60. package/dist/core/tty.js +6 -0
  61. package/dist/core/tty.js.map +1 -1
  62. package/dist/core/ucid.js +25 -0
  63. package/dist/core/ucid.js.map +1 -0
  64. package/dist/core/ui.js +26 -0
  65. package/dist/core/ui.js.map +1 -0
  66. package/dist/core/use-case.js +75 -0
  67. package/dist/core/use-case.js.map +1 -0
  68. package/dist/core/validate.js +22 -0
  69. package/dist/core/validate.js.map +1 -1
  70. package/dist/core/verify.js +154 -0
  71. package/dist/core/verify.js.map +1 -0
  72. package/dist/core/wizard.js +236 -266
  73. package/dist/core/wizard.js.map +1 -1
  74. package/dist/main.js +215 -29
  75. package/dist/main.js.map +1 -1
  76. package/hooks/cursor-otlp.mjs +244 -0
  77. package/hooks/github-pr-marker.mjs +30 -10
  78. package/hooks/jira-ticket-marker.mjs +69 -17
  79. package/hooks/linear-ticket-marker.mjs +68 -12
  80. package/hooks/marker-core.mjs +5 -0
  81. package/hooks/vocabulary.d.mts +35 -0
  82. package/hooks/vocabulary.mjs +109 -0
  83. package/package.json +7 -3
  84. package/skills/mainwave-instrument/SKILL.md +168 -0
  85. package/skills/mainwave-instrument/reference/api.md +142 -0
  86. package/skills/mainwave-instrument/reference/frameworks.md +170 -0
  87. package/skills/mainwave-instrument/reference/troubleshooting.md +131 -0
  88. package/skills/mainwave-setup/SKILL.md +114 -0
@@ -0,0 +1,142 @@
1
+ # Mainwave Python SDK — public surface
2
+
3
+ Everything here is stable. Anything not listed — in particular any
4
+ underscore-prefixed module — is internal, even when importable. The
5
+ authoritative list at runtime is `mainwave.__all__`.
6
+
7
+ ## Setup
8
+
9
+ ```python
10
+ mainwave.init(
11
+ *,
12
+ api_key: str | None = None, # env: MAINWAVE_API_KEY (required)
13
+ use_case_id: str | None = None, # env: MAINWAVE_USE_CASE_ID
14
+ collector_url: str | None = None, # env: MAINWAVE_COLLECTOR_URL
15
+ service_name: str | None = None, # env: OTEL_SERVICE_NAME
16
+ deployment_environment: str | None = None,# env: MAINWAVE_ENVIRONMENT
17
+ disabled: bool | None = None, # env: MAINWAVE_DISABLED
18
+ skip_instrumentors: list[str] | None = None,
19
+ ) -> None
20
+ ```
21
+
22
+ Idempotent when called again with identical config; raises
23
+ `MainwaveReinitConflict` when the config differs. Bad config raises
24
+ `MainwaveConfigError`. After a successful init, runtime errors are swallowed —
25
+ the SDK cannot break its host.
26
+
27
+ `skip_instrumentors` leaves a named instrumentor unwired even when installed.
28
+ It applies only to the one-time wiring at first init, so it is not part of the
29
+ re-init equality check.
30
+
31
+ ```python
32
+ mainwave.instrument(name: str | list[str] | None = None) -> list[str]
33
+ ```
34
+
35
+ Wires instrumentors after a late import. `None` re-walks the whole registry and
36
+ returns what newly wired. A name whose package is missing or whose version
37
+ conflicts is dropped from the result with a WARN — not raised. An _unregistered_
38
+ name raises `KeyError`, and a list is validated fully before anything wires.
39
+ Hyphens and underscores are equivalent (`llama-index` == `llama_index`).
40
+
41
+ ```python
42
+ mainwave.register_framework(name: str) -> None
43
+ ```
44
+
45
+ Stamps a framework name onto spans without wiring an instrumentor — for a
46
+ framework whose instrumentor is unavailable or incompatible, so it still appears
47
+ in telemetry.
48
+
49
+ ## Runs and spans
50
+
51
+ ```python
52
+ with mainwave.run(run_id, *, metadata=None, use_case_id=None, agent_name=None) as r: ...
53
+ async with mainwave.arun(...) as r: ...
54
+ r = mainwave.start_run(...) # same args, no context manager
55
+ with mainwave.span(name, *, attrs=None) as s: ...
56
+ with mainwave.bind_identity(*, use_case_id=None, agent_name=None): ...
57
+ ```
58
+
59
+ `span()` is the escape hatch for a manual span; it inherits the active run's id
60
+ and attributes. `bind_identity()` binds identity into the OTel context without
61
+ opening a run.
62
+
63
+ ### `Run`
64
+
65
+ ```python
66
+ r.run_id # str
67
+ r.set_metadata(**kwargs) -> None
68
+ r.record_error(exc: BaseException) -> None
69
+ r.end(status=StatusCode.OK, description=None, *,
70
+ reason=None, decision=None, iterations=None, cost=None) -> None
71
+ ```
72
+
73
+ `end()` is idempotent and is called for you on context-manager exit — with
74
+ `record_error` + an ERROR status when the block raises. The four keyword fields
75
+ are what the product surfaces read: `reason` is how the run terminated,
76
+ `decision` is the outcome the operator cares about, `iterations` is the loop
77
+ count, `cost` is dollars.
78
+
79
+ ## Flushing
80
+
81
+ ```python
82
+ mainwave.flush(timeout: float = 30.0) -> bool
83
+ await mainwave.aflush(timeout: float = 30.0) -> bool
84
+ ```
85
+
86
+ An `atexit` handler is registered automatically, but call `flush()` explicitly
87
+ in scripts and job handlers — an abrupt exit path can outrun `atexit`.
88
+
89
+ ## Errors
90
+
91
+ `MainwaveError` (base), `MainwaveConfigError`, `MainwaveReinitConflict`.
92
+
93
+ ## Testing helpers
94
+
95
+ ```python
96
+ from mainwave import testing
97
+
98
+ exporter = testing.install_in_memory_provider(
99
+ use_case_id="test-ucid", api_key="test-key",
100
+ service_name="test-service", deployment_environment="test",
101
+ )
102
+ testing.reset()
103
+ ```
104
+
105
+ `install_in_memory_provider` routes spans through the _production_ export
106
+ pipeline, so assertions see the wire shape the collector receives. Spans become
107
+ visible only once their trace completes — end the root span, exit the
108
+ `mainwave.run(...)` block, or call `mainwave.flush()` before asserting.
109
+
110
+ `reset()` is a full teardown (instrumentors unwound, provider shut down, OTel's
111
+ set-once guard rewound), so init/reset/init cycles work in a test suite. Acquire
112
+ the SDK _inside_ fixtures rather than importing it at module level in
113
+ `conftest.py`, since the reset hook clears global state.
114
+
115
+ ## Defaults
116
+
117
+ | Setting | Default |
118
+ | ------------------------ | -------------------------------------------------------- |
119
+ | `collector_url` | `https://collector.mainwave.com` |
120
+ | `service_name` | `mainwave-app` — always override |
121
+ | `deployment_environment` | `production` |
122
+ | `use_case_id` | derived (stable UUIDv5 of key + service name) when unset |
123
+
124
+ ## Optional dependency extras
125
+
126
+ `openai`, `anthropic`, `mistralai`, `google-genai`, `groq`, `bedrock`,
127
+ `vertexai`, `litellm`, `langchain`, `crewai`, `llama-index`.
128
+
129
+ `all` exists for CI matrices and example projects. Do not use it in an
130
+ application.
131
+
132
+ ## Attributes the SDK emits
133
+
134
+ `mainwave.ucid` (the use case) and `mainwave.ucid_source`, `mainwave.run_id`,
135
+ `gen_ai.agent.name` (the logical agent), and from `Run.end()`:
136
+ `agent.terminated_reason`, `agent.decision`, `agent.iteration_count`,
137
+ `agent.cost`. Anything passed as run `metadata=` or `set_metadata()` lands
138
+ under `mainwave.run.metadata.<key>`.
139
+
140
+ Identity is carried **on the span**, not on the OTel resource. The resource
141
+ holds only `service.name`. This is why a per-run `use_case_id` override works
142
+ and why spans created before a bind do not inherit it.
@@ -0,0 +1,170 @@
1
+ # Per-framework wiring
2
+
3
+ ## The default: do nothing
4
+
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
8
+ framework's calls are captured — no callbacks, no wrappers, no changes at the
9
+ call sites.
10
+
11
+ `init()` wires every instrumentor whose package is **installed**, not every one
12
+ the application actually calls. Those differ more often than you would expect —
13
+ `crewai[anthropic]` puts the Anthropic SDK in the dependency tree even when
14
+ every run goes to OpenAI. The unused instrumentor then stamps its framework name
15
+ onto the telemetry, and the operator reads a provider the app never called.
16
+
17
+ When more than one provider SDK is installed and the app uses one of them,
18
+ suppress the automatic pass and wire what you mean:
19
+
20
+ ```python
21
+ mainwave.init(service_name="research-agent",
22
+ skip_instrumentors=["openai", "anthropic"])
23
+ mainwave.instrument("openai")
24
+ ```
25
+
26
+ Check it: at INFO the SDK logs `mainwave: instrumented ...` with everything it
27
+ wired. If that line names a provider the app does not call, you need the skip.
28
+
29
+ The other thing that breaks the default is import order. If the LLM library is
30
+ imported after `init()` runs — a lazy import inside a function, a plugin loaded on
31
+ demand, a Click subcommand — the instrumentor had nothing to patch. Wire it
32
+ after the import:
33
+
34
+ ```python
35
+ def handler():
36
+ import openai
37
+ mainwave.instrument("openai")
38
+ ```
39
+
40
+ `instrument()` is safe to call repeatedly; it only wires what isn't wired.
41
+
42
+ ## LangChain — pick exactly one path
43
+
44
+ Both paths capture every call. Wiring both double-counts tokens and cost.
45
+
46
+ **Path A — auto-instrumentation.** Nothing to write:
47
+
48
+ ```python
49
+ mainwave.init(service_name="research-agent")
50
+ ```
51
+
52
+ **Path B — the explicit handler.** Choose this when you need per-chain identity,
53
+ for example one deployable serving several tenants or use cases:
54
+
55
+ ```python
56
+ mainwave.init(service_name="research-agent", skip_instrumentors=["langchain"])
57
+
58
+ from mainwave.langchain import CallbackHandler
59
+
60
+ handler = CallbackHandler(use_case_id=tenant_ucid, agent_name="research")
61
+ chain.invoke(input, config={"callbacks": [handler]})
62
+ ```
63
+
64
+ `skip_instrumentors=["langchain"]` is what keeps the two apart. The SDK also
65
+ defends this by construction — building a `CallbackHandler` uninstruments the
66
+ LangChain instrumentor — but declare the intent rather than relying on the
67
+ rescue.
68
+
69
+ The handler parents its spans via LangChain's `parent_run_id`, and
70
+ `mainwave.run()` establishes OTel context, so a turn comes out as one connected
71
+ trace rather than a scatter of roots.
72
+
73
+ `service_name=` on the handler is a deprecated alias for `agent_name=`. In new
74
+ code use `agent_name`.
75
+
76
+ ## CrewAI — two instrumentors, and the provider must match
77
+
78
+ CrewAI needs its own structure instrumentor _plus_ the instrumentor for the LLM
79
+ provider the crew actually calls. The `crewai` instrumentor emits the
80
+ crew → agent → task structure and is provider-agnostic; the provider
81
+ instrumentor emits the leaf LLM spans that carry `gen_ai.usage.*`, which is
82
+ where tokens and cost come from. With only the first, every run shows structure
83
+ and no cost.
84
+
85
+ The trap is that the provider is usually **resolved at runtime from config**,
86
+ not written at the call site. Wiring a hardcoded provider that the run does not
87
+ use drops every LLM span silently — the symptom is a run with one span and no
88
+ tokens. Read the provider the app resolves, and map it:
89
+
90
+ ```python
91
+ _PROVIDER_INSTRUMENTOR = {"openai": "openai", "ollama": "openai", "anthropic": "anthropic"}
92
+
93
+ mainwave.init(service_name="content-pipeline",
94
+ skip_instrumentors=["crewai", "openai", "anthropic"])
95
+ mainwave.instrument("crewai")
96
+ mainwave.instrument(_PROVIDER_INSTRUMENTOR[resolved_provider])
97
+ ```
98
+
99
+ CrewAI routes OpenAI-compatible providers (including Ollama and most local
100
+ gateways) through the OpenAI client, so one `openai` instrumentor covers them.
101
+ Anthropic uses its own SDK and needs its own.
102
+
103
+ `instrument()` returns what actually wired, so check rather than assume:
104
+
105
+ ```python
106
+ if not mainwave.instrument("crewai"):
107
+ log.warning("crew structure spans unavailable; install openinference-instrumentation-crewai")
108
+ ```
109
+
110
+ If the CrewAI instrumentor cannot wire against the installed CrewAI at all,
111
+ `register_framework("crewai")` keeps the framework visible in telemetry without
112
+ wiring anything — provider spans still carry tokens and cost, and what you lose
113
+ is crew/task structure. Reach for it only when `instrument("crewai")` has
114
+ actually come back empty; recent instrumentor releases wire against CrewAI 1.x
115
+ fine, and taking the fallback pre-emptively throws away the structure for
116
+ nothing.
117
+
118
+ ## No framework — hand-rolled LLM calls
119
+
120
+ An application calling an HTTP API directly has nothing to auto-instrument.
121
+ Emit OTel spans through the normal API and the SDK exports them:
122
+
123
+ ```python
124
+ from opentelemetry import trace
125
+ tracer = trace.get_tracer("my-app")
126
+
127
+ with mainwave.run(f"triage-{ticket.id}") as r:
128
+ with tracer.start_as_current_span("llm.chat") as span:
129
+ span.set_attribute("gen_ai.provider.name", "openai")
130
+ span.set_attribute("gen_ai.request.model", "gpt-4o-mini")
131
+ span.set_attribute("gen_ai.operation.name", "chat")
132
+ response, in_tok, out_tok = call_the_api(prompt)
133
+ span.set_attribute("gen_ai.usage.input_tokens", in_tok)
134
+ span.set_attribute("gen_ai.usage.output_tokens", out_tok)
135
+ r.end(reason="success")
136
+ ```
137
+
138
+ The `gen_ai.*` attributes are what mark the span as LLM activity. Without them
139
+ the trace is dropped — see `troubleshooting.md`.
140
+
141
+ ## An app that already uses OpenTelemetry
142
+
143
+ If the application builds its own `TracerProvider`, `init()` detects it and runs
144
+ in **coexist mode**: the SDK attaches its processors to the existing provider
145
+ instead of installing one, and forwards spans under the host's resource
146
+ untouched.
147
+
148
+ Leave their setup alone. Do not remove their exporter, do not replace their
149
+ provider, do not move their `TracerProvider` construction after `init()`. Their
150
+ existing backend keeps receiving everything it received before.
151
+
152
+ Only LLM-bearing traces are forwarded to Mainwave — the host's HTTP, database,
153
+ and background-job traces stay out. That filtering is what makes sharing a
154
+ provider safe.
155
+
156
+ ## Async applications
157
+
158
+ `mainwave.arun()` replaces `run()`, `await mainwave.aflush()` replaces
159
+ `flush()`. Instrumentors handle async clients without extra wiring.
160
+
161
+ In a web framework, initialize in the startup or lifespan hook — once per
162
+ process — and open a run per unit of work inside the handler:
163
+
164
+ ```python
165
+ @asynccontextmanager
166
+ async def lifespan(app):
167
+ mainwave.init(service_name="support-api")
168
+ yield
169
+ await mainwave.aflush()
170
+ ```
@@ -0,0 +1,131 @@
1
+ # No spans are showing up
2
+
3
+ Work these in order. The first cause is the most common and is deliberate
4
+ behavior, not a bug.
5
+
6
+ First, turn on the SDK's own logging — it announces what it wired, whether it
7
+ went into coexist mode, and whether it derived a use-case id:
8
+
9
+ ```python
10
+ import logging
11
+ logging.basicConfig(level=logging.INFO)
12
+ ```
13
+
14
+ ## 1. The trace had no LLM activity, so it was dropped whole
15
+
16
+ The exporter buffers by trace and, at finalize, **drops the entire trace unless
17
+ something in it shows LLM activity** — an SDK span (a `mainwave.run` wrapper or
18
+ the `mainwave.*` scope), an OpenInference instrumentor span, or any span
19
+ carrying `gen_ai.*` / `llm.*` attributes.
20
+
21
+ This is what lets the SDK share a host's `TracerProvider` without leaking the
22
+ host's HTTP, database, and background traces to Mainwave.
23
+
24
+ So a hand-rolled span with no `gen_ai.*` attributes, emitted outside any run,
25
+ vanishes silently and correctly. Fix it by giving the trace a reason to exist:
26
+ wrap the work in `mainwave.run(...)`, or put the real `gen_ai.*` attributes on
27
+ the span.
28
+
29
+ ## 2. `init()` didn't run, or ran too late
30
+
31
+ - Check the log line for the wired instrumentors. Nothing wired means nothing
32
+ was patched.
33
+ - `MAINWAVE_DISABLED` set truthy anywhere in the environment turns the SDK into
34
+ a no-op that logs and returns. Check the deployment's env, not just the shell.
35
+ - In a web app, confirm `init()` is in the startup hook and that the hook
36
+ actually runs under the process manager in use.
37
+
38
+ ## 3. The process exited before the batch drained
39
+
40
+ Scripts, cron jobs, serverless handlers, and CLI commands end fast enough to
41
+ outrun the exporter. Add `mainwave.flush()` — or `await mainwave.aflush()` — on
42
+ every exit path, including the error path.
43
+
44
+ Symptom that confirms it: spans appear when you add a `sleep` before exit.
45
+
46
+ ## 4. The library was imported after `init()`
47
+
48
+ Instrumentors patch at wire time. A lazy import — inside a function, a Click
49
+ subcommand, a plugin loader, a FastAPI route — was not importable when `init()`
50
+ walked the registry, so it was skipped.
51
+
52
+ `mainwave.instrument("openai")` after the import fixes it. The return value
53
+ tells you what actually wired; an empty list means the package still isn't
54
+ importable or its version conflicts with the instrumentor.
55
+
56
+ ## 5. Spans are landing, but not in the use case you're watching
57
+
58
+ - If `MAINWAVE_USE_CASE_ID` was unset, the SDK derived a stable id from the API
59
+ key and service name and logged it at INFO. Telemetry is arriving — into a use
60
+ case nobody created. Set the id explicitly.
61
+ - Identity binds at the root of a unit of work. **Spans created before the bind
62
+ do not inherit it**, so work started outside `mainwave.run(...)` /
63
+ `bind_identity(...)` carries the process default instead of the override.
64
+ - Verify against the id the code is actually sending, not the one you expected:
65
+
66
+ ```bash
67
+ npx @mainwave/cli@latest verify --ucid <use-case-id> --no-sample
68
+ ```
69
+
70
+ ## 6. One span per run, and no tokens or cost
71
+
72
+ Structure spans arrived; the leaf LLM spans did not. The instrumentor for the
73
+ provider the run actually used was never wired — commonly because the provider
74
+ is resolved from config at runtime and the wiring names a different one.
75
+
76
+ Check the `mainwave: instrumented ...` line at INFO against the provider the run
77
+ resolved. See `frameworks.md` § CrewAI, which is where this bites hardest.
78
+
79
+ ## 7. Telemetry names a framework the app never calls
80
+
81
+ `init()` wires every instrumentor whose package is **installed**, which is not
82
+ the same set as the frameworks the app calls — a provider SDK pulled in as a
83
+ transitive dependency gets wired and stamped like any other.
84
+
85
+ Suppress the automatic pass and wire deliberately:
86
+
87
+ ```python
88
+ mainwave.init(service_name="...", skip_instrumentors=["openai", "anthropic"])
89
+ mainwave.instrument("openai")
90
+ ```
91
+
92
+ ## 8. `MainwaveReinitConflict` at startup
93
+
94
+ `init()` was called twice with different settings in one process — commonly once
95
+ at import and once in a startup hook, or once per worker in a pre-fork server.
96
+ Initialize in exactly one place. Calling it again with _identical_ config is
97
+ fine and does nothing.
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`.
103
+
104
+ ## 10. Nothing is wrong locally, so check the wire
105
+
106
+ - The API key must belong to the same organization as the use case.
107
+ - `MAINWAVE_COLLECTOR_URL` defaults to `https://collector.mainwave.com`; an
108
+ override pointing at a local or stale collector sends telemetry somewhere real
109
+ but wrong.
110
+ - An egress-restricted network needs that host allowed. The SDK will not crash
111
+ the app when it can't reach the collector — it logs and drops, which looks
112
+ identical to "no instrumentation" from the outside.
113
+
114
+ ## Proving instrumentation works without the network
115
+
116
+ Assert on spans in-process, which isolates your wiring from every deployment
117
+ question above:
118
+
119
+ ```python
120
+ from mainwave import testing
121
+
122
+ def test_agent_emits_a_run():
123
+ exporter = testing.install_in_memory_provider()
124
+ run_the_agent()
125
+ mainwave.flush()
126
+ names = [s.name for s in exporter.get_finished_spans()]
127
+ assert names
128
+ ```
129
+
130
+ Spans only appear once their trace completes, so end the run (or flush) before
131
+ asserting. Call `testing.reset()` between tests.
@@ -0,0 +1,114 @@
1
+ ---
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.
4
+ ---
5
+
6
+ # Connecting a coding tool to Mainwave
7
+
8
+ The `mainwave-cli` does this whole flow. Your job is to drive it and read what
9
+ it tells you — **never hand-edit a settings file to add telemetry config.** The
10
+ CLI writes several files atomically, keeps secrets out of the ones that get
11
+ committed, and knows each tool's key names. A hand-written env block is how
12
+ people end up with a key in a repo and telemetry that silently doesn't flow.
13
+
14
+ Every prompt has a flag, so the whole flow runs without a terminal.
15
+
16
+ ## 1. Sign in
17
+
18
+ ```bash
19
+ npx @mainwave/cli@latest login --device
20
+ ```
21
+
22
+ `--device` matters here. The CLI shows a short code and opens the browser; the
23
+ human approves in the Mainwave session they already have. Without it, a run
24
+ with no TTY — which is what you are — assumes nobody is watching, falls back to
25
+ email and password, and stops asking for `MAINWAVE_EMAIL`.
26
+
27
+ Print the code and the URL for the user, and tell them to approve in the
28
+ browser. Then wait — the command blocks until they do, or until it times out.
29
+
30
+ If the user is on CI or has no browser, `MAINWAVE_EMAIL` and `MAINWAVE_PASSWORD`
31
+ in the environment take the password path with no flags at all. **Never ask the
32
+ user to type a password to you, and never put one on the command line.**
33
+
34
+ Already signed in? `whoami` says so without re-authenticating:
35
+
36
+ ```bash
37
+ npx @mainwave/cli@latest whoami --json
38
+ ```
39
+
40
+ ## 2. Set up this tool
41
+
42
+ ```bash
43
+ npx @mainwave/cli@latest setup <adapter> --yes --json
44
+ ```
45
+
46
+ Use the adapter for the tool you are running inside — `claude-code`, `codex`,
47
+ `copilot-cli`, `copilot-chat`, `cursor`, `claude-desktop`. Run `setup` with no
48
+ adapter to see what the CLI detects on this machine.
49
+
50
+ `--json` gives you one parseable document on stdout; narrative goes to stderr.
51
+ `--yes` is required for a non-interactive write — without it the CLI refuses
52
+ rather than showing a diff nobody confirms.
53
+
54
+ Flags worth knowing, all optional:
55
+
56
+ - `--scope local` writes repo config instead of user-level. Global is the
57
+ default and is usually right; local is a deliberate choice the user makes.
58
+ - `--use-case "<name>"` creates a use case by name, `--ucid <id|url>` binds an
59
+ existing one, `--no-use-case` skips. Left alone, the CLI asks — which it
60
+ cannot do without a terminal, so pass one of these.
61
+ - `--opt-in prompts,tool-details,tool-content` turns on the sensitive-data
62
+ captures, all off by default.
63
+
64
+ **Ask before enabling any opt-in.** `prompts` sends the user's prompt text off
65
+ the machine. That is the user's call every time, not a default you pick for
66
+ them, and not something to enable because it makes the demo better.
67
+
68
+ ## 3. Prove it works
69
+
70
+ ```bash
71
+ npx @mainwave/cli@latest verify --json
72
+ ```
73
+
74
+ This pushes a sample trace and waits for it to land, so it proves the network
75
+ path and the key. It does **not** prove the tool itself is emitting — the tool
76
+ has to run first, and most tools only read the new config at launch.
77
+
78
+ So: tell the user to restart the tool, have them do some work in it, then run
79
+ `verify --no-sample` to watch for the tool's own spans without the synthetic
80
+ one. Report the link it prints.
81
+
82
+ ## When something is already there
83
+
84
+ ```bash
85
+ npx @mainwave/cli@latest doctor <adapter> --json
86
+ npx @mainwave/cli@latest status --json
87
+ ```
88
+
89
+ `doctor` walks the whole settings hierarchy — including managed and org-policy
90
+ layers the CLI cannot write — and reports kill switches, stale versions, and
91
+ overrides. Run it before concluding anything is broken. A config that looks
92
+ right in the user file can be overridden a layer up, and `doctor` is the only
93
+ thing that sees that.
94
+
95
+ Re-running `setup` is safe and is the fix for most staleness: it converges
96
+ rather than duplicating.
97
+
98
+ ## Guardrails
99
+
100
+ - **Never write telemetry config by hand.** Use the CLI. If the CLI cannot do
101
+ what is needed, say so rather than reaching for the settings file.
102
+ - **Never print an API key, a token, or the contents of `~/.mainwave/credentials.json`.**
103
+ The CLI masks secrets in its own output; don't undo that by `cat`-ing files.
104
+ - **Never enable a data opt-in without asking.**
105
+ - **Never commit a settings file containing a key.** If `--scope local` wrote
106
+ into the repo, check what is tracked before suggesting a commit.
107
+ - Report what the CLI reported. Do not summarize a failure into a success — a
108
+ `verify` that timed out is a timeout, not "set up successfully".
109
+
110
+ ## Instrumenting an application
111
+
112
+ This skill connects a _coding tool_. Wiring the Mainwave SDK into an application
113
+ — an agent, a service, a pipeline — is a different job with its own skill:
114
+ `mainwave-instrument`.