@intelli-1113/stratos-sdk 1.2.2 → 1.3.1

package/src/cli-inspect.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/**
+ * stratos-inspect — check LangChain version compatibility for Stratos metrics.
+ *
+ *   npx stratos-inspect
+ *   npx stratos-inspect --json
+ *   npx stratos-inspect --fix
+ *   npx stratos-inspect --fix --yes
+ *   npx stratos-inspect --fix --dry-run
+ */
+
+import {
+  inspectLangChain,
+  fixLangChain,
+  printInspectReport,
+} from "./inspect-langchain.js";
+
+function parseArgs(argv) {
+  const flags = new Set(argv);
+  return {
+    json: flags.has("--json"),
+    fix: flags.has("--fix") || flags.has("--repair"),
+    yes: flags.has("--yes") || flags.has("-y"),
+    dryRun: flags.has("--dry-run"),
+    help: flags.has("--help") || flags.has("-h"),
+  };
+}
+
+function printHelp() {
+  console.log(`
+stratos-inspect — LangChain compatibility for @intelli-1113/stratos-sdk
+
+Usage:
+  stratos-inspect                 Inspect current project (cwd)
+  stratos-inspect --json          Machine-readable report
+  stratos-inspect --fix           Uninstall old LangChain (<1.0) and install 1.x
+  stratos-inspect --fix --yes     Same, no confirmation prompt
+  stratos-inspect --fix --dry-run Show plan only
+
+Why:
+  Stratos LangChain metrics need @langchain/core >=1.0.0 <2.0.0
+  (OpenLLMetry / @traceloop/instrumentation-langchain peer range).
+
+Exit codes:
+  0  compatible (or no LangChain) / fix succeeded
+  1  incompatible or fix failed / cancelled
+`);
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  const report = inspectLangChain();
+
+  if (!opts.fix) {
+    printInspectReport(report, { json: opts.json });
+    process.exit(report.compatible ? 0 : 1);
+  }
+
+  if (!opts.json) {
+    printInspectReport(report, { json: false });
+  }
+
+  const result = await fixLangChain({
+    yes: opts.yes,
+    dryRun: opts.dryRun,
+  });
+
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (result.dryRun) {
+    console.log("[stratos-inspect] Dry run plan:");
+    console.log(JSON.stringify(result.plan, null, 2));
+  } else if (result.cancelled) {
+    console.log("[stratos-inspect] Cancelled — no changes made.");
+  } else if (result.skipped) {
+    console.log(`[stratos-inspect] Skipped (${result.reason}). ${result.message || ""}`);
+  } else if (result.ok) {
+    console.log("[stratos-inspect] Done. LangChain should now be on 1.x.");
+    if (result.reportAfter) printInspectReport(result.reportAfter);
+  } else {
+    console.error(`[stratos-inspect] Fix failed: ${result.message || result.step || "unknown"}`);
+  }
+
+  process.exit(result.ok || result.skipped ? 0 : 1);
+}
+
+main().catch((err) => {
+  console.error("[stratos-inspect]", err);
+  process.exit(1);
+});

package/src/index.js

@@ -1,38 +1,57 @@
 // @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)
+// Config (environment):
+//   STRATOS_TOKEN      enrollment token from Stratos "Add agent"   (required)
+//   STRATOS_URL        Stratos origin (default http://localhost:4000)
+//   STRATOS_APP_NAME   display name for this agent                 (optional)
+//   STRATOS_VERCEL_AI  set 0 to disable auto Vercel AI patching    (default on)
+//   STRATOS_FRAMEWORK  override auto framework detection           (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.
+// Vercel AI: clients only need this register entry (or --import). No
+// experimental_telemetry in their generateText/streamText calls.
 import * as traceloop from "@traceloop/node-server-sdk";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
 import { createRequire } from "node:module";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
+import { enableVercelAiTelemetry } from "./vercel-ai.js";
+import { inspectLangChain } from "./inspect-langchain.js";
+
+export { inspectLangChain, fixLangChain } from "./inspect-langchain.js";
 
 const _require = createRequire(import.meta.url);
-const resolvable = (pkg) => { try { _require.resolve(pkg); return true; } catch { return false; } };
+const resolvable = (pkg) => {
+  try {
+    _require.resolve(pkg);
+    return true;
+  } catch {
+    return false;
+  }
+};
+const resolvableFromCwd = (pkg) => {
+  try {
+    createRequire(join(process.cwd(), "package.json")).resolve(pkg);
+    return true;
+  } catch {
+    return false;
+  }
+};
 
-// The agent's DIRECT dependencies (most reliable signal of the framework in use).
-// Resolution alone is unreliable — some packages (e.g. @google/adk) block default
-// resolution via "exports", and others appear only transitively.
 function agentDeps() {
   try {
-    const pkg = JSON.parse(readFileSync(join(process.cwd(), "package.json"), "utf8"));
+    const pkg = JSON.parse(
+      readFileSync(join(process.cwd(), "package.json"), "utf8")
+    );
     return { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
-  } catch { return {}; }
+  } catch {
+    return {};
+  }
 }
 
