@intelli-1113/stratos-sdk 1.2.2 → 1.3.1

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 CHANGED
@@ -1,64 +1,552 @@
1
- # @intelli-1113/stratos-sdk
2
-
3
- One-line [OpenLLMetry](https://traceloop.com/docs/openllmetry) telemetry for **Stratos AI** — streams agent liveness, tokens, cost, prompts and tool usage to your Stratos dashboard.
4
-
5
- ## Install
6
- ```bash
7
- npm i @intelli-1113/stratos-sdk
8
- ```
9
-
10
- ## Configure (environment)
11
- ```bash
12
- STRATOS_TOKEN=<token from Stratos → Add agent> # required
13
- STRATOS_URL=https://stratos.lnt.com # optional, default http://localhost:4000
14
- STRATOS_APP_NAME=my-agent # optional display name
15
- ```
16
-
17
- ## Use — pick one
18
-
19
- **Zero code changes** (recommended) — load before your app via Node's `--import`:
20
- ```bash
21
- node --import @intelli-1113/stratos-sdk/register server.js
22
- ```
23
-
24
- **One line** — must be the FIRST import in your entrypoint (before `openai`/`langchain`/etc.):
25
- ```js
26
- import "@intelli-1113/stratos-sdk/register";
27
- ```
28
-
29
- **Programmatic** — if you want to pass config explicitly:
30
- ```js
31
- import { start } from "@intelli-1113/stratos-sdk";
32
- start({ token: "...", url: "https://stratos.lnt.com", appName: "my-agent" });
33
- ```
34
-
35
- ## Why it must load first
36
- OpenLLMetry patches `openai`/`langchain` to capture spans — it has to run **before** those modules are imported. The `--import` flag and the `/register` entry both guarantee that.
37
-
38
- ## Auto-detected metadata (no manual entry)
39
- On each heartbeat the SDK reports, and Stratos auto-fills:
40
- - **framework** — detected from installed deps (langchain/langgraph, llamaindex, google-adk, vercel-ai, anthropic, openai…).
41
- - **model** — from `STRATOS_MODEL` / `NVIDIA_MODEL` / `OPENAI_MODEL` / `ANTHROPIC_MODEL` / `LLM_MODEL` / `MODEL` (or `start({ model })`).
42
- - **tools** — captured from spans automatically; you can also declare them via `STRATOS_TOOLS=a,b,c` or `start({ tools: [...] })`.
43
-
44
- ## Changing the URL or token
45
- Both come from env, read at startup — change the `.env` value and restart. No code edit, no SDK re-publish.
46
-
47
- ## MCP servers (Claude Desktop / Cursor / VS Code)
48
- The same package ships a `stratos-mcp-proxy` command for monitoring host-launched MCP servers.
49
- Install it globally, add an agent (type `mcp`) in Stratos, then wrap the server's command:
50
- ```bash
51
- npm i -g @intelli-1113/stratos-sdk
52
- ```
53
- ```json
54
- "weather": {
55
- "command": "stratos-mcp-proxy",
56
- "args": ["--","npx","-y","@scope/weather-mcp@latest"],
57
- "env": {
58
- "STRATOS_TOKEN":"<token>",
59
- "STRATOS_URL":"http://localhost:4000",
60
- "STRATOS_APP_NAME":"weather" }
61
- }
62
- ```
63
- It forwards the JSON-RPC stream verbatim and reports each **tool call** (name, args, result, latency) + liveness.
64
- Note: host MCP servers don't call the LLM themselves, so tokens/cost aren't captured.
1
+ # @intelli-1113/stratos-sdk
2
+
3
+ **One install** for [Stratos AI](https://github.com) agent observability:
4
+
5
+ 1. **OpenLLMetry / Traceloop** — LLM traces (model, tokens, prompts, tools, latency)
6
+ 2. **OTLP JSON → Stratos** — export to your dashboard (`/api/ingest`)
7
+ 3. **Heartbeat** — agent stays “online” between calls (`/api/heartbeat`)
8
+ 4. **Vercel AI auto-telemetry** — no `experimental_telemetry` in client code
9
+ 5. **`stratos-mcp-proxy`** — tool-call metering for host MCP servers
10
+
11
+ | | |
12
+ |---|---|
13
+ | **Package** | `@intelli-1113/stratos-sdk` |
14
+ | **Version** | `1.3.1` |
15
+ | **Runtime** | Node.js **≥ 18** (ESM; **≥ 20** recommended for LangChain instrumentation) |
16
+ | **Default Stratos URL** | `http://localhost:4000` |
17
+
18
+ ---
19
+
20
+ ## Table of contents
21
+
22
+ - [What you get](#what-you-get)
23
+ - [Install](#install)
24
+ - [Configure](#configure)
25
+ - [How to use](#how-to-use)
26
+ - [What is supported](#what-is-supported)
27
+ - [LangChain version inspect & fix](#langchain-version-inspect--fix)
28
+ - [Vercel AI SDK (important)](#vercel-ai-sdk-important)
29
+ - [Environment reference](#environment-reference)
30
+ - [Auto-detected metadata](#auto-detected-metadata)
31
+ - [MCP proxy](#mcp-proxy)
32
+ - [How it works](#how-it-works)
33
+ - [Troubleshooting](#troubleshooting)
34
+ - [Security & privacy](#security--privacy)
35
+ - [API](#api)
36
+
37
+ ---
38
+
39
+ ## What you get
40
+
41
+ | Feature | Description |
42
+ |--------|-------------|
43
+ | **Liveness** | Heartbeat so the agent shows online in Stratos |
44
+ | **LLM spans** | Model name, token usage, latency, prompts/outputs (when enabled) |
45
+ | **Tool spans** | Tool name, args, results (from instrumented frameworks / MCP proxy) |
46
+ | **Zero agent logic changes** | Prefer `node --import …/register` — no instrumentation in business code |
47
+ | **`.env` load** | On `--import`, loads `./.env` from `cwd` so `STRATOS_TOKEN` is available early |
48
+ | **MCP host tools** | `stratos-mcp-proxy` wraps Claude Desktop / Cursor / VS Code MCP servers |
49
+ | **LangChain inspect** | `stratos-inspect` checks core version; optional uninstall old + install 1.x |
50
+
51
+ Traces go to:
52
+
53
+ ```http
54
+ POST {STRATOS_URL}/api/ingest
55
+ Header: x-stratos-token: <STRATOS_TOKEN>
56
+ Body: OTLP/JSON
57
+ ```
58
+
59
+ ---
60
+
61
+ ## Install
62
+
63
+ ```bash
64
+ npm i @intelli-1113/stratos-sdk
65
+ ```
66
+
67
+ For MCP proxy use from a host app (global CLI):
68
+
69
+ ```bash
70
+ npm i -g @intelli-1113/stratos-sdk
71
+ ```
72
+
73
+ ---
74
+
75
+ ## Configure
76
+
77
+ 1. Open **Stratos AI** → **Add agent** → copy the enrollment **token**.
78
+ 2. Set environment variables (shell or `.env` in the project root):
79
+
80
+ ```env
81
+ # Required
82
+ STRATOS_TOKEN=your_enrollment_token_here
83
+
84
+ # Optional (defaults shown)
85
+ STRATOS_URL=http://localhost:4000
86
+ STRATOS_APP_NAME=my-agent
87
+ ```
88
+
89
+ Production example:
90
+
91
+ ```env
92
+ STRATOS_TOKEN=...
93
+ STRATOS_URL=https://stratos.example.com
94
+ STRATOS_APP_NAME=checkout-agent
95
+ ```
96
+
97
+ > Change token/URL anytime and **restart** the process. No code change required.
98
+
99
+ ---
100
+
101
+ ## How to use
102
+
103
+ ### Option A — Zero app-code changes (**recommended**)
104
+
105
+ Preload the SDK before your app. This is the **required** style for **Vercel AI SDK**.
106
+
107
+ ```bash
108
+ node --import @intelli-1113/stratos-sdk/register server.js
109
+ ```
110
+
111
+ `package.json`:
112
+
113
+ ```json
114
+ {
115
+ "scripts": {
116
+ "start": "node --import @intelli-1113/stratos-sdk/register server.js",
117
+ "dev": "node --import @intelli-1113/stratos-sdk/register --watch server.js"
118
+ }
119
+ }
120
+ ```
121
+
122
+ Windows PowerShell (same idea):
123
+
124
+ ```powershell
125
+ node --import @intelli-1113/stratos-sdk/register .\server.js
126
+ ```
127
+
128
+ Your application code stays normal (no Stratos APIs required):
129
+
130
+ ```js
131
+ // server.js — business logic only
132
+ import { generateText } from "ai";
133
+ import { mistral } from "@ai-sdk/mistral";
134
+ // or: ChatMistralAI from @langchain/mistralai, OpenAI SDK, etc.
135
+
136
+ const { text } = await generateText({
137
+ model: mistral("mistral-large-latest"),
138
+ prompt: "Hello",
139
+ });
140
+ ```
141
+
142
+ ### Option B — First import in the entrypoint
143
+
144
+ Works well for **LangChain**, **OpenAI**, **Anthropic**, **Google GenAI**, etc. (Traceloop auto-patches these **if** this import runs before those libraries load).
145
+
146
+ ```js
147
+ import "@intelli-1113/stratos-sdk/register"; // must be first
148
+ import { ChatOpenAI } from "@langchain/openai";
149
+ // ... rest of app
150
+ ```
151
+
152
+ > **Vercel AI note:** a normal `import "@intelli-1113/stratos-sdk/register"` in the **same file** as `import { generateText } from "ai"` is often **too late** (ESM links the whole graph before evaluation). Use **Option A (`--import`)** for Vercel AI.
153
+
154
+ ### Option C — Programmatic `start()`
155
+
156
+ ```js
157
+ import { start } from "@intelli-1113/stratos-sdk";
158
+
159
+ start({
160
+ token: process.env.STRATOS_TOKEN,
161
+ url: process.env.STRATOS_URL, // optional
162
+ appName: "my-agent", // optional
163
+ model: "mistral-large-latest", // optional heartbeat metadata
164
+ tools: ["web_search"], // optional heartbeat metadata
165
+ framework: "vercel-ai", // optional override
166
+ heartbeatMs: 30000, // optional
167
+ });
168
+ ```
169
+
170
+ For Vercel AI with Option C, still prefer launching with `--import @intelli-1113/stratos-sdk/register` so the ESM loader is active, **or** call `start()` only after registering the loader yourself (Option A is simpler).
171
+
172
+ ---
173
+
174
+ ## What is supported
175
+
176
+ ### Auto-instrumented stacks (OpenLLMetry / Traceloop)
177
+
178
+ These emit rich LLM/tool spans **without** client telemetry flags, when the SDK loads **before** the library:
179
+
180
+ | Stack | Node support via this SDK | Notes |
181
+ |-------|---------------------------|--------|
182
+ | **LangChain.js** | Yes | Agents, tools, chat models |
183
+ | **LangGraph.js** | Yes | Same family as LangChain |
184
+ | **LlamaIndex.TS** | Yes | When package is present |
185
+ | **OpenAI SDK** (`openai`) | Yes | Chat/completions |
186
+ | **Anthropic SDK** | Yes | Messages API |
187
+ | **Google Generative AI / GenAI** | Yes | Direct Google SDKs |
188
+ | **AWS Bedrock** (SDK path) | Yes | Via Traceloop instrumentation |
189
+ | **Together AI** | Yes | Via Traceloop |
190
+ | **Vertex AI** | Yes | Via Traceloop |
191
+ | **Vercel AI SDK** (`ai`) | Yes (**Stratos-specific**) | See [below](#vercel-ai-sdk-important) — needs `--import` |
192
+
193
+ ### Model providers (examples)
194
+
195
+ Model choice is independent of framework. These are common pairs:
196
+
197
+ | Provider | Typical packages | Observed when |
198
+ |----------|------------------|---------------|
199
+ | OpenAI | `openai`, `@ai-sdk/openai`, LangChain OpenAI | Instrumented path or Vercel AI + Stratos loader |
200
+ | Anthropic | `@anthropic-ai/sdk`, `@ai-sdk/anthropic` | Same |
201
+ | Google / Gemini | `@google/generative-ai`, `@google/genai`, `@ai-sdk/google` | Same |
202
+ | Mistral | `@ai-sdk/mistral`, `@langchain/mistralai` | Same |
203
+ | Azure OpenAI / Bedrock | respective SDKs or LangChain | Via instrumented SDKs / LangChain |
204
+
205
+ ### Not automatic (needs extra work or different product path)
206
+
207
+ | Approach | Why |
208
+ |----------|-----|
209
+ | Raw `fetch` to LLM HTTP APIs | Nothing to patch |
210
+ | Custom agent runtimes with no OTel | No spans unless you emit OTLP yourself |
211
+ | Python agents | Use the **Python** Stratos / OpenLLMetry package if provided (this package is **Node**) |
212
+ | Frameworks without OpenLLMetry support | May only show heartbeat until support is added |
213
+
214
+ ### Heartbeat-only vs full traces
215
+
216
+ | You see in Stratos | Meaning |
217
+ |--------------------|---------|
218
+ | Agent **online**, little detail | Heartbeat works; few/no LLM spans |
219
+ | Model, tokens, tools, prompts | Spans reached `/api/ingest` |
220
+
221
+ ---
222
+
223
+ ## LangChain version inspect & fix
224
+
225
+ Stratos LangChain **metrics** need:
226
+
227
+ ```text
228
+ @langchain/core >= 1.0.0 and < 2.0.0
229
+ ```
230
+
231
+ (from `@traceloop/instrumentation-langchain`, e.g. `^1.2.4` works).
232
+
233
+ Installing the SDK **does not** auto-upgrade the client’s LangChain 0.x app.
234
+ Use **`stratos-inspect`** in the **client project** to check and optionally fix.
235
+
236
+ ### Inspect only
237
+
238
+ ```bash
239
+ cd /path/to/client-agent
240
+ npx stratos-inspect
241
+ ```
242
+
243
+ JSON:
244
+
245
+ ```bash
246
+ npx stratos-inspect --json
247
+ ```
248
+
249
+ ### Uninstall old LangChain (&lt;1.0) and install 1.x
250
+
251
+ Interactive (asks y/N):
252
+
253
+ ```bash
254
+ npx stratos-inspect --fix
255
+ ```
256
+
257
+ Non-interactive (CI / scripts):
258
+
259
+ ```bash
260
+ npx stratos-inspect --fix --yes
261
+ ```
262
+
263
+ Dry run (show plan only):
264
+
265
+ ```bash
266
+ npx stratos-inspect --fix --dry-run
267
+ ```
268
+
269
+ What `--fix` does:
270
+
271
+ 1. Detects LangChain family packages in the project
272
+ 2. If `@langchain/core` is **&lt; 1.0** → uninstalls those packages
273
+ 3. Installs recommended **1.x** set (`@langchain/core@^1.2.4`, `langchain@^1.5.4`, plus any previous `@langchain/*` providers at `^1`)
274
+ 4. Uses npm / pnpm / yarn / bun based on lockfile
275
+
276
+ It will **not** auto-downgrade core **≥ 2.0**.
277
+
278
+ ### After install of Stratos
279
+
280
+ `postinstall` prints a warning if LangChain is present but incompatible (does **not** change deps).
281
+
282
+ At runtime, `start()` / `register` also warns and suggests `npx stratos-inspect --fix`.
283
+
284
+ Hard-fail on start if desired:
285
+
286
+ ---
287
+
288
+
289
+ ### What the SDK does for Vercel AI
290
+
291
+ 1. Registers a Node **custom module loader** on `register`
292
+ 2. Intercepts bare imports of `"ai"`
293
+ 3. Re-exports the real package
294
+ 4. Wraps `generateText`, `streamText`, `generateObject`, `streamObject`, `embed`, `embedMany`, and related helpers
295
+ 5. Injects telemetry defaults (`experimental_telemetry` / `telemetry`)
296
+
297
+ ### Client code (unchanged)
298
+
299
+ ```js
300
+ import { generateText, stepCountIs } from "ai";
301
+ import { openai } from "@ai-sdk/openai";
302
+ // import { mistral } from "@ai-sdk/mistral";
303
+ // import { google } from "@ai-sdk/google";
304
+
305
+ await generateText({
306
+ model: openai("gpt-4o"),
307
+ prompt: "Summarize today's agenda",
308
+ tools: { /* ... */ },
309
+ stopWhen: stepCountIs(5),
310
+ });
311
+ ```
312
+
313
+ ### How the client starts the process
314
+
315
+ ```bash
316
+ node --import @intelli-1113/stratos-sdk/register app.js
317
+ ```
318
+
319
+ ### Opt-out
320
+
321
+ | Goal | Setting |
322
+ |------|---------|
323
+ | Disable Vercel AI wrapping entirely | `STRATOS_VERCEL_AI=0` |
324
+ | Do not record prompts | `STRATOS_RECORD_INPUTS=0` |
325
+ | Do not record completions | `STRATOS_RECORD_OUTPUTS=0` |
326
+ | Disable one call only | Pass `experimental_telemetry: { isEnabled: false }` (or `telemetry: { isEnabled: false }` on AI SDK v7) |
327
+
328
+ ### AI SDK v7
329
+
330
+ If the app also installs `@ai-sdk/otel`, the SDK will try `registerTelemetry(new OpenTelemetry())` when available. The loader-based wrap still covers v5/v6-style `experimental_telemetry`.
331
+
332
+ ---
333
+
334
+ ## Environment reference
335
+
336
+ ### Core
337
+
338
+ | Variable | Required | Default | Description |
339
+ |----------|----------|---------|-------------|
340
+ | `STRATOS_TOKEN` | **Yes** | — | Enrollment token from Stratos → Add agent |
341
+ | `STRATOS_URL` | No | `http://localhost:4000` | Stratos origin (no trailing slash required) |
342
+ | `STRATOS_APP_NAME` | No | `npm_package_name` or `"agent"` | Display name / `service.name` |
343
+ | `STRATOS_HEARTBEAT_MS` | No | `30000` | Heartbeat interval (ms). `0` disables interval |
344
+
345
+ ### Metadata overrides
346
+
347
+ | Variable | Description |
348
+ |----------|-------------|
349
+ | `STRATOS_FRAMEWORK` | Force framework label (`langchain`, `vercel-ai`, `langgraph`, …) |
350
+ | `STRATOS_MODEL` | Preferred model label for heartbeat |
351
+ | `NVIDIA_MODEL` / `OPENAI_MODEL` / `ANTHROPIC_MODEL` / `GEMINI_MODEL` / `GOOGLE_MODEL` / `LLM_MODEL` / `MODEL` | Fallback model detection for heartbeat |
352
+ | `STRATOS_TOOLS` | Comma-separated tool names for heartbeat (`web_search,retriever`) |
353
+ | `STRATOS_FUNCTION_ID` | Default `functionId` on injected Vercel AI telemetry |
354
+ | `STRATOS_STRICT_LANGCHAIN` | Set `1` to throw on start if LangChain core is &lt; 1.0 |
355
+ | `STRATOS_SKIP_POSTINSTALL` | Set `1` to skip postinstall LangChain warning |
356
+
357
+ ### Vercel AI controls
358
+
359
+ | Variable | Default | Description |
360
+ |----------|---------|-------------|
361
+ | `STRATOS_VERCEL_AI` | on | Set `0` / `false` / `off` to disable auto wrap |
362
+ | `STRATOS_RECORD_INPUTS` | on | Set `0` to skip recording prompts |
363
+ | `STRATOS_RECORD_OUTPUTS` | on | Set `0` to skip recording outputs |
364
+
365
+ ---
366
+
367
+ ## Auto-detected metadata
368
+
369
+ On each heartbeat the SDK POSTs JSON to `{STRATOS_URL}/api/heartbeat` with:
370
+
371
+ | Field | Source |
372
+ |-------|--------|
373
+ | **framework** | `package.json` deps / resolution, or `STRATOS_FRAMEWORK` |
374
+ | **model** | Env vars above or `start({ model })` |
375
+ | **tools** | `STRATOS_TOOLS` or `start({ tools })` (spans refine tools over time) |
376
+
377
+ Detection order for framework (first match wins, unless overridden):
378
+
379
+ 1. Google ADK
380
+ 2. OpenAI Agents
381
+ 3. LlamaIndex
382
+ 4. CrewAI
383
+ 5. LangGraph
384
+ 6. LangChain
385
+ 7. Vercel AI (`ai`)
386
+ 8. Google GenAI SDKs
387
+ 9. Anthropic SDK
388
+ 10. OpenAI SDK
389
+
390
+ > If a project installs **both** LangChain and Vercel AI, framework detection may prefer LangChain. Set `STRATOS_FRAMEWORK=vercel-ai` (or use separate apps/tokens) when needed.
391
+
392
+ ---
393
+
394
+ ## MCP proxy
395
+
396
+ Host-launched MCP servers (Claude Desktop, Cursor, VS Code, …) do not run your Node agent process. Use the bundled CLI to proxy **tool calls**:
397
+
398
+ ```bash
399
+ npm i -g @intelli-1113/stratos-sdk
400
+ ```
401
+
402
+ Host config example:
403
+
404
+ ```json
405
+ {
406
+ "mcpServers": {
407
+ "weather": {
408
+ "command": "stratos-mcp-proxy",
409
+ "args": ["--", "npx", "-y", "@scope/weather-mcp@latest"],
410
+ "env": {
411
+ "STRATOS_TOKEN": "<token>",
412
+ "STRATOS_URL": "http://localhost:4000",
413
+ "STRATOS_APP_NAME": "weather"
414
+ }
415
+ }
416
+ }
417
+ }
418
+ ```
419
+
420
+ | Behavior | Detail |
421
+ |----------|--------|
422
+ | Protocol | Forwards JSON-RPC stdio **verbatim** |
423
+ | Telemetry | Each `tools/call` → OTLP-like span on `/api/ingest` |
424
+ | Liveness | Heartbeat on `/api/heartbeat` |
425
+ | Logging | **stderr only** (stdout is reserved for MCP) |
426
+ | LLM tokens | **Not** captured (MCP servers usually don’t call the LLM) |
427
+
428
+ Usage:
429
+
430
+ ```bash
431
+ stratos-mcp-proxy -- <command> [args...]
432
+ ```
433
+
434
+ ---
435
+
436
+ ## How it works
437
+
438
+ ```text
439
+ ┌─────────────────────┐
440
+ │ Your agent process │
441
+ │ (Node.js) │
442
+ └──────────┬──────────┘
443
+ │ 1. --import register
444
+ ▼
445
+ ┌─────────────────────┐
446
+ │ stratos-sdk │
447
+ │ • load .env │
448
+ │ • Vercel AI loader │
449
+ │ • Traceloop init │
450
+ │ • OTLP JSON export │
451
+ │ • heartbeat loop │
452
+ └──────────┬──────────┘
453
+ │
454
+ ├─ POST /api/ingest (spans: LLM + tools)
455
+ └─ POST /api/heartbeat (online + metadata)
456
+ │
457
+ ▼
458
+ ┌───────────────┐
459
+ │ Stratos AI │
460
+ │ :4000 UI │
461
+ └───────────────┘
462
+ ```
463
+
464
+ - **LangChain / OpenAI / …** → Traceloop instrumentations create spans.
465
+ - **Vercel AI** → Stratos loader injects telemetry so the `ai` package creates OTel spans; Traceloop exports them.
466
+ - **MCP** → `stratos-mcp-proxy` synthesizes tool spans.
467
+
468
+ ---
469
+
470
+ ## Troubleshooting
471
+
472
+ | Symptom | Likely cause | Fix |
473
+ |---------|--------------|-----|
474
+ | `[stratos] STRATOS_TOKEN not set` | Token missing at process start | Set `STRATOS_TOKEN` or put it in `.env` in `cwd` |
475
+ | Agent online, no tokens/tools | Framework not instrumented or Vercel AI without `--import` | Use `--import …/register`; confirm stack is supported |
476
+ | Vercel AI still no spans | Started without `--import` | `node --import @intelli-1113/stratos-sdk/register app.js` |
477
+ | Wrong framework label | Mixed deps in one `package.json` | Set `STRATOS_FRAMEWORK=vercel-ai` (or `langchain`) |
478
+ | Spans lost on short CLI scripts | Process exited before flush | SDK flushes on `beforeExit` / signals; keep process alive until request finishes |
479
+ | MCP tools not showing | Proxy not wrapping command / no token | Use `stratos-mcp-proxy -- …` and set env on the host config |
480
+ | Local Stratos empty | Wrong URL | Default is `http://localhost:4000`; ensure Stratos is running |
481
+
482
+ Verify the SDK loaded:
483
+
484
+ ```text
485
+ [stratos] telemetry → http://localhost:4000/api/ingest (heartbeat 30000ms, framework=…)
486
+ [stratos] vercel-ai auto-telemetry: esm-loader-shim # when Vercel path is active
487
+ ```
488
+
489
+ ---
490
+
491
+ ## Security & privacy
492
+
493
+ - **Token** — treat `STRATOS_TOKEN` like a secret; do not commit it.
494
+ - **Prompts/outputs** — may be sent in spans. Disable with:
495
+ - `STRATOS_RECORD_INPUTS=0`
496
+ - `STRATOS_RECORD_OUTPUTS=0`
497
+ - **Network** — telemetry is sent to `STRATOS_URL` only.
498
+ - **MCP proxy** — tool args/results are reported; avoid secrets in tool arguments when possible.
499
+
500
+ ---
501
+
502
+ ### Entry points
503
+
504
+ | Import | Purpose |
505
+ |--------|---------|
506
+ | `@intelli-1113/stratos-sdk/register` | Side-effect: env + Vercel loader + `start()` |
507
+ | `@intelli-1113/stratos-sdk` | `{ start }` for programmatic use |
508
+
509
+ ### CLI
510
+
511
+ | Command | Purpose |
512
+ |---------|---------|
513
+ | `stratos-inspect` | Check LangChain compatibility in current project |
514
+ | `stratos-inspect --fix [--yes]` | Uninstall old LangChain and install 1.x |
515
+ | `stratos-mcp-proxy -- <cmd> [args…]` | MCP stdio proxy with tool telemetry |
516
+
517
+ ### `inspectLangChain()` / `fixLangChain()`
518
+
519
+ See [LangChain version inspect & fix](#langchain-version-inspect--fix).
520
+
521
+ ---
522
+
523
+ ## Requirements
524
+
525
+ - **Node.js** 18+ (20+ recommended; `.env` via `process.loadEnvFile` when available)
526
+ - Network reachability to Stratos (`STRATOS_URL`)
527
+ - Valid **STRATOS_TOKEN** from the Stratos UI
528
+
529
+ ---
530
+
531
+ ## License
532
+
533
+ MIT
534
+
535
+ ---
536
+
537
+ ## Changelog (recent)
538
+
539
+ ### 1.3.1
540
+
541
+ - **`stratos-inspect`** CLI: check LangChain core version; optional `--fix` uninstall old + install 1.x
542
+ - **postinstall** warning if LangChain &lt; 1.0
543
+ - Runtime warning on `start()`; optional `STRATOS_STRICT_LANGCHAIN=1`
544
+ - Exports: `inspectLangChain`, `fixLangChain`
545
+
546
+ ### 1.3.0
547
+
548
+ - Auto Vercel AI SDK telemetry via ESM module loader (no client `experimental_telemetry`)
549
+ - Load `.env` from `cwd` when using `--import`
550
+ - Document `--import` as the recommended zero-code entry
551
+ - Framework / model / tools heartbeat metadata retained
552
+ - MCP proxy unchanged in purpose (`stratos-mcp-proxy`)
package/package.json CHANGED
@@ -1,22 +1,41 @@
1
- {
2
- "name": "@intelli-1113/stratos-sdk",
3
- "version": "1.2.2",
4
- "description": "One install for Stratos AI: OpenLLMetry agent telemetry (--import) AND the stratos-mcp-proxy for MCP servers.",
5
- "type": "module",
6
- "main": "./src/index.js",
7
- "exports": {
8
- ".": "./src/index.js",
9
- "./register": "./src/register.js"
10
- },
11
- "bin": { "stratos-mcp-proxy": "./src/mcp-proxy.js" },
12
- "files": ["src"],
13
- "scripts": {
14
- "test": "node -e \"import('./src/index.js').then(m=>console.log('ok',Object.keys(m)))\""
15
- },
16
- "keywords": ["stratos", "openllmetry", "opentelemetry", "observability", "llm", "agent"],
17
- "license": "MIT",
18
- "dependencies": {
19
- "@opentelemetry/exporter-trace-otlp-http": "^0.203.0",
20
- "@traceloop/node-server-sdk": "^0.27.0"
21
- }
22
- }
1
+ {
2
+ "name": "@intelli-1113/stratos-sdk",
3
+ "version": "1.3.1",
4
+ "description": "Stratos AI agent telemetry (OpenLLMetry), Vercel AI auto-spans, LangChain inspect/fix, MCP proxy.",
5
+ "type": "module",
6
+ "main": "./src/index.js",
7
+ "exports": {
8
+ ".": "./src/index.js",
9
+ "./register": "./src/register.js",
10
+ "./inspect": "./src/inspect-langchain.js"
11
+ },
12
+ "bin": {
13
+ "stratos-mcp-proxy": "./src/mcp-proxy.js",
14
+ "stratos-inspect": "./src/cli-inspect.js"
15
+ },
16
+ "files": [
17
+ "src"
18
+ ],
19
+ "scripts": {
20
+ "postinstall": "node ./src/postinstall.js",
21
+ "test": "node -e \"import('./src/index.js').then(m=>console.log('ok',Object.keys(m)))\"",
22
+ "inspect": "node ./src/cli-inspect.js"
23
+ },
24
+ "keywords": [
25
+ "stratos",
26
+ "openllmetry",
27
+ "opentelemetry",
28
+ "observability",
29
+ "llm",
30
+ "agent",
31
+ "vercel-ai",
32
+ "langchain"
33
+ ],
34
+ "license": "MIT",
35
+ "dependencies": {
36
+ "@opentelemetry/exporter-trace-otlp-http": "^0.203.0",
37
+ "@traceloop/node-server-sdk": "^0.27.0",
38
+ "import-in-the-middle": "^1.15.0",
39
+ "require-in-the-middle": "^7.5.2"
40
+ }
41
+ }