@intelli-1113/stratos-sdk 1.2.3 → 1.3.2

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/enforcement.js

@@ -0,0 +1,163 @@
+// Network-level budget / lifecycle enforcement.
+//
+// WHY THE NETWORK LAYER, NOT THE SDK LAYER
+// -----------------------------------------------------------------------------
+// OpenAI, Anthropic, LangChain, Vercel AI, Google GenAI — every one of them
+// ultimately does the same thing: send an outbound HTTP request to the
+// provider's API. Traceloop's own instrumentation (which this SDK depends on
+// but does not own — @traceloop/instrumentation-openai et al.) exposes no
+// pre-call hook that can refuse a request; its config surface is
+// traceContent / enrichTokens / exceptionLogger / uploadBase64Image only.
+// Wrapping every provider SDK's call function individually is also a moving
+// target — a "custom agent" built directly on a raw SDK gets no protection
+// until someone ships a wrapper for that specific library.
+//
+// Patching global `fetch` (and `http`/`https` as a fallback for older
+// transports) catches all of them in ONE place, before the request leaves the
+// process, with no per-provider code and no dependency on Traceloop's
+// internals. This module is installed from register.js, before any provider
+// SDK is imported by the agent's own code — the same ordering guarantee the
+// Vercel AI ESM loader already relies on.
+//
+// This does NOT cover the MCP proxy path (src/mcp-proxy.js): that spawns a
+// separate child process and proxies its stdio, so patching fetch in THIS
+// process has no effect on the child's own network calls. The proxy has its
+// own, necessary check at the JSON-RPC `tools/call` boundary instead.
+
+import http from "node:http";
+import https from "node:https";
+
+export class StratosBudgetBlockedError extends Error {
+  constructor(reason) {
+    super(`[stratos] request blocked: ${reason || "budget or lifecycle limit reached"}`);
+    this.name = "StratosBudgetBlockedError";
+    this.stratosBlocked = true;
+  }
+}
+
+// Cached from the heartbeat response (see index.js / mcp-proxy.js). Starts
+// unblocked: an agent must never be frozen just because it hasn't heard back
+// from Stratos yet — same fail-open philosophy as the server's own enforcement
+// check (lib/quotaEnforce.ts: "fail open, loudly").
+let _blocked = false;
+let _reason = null;
+
+export function setBlocked(blocked, reason) {
+  _blocked = !!blocked;
+  _reason = reason || null;
+}
+
+export function isBlocked() {
+  return { blocked: _blocked, reason: _reason };
+}
+
+// Hostnames of LLM/agent providers to guard. Extend without an SDK release via
+// STRATOS_BLOCK_HOSTS (comma-separated substrings) — e.g. a private Azure
+// OpenAI deployment hostname, or a self-hosted gateway.
+const DEFAULT_PROVIDER_HOSTS = [
+  "api.openai.com",
+  "api.anthropic.com",
+  "generativelanguage.googleapis.com",
+  "aiplatform.googleapis.com",
+  "bedrock-runtime.", // *.amazonaws.com region-scoped, matched by substring
+  "api.cohere.ai",
+  "api.mistral.ai",
+  "openrouter.ai",
+  "api.together.xyz",
+  "api.groq.com",
+  "openai.azure.com",
+];
+
+function providerHosts() {
+  const extra = (process.env.STRATOS_BLOCK_HOSTS || "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  return [...DEFAULT_PROVIDER_HOSTS, ...extra];
+}
+
+// Never guard Stratos's own host: the agent has to be able to reach Stratos to
+// find out it has been unblocked. If this returned the wrong host the agent
+// would deadlock itself — checked defensively, not just assumed.
+function ownHost() {
+  try {
+    return new URL(process.env.STRATOS_URL || "http://localhost:4000").host;
+  } catch {
+    return "";
+  }
+}
+
+function hostFromInput(input) {
+  try {
+    if (typeof input === "string") return new URL(input).host;
+    if (input instanceof URL) return input.host;
+    if (input && typeof input === "object") {
+      if (input.url) return new URL(input.url).host; // Request-like
+      if (input.hostname || input.host) return String(input.hostname || input.host);
+    }
+  } catch {
+    // Not a parseable URL. Let it through — this guard only ever restricts
+    // requests to a known provider host, never anything it can't identify.
+  }
+  return "";
+}
+
+function isGuardedHost(host) {
+  if (!host) return false;
+  if (host === ownHost()) return false;
+  return providerHosts().some((h) => host.includes(h));
+}
+
+let installed = false;
+
+/**
+ * Patch global fetch and http(s).request so a blocked agent cannot reach any
+ * known LLM provider, regardless of which SDK it is using. Idempotent — safe
+ * to call more than once, and safe to call when no provider SDK is present.
+ */
+export function installNetworkGuard() {
+  if (installed) return;
+  installed = true;
+
+  if (typeof globalThis.fetch === "function" && !globalThis.fetch.__stratosGuarded) {
+    const realFetch = globalThis.fetch.bind(globalThis);
+    const guarded = function stratosGuardedFetch(input, init) {
+      if (isGuardedHost(hostFromInput(input))) {
+        const { blocked, reason } = isBlocked();
+        if (blocked) return Promise.reject(new StratosBudgetBlockedError(reason));
+      }
+      return realFetch(input, init);
+    };
+    guarded.__stratosGuarded = true;
+    globalThis.fetch = guarded;
+  }
+
+  patchRequestModule(http);
+  patchRequestModule(https);
+}
+
+/**
+ * Secondary guard for legacy http(s)-based clients — the fetch guard above is
+ * the primary path and already covers current OpenAI / Anthropic / Google /
+ * Vercel AI SDKs, which all use fetch on Node 18+. A synchronous throw here is
+ * non-standard for a network failure (Node normally emits an async 'error' on
+ * the returned request), but building a spec-compliant fake ClientRequest for
+ * a fallback path most agents never exercise is not worth the complexity —
+ * callers of http(s).request that care will have it in a try/catch already,
+ * since the real function can also throw synchronously for invalid options.
+ */
+function patchRequestModule(mod) {
+  if (!mod || !mod.request || mod.request.__stratosGuarded) return;
+  const real = mod.request;
+  const guarded = function stratosGuardedRequest(...args) {
+    const opts = args.find((a) => a && typeof a === "object" && typeof a !== "function");
+    const host = opts ? String(opts.hostname || opts.host || "") : hostFromInput(args[0]);
+    if (isGuardedHost(host)) {
+      const { blocked, reason } = isBlocked();
+      if (blocked) throw new StratosBudgetBlockedError(reason);
+    }
+    return real.apply(mod, args);
+  };
+  guarded.__stratosGuarded = true;
+  mod.request = guarded;
+}

package/src/index.js

@@ -1,38 +1,58 @@
 // @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";
+import { setBlocked } from "./enforcement.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,24 +65,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.GEMINI_MODEL || process.env.GOOGLE_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;
@@ -73,42 +113,98 @@ export function start(opts = {}) {
   traceloop.initialize({
     appName,
     disableBatch: true,
-    exporter: new OTLPTraceExporter({ url: ingest, headers: { "x-stratos-token": token } }),
+    logLevel: process.env.STRATOS_DEBUG ? "debug" : undefined,
+    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).
+  // Heartbeat is also how the network guard (enforcement.js) learns whether to
+  // freeze this agent — budget exhausted, period crossed, or the agent
+  // manually disabled from the Control Tower all collapse into the same
+  // { blocked, reason } flag on the server, so the SDK does not need to know
+  // *why*, only that it is. The response used to be discarded entirely
+  // (`.catch(() => {})`, no `.then()`); reading it is the only change here.
+  let warnedBlocked = false;
   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(() => {});
+    })
+      .then((r) => r.json().catch(() => null))
+      .then((data) => {
+        if (!data || typeof data.blocked !== "boolean") return;
+        setBlocked(data.blocked, data.reason);
+        if (data.blocked && !warnedBlocked) {
+          warnedBlocked = true;
+          console.warn(
+            `[stratos] BLOCKED: ${data.reason || "budget or lifecycle limit reached"} — ` +
+              `outbound calls to LLM providers will be refused until this clears.`
+          );
+        } else if (!data.blocked && warnedBlocked) {
+          warnedBlocked = false;
+          console.log("[stratos] unblocked — outbound calls to LLM providers resumed.");
+        }
+      })
+      .catch(() => {});
   ping();
   if (heartbeatMs > 0) setInterval(ping, heartbeatMs).unref();
 
-  // disableBatch exports each span the moment it ends via an async HTTP POST —
-  // fine for long-running servers, but a one-shot script (no open server/handle)
-  // drains the event loop and exits the instant it's done, killing that request
-  // mid-flight before it reaches Stratos. 'beforeExit' fires exactly at that point
-  // (and, unlike 'exit', still lets us start async work), so flushing there makes
-  // every consumer — script or server — deliver its spans with zero code changes.
   process.on("beforeExit", () => {
     traceloop.forceFlush().catch(() => {});
   });
-  // Also flush on Ctrl+C / kill so a killed server doesn't lose its last spans.
   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 || "?"})`);
+  console.log(
+    `[stratos] telemetry → ${ingest} (heartbeat ${heartbeatMs}ms, framework=${meta.framework || "?"})`
+  );
 }
 
 export default { start };