@intelli-1113/stratos-sdk 1.3.1 → 1.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intelli-1113/stratos-sdk",
-  "version": "1.3.1",
+  "version": "1.3.3",
   "description": "Stratos AI agent telemetry (OpenLLMetry), Vercel AI auto-spans, LangChain inspect/fix, MCP proxy.",
   "type": "module",
   "main": "./src/index.js",
@@ -37,5 +37,13 @@
     "@traceloop/node-server-sdk": "^0.27.0",
     "import-in-the-middle": "^1.15.0",
     "require-in-the-middle": "^7.5.2"
+  },
+  "peerDependencies": {
+    "@langchain/core": ">=1.0.0 <2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@langchain/core": {
+      "optional": true
+    }
   }
 }

package/src/cli-inspect.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 /**
  * stratos-inspect — check LangChain version compatibility for Stratos metrics.
  *

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

@@ -16,6 +16,7 @@ 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";
 
@@ -50,21 +51,46 @@ function agentDeps() {
 
 function detectFramework() {
   if (process.env.STRATOS_FRAMEWORK) return process.env.STRATOS_FRAMEWORK;
+
   const deps = agentDeps();
-  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";
-  if (has("crewai")) return "crewai";
-  if (has("@langchain/langgraph")) return "langgraph";
-  if (has("langchain") || has("@langchain/core")) return "langchain";
-  if (has("ai")) return "vercel-ai";
-  if (has("@google/generative-ai") || has("@google/genai")) return "google-genai";
-  if (has("@anthropic-ai/sdk")) return "anthropic";
-  if (has("openai")) return "openai";
+  const inDeps = (n) => n in deps;
+  const isResolvable = (n) => resolvableFromCwd(n) || resolvable(n);
+
+  // 1. FIRST PASS: Check explicit dependencies declared in the user's package.json
+  if (inDeps("@google/adk") || inDeps("google-adk") || inDeps("@iqai/adk")) return "google-adk";
+  if (inDeps("@openai/agents")) return "openai-agents";
+  if (inDeps("llamaindex")) return "llamaindex";
+  if (inDeps("crewai")) return "crewai";
+
+  // If the user explicitly declared langgraph in package.json
+  if (inDeps("@langchain/langgraph")) return "langgraph";
+  // If the user declared langchain or @langchain/core
+  if (inDeps("langchain") || inDeps("@langchain/core")) return "langchain";
+
+  if (inDeps("ai")) return "vercel-ai";
+  if (inDeps("@google/generative-ai") || inDeps("@google/genai")) return "google-genai";
+  if (inDeps("@anthropic-ai/sdk")) return "anthropic";
+  if (inDeps("openai")) return "openai";
+
+  // 2. SECOND PASS: Fallback to node_modules inspection if package.json has no direct match
+  if (isResolvable("@google/adk") || isResolvable("google-adk") || isResolvable("@iqai/adk")) return "google-adk";
+  if (isResolvable("@openai/agents")) return "openai-agents";
+  if (isResolvable("llamaindex")) return "llamaindex";
+  if (isResolvable("crewai")) return "crewai";
+
+  // Prioritize langchain over internal transitive langgraph
+  if (isResolvable("langchain") || isResolvable("@langchain/core")) return "langchain";
+  if (isResolvable("@langchain/langgraph")) return "langgraph";
+
+  if (isResolvable("ai")) return "vercel-ai";
+  if (isResolvable("@google/generative-ai") || isResolvable("@google/genai")) return "google-genai";
+  if (isResolvable("@anthropic-ai/sdk")) return "anthropic";
+  if (isResolvable("openai")) return "openai";
+
   return null;
 }
 
+
 function detectModel(opts) {
   return (
     opts.model ||
@@ -112,6 +138,7 @@ export function start(opts = {}) {
   traceloop.initialize({
     appName,
     disableBatch: true,
+    logLevel: process.env.STRATOS_DEBUG ? "debug" : undefined,
     exporter: new OTLPTraceExporter({
       url: ingest,
       headers: { "x-stratos-token": token },
@@ -156,6 +183,13 @@ export function start(opts = {}) {
     tools: toolsEnv,
   };
 
+  // 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",
@@ -164,7 +198,23 @@ export function start(opts = {}) {
         "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();
 

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

@@ -4,14 +4,19 @@
 //
 // 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
+//  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));
 
@@ -25,6 +30,17 @@ try {
   /* 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(

package/src/vercel-ai-loader.js

@@ -14,6 +14,13 @@ 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;
+// The network guard (enforcement.js, installed from register.js) already
+// refuses these calls at the fetch layer once blocked — Vercel AI's own client
+// uses fetch internally, same as everyone else. This second check is
+// redundant with that but deliberately kept: it fails before Vercel AI builds
+// its request/retry/streaming machinery, and the error reads as ours rather
+// than as a generic fetch failure surfaced through their error wrapper.
+const ENFORCEMENT_URL = pathToFileURL(join(__dirname, "enforcement.js")).href;
 
 function flagEnabled(name, defaultOn = true) {
   const v = process.env[name];
@@ -67,10 +74,15 @@ export async function load(url, context, nextLoad) {
   let source = "";
   source += `import * as __real from ${JSON.stringify(realUrl)};\n`;
   source += `import { injectTelemetryOptions } from ${JSON.stringify(INJECT_URL)};\n`;
+  source += `import { isBlocked } from ${JSON.stringify(ENFORCEMENT_URL)};\n`;
   source += `
 function __stratosWrap(fn) {
   if (typeof fn !== "function" || fn.__stratosWrapped) return fn;
   const wrapped = function stratosVercelAiWrap(opts, ...rest) {
+    const __b = isBlocked();
+    if (__b.blocked) {
+      throw new Error("[stratos] request blocked: " + (__b.reason || "budget or lifecycle limit reached"));
+    }
     return fn.call(this, injectTelemetryOptions(opts), ...rest);
   };
   wrapped.__stratosWrapped = true;