@intelli-1113/stratos-sdk 1.0.0

package/README.md

@@ -0,0 +1,39 @@
+# @intelli-1113/stratos-sdk
+
+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.
+
+## Install
+```bash
+npm i @intelli-1113/stratos-sdk
+```
+
+## Configure (environment)
+```bash
+STRATOS_TOKEN=<token from Stratos → Add agent>   # required
+STRATOS_URL=https://stratos.lnt.com              # optional, default http://localhost:4000
+STRATOS_APP_NAME=my-agent                         # optional display name
+```
+
+## Use — pick one
+
+**Zero code changes** (recommended) — load before your app via Node's `--import`:
+```bash
+node --import @intelli-1113/stratos-sdk/register server.js
+```
+
+**One line** — must be the FIRST import in your entrypoint (before `openai`/`langchain`/etc.):
+```js
+import "@intelli-1113/stratos-sdk/register";
+```
+
+**Programmatic** — if you want to pass config explicitly:
+```js
+import { start } from "@intelli-1113/stratos-sdk";
+start({ token: "...", url: "https://stratos.lnt.com", appName: "my-agent" });
+```
+
+## Why it must load first
+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.
+
+## Changing the URL or token
+Both come from env, read at startup — change the `.env` value and restart. No code edit, no SDK re-publish.

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@intelli-1113/stratos-sdk",
+  "version": "1.0.0",
+  "description": "One-line OpenLLMetry telemetry for Stratos AI — agent liveness, tokens, cost, prompts and tools.",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./register": "./src/register.js"
+  },
+  "files": ["src"],
+  "scripts": {
+    "test": "node -e \"import('./src/index.js').then(m=>console.log('ok',Object.keys(m)))\""
+  },
+  "keywords": ["stratos", "openllmetry", "opentelemetry", "observability", "llm", "agent"],
+  "license": "MIT",
+  "dependencies": {
+    "@opentelemetry/exporter-trace-otlp-http": "^0.203.0",
+    "@traceloop/node-server-sdk": "^0.27.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,49 @@
+// @intelli-1113/stratos-sdk — initialize OpenLLMetry and stream telemetry to Stratos AI.
+//
+// Config comes from the environment (so the ingest URL / token can change
+// without editing code or re-publishing the SDK):
+//   STRATOS_TOKEN     enrollment token from Stratos "Add agent"   (required)
+//   STRATOS_URL       Stratos origin, e.g. https://stratos.lnt.com (default http://localhost:4000)
+//   STRATOS_APP_NAME  display name for this agent                 (optional)
+//
+// Why this exists: traceloop defaults to OTLP *protobuf* at <baseUrl>/v1/traces;
+// Stratos ingests OTLP *JSON* at /api/ingest. This wires a JSON exporter to the
+// right URL and runs a heartbeat so the agent shows online while it's up.
+import * as traceloop from "@traceloop/node-server-sdk";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+
+let started = false;
+
+export function start(opts = {}) {
+  if (started) return; // idempotent — safe to import/register more than once
+  const token = opts.token || process.env.STRATOS_TOKEN || "";
+  const origin = (opts.url || process.env.STRATOS_URL || "http://localhost:4000").replace(/\/+$/, "");
+  const appName = opts.appName || process.env.STRATOS_APP_NAME || process.env.npm_package_name || "agent";
+  const heartbeatMs = Number(opts.heartbeatMs || process.env.STRATOS_HEARTBEAT_MS || 30000);
+
+  if (!token) {
+    console.warn("[stratos] STRATOS_TOKEN not set — telemetry disabled. Add the token from Stratos > Add agent.");
+    return;
+  }
+  started = true;
+
+  const ingest = `${origin}/api/ingest`;
+  const heartbeatUrl = `${origin}/api/heartbeat`;
+
+  traceloop.initialize({
+    appName,
+    disableBatch: true,
+    exporter: new OTLPTraceExporter({ url: ingest, headers: { "x-stratos-token": token } }),
+  });
+
+  // Keep the agent "online" while the process is alive (telemetry alone only
+  // fires on LLM calls, which would let liveness lapse between requests).
+  const ping = () =>
+    fetch(heartbeatUrl, { method: "POST", headers: { "x-stratos-token": token } }).catch(() => {});
+  ping();
+  if (heartbeatMs > 0) setInterval(ping, heartbeatMs).unref();
+
+  console.log(`[stratos] telemetry → ${ingest} (heartbeat ${heartbeatMs}ms)`);
+}
+
+export default { start };

package/src/register.js

@@ -0,0 +1,5 @@
+// Side-effect entry so telemetry starts before your app code loads.
+//   node --import @intelli-1113/stratos-sdk/register server.js   (zero code changes)
+//   import "@intelli-1113/stratos-sdk/register";                 (first line of entrypoint)
+import { start } from "./index.js";
+start();