@intelli-1113/stratos-sdk 1.2.3 → 1.3.1

package/src/inspect-langchain.js

@@ -0,0 +1,428 @@
+// LangChain / Stratos compatibility inspect + optional fix (client project cwd).
+//
+// Traceloop instrumentation peer (via @traceloop/instrumentation-langchain):
+//   @langchain/core >=1.0.0 <2.0.0
+//
+// Usage (CLI):
+//   npx stratos-inspect
+//   npx stratos-inspect --fix
+//   npx stratos-inspect --fix --yes
+
+import { createRequire } from "node:module";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { createInterface } from "node:readline";
+
+/** Peer range of @traceloop/instrumentation-langchain@0.27 */
+export const LANGCHAIN_CORE_RANGE = {
+  minInclusive: "1.0.0",
+  maxExclusive: "2.0.0",
+  npmInstall: "@langchain/core@^1.2.4",
+};
+
+/** Packages we may touch when --fix is used (only if present / related). */
+export const LANGCHAIN_FAMILY = [
+  "langchain",
+  "@langchain/core",
+  "@langchain/community",
+  "@langchain/openai",
+  "@langchain/anthropic",
+  "@langchain/mistralai",
+  "@langchain/google-genai",
+  "@langchain/google-vertexai",
+  "@langchain/tavily",
+  "@langchain/langgraph",
+  "@langchain/langgraph-checkpoint",
+  "@langchain/classic",
+  "@langchain/textsplitters",
+];
+
+/** Safe 1.x installs for a typical Stratos + LangChain agent. */
+export const RECOMMENDED_INSTALL = [
+  "@langchain/core@^1.2.4",
+  "langchain@^1.5.4",
+];
+
+function parseSemver(v) {
+  if (!v || typeof v !== "string") return null;
+  const cleaned = v.replace(/^[=v^~<>]*/, "").split("-")[0].trim();
+  const m = cleaned.match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!m) {
+    // package.json range like "^0.3.0" → take first numbers
+    const m2 = v.match(/(\d+)\.(\d+)\.(\d+)/) || v.match(/(\d+)\.(\d+)/);
+    if (!m2) return null;
+    return {
+      major: Number(m2[1]),
+      minor: Number(m2[2]),
+      patch: Number(m2[3] || 0),
+      raw: v,
+    };
+  }
+  return {
+    major: Number(m[1]),
+    minor: Number(m[2]),
+    patch: Number(m[3]),
+    raw: v,
+  };
+}
+
+function cmp(a, b) {
+  if (a.major !== b.major) return a.major - b.major;
+  if (a.minor !== b.minor) return a.minor - b.minor;
+  return a.patch - b.patch;
+}
+
+/**
+ * @returns {"ok"|"too_old"|"too_new"|"unknown"|"absent"}
+ */
+export function classifyCoreVersion(versionStr) {
+  if (!versionStr) return "absent";
+  const v = parseSemver(versionStr);
+  if (!v) return "unknown";
+  const min = parseSemver(LANGCHAIN_CORE_RANGE.minInclusive);
+  const max = parseSemver(LANGCHAIN_CORE_RANGE.maxExclusive);
+  if (cmp(v, min) < 0) return "too_old";
+  if (cmp(v, max) >= 0) return "too_new";
+  return "ok";
+}
+
+function readPkgJson(cwd) {
+  const p = join(cwd, "package.json");
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function declaredDeps(pkg) {
+  return {
+    ...(pkg?.dependencies || {}),
+    ...(pkg?.devDependencies || {}),
+    ...(pkg?.optionalDependencies || {}),
+  };
+}
+
+function resolveInstalledVersion(cwd, name) {
+  try {
+    const req = createRequire(join(cwd, "package.json"));
+    const pkgPath = req.resolve(`${name}/package.json`);
+    const meta = JSON.parse(readFileSync(pkgPath, "utf8"));
+    return { version: meta.version, path: pkgPath };
+  } catch {
+    return null;
+  }
+}
+
+function detectPackageManager(cwd) {
+  if (existsSync(join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(join(cwd, "yarn.lock"))) return "yarn";
+  if (existsSync(join(cwd, "bun.lockb")) || existsSync(join(cwd, "bun.lock")))
+    return "bun";
+  return "npm";
+}
+
+/**
+ * Inspect LangChain compatibility for a project directory (default: cwd).
+ * @param {{ cwd?: string }} [opts]
+ */
+export function inspectLangChain(opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const pkg = readPkgJson(cwd);
+  const declared = pkg ? declaredDeps(pkg) : {};
+
+  const found = [];
+  for (const name of LANGCHAIN_FAMILY) {
+    const declaredRange = declared[name] || null;
+    const installed = resolveInstalledVersion(cwd, name);
+    if (!declaredRange && !installed) continue;
+    found.push({
+      name,
+      declared: declaredRange,
+      installed: installed?.version || null,
+      installPath: installed?.path || null,
+    });
+  }
+
+  const core =
+    found.find((f) => f.name === "@langchain/core") ||
+    (declared["@langchain/core"]
+      ? {
+          name: "@langchain/core",
+          declared: declared["@langchain/core"],
+          installed: null,
+          installPath: null,
+        }
+      : null);
+
+  const coreVersion = core?.installed || core?.declared || null;
+  const status = core
+    ? classifyCoreVersion(core?.installed || core?.declared)
+    : found.length
+      ? "unknown"
+      : "absent";
+
+  const compatible = status === "ok" || status === "absent";
+  // absent = no LangChain → Stratos still fine (other frameworks)
+  // too_old / too_new / unknown with langchain present → problem for LC metrics
+
+  const hasLangChain = found.length > 0 || !!core;
+  const needsUpgrade = status === "too_old";
+  const needsAttention = status === "too_old" || status === "too_new";
+
+  return {
+    cwd,
+    packageManager: detectPackageManager(cwd),
+    hasLangChain,
+    status,
+    compatible: !hasLangChain || status === "ok",
+    needsUpgrade,
+    needsAttention,
+    core: core
+      ? {
+          declared: core.declared,
+          installed: core.installed,
+          versionForCheck: coreVersion,
+          status,
+        }
+      : null,
+    packages: found,
+    required: {
+      peer: `@langchain/core >=${LANGCHAIN_CORE_RANGE.minInclusive} <${LANGCHAIN_CORE_RANGE.maxExclusive}`,
+      recommendedInstall: RECOMMENDED_INSTALL,
+    },
+    message: buildMessage(status, hasLangChain, coreVersion),
+  };
+}
+
+function buildMessage(status, hasLangChain, coreVersion) {
+  if (!hasLangChain || status === "absent") {
+    return "No LangChain packages found — nothing to upgrade for LangChain metrics.";
+  }
+  if (status === "ok") {
+    return `@langchain/core@${coreVersion} is compatible with Stratos LangChain auto-instrumentation.`;
+  }
+  if (status === "too_old") {
+    return (
+      `@langchain/core@${coreVersion} is too old for Stratos LangChain metrics. ` +
+      `Required: >=1.0.0 <2.0.0. Uninstall old LangChain packages, then install 1.x.`
+    );
+  }
+  if (status === "too_new") {
+    return (
+      `@langchain/core@${coreVersion} is newer than the current OpenLLMetry peer range (<2.0.0). ` +
+      `LangChain metrics may not work until Stratos/Traceloop supports core 2.x.`
+    );
+  }
+  return `Could not parse @langchain/core version (${coreVersion}). Expected >=1.0.0 <2.0.0.`;
+}
+
+function runPm(pm, args, cwd) {
+  const cmd = pm === "npm" ? "npm" : pm;
+  const result = spawnSync(cmd, args, {
+    cwd,
+    stdio: "inherit",
+    shell: process.platform === "win32",
+    env: process.env,
+  });
+  return result.status === 0;
+}
+
+/**
+ * Uninstall detected LangChain family packages, then install recommended 1.x set
+ * (+ re-install any previously present family packages at ^1 if they were there).
+ *
+ * @param {{ cwd?: string, yes?: boolean, dryRun?: boolean }} [opts]
+ */
+export async function fixLangChain(opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const report = inspectLangChain({ cwd });
+  const pm = report.packageManager;
+
+  if (!report.hasLangChain) {
+    return {
+      ok: true,
+      skipped: true,
+      reason: "no-langchain",
+      report,
+    };
+  }
+
+  if (report.status === "ok") {
+    return {
+      ok: true,
+      skipped: true,
+      reason: "already-compatible",
+      report,
+    };
+  }
+
+  if (report.status === "too_new") {
+    return {
+      ok: false,
+      skipped: true,
+      reason: "too-new",
+      report,
+      message:
+        "Core is >=2.0.0 — automatic downgrade is not performed. Pin <2 or wait for SDK support.",
+    };
+  }
+
+  if (report.status !== "too_old" && report.status !== "unknown") {
+    return { ok: false, skipped: true, reason: report.status, report };
+  }
+
+  const toRemove = report.packages.map((p) => p.name);
+  // Also remove declared-only names
+  const pkg = readPkgJson(cwd);
+  const declared = pkg ? declaredDeps(pkg) : {};
+  for (const name of LANGCHAIN_FAMILY) {
+    if (declared[name] && !toRemove.includes(name)) toRemove.push(name);
+  }
+
+  // Reinstall: recommended base + any extra family packages client had, on ^1
+  const reinstall = new Set(RECOMMENDED_INSTALL);
+  for (const name of toRemove) {
+    if (name === "@langchain/core" || name === "langchain") continue;
+    // keep provider packages if they were present
+    if (report.packages.some((p) => p.name === name) || declared[name]) {
+      reinstall.add(`${name}@^1`);
+    }
+  }
+
+  const plan = {
+    packageManager: pm,
+    uninstall: toRemove,
+    install: [...reinstall],
+  };
+
+  if (opts.dryRun) {
+    return { ok: true, dryRun: true, plan, report };
+  }
+
+  if (!opts.yes) {
+    const confirmed = await confirm(
+      `\n[stratos-inspect] About to:\n` +
+        `  1) uninstall: ${toRemove.join(", ")}\n` +
+        `  2) install:   ${[...reinstall].join(", ")}\n` +
+        `in ${cwd}\n\nProceed? [y/N] `
+    );
+    if (!confirmed) {
+      return { ok: false, cancelled: true, plan, report };
+    }
+  }
+
+  console.log(`\n[stratos-inspect] Using package manager: ${pm}`);
+  console.log(`[stratos-inspect] Uninstalling old LangChain packages…`);
+
+  let uninstallOk = true;
+  if (toRemove.length) {
+    if (pm === "npm") {
+      uninstallOk = runPm("npm", ["uninstall", ...toRemove], cwd);
+    } else if (pm === "pnpm") {
+      uninstallOk = runPm("pnpm", ["remove", ...toRemove], cwd);
+    } else if (pm === "yarn") {
+      uninstallOk = runPm("yarn", ["remove", ...toRemove], cwd);
+    } else if (pm === "bun") {
+      uninstallOk = runPm("bun", ["remove", ...toRemove], cwd);
+    }
+  }
+
+  if (!uninstallOk) {
+    return {
+      ok: false,
+      step: "uninstall",
+      plan,
+      report,
+      message: "Uninstall failed — fix manually and re-run stratos-inspect --fix",
+    };
+  }
+
+  console.log(`[stratos-inspect] Installing LangChain 1.x packages…`);
+  const installList = [...reinstall];
+  let installOk = false;
+  if (pm === "npm") {
+    installOk = runPm("npm", ["install", ...installList], cwd);
+  } else if (pm === "pnpm") {
+    installOk = runPm("pnpm", ["add", ...installList], cwd);
+  } else if (pm === "yarn") {
+    installOk = runPm("yarn", ["add", ...installList], cwd);
+  } else if (pm === "bun") {
+    installOk = runPm("bun", ["add", ...installList], cwd);
+  }
+
+  const after = inspectLangChain({ cwd });
+  return {
+    ok: installOk && after.status === "ok",
+    step: "install",
+    plan,
+    reportBefore: report,
+    reportAfter: after,
+    message: after.message,
+  };
+}
+
+function confirm(question) {
+  if (!process.stdin.isTTY) {
+    console.warn(
+      "[stratos-inspect] Non-interactive terminal — pass --yes to apply fix, or run with a TTY."
+    );
+    return Promise.resolve(false);
+  }
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      const a = String(answer || "").trim().toLowerCase();
+      resolve(a === "y" || a === "yes");
+    });
+  });
+}
+
+/** Human-readable print for CLI / postinstall */
+export function printInspectReport(report, { json = false } = {}) {
+  if (json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  console.log("\n[stratos-inspect] LangChain compatibility");
+  console.log(`  project:  ${report.cwd}`);
+  console.log(`  pm:       ${report.packageManager}`);
+  console.log(`  status:   ${report.status}`);
+  console.log(`  required: ${report.required.peer}`);
+
+  if (report.core) {
+    console.log(
+      `  core:     installed=${report.core.installed || "—"}  declared=${report.core.declared || "—"}`
+    );
+  }
+
+  if (report.packages.length) {
+    console.log("  packages:");
+    for (const p of report.packages) {
+      console.log(
+        `    - ${p.name}: ${p.installed || p.declared || "?"}${p.installed && p.declared ? ` (declared ${p.declared})` : ""}`
+      );
+    }
+  }
+
+  console.log(`\n  ${report.message}`);
+
+  if (report.needsUpgrade) {
+    console.log(`
+  Fix (interactive):
+    npx stratos-inspect --fix
+
+  Fix (non-interactive):
+    npx stratos-inspect --fix --yes
+
+  Or manually:
+    npm uninstall ${report.packages.map((p) => p.name).join(" ")}
+    npm install ${report.required.recommendedInstall.join(" ")}
+`);
+  }
+  console.log("");
+}

package/src/postinstall.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// Runs after `npm install @intelli-1113/stratos-sdk`.
+// Warns only — never auto-uninstalls (use: npx stratos-inspect --fix).
+//
+// npm sets INIT_CWD to the project where the user ran `npm install`
+// (not node_modules/@intelli-1113/stratos-sdk).
+
+import { inspectLangChain, printInspectReport } from "./inspect-langchain.js";
+
+try {
+  if (process.env.STRATOS_SKIP_POSTINSTALL === "1") process.exit(0);
+
+  // Prefer the consumer project root
+  const cwd = process.env.INIT_CWD || process.cwd();
+  const report = inspectLangChain({ cwd });
+  if (!report.hasLangChain) process.exit(0);
+  if (report.compatible) process.exit(0);
+
+  console.warn(
+    "\n[stratos] ⚠ LangChain version is not compatible with Stratos auto-metrics."
+  );
+  printInspectReport(report);
+  console.warn(
+    "[stratos] In your project, run:\n  npx stratos-inspect --fix\n"
+  );
+} catch {
+  // Never fail the host install
+  process.exit(0);
+}

package/src/register.js

@@ -1,5 +1,41 @@
-// 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();
+// 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)
+//
+// Order matters:
+//  1) Load .env from cwd (so --import sees STRATOS_TOKEN before start)
+//  2) Register Vercel AI ESM loader (intercepts `import … from "ai"`)
+//  3) start() → Traceloop + OTLP export to Stratos
+
+import { register as registerModuleHook } from "node:module";
+import { pathToFileURL } from "node:url";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// So `node --import …/register app.js` picks up STRATOS_* without client code
+try {
+  const envPath = join(process.cwd(), ".env");
+  if (existsSync(envPath) && typeof process.loadEnvFile === "function") {
+    process.loadEnvFile(envPath);
+  }
+} catch {
+  /* optional */
+}
+
+// Must run before any consumer imports of `ai`
+try {
+  registerModuleHook(
+    pathToFileURL(join(__dirname, "vercel-ai-loader.js")).href
+  );
+} catch (err) {
+  console.warn(
+    "[stratos] could not register Vercel AI loader:",
+    err?.message || err
+  );
+}
+
+import { start } from "./index.js";
+start();

package/src/vercel-ai-inject.js

@@ -0,0 +1,78 @@
+// Pure helpers for Vercel AI telemetry injection (no side effects).
+// Used by the ESM loader shim and optional call-site wrappers.
+
+export function flagEnabled(name, defaultOn = true) {
+  const v = process.env[name];
+  if (v == null || v === "") return defaultOn;
+  return !["0", "false", "off", "no"].includes(String(v).toLowerCase());
+}
+
+export function defaultTelemetrySettings() {
+  return {
+    isEnabled: true,
+    recordInputs: flagEnabled("STRATOS_RECORD_INPUTS", true),
+    recordOutputs: flagEnabled("STRATOS_RECORD_OUTPUTS", true),
+    functionId: process.env.STRATOS_FUNCTION_ID || "stratos-vercel-ai",
+    metadata: {
+      framework: "vercel-ai",
+      agent:
+        process.env.STRATOS_APP_NAME ||
+        process.env.npm_package_name ||
+        "agent",
+    },
+  };
+}
+
+/**
+ * Merge Stratos defaults into AI SDK call options.
+ * Respects client opt-out: experimental_telemetry/telemetry isEnabled: false.
+ */
+export function injectTelemetryOptions(opts) {
+  if (!opts || typeof opts !== "object" || Array.isArray(opts)) return opts;
+
+  const defaults = defaultTelemetrySettings();
+
+  if (opts.experimental_telemetry?.isEnabled === false) return opts;
+  if (opts.telemetry?.isEnabled === false) return opts;
+
+  const next = { ...opts };
+
+  next.experimental_telemetry = {
+    ...defaults,
+    ...(opts.experimental_telemetry || {}),
+    isEnabled: opts.experimental_telemetry?.isEnabled ?? true,
+    metadata: {
+      ...defaults.metadata,
+      ...(opts.experimental_telemetry?.metadata || {}),
+    },
+  };
+
+  if (opts.telemetry == null || typeof opts.telemetry === "object") {
+    next.telemetry = {
+      ...defaults,
+      ...(opts.telemetry || {}),
+      isEnabled: opts.telemetry?.isEnabled ?? true,
+      metadata: {
+        ...defaults.metadata,
+        ...(opts.telemetry?.metadata || {}),
+      },
+    };
+  }
+
+  return next;
+}
+
+/** Functions whose first argument is call options that accept telemetry. */
+export const TELEMETRY_CALL_NAMES = [
+  "generateText",
+  "streamText",
+  "generateObject",
+  "streamObject",
+  "embed",
+  "embedMany",
+  "experimental_generateImage",
+  "experimental_generateSpeech",
+  "generateImage",
+  "generateSpeech",
+  "experimental_transcribe",
+];

package/src/vercel-ai-loader.js

@@ -0,0 +1,99 @@
+// Node custom module loader: rewrite bare specifier `ai` → Stratos shim
+// that re-exports the real package with telemetry injected on generate*/stream*/embed*.
+//
+// Registered from register.js BEFORE start(), so client code needs no changes:
+//   import "@intelli-1113/stratos-sdk/register";
+//   import { generateText } from "ai";  // ← gets wrapped exports
+
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { TELEMETRY_CALL_NAMES } from "./vercel-ai-inject.js";
+
+const SHIM_URL = "stratos-sdk:ai";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const INJECT_URL = pathToFileURL(join(__dirname, "vercel-ai-inject.js")).href;
+
+function flagEnabled(name, defaultOn = true) {
+  const v = process.env[name];
+  if (v == null || v === "") return defaultOn;
+  return !["0", "false", "off", "no"].includes(String(v).toLowerCase());
+}
+
+export async function resolve(specifier, context, nextResolve) {
+  if (!flagEnabled("STRATOS_VERCEL_AI", true)) {
+    return nextResolve(specifier, context);
+  }
+
+  // Only rewrite the bare package name. Absolute/file imports of real `ai` pass through
+  // (used by this shim to load the original module without recursion).
+  if (specifier === "ai") {
+    return {
+      shortCircuit: true,
+      url: SHIM_URL,
+      format: "module",
+    };
+  }
+  return nextResolve(specifier, context);
+}
+
+export async function load(url, context, nextLoad) {
+  if (url !== SHIM_URL) {
+    return nextLoad(url, context);
+  }
+
+  const req = createRequire(join(process.cwd(), "package.json"));
+  let realPath;
+  try {
+    realPath = req.resolve("ai");
+  } catch (err) {
+    // Consumer doesn't have `ai` — fall through to a clear error on use
+    return {
+      format: "module",
+      shortCircuit: true,
+      source: `throw new Error("[stratos] package \\"ai\\" (Vercel AI SDK) is not installed in this project");\n`,
+    };
+  }
+
+  const realUrl = pathToFileURL(realPath).href;
+  // Load real module via absolute URL (does not match specifier === "ai")
+  const real = await import(realUrl);
+  const wrapSet = new Set(TELEMETRY_CALL_NAMES);
+  const keys = Object.keys(real).filter(
+    (k) => k !== "default" && k !== "__esModule" && /^[A-Za-z_$][\w$]*$/.test(k)
+  );
+
+  let source = "";
+  source += `import * as __real from ${JSON.stringify(realUrl)};\n`;
+  source += `import { injectTelemetryOptions } from ${JSON.stringify(INJECT_URL)};\n`;
+  source += `
+function __stratosWrap(fn) {
+  if (typeof fn !== "function" || fn.__stratosWrapped) return fn;
+  const wrapped = function stratosVercelAiWrap(opts, ...rest) {
+    return fn.call(this, injectTelemetryOptions(opts), ...rest);
+  };
+  wrapped.__stratosWrapped = true;
+  try { Object.defineProperty(wrapped, "name", { value: fn.name || "stratosVercelAiWrap" }); } catch {}
+  return wrapped;
+}
+`;
+
+  for (const k of keys) {
+    if (wrapSet.has(k)) {
+      source += `export const ${k} = __stratosWrap(__real[${JSON.stringify(k)}]);\n`;
+    } else {
+      source += `export const ${k} = __real[${JSON.stringify(k)}];\n`;
+    }
+  }
+
+  if (Object.prototype.hasOwnProperty.call(real, "default")) {
+    source += `export default __real.default;\n`;
+  }
+
+  return {
+    format: "module",
+    shortCircuit: true,
+    source,
+  };
+}