@lynxops/sdk 1.0.2

package/dist/index.js

@@ -0,0 +1,1339 @@
+// src/core/tracer.ts
+import { AsyncLocalStorage } from "async_hooks";
+
+// src/utils/payload.ts
+import { createHash } from "crypto";
+
+// src/config/patterns.json
+var patterns_default = {
+  riskPatterns: [
+    { pattern: "ignore", flags: "i" },
+    { pattern: "transfer", flags: "i" },
+    { pattern: "payment", flags: "i" },
+    { pattern: "delete", flags: "i" },
+    { pattern: "system prompt", flags: "i" },
+    { pattern: "bypass", flags: "i" },
+    { pattern: "shutdown", flags: "i" },
+    { pattern: "sudo", flags: "i" },
+    { pattern: "admin", flags: "i" },
+    { pattern: "leak", flags: "i" }
+  ],
+  piiRules: [
+    {
+      name: "EMAIL",
+      pattern: "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}",
+      flags: "g",
+      replacement: "[MASKED_EMAIL]"
+    },
+    {
+      name: "SSN",
+      pattern: "\\d{6}-[1-9]\\d{6}",
+      flags: "g",
+      replacement: "[MASKED_SSN]"
+    },
+    {
+      name: "CREDIT_CARD",
+      pattern: "\\b(?:\\d[ -]*?){13,16}\\b",
+      flags: "g",
+      replacement: "[MASKED_CARD]"
+    },
+    {
+      name: "PHONE",
+      pattern: "(?:01[016789]-\\d{3,4}-\\d{4})|(?:\\+82-\\d{1,2}-\\d{3,4}-\\d{4})",
+      flags: "g",
+      replacement: "[MASKED_PHONE]"
+    },
+    {
+      name: "JWT",
+      pattern: "ey[hH]bGciOi[A-Za-z0-9-_=]+\\.[A-Za-z0-9-_=]+\\.?[A-Za-z0-9-_.+/=]*",
+      flags: "g",
+      replacement: "[MASKED_JWT]"
+    },
+    {
+      name: "API_KEY",
+      pattern: "(?:sk-[a-zA-Z0-9]{32,})|(?:Bearer\\s+[a-zA-Z0-9-_.]+)",
+      flags: "gi",
+      replacement: "[MASKED_KEY]"
+    }
+  ]
+};
+
+// src/utils/payload.ts
+var RISK_PATTERNS = patterns_default.riskPatterns.map(
+  (item) => new RegExp(item.pattern, item.flags)
+);
+function getHash(data) {
+  const str = typeof data === "string" ? data : JSON.stringify(data);
+  return createHash("sha256").update(str || "").digest("hex").slice(0, 16);
+}
+function extractRiskFlags(text) {
+  const flags = [];
+  for (const pattern of RISK_PATTERNS) {
+    if (pattern.test(text)) {
+      const cleanPattern = pattern.source.replace(/\\/g, "");
+      flags.push(cleanPattern);
+    }
+  }
+  return flags;
+}
+function headTailTruncate(text, maxLen = 1e3) {
+  if (text.length <= maxLen) return text;
+  const reserve = 80;
+  const half = Math.floor((maxLen - reserve) / 2);
+  if (half <= 0) return "... [TRUNCATED] ...";
+  const head = text.substring(0, half);
+  const tail = text.substring(text.length - half);
+  const truncatedCount = text.length - (head.length + tail.length);
+  return `${head}... [TRUNCATED ${truncatedCount} CHARS] ...${tail}`;
+}
+var PII_RULES = patterns_default.piiRules.map((rule) => ({
+  name: rule.name,
+  regex: new RegExp(rule.pattern, rule.flags),
+  replacement: rule.replacement
+}));
+var SENSITIVE_KEY_PATTERN = /(?:api[-_]?key|authorization|auth[-_]?token|bearer|client[-_]?secret|cookie|credential|jwt|password|private[-_]?key|refresh[-_]?token|secret|session[-_]?token|token)/i;
+function maskPIIString(text) {
+  let masked = text;
+  for (const rule of PII_RULES) {
+    masked = masked.replace(rule.regex, rule.replacement);
+  }
+  return masked;
+}
+function recursiveMaskPII(obj) {
+  if (obj === null || obj === void 0) return obj;
+  if (typeof obj === "string") {
+    return maskPIIString(obj);
+  }
+  if (Array.isArray(obj)) {
+    return obj.map((item) => recursiveMaskPII(item));
+  }
+  if (typeof obj === "object") {
+    const res = {};
+    for (const key of Object.keys(obj)) {
+      if (SENSITIVE_KEY_PATTERN.test(key)) {
+        res[key] = "[MASKED_SECRET]";
+      } else {
+        res[key] = recursiveMaskPII(obj[key]);
+      }
+    }
+    return res;
+  }
+  return obj;
+}
+function processPayload(payload, config) {
+  if (!payload || typeof payload !== "object") return payload;
+  let copy;
+  try {
+    copy = JSON.parse(JSON.stringify(payload));
+  } catch {
+    return { error: "[Unserializable Payload]" };
+  }
+  copy = recursiveMaskPII(copy);
+  if (config.captureInput === false && "input" in copy) {
+    delete copy.input;
+  }
+  if (config.captureOutput === false && "output" in copy) {
+    delete copy.output;
+  }
+  const mode = config.captureMode || "smart";
+  let textToAnalyze = "";
+  if (copy.input) {
+    textToAnalyze += typeof copy.input === "string" ? copy.input : JSON.stringify(copy.input);
+  }
+  if (copy.output) {
+    textToAnalyze += typeof copy.output === "string" ? copy.output : JSON.stringify(copy.output);
+  }
+  const riskFlags = textToAnalyze ? extractRiskFlags(textToAnalyze) : [];
+  if (riskFlags.length > 0) {
+    copy.riskFlags = riskFlags;
+  }
+  if (mode === "metadata-only") {
+    if ("input" in copy) {
+      const inputStr = typeof copy.input === "string" ? copy.input : JSON.stringify(copy.input);
+      copy.promptHash = getHash(copy.input);
+      copy.promptLength = inputStr.length;
+      delete copy.input;
+    }
+    if ("output" in copy) {
+      const outputStr = typeof copy.output === "string" ? copy.output : JSON.stringify(copy.output);
+      copy.responseHash = getHash(copy.output);
+      copy.responseLength = outputStr.length;
+      delete copy.output;
+    }
+    return copy;
+  }
+  if (mode === "smart") {
+    const maxLen = config.maxPayloadLength ?? 1e3;
+    const walkAndSmartTruncate = (obj) => {
+      if (!obj || typeof obj !== "object") return obj;
+      if (Array.isArray(obj)) {
+        return obj.map((item) => walkAndSmartTruncate(item));
+      }
+      const res = {};
+      for (const key of Object.keys(obj)) {
+        const priorityKeys = [
+          "spanid",
+          "parentspanid",
+          "latency",
+          "usage",
+          "cost",
+          "error",
+          "path",
+          "riskflags"
+        ];
+        if (priorityKeys.includes(key.toLowerCase())) {
+          res[key] = obj[key];
+        } else if (typeof obj[key] === "object") {
+          res[key] = walkAndSmartTruncate(obj[key]);
+        } else if (typeof obj[key] === "string") {
+          res[key] = headTailTruncate(obj[key], maxLen);
+        } else {
+          res[key] = obj[key];
+        }
+      }
+      return res;
+    };
+    return walkAndSmartTruncate(copy);
+  }
+  return copy;
+}
+
+// src/utils/id.ts
+import { randomBytes, randomUUID } from "crypto";
+function generateTraceId() {
+  try {
+    return randomBytes(16).toString("hex");
+  } catch {
+    return randomUUID().replace(/-/g, "").slice(0, 32);
+  }
+}
+function generateSpanId() {
+  try {
+    return randomBytes(8).toString("hex");
+  } catch {
+    return randomUUID().replace(/-/g, "").slice(0, 16);
+  }
+}
+function generateEventId() {
+  try {
+    return randomBytes(16).toString("hex");
+  } catch {
+    return randomUUID().replace(/-/g, "").slice(0, 32);
+  }
+}
+
+// src/utils/usage.ts
+function extractTokenUsage(result) {
+  if (!result || typeof result !== "object") return void 0;
+  const usage = result.usage ?? result.llmOutput?.tokenUsage ?? result.generationInfo?.tokenUsage ?? result.response_metadata?.tokenUsage ?? result.response_metadata?.usage;
+  if (usage) {
+    const promptTokens = usage.prompt_tokens ?? usage.input_tokens ?? usage.promptTokens ?? usage.inputTokens ?? 0;
+    const completionTokens = usage.completion_tokens ?? usage.output_tokens ?? usage.completionTokens ?? usage.outputTokens ?? 0;
+    return {
+      promptTokens,
+      completionTokens,
+      totalTokens: promptTokens + completionTokens
+    };
+  }
+  const usageMetadata = result.usageMetadata;
+  if (usageMetadata) {
+    const promptTokens = usageMetadata.promptTokenCount ?? 0;
+    const completionTokens = usageMetadata.candidatesTokenCount ?? usageMetadata.completionTokenCount ?? 0;
+    return {
+      promptTokens,
+      completionTokens,
+      totalTokens: promptTokens + completionTokens
+    };
+  }
+  return void 0;
+}
+
+// src/instrumentation/index.ts
+function stableHash(data) {
+  const str = typeof data === "string" ? data : JSON.stringify(data ?? "");
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    hash = hash * 31 + str.charCodeAt(i) >>> 0;
+  }
+  return hash.toString(16).padStart(8, "0");
+}
+function getProvider(path, model) {
+  const pathStr = path.join(".");
+  if (pathStr.includes("messages.create")) return "anthropic";
+  if (pathStr.includes("generateContent")) return "google";
+  if (pathStr.includes("generateText") || pathStr.includes("streamText")) return "vercel-ai";
+  if (pathStr.includes("ollama")) return "ollama";
+  if (pathStr.includes("cohere")) return "cohere";
+  if (model?.toLowerCase().includes("claude")) return "anthropic";
+  if (model?.toLowerCase().includes("gemini")) return "google";
+  return "openai";
+}
+function getMessages(input) {
+  if (Array.isArray(input?.messages)) return input.messages;
+  if (Array.isArray(input?.contents)) return input.contents;
+  if (Array.isArray(input?.prompt)) return input.prompt;
+  return void 0;
+}
+function getTextLength(data) {
+  if (data === void 0 || data === null) return 0;
+  if (typeof data === "string") return data.length;
+  try {
+    return JSON.stringify(data).length;
+  } catch {
+    return 0;
+  }
+}
+function extractLlmMetadata(input, path) {
+  const messages = getMessages(input);
+  const systemMessage = messages?.find((item) => item?.role === "system");
+  const userMessage = [...messages ?? []].reverse().find((item) => item?.role === "user");
+  const model = input?.model ?? input?.modelName;
+  const maxTokens = input?.max_tokens ?? input?.maxTokens ?? input?.maxOutputTokens;
+  return {
+    provider: getProvider(path, model),
+    model,
+    temperature: input?.temperature,
+    topP: input?.top_p ?? input?.topP,
+    maxTokens,
+    seed: input?.seed,
+    promptVersion: input?.promptVersion,
+    systemPromptHash: systemMessage ? stableHash(systemMessage) : void 0,
+    userPromptHash: userMessage ? stableHash(userMessage) : void 0,
+    messageCount: messages?.length,
+    contextLength: getTextLength(input)
+  };
+}
+function summarizeResult(result) {
+  if (result === void 0 || result === null) return void 0;
+  if (typeof result === "string") return result.slice(0, 240);
+  if (typeof result === "number" || typeof result === "boolean") return String(result);
+  try {
+    return JSON.stringify(result).slice(0, 240);
+  } catch {
+    return "[Unserializable Result]";
+  }
+}
+function instrumentLLM(tracer, instance, optionsOrLabel = "llm.inference") {
+  const options = typeof optionsOrLabel === "string" ? { modelLabel: optionsOrLabel } : optionsOrLabel;
+  const modelLabel = options.modelLabel ?? "llm.inference";
+  const customRule = options.customRule;
+  const isTargetLLMMethod = (path) => {
+    if (customRule?.isTargetMethod) {
+      return customRule.isTargetMethod(path);
+    }
+    const pathStr = path.join(".");
+    return pathStr === "chat.completions.create" || // OpenAI
+    pathStr === "messages.create" || // Anthropic (Claude)
+    pathStr === "models.generateContent" || // Google Gen AI 신규
+    pathStr === "generateContent" || // Google Generative AI 기존
+    pathStr === "generateText" || // Vercel AI SDK
+    pathStr === "streamText" || // Vercel AI SDK
+    pathStr === "generateObject" || // Vercel AI SDK
+    pathStr === "streamObject" || // Vercel AI SDK
+    pathStr === "ollama.chat" || // Ollama Chat
+    pathStr === "ollama.generate" || // Ollama Generate
+    pathStr === "cohere.chat" || // Cohere Chat
+    pathStr === "cohere.generate" || // Cohere Generate
+    pathStr === "chat" || // Ollama/Cohere direct
+    pathStr === "invoke" || // LangChain
+    pathStr === "predict";
+  };
+  const createRecursiveProxy = (target, path = []) => {
+    if (target == null || typeof target !== "object" && typeof target !== "function") {
+      return target;
+    }
+    return new Proxy(target, {
+      get(obj, prop) {
+        if (typeof prop === "symbol") {
+          return Reflect.get(obj, prop);
+        }
+        const val = obj[prop];
+        const newPath = [...path, prop];
+        if (typeof val === "function" && isTargetLLMMethod(newPath)) {
+          return async function(...args) {
+            const context = LynxTracer.getStore();
+            const spanId = generateSpanId();
+            const parentSpanId = context?.spanId;
+            const startTime = Date.now();
+            const rawInput = customRule?.extractInput ? customRule.extractInput(args) : args[0];
+            const llmMetadata = extractLlmMetadata(rawInput, newPath);
+            if (context) {
+              tracer.captureInternal("LLM_CALL", modelLabel, {
+                input: rawInput,
+                path: newPath.join("."),
+                phase: "start",
+                spanId,
+                parentSpanId,
+                ...llmMetadata
+              }, context);
+            }
+            try {
+              const result = Reflect.apply(val, obj, args);
+              const resolvedResult = result instanceof Promise ? await result : result;
+              const latency = Date.now() - startTime;
+              const rawOutput = customRule?.extractOutput ? customRule.extractOutput(resolvedResult) : resolvedResult;
+              const usage = customRule?.extractUsage ? customRule.extractUsage(resolvedResult) : extractTokenUsage(resolvedResult);
+              if (context) {
+                tracer.captureInternal("LLM_CALL", modelLabel, {
+                  output: rawOutput,
+                  phase: "end",
+                  spanId,
+                  parentSpanId,
+                  latency,
+                  usage,
+                  ...llmMetadata
+                }, context);
+              }
+              return resolvedResult;
+            } catch (err) {
+              const error = err;
+              const latency = Date.now() - startTime;
+              if (context) {
+                tracer.captureInternal("ERROR", modelLabel, {
+                  error: error.message,
+                  phase: "error",
+                  spanId,
+                  parentSpanId,
+                  latency
+                }, context);
+              }
+              throw err;
+            }
+          };
+        }
+        if (val && (typeof val === "object" || typeof val === "function")) {
+          return createRecursiveProxy(val, newPath);
+        }
+        return val;
+      }
+    });
+  };
+  return createRecursiveProxy(instance);
+}
+function instrumentTool(tracer, toolName, fn, metadata = {}) {
+  return (async (...args) => {
+    const context = LynxTracer.getStore();
+    const spanId = generateSpanId();
+    const parentSpanId = context?.spanId;
+    const startTime = Date.now();
+    if (context) {
+      tracer.captureInternal("TOOL_CALL", toolName, {
+        toolName,
+        toolVersion: metadata.toolVersion,
+        sideEffect: metadata.sideEffect,
+        riskLevel: metadata.riskLevel,
+        externalTarget: metadata.externalTarget,
+        idempotencyKey: metadata.idempotencyKey,
+        args: args[0],
+        argsHash: stableHash(args[0]),
+        input: args[0],
+        phase: "start",
+        spanId,
+        parentSpanId
+      }, context);
+    }
+    try {
+      const result = fn(...args);
+      const resolvedResult = result instanceof Promise ? await result : result;
+      const latency = Date.now() - startTime;
+      if (context) {
+        tracer.captureInternal("TOOL_RESULT", toolName, {
+          toolName,
+          toolVersion: metadata.toolVersion,
+          result: resolvedResult,
+          resultSummary: summarizeResult(resolvedResult),
+          output: resolvedResult,
+          phase: "end",
+          spanId,
+          parentSpanId,
+          latency
+        }, context);
+      }
+      return resolvedResult;
+    } catch (err) {
+      const error = err;
+      const latency = Date.now() - startTime;
+      if (context) {
+        tracer.captureInternal("ERROR", toolName, {
+          error: error.message,
+          phase: "error",
+          spanId,
+          parentSpanId,
+          latency
+        }, context);
+      }
+      throw err;
+    }
+  });
+}
+
+// src/core/tracer.ts
+var SDK_VERSION = "1.0.0";
+var DEFAULT_ENDPOINT = "https://api.lynxops.co";
+var DEFAULT_MAX_QUEUE_SIZE = 1e3;
+var DEFAULT_BATCH_SIZE = 50;
+var LynxPolicyError = class extends Error {
+  constructor(message, action, policyId, severity, reason, metadata) {
+    super(message);
+    this.action = action;
+    this.policyId = policyId;
+    this.severity = severity;
+    this.reason = reason;
+    this.metadata = metadata;
+    this.name = "LynxPolicyError";
+  }
+  action;
+  policyId;
+  severity;
+  reason;
+  metadata;
+};
+function stableHash2(data) {
+  const str = typeof data === "string" ? data : JSON.stringify(data ?? "");
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    hash = hash * 31 + str.charCodeAt(i) >>> 0;
+  }
+  return hash.toString(16).padStart(8, "0");
+}
+var LynxTracer = class _LynxTracer {
+  static storage = new AsyncLocalStorage();
+  static instances = /* @__PURE__ */ new Set();
+  static beforeExitHookRegistered = false;
+  config;
+  pendingPromises = /* @__PURE__ */ new Set();
+  eventQueue = [];
+  retryQueue = [];
+  lastFailureTime = 0;
+  backoffDelayMs = 1e3;
+  flushTimer = null;
+  isShuttingDown = false;
+  isFlushInProgress = false;
+  consecutiveFlushFailures = 0;
+  circuitOpenedAt = 0;
+  droppedEventCount = 0;
+  lastDeliveryAt;
+  lastError;
+  /**
+   * Creates a tracer with the provided Lynx telemetry configuration.
+   *
+   * The constructor starts a background flush timer. The timer is unref'ed in
+   * Node.js so it will not keep the process alive by itself. Call `shutdown()`
+   * in tests, short-lived scripts, or server shutdown hooks to flush remaining
+   * telemetry and clear the timer.
+   *
+   * @param config Runtime configuration for telemetry capture and delivery.
+   */
+  constructor(config) {
+    this.config = {
+      ...config,
+      endpoint: config.endpoint ?? DEFAULT_ENDPOINT
+    };
+    _LynxTracer.instances.add(this);
+    const interval = this.config.delivery?.flushIntervalMs ?? 3e3;
+    this.flushTimer = setInterval(() => {
+      void this.flushInternal(false);
+    }, interval);
+    if (this.flushTimer && typeof this.flushTimer.unref === "function") {
+      this.flushTimer.unref();
+    }
+    if (typeof process !== "undefined" && !_LynxTracer.beforeExitHookRegistered) {
+      _LynxTracer.beforeExitHookRegistered = true;
+      process.once("beforeExit", () => {
+        void _LynxTracer.shutdownAll();
+      });
+    }
+  }
+  static async shutdownAll() {
+    await Promise.allSettled(
+      Array.from(_LynxTracer.instances).map((instance) => instance.shutdown())
+    );
+  }
+  /**
+   * Returns the current Lynx async execution context, if one is active.
+   *
+   * This is mainly useful for advanced instrumentation helpers that need to
+   * attach their own telemetry to the currently running `run()` context.
+   *
+   * @returns The current context, or `undefined` when called outside `run()`.
+   */
+  static getStore() {
+    return _LynxTracer.storage.getStore();
+  }
+  getFlushOnRunEnd() {
+    return this.config.delivery?.flushOnRunEnd ?? false;
+  }
+  getRequestTimeoutMs() {
+    return this.config.delivery?.timeoutMs ?? 1e3;
+  }
+  isBackgroundOnly() {
+    return (this.config.delivery?.mode ?? "BACKGROUND") === "BACKGROUND";
+  }
+  getMaxQueueSize() {
+    return this.config.delivery?.maxQueueSize ?? DEFAULT_MAX_QUEUE_SIZE;
+  }
+  getOverflowStrategy() {
+    return this.config.delivery?.overflowStrategy ?? "DROP_OLDEST";
+  }
+  enqueueEvent(event) {
+    const maxQueueSize = this.getMaxQueueSize();
+    if (maxQueueSize <= 0) {
+      this.droppedEventCount += 1;
+      return false;
+    }
+    const totalQueued = this.eventQueue.length + this.retryQueue.length;
+    if (totalQueued >= maxQueueSize) {
+      this.droppedEventCount += 1;
+      if (this.getOverflowStrategy() === "DROP_NEWEST") {
+        return false;
+      }
+      if (this.retryQueue.length > 0) {
+        this.retryQueue.shift();
+      } else {
+        this.eventQueue.shift();
+      }
+    }
+    this.eventQueue.push(event);
+    return true;
+  }
+  enqueueRetryEvent(event) {
+    const maxQueueSize = this.getMaxQueueSize();
+    if (maxQueueSize <= 0) {
+      this.droppedEventCount += 1;
+      return false;
+    }
+    const totalQueued = this.eventQueue.length + this.retryQueue.length;
+    if (totalQueued >= maxQueueSize) {
+      this.droppedEventCount += 1;
+      if (this.getOverflowStrategy() === "DROP_NEWEST") {
+        return false;
+      }
+      if (this.eventQueue.length > 0) {
+        this.eventQueue.shift();
+      } else {
+        this.retryQueue.shift();
+      }
+    }
+    this.retryQueue.push(event);
+    return true;
+  }
+  /**
+   * Flushes queued telemetry events to the Lynx ingestion endpoint.
+   *
+   * Events are sent in a single batch request. If delivery fails, the batch is
+   * moved into an in-memory retry queue and future flushes are delayed with
+   * exponential backoff. Normal applications usually do not need to call this
+   * manually because the tracer flushes on an interval.
+   *
+   * @returns A promise that resolves after the current flush attempt completes.
+   */
+  async flush() {
+    await this.flushInternal(true);
+  }
+  async flushInternal(waitForDelivery) {
+    if (this.eventQueue.length === 0 && this.retryQueue.length === 0) {
+      return;
+    }
+    if (this.isFlushInProgress) {
+      return;
+    }
+    if (this.isCircuitOpen()) {
+      return;
+    }
+    if (this.lastFailureTime > 0 && Date.now() - this.lastFailureTime < this.backoffDelayMs) {
+      return;
+    }
+    const eventsToFlush = [...this.retryQueue, ...this.eventQueue];
+    this.retryQueue.length = 0;
+    this.eventQueue.length = 0;
+    if (eventsToFlush.length === 0) {
+      return;
+    }
+    this.isFlushInProgress = true;
+    const url = `${this.config.endpoint}/openapi/v1/events/batch`;
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.config.apiKey) {
+      headers["x-api-key"] = this.config.apiKey;
+      headers["Authorization"] = `Bearer ${this.config.apiKey}`;
+    }
+    const promise = fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(eventsToFlush),
+      signal: AbortSignal.timeout(this.getRequestTimeoutMs())
+    }).then(async (res) => {
+      if (!res.ok) {
+        const text = await res.text();
+        console.error(
+          `[LynxTracer] telemetry batch flush failed with status ${res.status}: ${text}`
+        );
+        this.handleFailedEvents(eventsToFlush, "http_error");
+      } else {
+        const result = await res.json().catch(() => ({ success: true }));
+        if (result && result.success === false) {
+          console.error(
+            "[LynxTracer] telemetry batch flush returned failed details:",
+            result
+          );
+          this.handleFailedEvents(eventsToFlush, "batch_failed");
+        } else {
+          this.handleSuccessfulFlush();
+        }
+      }
+    }).catch((err) => {
+      console.error("LynxTracer telemetry batch flush failed:", err);
+      this.handleFailedEvents(eventsToFlush, "network_error");
+    }).finally(() => {
+      this.pendingPromises.delete(promise);
+      this.isFlushInProgress = false;
+    });
+    this.pendingPromises.add(promise);
+    if (waitForDelivery || this.isShuttingDown) {
+      await promise;
+    }
+  }
+  /**
+   * Returns a lightweight snapshot of SDK delivery health.
+   *
+   * Use this for readiness diagnostics, operational dashboards, or tests. The
+   * status reflects local SDK state only; it does not perform a network request.
+   *
+   * @returns Current queue, circuit breaker, and delivery state.
+   */
+  getStatus() {
+    return {
+      queueSize: this.eventQueue.length + this.retryQueue.length,
+      droppedEvents: this.droppedEventCount,
+      circuitState: this.getCircuitState(),
+      lastDeliveryAt: this.lastDeliveryAt,
+      lastError: this.lastError,
+      pendingTransmissions: this.pendingPromises.size
+    };
+  }
+  /**
+   * Flushes queued telemetry and releases SDK timers.
+   *
+   * Use this for graceful process shutdown, tests, CLI scripts, and serverless
+   * handlers where the runtime may terminate before the background interval
+   * fires. Calling `shutdown()` more than once is safe.
+   *
+   * @returns A promise that resolves after pending telemetry transmissions settle.
+   */
+  async shutdown(options = {}) {
+    if (this.isShuttingDown) return;
+    this.isShuttingDown = true;
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+    const shutdownWork = async () => {
+      await this.flushInternal(true);
+      if (this.pendingPromises.size > 0) {
+        await Promise.allSettled(Array.from(this.pendingPromises));
+      }
+    };
+    if (options.timeoutMs !== void 0) {
+      await Promise.race([
+        shutdownWork(),
+        new Promise((resolve) => setTimeout(resolve, options.timeoutMs))
+      ]);
+    } else {
+      await shutdownWork();
+    }
+    _LynxTracer.instances.delete(this);
+  }
+  isCircuitBreakerEnabled() {
+    return this.config.circuitBreaker?.enabled ?? true;
+  }
+  isCircuitOpen() {
+    if (!this.isCircuitBreakerEnabled() || this.circuitOpenedAt === 0) {
+      return false;
+    }
+    return Date.now() - this.circuitOpenedAt < (this.config.circuitBreaker?.cooldownMs ?? 3e4);
+  }
+  getCircuitState() {
+    if (!this.isCircuitBreakerEnabled()) {
+      return "DISABLED";
+    }
+    if (this.circuitOpenedAt === 0) {
+      return "CLOSED";
+    }
+    return this.isCircuitOpen() ? "OPEN" : "HALF_OPEN";
+  }
+  handleSuccessfulFlush() {
+    this.lastFailureTime = 0;
+    this.backoffDelayMs = 1e3;
+    this.consecutiveFlushFailures = 0;
+    this.circuitOpenedAt = 0;
+    this.lastDeliveryAt = (/* @__PURE__ */ new Date()).toISOString();
+    this.lastError = void 0;
+  }
+  handleFailedEvents(events, reason) {
+    this.lastFailureTime = Date.now();
+    this.consecutiveFlushFailures += 1;
+    if (this.isCircuitBreakerEnabled() && this.consecutiveFlushFailures >= (this.config.circuitBreaker?.failureThreshold ?? 3)) {
+      this.circuitOpenedAt = Date.now();
+      console.warn(
+        `[LynxTracer] Telemetry circuit breaker opened after ${this.consecutiveFlushFailures} consecutive failures. Reason: ${reason}.`
+      );
+    }
+    this.lastError = reason;
+    for (const event of events) {
+      this.enqueueRetryEvent(event);
+    }
+    this.backoffDelayMs = Math.min(this.backoffDelayMs * 2, 6e4);
+    console.warn(
+      `[LynxTracer] Offline retry buffer saved ${events.length} events. Total size: ${this.retryQueue.length}. Backing off for ${this.backoffDelayMs}ms.`
+    );
+  }
+  /**
+   * Runs code inside a Lynx trace context.
+   *
+   * Every semantic event, instrumented LLM call, and instrumented tool call made
+   * inside `executionBlock` will be associated with the same run/session. Nested
+   * `run()` calls automatically inherit the parent run id and create a child
+   * span relationship.
+   *
+   * @typeParam T The value returned by the wrapped execution block.
+   * @param optionsOrAgentName Agent name or detailed run options.
+   * @param executionBlock Function to execute while the Lynx context is active.
+   * @returns The original return value of `executionBlock`.
+   *
+   * @example
+   * ```ts
+   * await lynx.run({ agentName: "SupportAgent", sessionId: "s-123" }, async () => {
+   *   lynx.userInput("I need a refund");
+   *   return await agent.handle();
+   * });
+   * ```
+   */
+  async run(optionsOrAgentName, executionBlock) {
+    const options = typeof optionsOrAgentName === "string" ? { agentName: optionsOrAgentName } : optionsOrAgentName;
+    const agentName = options.agentName;
+    const parentContext = _LynxTracer.storage.getStore();
+    const runId = options.runId ?? (parentContext ? parentContext.runId : generateTraceId());
+    const parentSpanId = parentContext ? parentContext.spanId : void 0;
+    const spanId = generateSpanId();
+    const workspaceId = options.workspaceId ?? parentContext?.workspaceId ?? this.config.workspaceId ?? process.env.LYNX_WORKSPACE_ID;
+    const agentId = options.agentId ?? parentContext?.agentId ?? this.config.agentId ?? process.env.LYNX_AGENT_ID ?? agentName;
+    const sessionId = options.sessionId ?? parentContext?.sessionId ?? process.env.LYNX_SESSION_ID ?? `session_${runId}`;
+    const sampled = parentContext ? parentContext.sampled ?? true : this.config.sampleRate !== void 0 ? Math.random() < this.config.sampleRate : true;
+    const currentContext = {
+      runId,
+      agentName,
+      spanId,
+      parentSpanId,
+      sampled,
+      workspaceId,
+      agentId,
+      sessionId,
+      eventCounts: parentContext?.eventCounts ?? {},
+      attributes: { ...parentContext?.attributes }
+    };
+    this.captureInternal(
+      "CONTEXT_ALERT",
+      `run.start:${agentName}`,
+      {
+        message: `Agent execution thread started`,
+        phase: "start",
+        spanId,
+        parentSpanId
+      },
+      currentContext
+    );
+    const startTime = Date.now();
+    return _LynxTracer.storage.run(currentContext, async () => {
+      try {
+        const result = await executionBlock();
+        const latency = Date.now() - startTime;
+        this.captureInternal(
+          "CONTEXT_ALERT",
+          `run.end:${agentName}`,
+          {
+            message: `Agent execution thread succeeded`,
+            phase: "end",
+            spanId,
+            parentSpanId,
+            latency
+          },
+          currentContext
+        );
+        return result;
+      } catch (err) {
+        const latency = Date.now() - startTime;
+        this.captureInternal(
+          "ERROR",
+          `run.error:${agentName}`,
+          {
+            error: err.message,
+            phase: "error",
+            spanId,
+            parentSpanId,
+            latency
+          },
+          currentContext
+        );
+        throw err;
+      } finally {
+        if (this.getFlushOnRunEnd()) {
+          await this.flushInternal(!this.isBackgroundOnly());
+        }
+        if (!this.isBackgroundOnly() && this.pendingPromises.size > 0) {
+          await Promise.all(Array.from(this.pendingPromises));
+        }
+      }
+    });
+  }
+  /**
+   * Captures a custom context event for the active run.
+   *
+   * Prefer semantic helpers such as `userInput()`, `decision()`, `context()`,
+   * `memory()`, and `outcome()` when the event has a clear meaning. Use `log()`
+   * for compatibility or for ad-hoc diagnostic payloads.
+   *
+   * @param label Human-readable event label.
+   * @param payload JSON-serializable diagnostic payload.
+   */
+  log(label, payload) {
+    const context = _LynxTracer.storage.getStore();
+    if (context) {
+      this.captureInternal("CONTEXT_ALERT", label, payload, context);
+    } else {
+      console.warn(
+        "[LynxTracer] Log was called outside a running context. Event ignored."
+      );
+    }
+  }
+  /**
+   * Captures the user input that started or influenced the current agent run.
+   *
+   * This event gives root-cause analysis a clear starting point and separates
+   * user intent from prompts, tool results, and internal agent state.
+   *
+   * @param input Raw or structured user input.
+   * @param metadata Optional metadata such as `userId`, `channel`, or `locale`.
+   */
+  userInput(input, metadata = {}) {
+    this.capture("USER_INPUT", "user.input", { input, ...metadata });
+  }
+  /**
+   * Captures an agent decision and the reason behind it.
+   *
+   * Use this when the agent chooses a workflow, tool, policy branch, or final
+   * action. The `options` object can include candidates, confidence scores, or
+   * any domain-specific reasoning metadata.
+   *
+   * @param reason Short explanation of the selected action.
+   * @param options Optional structured metadata about the decision.
+   */
+  decision(reasonOrDecision, options = {}) {
+    if (typeof reasonOrDecision === "string") {
+      this.capture("AGENT_DECISION", "agent.decision", {
+        reason: reasonOrDecision,
+        ...options
+      });
+      return;
+    }
+    this.capture("AGENT_DECISION", `agent.decision:${reasonOrDecision.name}`, {
+      ...reasonOrDecision,
+      ...reasonOrDecision.metadata
+    });
+  }
+  /**
+   * Captures retrieved or constructed context used by the agent.
+   *
+   * Use this for RAG results, conversation summaries, selected documents,
+   * request-scoped state, or any context that may have influenced the next LLM
+   * or tool call.
+   *
+   * @param data Context data or a summary of the context.
+   * @param metadata Optional metadata such as source, query, score, or label.
+   */
+  context(labelOrData, dataOrMetadata = {}, metadata = {}) {
+    if (typeof labelOrData === "string") {
+      this.capture("CONTEXT_RETRIEVAL", labelOrData, {
+        data: dataOrMetadata,
+        ...metadata
+      });
+      return;
+    }
+    this.capture(
+      "CONTEXT_RETRIEVAL",
+      dataOrMetadata.label ?? "context.retrieval",
+      {
+        data: labelOrData,
+        ...dataOrMetadata
+      }
+    );
+  }
+  /**
+   * Adds attributes to the current run context.
+   *
+   * Attributes are attached to subsequent events captured in the same async
+   * context. Use this for stable request or business identifiers such as
+   * `orderId`, `tenantId`, or `workflowId`.
+   *
+   * @param attributes Key-value attributes to merge into the active context.
+   */
+  setAttributes(attributes) {
+    const context = _LynxTracer.storage.getStore();
+    if (!context) {
+      console.warn("[LynxTracer] setAttributes called outside a run context.");
+      return;
+    }
+    context.attributes = {
+      ...context.attributes,
+      ...attributes
+    };
+  }
+  /**
+   * Captures access to short-term or long-term agent memory.
+   *
+   * This helps identify stale memory, missing memory, or memory values that
+   * influenced an incorrect action.
+   *
+   * @param operation Memory operation name, such as `read`, `write`, or `search`.
+   * @param data Memory key/value, query result, or a safe summary.
+   * @param metadata Optional metadata such as hit/miss, store name, or freshness.
+   */
+  memory(operation, data, metadata = {}) {
+    this.capture("MEMORY_ACCESS", `memory.${operation}`, {
+      operation,
+      data,
+      ...metadata
+    });
+  }
+  /**
+   * Captures the final technical and business outcome of the current session.
+   *
+   * Use this to distinguish "the code ran successfully" from "the business task
+   * succeeded." That distinction is central for detecting AI failures that do
+   * not throw runtime exceptions.
+   *
+   * @param options Outcome status, business status, reason, impact, and metadata.
+   */
+  outcome(options) {
+    this.capture("SESSION_OUTCOME", "session.outcome", options);
+  }
+  /**
+   * Captures a human-readable annotation for the active run.
+   *
+   * `annotate()` is intended for breadcrumbs that help operators understand the
+   * trace but do not fit one of the stricter semantic event helpers.
+   *
+   * @param label Annotation label.
+   * @param payload JSON-serializable annotation payload.
+   */
+  annotate(label, payload) {
+    this.capture("CONTEXT_ALERT", label, { annotation: true, ...payload });
+  }
+  /**
+   * Captures a semantic event for the active Lynx run context.
+   */
+  capture(eventType, label, payload) {
+    const context = _LynxTracer.storage.getStore();
+    if (!context) {
+      console.warn(
+        `[LynxTracer] Warning: event ${eventType} was captured outside a LynxTracer context!`
+      );
+      return;
+    }
+    this.captureInternal(eventType, label, payload, context);
+  }
+  /**
+   * Captures an event using an explicit Lynx context.
+   *
+   * This method is public for low-level instrumentation modules, but application
+   * code should usually call the semantic helpers or `instrumentLLM()` /
+   * `instrumentTool()` instead. Payloads are processed for PII masking,
+   * capture-mode filtering, runtime metadata, and loop detection before they are
+   * queued for delivery.
+   *
+   * @param eventType Lynx event type to record.
+   * @param label Human-readable event label.
+   * @param payload JSON-serializable event payload.
+   * @param context Explicit Lynx trace context.
+   */
+  captureInternal(eventType, label, payload, context) {
+    const isError = eventType === "ERROR" || payload && (payload.error || "error" in payload);
+    if (context.sampled === false && !isError) {
+      return;
+    }
+    const loopPayload = this.detectLoop(eventType, label, payload, context);
+    const processedPayload = processPayload(
+      {
+        ...context.attributes,
+        ...payload,
+        ...loopPayload,
+        sdkVersion: SDK_VERSION,
+        droppedEventCount: this.droppedEventCount || void 0,
+        appVersion: payload?.appVersion ?? this.config.appVersion,
+        deploymentId: payload?.deploymentId ?? this.config.deploymentId,
+        environment: payload?.environment ?? this.config.environment,
+        policyVersion: payload?.policyVersion ?? this.config.policyVersion
+      },
+      this.config
+    );
+    const eventPayload = {
+      ...processedPayload,
+      spanId: processedPayload.spanId || context.spanId,
+      parentSpanId: processedPayload.parentSpanId || context.parentSpanId
+    };
+    const eventDto = {
+      eventId: generateEventId(),
+      clientId: this.config.clientId,
+      runId: context.runId,
+      agentName: context.agentName,
+      eventType,
+      label,
+      payload: eventPayload,
+      timestamp: Date.now(),
+      workspaceId: context.workspaceId,
+      agentId: context.agentId,
+      sessionId: context.sessionId,
+      schemaVersion: "1"
+    };
+    const queued = this.enqueueEvent(eventDto);
+    if (!queued) {
+      return;
+    }
+    if (loopPayload.loopDetected && eventType !== "LOOP_DETECTED") {
+      this.captureInternal(
+        "LOOP_DETECTED",
+        `loop:${label}`,
+        {
+          repeatedLabel: label,
+          loopCount: loopPayload.loopCount,
+          argsHash: loopPayload.argsHash
+        },
+        context
+      );
+    }
+    const maxBatchSize = this.config.delivery?.batchSize ?? DEFAULT_BATCH_SIZE;
+    if (!this.isBackgroundOnly() && this.eventQueue.length >= maxBatchSize) {
+      void this.flushInternal(false);
+    }
+  }
+  /**
+   * Wraps an LLM client with automatic Lynx telemetry.
+   *
+   * The returned proxy preserves the original client shape while intercepting
+   * supported generation methods such as OpenAI `chat.completions.create`,
+   * Anthropic `messages.create`, Google `generateContent`, Vercel AI SDK
+   * `generateText`, LangChain `invoke`, and similar methods. Captured telemetry
+   * includes input/output, provider, model, generation config, latency, token
+   * usage, span ids, and errors.
+   *
+   * @typeParam T LLM client object type.
+   * @param instance LLM client instance to wrap.
+   * @param optionsOrLabel Event label or custom extraction/interception rules.
+   * @returns A proxy with the same public interface as `instance`.
+   */
+  instrumentLLM(instance, optionsOrLabel = "llm.inference") {
+    return instrumentLLM(this, instance, optionsOrLabel);
+  }
+  /**
+   * Wraps a tool function with automatic Lynx telemetry.
+   *
+   * The wrapped function emits `TOOL_CALL` before execution and `TOOL_RESULT`
+   * after success. Errors are captured as `ERROR` and then rethrown. Use
+   * `metadata` to describe side effects, risk level, external targets, or tool
+   * version so debugging and governance views can reason about the call.
+   *
+   * @typeParam T Tool function type.
+   * @param toolName Stable tool name shown in traces and analytics.
+   * @param fn Tool function to execute.
+   * @param metadata Optional tool metadata for governance and RCA.
+   * @returns A wrapped function with the same call signature as `fn`.
+   */
+  instrumentTool(toolName, fn, metadata = {}) {
+    return instrumentTool(this, toolName, fn, metadata);
+  }
+  getDefaultFailureMode(riskLevel) {
+    if (riskLevel === "HIGH" || riskLevel === "CRITICAL") {
+      return "FAIL_CLOSED";
+    }
+    if (riskLevel === "MEDIUM") {
+      return "REQUIRE_APPROVAL";
+    }
+    return "FAIL_OPEN";
+  }
+  normalizePolicyDecision(decision) {
+    const action = decision.action ?? (decision.allow === false ? "BLOCK" : "ALLOW");
+    const allow = action === "ALLOW" || action === "WARN";
+    return {
+      ...decision,
+      action,
+      allow
+    };
+  }
+  decisionFromPolicyError(err, options) {
+    const failureMode = options.failureMode ?? this.getDefaultFailureMode(options.riskLevel);
+    const reason = err instanceof Error ? err.message : "Policy evaluation failed";
+    const action = failureMode === "FAIL_OPEN" ? "ALLOW" : failureMode === "REQUIRE_APPROVAL" ? "REQUIRE_APPROVAL" : "BLOCK";
+    return {
+      action,
+      allow: action === "ALLOW",
+      reason,
+      severity: options.riskLevel,
+      metadata: {
+        policyError: true,
+        failureMode
+      }
+    };
+  }
+  /**
+   * Wraps a tool with a local policy check before execution.
+   *
+   * `guardTool()` emits a `POLICY_EVALUATION` event before the tool runs. When
+   * `beforeCall` returns `{ allow: false }`, Lynx also emits
+   * `POLICY_VIOLATION` and `GUARDRAIL_ACTIVATED`, then throws before executing
+   * the original tool. This provides the SDK-side hook needed for "observe first,
+   * then prevent recurrence" workflows.
+   *
+   * @typeParam T Tool function type.
+   * @param toolName Stable tool name shown in traces and policy events.
+   * @param fn Tool function to guard.
+   * @param options Tool metadata and an optional `beforeCall` policy callback.
+   * @returns A guarded function with the same call signature as `fn`.
+   */
+  guardTool(toolName, fn, options = {}) {
+    const guarded = (async (...args) => {
+      const input = args[0];
+      let decision;
+      try {
+        decision = this.normalizePolicyDecision(
+          options.beforeCall ? await options.beforeCall({
+            toolName,
+            input,
+            args,
+            metadata: options
+          }) : { action: "ALLOW" }
+        );
+      } catch (err) {
+        decision = this.decisionFromPolicyError(err, options);
+      }
+      this.capture("POLICY_EVALUATION", `policy:${toolName}`, {
+        toolName,
+        input,
+        args,
+        argsHash: stableHash2(input),
+        action: decision.action,
+        allow: decision.allow,
+        policyId: decision.policyId,
+        policyVersion: decision.policyVersion ?? options.policyVersion ?? this.config.policyVersion,
+        reason: decision.reason,
+        severity: decision.severity,
+        metadata: decision.metadata
+      });
+      if (!decision.allow) {
+        this.capture("POLICY_VIOLATION", `policy.violation:${toolName}`, {
+          toolName,
+          input,
+          args,
+          argsHash: stableHash2(input),
+          action: decision.action,
+          policyId: decision.policyId,
+          policyVersion: decision.policyVersion ?? options.policyVersion ?? this.config.policyVersion,
+          reason: decision.reason,
+          severity: decision.severity ?? options.riskLevel
+        });
+        this.capture("GUARDRAIL_ACTIVATED", `guardrail.blocked:${toolName}`, {
+          toolName,
+          action: decision.action,
+          reason: decision.reason,
+          riskLevel: decision.severity ?? options.riskLevel
+        });
+        throw new LynxPolicyError(
+          decision.reason || `Lynx guard blocked tool call: ${toolName}`,
+          decision.action === "REQUIRE_APPROVAL" ? "REQUIRE_APPROVAL" : "BLOCK",
+          decision.policyId,
+          decision.severity ?? options.riskLevel,
+          decision.reason,
+          decision.metadata
+        );
+      }
+      const instrumented = this.instrumentTool(toolName, fn, options);
+      return instrumented(...args);
+    });
+    return guarded;
+  }
+  detectLoop(eventType, label, payload, context) {
+    if (eventType !== "TOOL_CALL" && eventType !== "CALL_TOOLS" && eventType !== "LLM_CALL") {
+      return {};
+    }
+    const phase = payload?.phase;
+    if (phase && phase !== "start") {
+      return {};
+    }
+    const argsHash = stableHash2(
+      payload?.args ?? payload?.input ?? payload?.model ?? label
+    );
+    const key = `${eventType}:${label}:${argsHash}`;
+    context.eventCounts ??= {};
+    const loopCount = (context.eventCounts[key] ?? 0) + 1;
+    context.eventCounts[key] = loopCount;
+    if (loopCount < 5) {
+      return { argsHash };
+    }
+    return {
+      argsHash,
+      loopDetected: true,
+      loopCount,
+      repeatedLabel: label
+    };
+  }
+};
+
+// src/core/register.ts
+var parseBool = (val) => {
+  if (val === void 0) return void 0;
+  return val.toLowerCase() === "true";
+};
+var parseNum = (val) => {
+  if (val === void 0) return void 0;
+  const num = parseFloat(val);
+  return isNaN(num) ? void 0 : num;
+};
+var lynx = new LynxTracer({
+  clientId: process.env.LYNX_CLIENT_ID || "local_dev_env",
+  endpoint: process.env.LYNX_ENDPOINT || DEFAULT_ENDPOINT,
+  sampleRate: parseNum(process.env.LYNX_SAMPLE_RATE),
+  captureInput: parseBool(process.env.LYNX_CAPTURE_INPUT),
+  captureOutput: parseBool(process.env.LYNX_CAPTURE_OUTPUT),
+  maxPayloadLength: parseNum(process.env.LYNX_MAX_PAYLOAD_LENGTH),
+  captureMode: process.env.LYNX_CAPTURE_MODE || "smart",
+  workspaceId: process.env.LYNX_WORKSPACE_ID,
+  agentId: process.env.LYNX_AGENT_ID,
+  apiKey: process.env.LYNX_API_KEY,
+  appVersion: process.env.LYNX_APP_VERSION,
+  deploymentId: process.env.LYNX_DEPLOYMENT_ID,
+  environment: process.env.LYNX_ENVIRONMENT || process.env.NODE_ENV,
+  policyVersion: process.env.LYNX_POLICY_VERSION,
+  delivery: {
+    mode: process.env.LYNX_DELIVERY_MODE,
+    timeoutMs: parseNum(process.env.LYNX_DELIVERY_TIMEOUT_MS),
+    flushOnRunEnd: parseBool(process.env.LYNX_DELIVERY_FLUSH_ON_RUN_END),
+    flushIntervalMs: parseNum(process.env.LYNX_DELIVERY_FLUSH_INTERVAL_MS),
+    batchSize: parseNum(process.env.LYNX_DELIVERY_BATCH_SIZE),
+    maxQueueSize: parseNum(process.env.LYNX_DELIVERY_MAX_QUEUE_SIZE),
+    overflowStrategy: process.env.LYNX_DELIVERY_OVERFLOW_STRATEGY
+  },
+  circuitBreaker: {
+    enabled: parseBool(process.env.LYNX_CIRCUIT_BREAKER_ENABLED),
+    failureThreshold: parseNum(
+      process.env.LYNX_CIRCUIT_BREAKER_FAILURE_THRESHOLD
+    ),
+    cooldownMs: parseNum(process.env.LYNX_CIRCUIT_BREAKER_COOLDOWN_MS)
+  }
+});
+export {
+  DEFAULT_ENDPOINT,
+  LynxPolicyError,
+  LynxTracer,
+  instrumentLLM,
+  instrumentTool,
+  lynx
+};