@intelli-1113/stratos-sdk 1.2.3 → 1.3.2

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/mcp-proxy.js

@@ -23,6 +23,12 @@ console.log = console.info = (...a) => process.stderr.write(a.map(String).join("
 
 import { spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
+// The network guard installed by register.js (see enforcement.js) patches
+// THIS process's fetch/http — it has no effect on the target MCP server, which
+// runs as a separate child process spawned below, possibly in a different
+// language/runtime entirely. The only place budget/lifecycle enforcement can
+// act on that child is here, at the JSON-RPC boundary between the host and it.
+import { setBlocked, isBlocked } from "./enforcement.js";
 
 let argv = process.argv.slice(2);
 const sep = argv.indexOf("--");
@@ -65,9 +71,26 @@ function reportTool(name, argsObj, out, isErr, startMs, endMs) {
   fetch(`${URL}/api/ingest`, { method: "POST", headers: hdr, body: JSON.stringify(body) }).catch(() => {});
 }
 
+let warnedBlocked = false;
 function heartbeat() {
   if (!TOKEN) return;
-  fetch(`${URL}/api/heartbeat`, { method: "POST", headers: hdr }).catch(() => {});
+  fetch(`${URL}/api/heartbeat`, { method: "POST", headers: hdr })
+    .then((r) => r.json().catch(() => null))
+    .then((data) => {
+      if (!data || typeof data.blocked !== "boolean") return;
+      setBlocked(data.blocked, data.reason);
+      // Visible feedback in the proxy's own log (stderr — stdout is the
+      // protocol channel). Without this there is no way to see a block take
+      // effect other than a tool call failing with no explanation.
+      if (data.blocked && !warnedBlocked) {
+        warnedBlocked = true;
+        process.stderr.write(`[stratos-proxy] BLOCKED: ${data.reason || "budget or lifecycle limit reached"} — tools/call will be refused until this clears.\n`);
+      } else if (!data.blocked && warnedBlocked) {
+        warnedBlocked = false;
+        process.stderr.write("[stratos-proxy] unblocked — tool calls resumed.\n");
+      }
+    })
+    .catch(() => {});
 }
 heartbeat();
 const hbTimer = setInterval(heartbeat, HEARTBEAT_MS);
@@ -83,7 +106,24 @@ linePump(process.stdin, (line) => {
   let m; try { m = JSON.parse(line); } catch { child.stdin.write(line + "\n"); return; }
   if (m && m.id != null && m.method === "tools/call") {
     const name = (m.params && m.params.name) || "tool";
-    pendingCalls.set(m.id, { name, args: (m.params && m.params.arguments) || {}, start: Date.now() });
+    const args = (m.params && m.params.arguments) || {};
+    const { blocked, reason } = isBlocked();
+    if (blocked) {
+      // Refuse before the child ever sees this call — do NOT forward to
+      // child.stdin. The host gets a normal JSON-RPC error response (not a
+      // dropped connection), and the refusal itself is still reported so it is
+      // visible on Stratos rather than silently vanishing.
+      const now = Date.now();
+      const errResp = {
+        jsonrpc: "2.0",
+        id: m.id,
+        error: { code: -32001, message: `Stratos: blocked — ${reason || "budget or lifecycle limit reached"}` },
+      };
+      process.stdout.write(JSON.stringify(errResp) + "\n");
+      reportTool(name, args, { blocked: true, reason: reason || null }, true, now, now);
+      return;
+    }
+    pendingCalls.set(m.id, { name, args, start: Date.now() });
   }
   child.stdin.write(line + "\n");
 });

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,57 @@
-// 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) Install the network guard (see enforcement.js) — before ANY provider SDK
+//     (openai, @anthropic-ai/sdk, langchain, ai, …) has a chance to import and
+//     capture a reference to the unpatched global fetch/http/https.
+//  3) Register Vercel AI ESM loader (intercepts `import … from "ai"`)
+//  4) start() → Traceloop + OTLP export to Stratos, and the heartbeat that
+//     keeps the network guard's blocked/unblocked state up to date.
+
+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";
+import { installNetworkGuard } from "./enforcement.js";
+
+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 a provider SDK — it patches the
+// shared, global fetch/http/https that every one of them ultimately calls
+// through, so a single install here covers openai/anthropic/langchain/ai/…
+// without a per-library wrapper. See enforcement.js for why this is the
+// network layer and not the SDK layer.
+try {
+  installNetworkGuard();
+} catch (err) {
+  console.warn("[stratos] could not install network guard:", err?.message || err);
+}
+
+// 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",
+];