-// Detect the agent framework from declared deps (preferred) or resolution — no manual input.
 function detectFramework() {
+  if (process.env.STRATOS_FRAMEWORK) return process.env.STRATOS_FRAMEWORK;
   const deps = agentDeps();
-  const has = (n) => n in deps || resolvable(n);
-  // Higher-level agent frameworks FIRST (several pull in @langchain/* transitively).
+  const has = (n) => n in deps || resolvableFromCwd(n) || resolvable(n);
   if (has("@google/adk") || has("google-adk") || has("@iqai/adk")) return "google-adk";
   if (has("@openai/agents")) return "openai-agents";
   if (has("llamaindex")) return "llamaindex";
@@ -45,23 +64,44 @@ function detectFramework() {
   if (has("openai")) return "openai";
   return null;
 }
-// Best-effort model from common env vars (or opts.model). Spans still refine it.
+
 function detectModel(opts) {
-  return opts.model || process.env.STRATOS_MODEL || process.env.NVIDIA_MODEL || process.env.OPENAI_MODEL
-    || process.env.ANTHROPIC_MODEL || process.env.LLM_MODEL || process.env.MODEL || null;
+  return (
+    opts.model ||
+    process.env.STRATOS_MODEL ||
+    process.env.NVIDIA_MODEL ||
+    process.env.OPENAI_MODEL ||
+    process.env.ANTHROPIC_MODEL ||
+    process.env.GEMINI_MODEL ||
+    process.env.GOOGLE_MODEL ||
+    process.env.LLM_MODEL ||
+    process.env.MODEL ||
+    null
+  );
 }
 
 let started = false;
 
 export function start(opts = {}) {
-  if (started) return; // idempotent — safe to import/register more than once
+  if (started) return;
   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);
+  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.");
+    console.warn(
+      "[stratos] STRATOS_TOKEN not set — telemetry disabled. Add the token from Stratos > Add agent."
+    );
     return;
   }
   started = true;
@@ -72,26 +112,74 @@ export function start(opts = {}) {
   traceloop.initialize({
     appName,
     disableBatch: true,
-    exporter: new OTLPTraceExporter({ url: ingest, headers: { "x-stratos-token": token } }),
+    exporter: new OTLPTraceExporter({
+      url: ingest,
+      headers: { "x-stratos-token": token },
+    }),
   });
 
-  // Auto-detected metadata sent on every heartbeat → Stratos auto-fills the
-  // agent's framework/model/tools (no manual entry, no reliance on span quality).
-  const toolsEnv = (opts.tools || (process.env.STRATOS_TOOLS || "").split(",")).map((s) => String(s).trim()).filter(Boolean);
-  const meta = { framework: detectFramework(), model: detectModel(opts), tools: toolsEnv };
+  // LangChain version check (warn only — fix via: npx stratos-inspect --fix)
+  try {
+    const lc = inspectLangChain();
+    if (lc.hasLangChain && lc.needsAttention) {
+      console.warn(`[stratos] ${lc.message}`);
+      console.warn("[stratos] Fix: npx stratos-inspect --fix");
+      if (process.env.STRATOS_STRICT_LANGCHAIN === "1" && lc.needsUpgrade) {
+        throw new Error(
+          "Incompatible @langchain/core (<1.0). Upgrade with: npx stratos-inspect --fix --yes"
+        );
+      }
+    }
+  } catch (err) {
+    if (process.env.STRATOS_STRICT_LANGCHAIN === "1") throw err;
+  }
+
+  // Vercel AI v7 optional global register; v5/v6 covered by ESM loader in register.js
+  enableVercelAiTelemetry()
+    .then((r) => {
+      if (r.enabled) {
+        console.log(`[stratos] vercel-ai auto-telemetry: ${r.mode}`);
+      }
+    })
+    .catch(() => {});
+
+  const toolsEnv = (
+    opts.tools ||
+    (process.env.STRATOS_TOOLS || "").split(",")
+  )
+    .map((s) => String(s).trim())
+    .filter(Boolean);
+
+  const meta = {
+    framework: opts.framework || detectFramework(),
+    model: detectModel(opts),
+    tools: toolsEnv,
+  };
 
-  // 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, "Content-Type": "application/json" },
+      headers: {
+        "x-stratos-token": token,
+        "Content-Type": "application/json",
+      },
       body: JSON.stringify(meta),
     }).catch(() => {});
   ping();
   if (heartbeatMs > 0) setInterval(ping, heartbeatMs).unref();
 
-  console.log(`[stratos] telemetry → ${ingest} (heartbeat ${heartbeatMs}ms, framework=${meta.framework || "?"})`);
+  process.on("beforeExit", () => {
+    traceloop.forceFlush().catch(() => {});
+  });
+  for (const sig of ["SIGINT", "SIGTERM"]) {
+    process.on(sig, () => {
+      traceloop.forceFlush().finally(() => process.exit(0));
+    });
+  }
+
+  console.log(
+    `[stratos] telemetry → ${ingest} (heartbeat ${heartbeatMs}ms, framework=${meta.framework || "?"})`
+  );
 }
 
 export default { start };