@intelli-1113/stratos-sdk 1.3.3 → 1.3.5

package/README.md

@@ -1,3 +1,7 @@
+## Change version in package.json
+## npm login
+## npm publish --access public
+
 # @intelli-1113/stratos-sdk
 
 **One install** for [Stratos AI](https://github.com) agent observability:

package/package.json

@@ -1,15 +1,23 @@
 {
   "name": "@intelli-1113/stratos-sdk",
-  "version": "1.3.3",
+  "version": "1.3.5",
   "description": "Stratos AI agent telemetry (OpenLLMetry), Vercel AI auto-spans, LangChain inspect/fix, MCP proxy.",
   "type": "module",
   "main": "./src/index.js",
   "exports": {
     ".": "./src/index.js",
     "./register": "./src/register.js",
-    "./inspect": "./src/inspect-langchain.js"
+    "./inspect": "./src/inspect-langchain.js",
+    "./otel-bridge": "./src/otel-bridge.js",
+    "./otel-bridge-harness": "./src/otel-bridge-harness.js",
+    "./execution-spans": "./src/execution-spans.js",
+    "./config-templates": "./src/config-templates.js"
   },
   "bin": {
+    "stratos": "./src/cli.js",
+    "stratos-setup": "./src/cli-setup.js",
+    "stratos-doctor": "./src/cli-doctor.js",
+    "stratos-otel-bridge": "./src/otel-bridge.js",
     "stratos-mcp-proxy": "./src/mcp-proxy.js",
     "stratos-inspect": "./src/cli-inspect.js"
   },
@@ -19,6 +27,8 @@
   "scripts": {
     "postinstall": "node ./src/postinstall.js",
     "test": "node -e \"import('./src/index.js').then(m=>console.log('ok',Object.keys(m)))\"",
+    "setup": "node ./src/cli.js setup claude-code",
+    "doctor": "node ./src/cli.js doctor",
     "inspect": "node ./src/cli-inspect.js"
   },
   "keywords": [
@@ -35,6 +45,7 @@
   "dependencies": {
     "@opentelemetry/exporter-trace-otlp-http": "^0.203.0",
     "@traceloop/node-server-sdk": "^0.27.0",
+    "cross-spawn": "^7.0.3",
     "import-in-the-middle": "^1.15.0",
     "require-in-the-middle": "^7.5.2"
   },

package/src/cli-doctor.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export async function doctorCommand() {
+  console.log("[stratos-doctor] Running diagnostics...\n");
+
+  const checks = [];
+  let passed = 0;
+  let failed = 0;
+
+  const token = process.env.STRATOS_TOKEN;
+  const url = process.env.STRATOS_URL || "https://stratos.anthropic.com";
+
+  if (token && token.startsWith("sk_")) {
+    console.log("✓ STRATOS_TOKEN set");
+    passed++;
+  } else {
+    console.log("✗ STRATOS_TOKEN missing or invalid (must start with sk_)");
+    checks.push("Set STRATOS_TOKEN environment variable with your enrollment token");
+    failed++;
+  }
+
+  if (url && url.startsWith("https://")) {
+    console.log(`✓ STRATOS_URL configured: ${url}`);
+    passed++;
+  } else {
+    console.log("✗ STRATOS_URL missing or invalid (must be https://)");
+    checks.push("Set STRATOS_URL environment variable");
+    failed++;
+  }
+
+  if (process.env.NODE_OPTIONS?.includes("stratos-sdk/register")) {
+    console.log("✓ NODE_OPTIONS includes stratos-sdk/register");
+    passed++;
+  } else {
+    console.log("✗ NODE_OPTIONS not set to include stratos-sdk/register");
+    checks.push(
+      "Add to NODE_OPTIONS: --import @intelli-1113/stratos-sdk/register"
+    );
+    failed++;
+  }
+
+  if (process.env.STRATOS_RECORD_INPUTS === "0") {
+    console.log("✓ STRATOS_RECORD_INPUTS=0 (content-off)");
+    passed++;
+  } else {
+    console.log("⚠ STRATOS_RECORD_INPUTS not set to 0 (prompts may be recorded)");
+    checks.push("Set STRATOS_RECORD_INPUTS=0 to disable prompt recording");
+  }
+
+  if (process.env.STRATOS_RECORD_OUTPUTS === "0") {
+    console.log("✓ STRATOS_RECORD_OUTPUTS=0 (content-off)");
+    passed++;
+  } else {
+    console.log(
+      "⚠ STRATOS_RECORD_OUTPUTS not set to 0 (responses may be recorded)"
+    );
+    checks.push("Set STRATOS_RECORD_OUTPUTS=0 to disable response recording");
+  }
+
+  const claudeDir = join(homedir(), ".claude");
+  const settingsPath = join(claudeDir, "settings.json");
+  const envPath = join(claudeDir, ".env");
+
+  if (existsSync(settingsPath)) {
+    console.log(`✓ Settings file exists: ${settingsPath}`);
+    passed++;
+  } else {
+    console.log(`✗ Settings file missing: ${settingsPath}`);
+    checks.push("Run: stratos setup claude-code");
+    failed++;
+  }
+
+  if (existsSync(envPath)) {
+    console.log(`✓ Environment file exists: ${envPath}`);
+    passed++;
+  } else {
+    console.log(`⚠ Env file missing: ${envPath}`);
+    checks.push("Run: stratos setup claude-code");
+  }
+
+  if (token && url && failed === 0) {
+    try {
+      console.log("\n[stratos-doctor] Testing connectivity...");
+      const response = await fetch(`${url}/api/health`, {
+        method: "GET",
+        headers: {
+          "x-stratos-token": token,
+          "user-agent": "stratos-sdk-doctor",
+        },
+        timeout: 5000,
+      });
+
+      if (response.ok) {
+        console.log("✓ Connected to Stratos server");
+        passed++;
+      } else if (response.status === 401 || response.status === 403) {
+        console.log(`✗ Stratos server rejected token (${response.status})`);
+        checks.push("Verify STRATOS_TOKEN is correct");
+        failed++;
+      } else {
+        console.log(`✗ Stratos server returned ${response.status}`);
+        checks.push(`Check STRATOS_URL (got ${response.status})`);
+        failed++;
+      }
+    } catch (err) {
+      console.log(`✗ Could not connect to Stratos server: ${err.message}`);
+      checks.push(
+        `Check STRATOS_URL is reachable: ${url}\n` +
+          `Common issues:\n` +
+          `  - Network connectivity\n` +
+          `  - Firewall blocking\n` +
+          `  - Invalid URL`
+      );
+      failed++;
+    }
+  }
+
+  console.log("\n" + "=".repeat(60));
+  if (failed === 0) {
+    console.log("✓ stratos-doctor: All checks passed");
+    console.log(
+      "\nYou are connected to Stratos. Your Claude usage will now be tracked."
+    );
+  } else {
+    console.log(`✗ stratos-doctor: ${failed} check(s) failed\n`);
+    if (checks.length > 0) {
+      console.log("Remediation steps:");
+      checks.forEach((check, i) => {
+        console.log(`  ${i + 1}. ${check}`);
+      });
+    }
+    process.exit(1);
+  }
+  console.log("=".repeat(60) + "\n");
+}
+
+doctorCommand().catch((err) => {
+  console.error("[stratos-doctor] Fatal error:", err.message);
+  process.exit(1);
+});

package/src/cli-setup.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { join, resolve } from "node:path";
+import { execSync } from "node:child_process";
+
+export async function setupCommand(surface) {
+  if (!surface) {
+    console.error("[stratos-setup] Error: Surface required");
+    console.error("Usage: stratos setup <surface>");
+    console.error("Example: stratos setup claude-code");
+    process.exit(1);
+  }
+
+  if (surface !== "claude-code") {
+    console.error(`[stratos-setup] Error: Unsupported surface '${surface}'`);
+    console.error("Currently supported: claude-code");
+    process.exit(1);
+  }
+
+  console.log(`[stratos-setup] Configuring Stratos for ${surface}...\n`);
+
+  const claudeCodePath = detectClaudeCode();
+  if (!claudeCodePath) {
+    console.error("[stratos-setup] Error: Claude Code not detected on this machine");
+    console.error("Install Claude Code from https://claude.ai/code before running setup.");
+    process.exit(1);
+  }
+
+  console.log(`✓ Found Claude Code at: ${claudeCodePath}\n`);
+
+  const token = process.env.STRATOS_TOKEN;
+  if (!token) {
+    console.error("[stratos-setup] Error: STRATOS_TOKEN environment variable not set");
+    console.error("Provide your enrollment token via: export STRATOS_TOKEN=sk_...");
+    process.exit(1);
+  }
+
+  const url = process.env.STRATOS_URL || "https://stratos.anthropic.com";
+  console.log(`✓ Using Stratos server: ${url}\n`);
+
+  const claudeDir = join(homedir(), ".claude");
+  mkdirSync(claudeDir, { recursive: true });
+
+  const envPath = join(claudeDir, ".env");
+  const envContent = `STRATOS_TOKEN=${token}
+STRATOS_URL=${url}
+STRATOS_RECORD_INPUTS=0
+STRATOS_RECORD_OUTPUTS=0
+NODE_OPTIONS=--import @intelli-1113/stratos-sdk/register
+`;
+
+  writeFileSync(envPath, envContent, "utf8");
+  console.log(`✓ Wrote config to: ${envPath}`);
+
+  const settingsPath = join(claudeDir, "settings.json");
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+    } catch {
+      console.warn("[stratos-setup] Warning: Could not parse existing settings.json, will merge");
+    }
+  }
+
+  settings.env = settings.env || {};
+  settings.env.STRATOS_TOKEN = token;
+  settings.env.STRATOS_URL = url;
+  settings.env.STRATOS_RECORD_INPUTS = "0";
+  settings.env.STRATOS_RECORD_OUTPUTS = "0";
+  settings.env.NODE_OPTIONS = "--import @intelli-1113/stratos-sdk/register";
+
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2), "utf8");
+  console.log(`✓ Updated: ${settingsPath}\n`);
+
+  console.log("[stratos-setup] Setup complete. Running doctor to verify...\n");
+
+  const { doctorCommand } = await import("./cli-doctor.js");
+  await doctorCommand();
+}
+
+function detectClaudeCode() {
+  const os = platform();
+  const home = homedir();
+
+  if (os === "darwin") {
+    const macPath = join(home, "Applications", "Claude.app");
+    if (existsSync(macPath)) return macPath;
+  }
+
+  if (os === "win32") {
+    const paths = [
+      join(home, "AppData", "Local", "Programs", "claude"),
+      "C:\\Program Files\\Claude",
+      "C:\\Program Files (x86)\\Claude",
+    ];
+    for (const p of paths) {
+      if (existsSync(p)) return p;
+    }
+  }
+
+  if (os === "linux") {
+    const paths = [
+      join(home, ".local", "share", "applications", "claude"),
+      join(home, ".config", "claude"),
+    ];
+    for (const p of paths) {
+      if (existsSync(p)) return p;
+    }
+  }
+
+  try {
+    const result = execSync("which claude 2>/dev/null || where claude 2>nul", {
+      encoding: "utf8",
+    }).trim();
+    if (result) return result;
+  } catch {}
+
+  return null;
+}

package/src/cli.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+
+import { parseArgs } from "node:util";
+import { setupCommand } from "./cli-setup.js";
+import { doctorCommand } from "./cli-doctor.js";
+
+const VERSION = "1.3.4";
+
+function printHelp() {
+  console.log(`
+stratos CLI ${VERSION}
+
+Usage:
+  stratos <command> [options]
+
+Commands:
+  setup <surface>       Configure Stratos on a surface (e.g., claude-code)
+  doctor                Validate Stratos setup and connectivity
+  --help, -h            Show this message
+  --version, -v         Show version
+
+Examples:
+  stratos setup claude-code
+  stratos doctor
+`);
+}
+
+async function main() {
+  const { values, positional } = parseArgs({
+    options: {
+      help: { type: "boolean", short: "h" },
+      version: { type: "boolean", short: "v" },
+    },
+    allowPositionals: true,
+  });
+
+  if (values.help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (values.version) {
+    console.log(`stratos ${VERSION}`);
+    process.exit(0);
+  }
+
+  const [command, ...args] = positional;
+
+  if (!command) {
+    printHelp();
+    process.exit(0);
+  }
+
+  try {
+    if (command === "setup") {
+      await setupCommand(...args);
+    } else if (command === "doctor") {
+      await doctorCommand();
+    } else {
+      console.error(`Unknown command: ${command}`);
+      printHelp();
+      process.exit(1);
+    }
+  } catch (err) {
+    console.error(`[stratos] Error:`, err.message);
+    process.exit(1);
+  }
+}
+
+main();

package/src/config-templates.js

@@ -0,0 +1,183 @@
+import { platform } from "node:os";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export class ConfigTemplate {
+  constructor(opts = {}) {
+    this.personEmail = opts.personEmail || "alice@company.com";
+    this.surface = opts.surface || "claude-code"; // claude-code, claude-chat, claude-cowork
+    this.token = opts.token || `sk_dev_${opts.personEmail.split("@")[0]}_${opts.surface}_${Date.now()}`;
+    this.url = opts.url || "https://stratos.company.com";
+    this.osType = opts.osType || platform();
+    this.contentOff = opts.contentOff !== false;
+    this.recordInputs = opts.recordInputs === true ? "1" : "0";
+    this.recordOutputs = opts.recordOutputs === true ? "1" : "0";
+  }
+
+  toEnv() {
+    return `STRATOS_TOKEN=${this.token}
+STRATOS_URL=${this.url}
+STRATOS_SURFACE=${this.surface}
+STRATOS_RECORD_INPUTS=${this.recordInputs}
+STRATOS_RECORD_OUTPUTS=${this.recordOutputs}
+NODE_OPTIONS=--import @intelli-1113/stratos-sdk/register
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+`;
+  }
+
+  toSettingsJson() {
+    return {
+      surface: this.surface,
+      owner_email: this.personEmail,
+      env: {
+        STRATOS_TOKEN: this.token,
+        STRATOS_URL: this.url,
+        STRATOS_SURFACE: this.surface,
+        STRATOS_RECORD_INPUTS: this.recordInputs,
+        STRATOS_RECORD_OUTPUTS: this.recordOutputs,
+        NODE_OPTIONS: "--import @intelli-1113/stratos-sdk/register",
+        OTEL_EXPORTER_OTLP_ENDPOINT: "http://localhost:4318",
+      },
+      hooks: {
+        PreToolUse: { enabled: true },
+        PostToolUse: { enabled: true },
+        SessionStart: { enabled: true },
+        SessionStop: { enabled: true },
+        SubagentStop: { enabled: true },
+        UserPromptSubmit: { enabled: true },
+      },
+    };
+  }
+
+  toYaml() {
+    const settings = this.toSettingsJson();
+    return `# Stratos SDK Configuration
+# Generated for: ${this.personEmail}
+# Surface: ${this.surface}
+# OS: ${this.osType}
+
+surface: ${settings.surface}
+owner_email: ${settings.owner_email}
+
+env:
+${Object.entries(settings.env)
+  .map(([k, v]) => `  ${k}: ${v}`)
+  .join("\n")}
+
+hooks:
+${Object.entries(settings.hooks)
+  .map(([k, v]) => `  ${k}: ${v.enabled}`)
+  .join("\n")}
+
+content_off: ${this.contentOff}
+created_at: ${new Date().toISOString()}
+`;
+  }
+
+  toBundle() {
+    return {
+      version: "1.0",
+      person: this.personEmail,
+      surface: this.surface,
+      os: this.osType,
+      config: this.toSettingsJson(),
+      env_file: this.toEnv(),
+      yaml_template: this.toYaml(),
+      metadata: {
+        created_at: new Date().toISOString(),
+        sdk_version: "1.4.0",
+      },
+    };
+  }
+
+  save(dirPath) {
+    const fileName = `stratos-config-${this.personEmail.replace(/@.*/, "")}-${this.surface}`;
+    const yamlPath = join(dirPath, `${fileName}.yaml`);
+    const jsonPath = join(dirPath, `${fileName}.json`);
+
+    writeFileSync(yamlPath, this.toYaml(), "utf8");
+    writeFileSync(jsonPath, JSON.stringify(this.toBundle(), null, 2), "utf8");
+
+    return { yamlPath, jsonPath };
+  }
+}
+
+export class MDMBundleGenerator {
+  constructor(opts = {}) {
+    this.orgUrl = opts.orgUrl || "https://stratos.company.com";
+    this.adminToken = opts.adminToken;
+    this.templates = [];
+  }
+
+  addTemplate(template) {
+    this.templates.push(template);
+  }
+
+  generateForPerson(personEmail, surfaces = ["claude-code", "claude-chat", "claude-cowork"]) {
+    const templates = [];
+    for (const surface of surfaces) {
+      const template = new ConfigTemplate({
+        personEmail,
+        surface,
+        url: this.orgUrl,
+      });
+      templates.push(template);
+    }
+    return templates;
+  }
+
+  toManifest() {
+    return {
+      version: "1.0",
+      org_url: this.orgUrl,
+      bundles: this.templates.map((t) => t.toBundle()),
+      metadata: {
+        created_at: new Date().toISOString(),
+        total_bundles: this.templates.length,
+        total_people: new Set(this.templates.map((t) => t.personEmail)).size,
+        total_surfaces: new Set(this.templates.map((t) => t.surface)).size,
+      },
+    };
+  }
+
+  async postToEnrollment(enrollmentUrl) {
+    if (!this.adminToken) {
+      console.error("[mdm-bundle] Admin token required to post enrollment");
+      return false;
+    }
+
+    try {
+      const manifest = this.toManifest();
+      const res = await fetch(`${enrollmentUrl}/api/mdm/bundle`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.adminToken}`,
+        },
+        body: JSON.stringify(manifest),
+      });
+
+      if (!res.ok) {
+        console.error(`[mdm-bundle] Enrollment returned ${res.status}`);
+        return false;
+      }
+
+      console.log("[mdm-bundle] Bundle posted to enrollment successfully");
+      return true;
+    } catch (err) {
+      console.error(`[mdm-bundle] Failed to post: ${err.message}`);
+      return false;
+    }
+  }
+}
+
+export function createDefaultMDMBundle(personEmails, orgUrl) {
+  const generator = new MDMBundleGenerator({ orgUrl });
+
+  for (const email of personEmails) {
+    const templates = generator.generateForPerson(email);
+    templates.forEach((t) => generator.addTemplate(t));
+  }
+
+  return generator;
+}

package/src/enforcement.js

@@ -73,7 +73,9 @@ function providerHosts() {
     .split(",")
     .map((s) => s.trim())
     .filter(Boolean);
-  return [...DEFAULT_PROVIDER_HOSTS, ...extra];
+  // P1-02: Add "api." catch-all to block future/unlisted providers (NVIDIA, DeepSeek, Fireworks, xAI, etc.)
+  // while keeping explicit list for clarity
+  return [...DEFAULT_PROVIDER_HOSTS, ...extra, "api."];
 }
 
 // Never guard Stratos's own host: the agent has to be able to reach Stratos to
@@ -160,4 +162,23 @@ function patchRequestModule(mod) {
   };
   guarded.__stratosGuarded = true;
   mod.request = guarded;
+
+  // P1-01: Also wrap .get() to catch https.get() and named imports like `import { get } from "node:https"`
+  if (mod.get && !mod.get.__stratosGuarded) {
+    const realGet = mod.get;
+    const guardedGet = function stratosGuardedGet(...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 realGet.apply(mod, args);
+    };
+    guardedGet.__stratosGuarded = true;
+    mod.get = guardedGet;
+  }
+
+  // Ensure named imports (import { request, get } from "node:https") see wrapped versions
+  module.syncBuiltinESMExports?.();
 }

package/src/execution-spans.js

@@ -0,0 +1,166 @@
+import { randomBytes } from "node:crypto";
+
+const TOKEN = process.env.STRATOS_TOKEN || "";
+const STRATOS_URL = process.env.STRATOS_URL || "http://localhost:4000";
+const SURFACE = process.env.STRATOS_SURFACE || "unknown";
+
+const hdr = { "Content-Type": "application/json", "x-stratos-token": TOKEN };
+
+export class ExecutionSpan {
+  constructor(opts = {}) {
+    this.type = opts.type; // skill, subagent, hook, cmd, plugin, mcp
+    this.name = opts.name;
+    this.startTime = opts.startTime || Date.now();
+    this.endTime = opts.endTime || null;
+    this.status = opts.status || "running"; // running, success, error
+    this.reason = opts.reason || null;
+    this.metadata = opts.metadata || {};
+  }
+
+  end(status = "success", reason = null) {
+    this.endTime = Date.now();
+    this.status = status;
+    this.reason = reason;
+  }
+
+  toOtlpSpan() {
+    const traceId = (randomBytes(16)).toString("hex");
+    const spanId = (randomBytes(8)).toString("hex");
+    const startNano = BigInt(this.startTime) * 1000000n;
+    const endNano = BigInt(this.endTime || Date.now()) * 1000000n;
+
+    const attr = (k, v) => ({
+      key: k,
+      value: {
+        stringValue: String(v),
+      },
+    });
+
+    const attributes = [
+      attr("traceloop.span.kind", this.type),
+      attr("traceloop.entity.name", this.name),
+      attr("stratos.surface", SURFACE),
+      attr("stratos.execution.type", this.type),
+      attr("stratos.execution.status", this.status),
+    ];
+
+    if (this.reason) {
+      attributes.push(attr("stratos.execution.reason", this.reason));
+    }
+
+    for (const [k, v] of Object.entries(this.metadata || {})) {
+      if (v != null && typeof v !== "object") {
+        attributes.push(attr(`stratos.${k}`, v));
+      }
+    }
+
+    return {
+      traceId,
+      spanId,
+      name: `${this.type}:${this.name}`,
+      startTimeUnixNano: startNano.toString(),
+      endTimeUnixNano: endNano.toString(),
+      attributes,
+    };
+  }
+
+  static async post(span) {
+    if (!TOKEN) return;
+
+    const otlpSpan = span.toOtlpSpan();
+    const payload = {
+      resourceSpans: [
+        {
+          resource: {
+            attributes: [{ key: "service.name", value: { stringValue: SURFACE } }],
+          },
+          scopeSpans: [
+            {
+              spans: [otlpSpan],
+            },
+          ],
+        },
+      ],
+    };
+
+    try {
+      const res = await fetch(`${STRATOS_URL}/api/ingest`, {
+        method: "POST",
+        headers: hdr,
+        body: JSON.stringify(payload),
+      });
+      if (!res.ok) {
+        console.error(`[execution-spans] Stratos returned ${res.status}`);
+      }
+    } catch (err) {
+      console.error(`[execution-spans] Failed to post span: ${err.message}`);
+    }
+  }
+}
+
+export async function postSkillSpan(skillName, status = "success", reason = null) {
+  const span = new ExecutionSpan({
+    type: "skill",
+    name: skillName,
+    status,
+    reason,
+  });
+  span.end(status, reason);
+  await ExecutionSpan.post(span);
+}
+
+export async function postSubagentSpan(subagentName, status = "success", reason = null, metadata = {}) {
+  const span = new ExecutionSpan({
+    type: "subagent",
+    name: subagentName,
+    status,
+    reason,
+    metadata,
+  });
+  span.end(status, reason);
+  await ExecutionSpan.post(span);
+}
+
+export async function postHookSpan(hookName, status = "success", reason = null) {
+  const span = new ExecutionSpan({
+    type: "hook",
+    name: hookName,
+    status,
+    reason,
+  });
+  span.end(status, reason);
+  await ExecutionSpan.post(span);
+}
+
+export async function postToolSpan(toolName, status = "success", reason = null) {
+  const span = new ExecutionSpan({
+    type: "mcp",
+    name: toolName,
+    status,
+    reason,
+  });
+  span.end(status, reason);
+  await ExecutionSpan.post(span);
+}
+
+export async function postCommandSpan(cmd, status = "success", reason = null) {
+  const span = new ExecutionSpan({
+    type: "cmd",
+    name: cmd,
+    status,
+    reason,
+  });
+  span.end(status, reason);
+  await ExecutionSpan.post(span);
+}
+
+export async function postPluginSpan(pluginName, status = "success", reason = null) {
+  const span = new ExecutionSpan({
+    type: "plugin",
+    name: pluginName,
+    status,
+    reason,
+  });
+  span.end(status, reason);
+  await ExecutionSpan.post(span);
+}

package/src/index.js

@@ -90,6 +90,35 @@ function detectFramework() {
   return null;
 }
 
+/**
+ * Warn user if no supported framework is detected.
+ * Provide list of supported frameworks and docs link.
+ */
+function warnUnsupportedFramework(detectedFramework) {
+  if (detectedFramework) return false; // Framework detected, no warning needed
+
+  const supportedFrameworks = [
+    "LangChain (@langchain/core, @langchain/langgraph)",
+    "OpenAI (@openai/agents, openai)",
+    "Anthropic (@anthropic-ai/sdk)",
+    "Vercel AI (ai)",
+    "Google GenAI (@google/genai, @google/generative-ai)",
+    "LlamaIndex (llamaindex)",
+    "CrewAI (crewai)",
+    "Google ADK (@google/adk, google-adk)",
+    "OpenAI Agents (@openai/agents)",
+  ];
+
+  const message = [
+    "[stratos] ⚠ No supported framework detected.",
+    "[stratos] Supported frameworks:",
+    ...supportedFrameworks.map((fw) => `[stratos]   • ${fw}`),
+    "[stratos] To add your framework: https://docs.stratos.ai/integrate",
+  ].join("\n");
+
+  console.warn(message);
+  return true; // Flag indicating unsupported framework
+}
 
 function detectModel(opts) {
   return (
@@ -120,9 +149,11 @@ export function start(opts = {}) {
     process.env.STRATOS_APP_NAME ||
     process.env.npm_package_name ||
     "agent";
-  const heartbeatMs = Number(
+  // P1-03: Prevent STRATOS_HEARTBEAT_MS=0 from disabling heartbeat (unblockable agent)
+  // Minimum 1s to allow normal config but prevent 0
+  const heartbeatMs = Math.max(1000, Number(
     opts.heartbeatMs || process.env.STRATOS_HEARTBEAT_MS || 30000
-  );
+  ));
 
   if (!token) {
     console.warn(
@@ -135,10 +166,18 @@ export function start(opts = {}) {
   const ingest = `${origin}/api/ingest`;
   const heartbeatUrl = `${origin}/api/heartbeat`;
 
+  // P1-04: Helper to check if a feature flag is enabled (matches Vercel AI convention)
+  function flagEnabled(key) {
+    const val = process.env[key];
+    return val !== "0" && val !== "false";
+  }
+
   traceloop.initialize({
     appName,
     disableBatch: true,
     logLevel: process.env.STRATOS_DEBUG ? "debug" : undefined,
+    // P1-04: Respect STRATOS_RECORD_INPUTS/OUTPUTS for all frameworks (not just Vercel AI)
+    traceContent: flagEnabled('STRATOS_RECORD_INPUTS') && flagEnabled('STRATOS_RECORD_OUTPUTS'),
     exporter: new OTLPTraceExporter({
       url: ingest,
       headers: { "x-stratos-token": token },
@@ -183,6 +222,10 @@ export function start(opts = {}) {
     tools: toolsEnv,
   };
 
+  // Warn if no supported framework is detected
+  const isUnsupportedFramework = warnUnsupportedFramework(meta.framework);
+  meta.frameworkSupported = !isUnsupportedFramework;
+
   // 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
@@ -199,7 +242,14 @@ export function start(opts = {}) {
       },
       body: JSON.stringify(meta),
     })
-      .then((r) => r.json().catch(() => null))
+      .then((r) => {
+        // P1-03: Treat 401/403 (revoked token) as blocked state
+        if (r.status === 401 || r.status === 403) {
+          setBlocked(true, "token revoked or unauthorized");
+          return null;
+        }
+        return r.json().catch(() => null);
+      })
       .then((data) => {
         if (!data || typeof data.blocked !== "boolean") return;
         setBlocked(data.blocked, data.reason);

package/src/inspect-langchain.js

@@ -9,7 +9,7 @@
 //   npx stratos-inspect --fix --yes
 
 import { createRequire } from "node:module";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
 import { createInterface } from "node:readline";
@@ -317,6 +317,12 @@ export async function fixLangChain(opts = {}) {
   console.log(`\n[stratos-inspect] Using package manager: ${pm}`);
   console.log(`[stratos-inspect] Uninstalling old LangChain packages…`);
 
+  // P1-07: Back up package.json and lockfile before making changes
+  const pkgPath = join(cwd, "package.json");
+  const lockPath = join(cwd, `${pm}-lock.${pm === "yarn" ? "yaml" : pm === "bun" ? "lock" : "json"}`);
+  const pkgBackup = readFileSync(pkgPath, "utf8");
+  const lockBackup = existsSync(lockPath) ? readFileSync(lockPath, "utf8") : null;
+
   let uninstallOk = true;
   if (toRemove.length) {
     if (pm === "npm") {
@@ -353,9 +359,23 @@ export async function fixLangChain(opts = {}) {
     installOk = runPm("bun", ["add", ...installList], cwd);
   }
 
+  // P1-07: If install failed, restore backups to leave project in consistent state
+  if (!installOk) {
+    console.log(`[stratos-inspect] Restoring package.json and lockfile…`);
+    writeFileSync(pkgPath, pkgBackup);
+    if (lockBackup) writeFileSync(lockPath, lockBackup);
+    return {
+      ok: false,
+      step: "install",
+      plan,
+      reportBefore: report,
+      message: "Install failed — backups restored. Fix manually and re-run stratos-inspect --fix",
+    };
+  }
+
   const after = inspectLangChain({ cwd });
   return {
-    ok: installOk && after.status === "ok",
+    ok: after.status === "ok",
     step: "install",
     plan,
     reportBefore: report,

package/src/mcp-proxy.js

@@ -21,7 +21,8 @@
 // CRITICAL: stdout is the MCP channel — keep it clean. Route all logging to stderr.
 console.log = console.info = (...a) => process.stderr.write(a.map(String).join(" ") + "\n");
 
-import { spawn } from "node:child_process";
+// P1-06: Use cross-spawn to safely handle arguments on Windows (avoids shell injection)
+import spawn from "cross-spawn";
 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
@@ -98,10 +99,21 @@ hbTimer.unref?.();
 
 const pendingCalls = new Map();
 
-const child = spawn(cmd, args, { stdio: ["pipe", "pipe", "inherit"], shell: process.platform === "win32" });
+// P1-06: cross-spawn handles Windows paths transparently without shell
+const child = spawn(cmd, args, { stdio: ["pipe", "pipe", "inherit"] });
 child.on("error", (e) => { process.stderr.write(`[stratos-proxy] failed to start target: ${e.message}\n`); process.exit(1); });
 child.on("exit", (code) => { try { heartbeat(); clearInterval(hbTimer); } catch {} process.exit(code == null ? 0 : code); });
 
+// P1-05: Forward signals to child process and handle cleanup
+for (const sig of ["SIGINT", "SIGTERM"]) {
+  process.on(sig, () => {
+    if (child.pid && !child.killed) {
+      child.kill(sig);
+      setTimeout(() => { if (!child.killed) child.kill("SIGKILL"); }, 2000);
+    }
+  });
+}
+
 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") {
@@ -148,5 +160,11 @@ function linePump(stream, onLine) {
       if (line.trim()) onLine(line);
     }
   });
-  stream.on("end", () => { if (buf.trim()) onLine(buf); });
+  stream.on("end", () => {
+    if (buf.trim()) onLine(buf);
+    // P1-05: When host disconnects (stdin ends), close child's stdin to signal EOF
+    if (stream === process.stdin && child.stdin) {
+      child.stdin.end();
+    }
+  });
 }

package/src/otel-bridge-harness.js

@@ -0,0 +1,115 @@
+import spawn from "cross-spawn";
+import { setTimeout as sleep } from "node:timers/promises";
+
+export class OtelBridgeHarness {
+  constructor(opts = {}) {
+    this.token = opts.token || process.env.STRATOS_TOKEN;
+    this.url = opts.url || process.env.STRATOS_URL || "http://localhost:4000";
+    this.surface = opts.surface || process.env.STRATOS_SURFACE || "unknown";
+    this.port = opts.port || 4318;
+    this.child = null;
+    this.restartCount = 0;
+    this.maxRestarts = 5;
+    this.restartDelay = 1000;
+  }
+
+  start() {
+    if (this.child) {
+      console.warn("[otel-bridge-harness] Already running");
+      return;
+    }
+
+    const env = {
+      ...process.env,
+      STRATOS_TOKEN: this.token,
+      STRATOS_URL: this.url,
+      STRATOS_SURFACE: this.surface,
+      OTEL_EXPORTER_OTLP_PORT: String(this.port),
+    };
+
+    this.child = spawn("node", [require.resolve("./otel-bridge.js")], {
+      stdio: ["ignore", "pipe", "pipe"],
+      env,
+      detached: false,
+    });
+
+    this.child.stdout.on("data", (data) => {
+      console.log(`[otel-bridge] ${data.toString().trim()}`);
+    });
+
+    this.child.stderr.on("data", (data) => {
+      console.error(`[otel-bridge] ${data.toString().trim()}`);
+    });
+
+    this.child.on("error", (err) => {
+      console.error(`[otel-bridge-harness] Error: ${err.message}`);
+      this.child = null;
+      this._scheduleRestart();
+    });
+
+    this.child.on("exit", (code) => {
+      console.warn(`[otel-bridge-harness] Bridge exited (code: ${code})`);
+      this.child = null;
+      if (code !== 0) {
+        this._scheduleRestart();
+      }
+    });
+
+    console.log(`[otel-bridge-harness] Started (PID: ${this.child.pid})`);
+  }
+
+  async _scheduleRestart() {
+    if (this.restartCount >= this.maxRestarts) {
+      console.error("[otel-bridge-harness] Max restarts exceeded. Giving up.");
+      return;
+    }
+
+    this.restartCount++;
+    const delay = this.restartDelay * Math.pow(2, this.restartCount - 1);
+    console.log(`[otel-bridge-harness] Restarting in ${delay}ms (attempt ${this.restartCount}/${this.maxRestarts})`);
+
+    await sleep(delay);
+    this.start();
+  }
+
+  stop() {
+    if (!this.child) return;
+
+    console.log("[otel-bridge-harness] Stopping...");
+    this.child.kill("SIGTERM");
+
+    setTimeout(() => {
+      if (this.child && !this.child.killed) {
+        console.warn("[otel-bridge-harness] Force killing after timeout");
+        this.child.kill("SIGKILL");
+      }
+    }, 2000);
+
+    this.child = null;
+  }
+
+  isRunning() {
+    return this.child != null && !this.child.killed;
+  }
+
+  getPid() {
+    return this.child?.pid || null;
+  }
+}
+
+export async function startOtelBridge(opts = {}) {
+  const harness = new OtelBridgeHarness(opts);
+  harness.start();
+
+  process.on("SIGINT", () => {
+    harness.stop();
+    process.exit(0);
+  });
+
+  process.on("SIGTERM", () => {
+    harness.stop();
+    process.exit(0);
+  });
+
+  return harness;
+}

package/src/otel-bridge.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+
+import http from "node:http";
+import { randomBytes } from "node:crypto";
+
+const TOKEN = process.env.STRATOS_TOKEN || "";
+const STRATOS_URL = process.env.STRATOS_URL || "http://localhost:4000";
+const PORT = process.env.OTEL_EXPORTER_OTLP_PORT || 4318;
+const SURFACE = process.env.STRATOS_SURFACE || "unknown";
+
+if (!TOKEN) {
+  console.warn("[otel-bridge] Warning: STRATOS_TOKEN not set. Telemetry will not be forwarded.");
+}
+
+const hdr = { "Content-Type": "application/json", "x-stratos-token": TOKEN };
+
+function redactContent(obj) {
+  if (!obj || typeof obj !== "object") return obj;
+  if (Array.isArray(obj)) return obj.map(redactContent);
+  const copy = { ...obj };
+  for (const key of Object.keys(copy)) {
+    if (key.includes("prompt") || key.includes("request") || key.includes("response") || key.includes("content")) {
+      copy[key] = null;
+    } else if (typeof copy[key] === "object") {
+      copy[key] = redactContent(copy[key]);
+    }
+  }
+  return copy;
+}
+
+function otlpToStratosSpan(otlpMetric) {
+  const traceId = (randomBytes(16)).toString("hex");
+  const spanId = (randomBytes(8)).toString("hex");
+  const now = BigInt(Date.now()) * 1000000n;
+
+  const attributes = otlpMetric.attributes || [];
+  const attrMap = {};
+  for (const attr of attributes) {
+    attrMap[attr.key] = attr.value?.stringValue || attr.value?.doubleValue || String(attr.value);
+  }
+
+  const redacted = redactContent(attrMap);
+
+  return {
+    traceId,
+    spanId,
+    name: `${SURFACE}.otel.usage`,
+    startTimeUnixNano: now.toString(),
+    endTimeUnixNano: now.toString(),
+    attributes: [
+      { key: "traceloop.span.kind", value: { stringValue: "llm" } },
+      { key: "stratos.surface", value: { stringValue: SURFACE } },
+      { key: "otel.bridge", value: { stringValue: "true" } },
+      ...Object.entries(redacted).map(([k, v]) => ({
+        key: `otel.${k}`,
+        value: { stringValue: String(v) },
+      })),
+    ],
+  };
+}
+
+function buildStratosPayload(otlpSpans) {
+  const attr = (k, v) => ({ key: k, value: { stringValue: String(v) } });
+  return {
+    resourceSpans: [
+      {
+        resource: { attributes: [attr("service.name", SURFACE)] },
+        scopeSpans: [
+          {
+            spans: otlpSpans.map((span) => ({
+              traceId: span.traceId,
+              spanId: span.spanId,
+              name: span.name,
+              startTimeUnixNano: span.startTimeUnixNano,
+              endTimeUnixNano: span.endTimeUnixNano,
+              attributes: span.attributes,
+            })),
+          },
+        ],
+      },
+    ],
+  };
+}
+
+const server = http.createServer(async (req, res) => {
+  const { method, url } = req;
+
+  if (url === "/v1/traces" && method === "POST") {
+    let body = "";
+    req.on("data", (chunk) => {
+      body += chunk.toString();
+    });
+
+    req.on("end", async () => {
+      try {
+        const otlpPayload = JSON.parse(body);
+        const otlpSpans = [];
+
+        for (const resourceSpan of otlpPayload.resourceSpans || []) {
+          for (const scopeSpan of resourceSpan.scopeSpans || []) {
+            for (const span of scopeSpan.spans || []) {
+              otlpSpans.push(otlpToStratosSpan(span));
+            }
+          }
+        }
+
+        if (otlpSpans.length > 0 && TOKEN) {
+          const stratosPayload = buildStratosPayload(otlpSpans);
+          try {
+            const fres = await fetch(`${STRATOS_URL}/api/ingest`, {
+              method: "POST",
+              headers: hdr,
+              body: JSON.stringify(stratosPayload),
+            });
+            if (!fres.ok) {
+              console.error(`[otel-bridge] Stratos returned ${fres.status}`);
+            }
+          } catch (err) {
+            console.error(`[otel-bridge] Failed to forward to Stratos: ${err.message}`);
+          }
+        }
+
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({}));
+      } catch (err) {
+        console.error(`[otel-bridge] Parse error: ${err.message}`);
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "parse error" }));
+      }
+    });
+    return;
+  }
+
+  if (url === "/v1/metrics" && method === "POST") {
+    req.on("data", () => {}); // Drain
+    req.on("end", () => {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({}));
+    });
+    return;
+  }
+
+  if (url === "/health" && method === "GET") {
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ status: "ok", surface: SURFACE }));
+    return;
+  }
+
+  res.writeHead(404, { "Content-Type": "application/json" });
+  res.end(JSON.stringify({ error: "not found" }));
+});
+
+server.listen(PORT, "localhost", () => {
+  console.log(
+    `[otel-bridge] listening on http://localhost:${PORT}` +
+      (TOKEN ? ` (forwarding to ${STRATOS_URL})` : " (token not set; telemetry disabled)")
+  );
+  console.log(`[otel-bridge] surface: ${SURFACE}`);
+  console.log(`[otel-bridge] Set OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:${PORT} in your app`);
+});
+
+process.on("SIGINT", () => {
+  console.log("[otel-bridge] shutting down");
+  server.close(() => process.exit(0));
+});
+
+process.on("SIGTERM", () => {
+  console.log("[otel-bridge] shutting down");
+  server.close(() => process.exit(0));
+});