netra-sdk 1.1.0 → 1.3.0

package/dist/index.js

@@ -610,7 +610,8 @@ var DEFAULT_INSTRUMENTS_FOR_ROOT = /* @__PURE__ */ new Set([
   // AI frameworks
   "langchain" /* LANGCHAIN */,
   "langgraph" /* LANGGRAPH */,
-  "llama_index" /* LLAMA_INDEX */
+  "llama_index" /* LLAMA_INDEX */,
+  "openai_agents" /* OPENAI_AGENTS */
 ]);
 var DEFAULT_INSTRUMENTS = /* @__PURE__ */ new Set([
   ...DEFAULT_INSTRUMENTS_FOR_ROOT,
@@ -3626,6 +3627,13 @@ var SpanAttributes2 = {
 };
 
 // src/instrumentation/utils.ts
+var VALID_NATIVE_TRACING_MODES = /* @__PURE__ */ new Set(["both", "netra", "netra-strict"]);
+function parseNativeTracingEnv(name) {
+  const val = process.env[name];
+  if (val === void 0 || val === "") return void 0;
+  if (VALID_NATIVE_TRACING_MODES.has(val)) return val;
+  return void 0;
+}
 var SUPPRESS_INSTRUMENTATION_KEY = /* @__PURE__ */ Symbol("netra.suppress_instrumentation");
 function shouldSuppressInstrumentation() {
   const ctx = context.active();
@@ -9132,6 +9140,8 @@ var cachedAgentsModule = null;
 var isInstrumented6 = false;
 var activeTracer = null;
 var activeProcessor = null;
+var originalProcessors = null;
+var didReplaceProcessors = false;
 async function resolveAgentsModule() {
   if (cachedAgentsModule) return cachedAgentsModule;
   try {
@@ -9184,20 +9194,51 @@ var NetraOpenAIAgentsInstrumentor = class {
     }
     const systemName = options.systemName ?? DEFAULT_LLM_SYSTEM;
     activeProcessor = new NetraAgentsTracingProcessor(activeTracer, systemName);
+    const mode = options.nativeTracing ?? parseNativeTracingEnv("NATIVE_TRACING_MODE") ?? "netra-strict";
+    const canSet = typeof agentsModule.setTraceProcessors === "function";
+    const canAdd = typeof agentsModule.addTraceProcessor === "function";
+    let strategy;
+    if (mode === "both" || mode === "netra" && !canSet) {
+      strategy = "append";
+    } else if (canSet) {
+      strategy = "replace";
+    } else {
+      strategy = "skip";
+    }
     try {
-      if (typeof agentsModule.addTraceProcessor === "function") {
-        agentsModule.addTraceProcessor(activeProcessor);
-      } else if (typeof agentsModule.setTraceProcessors === "function") {
-        const existing = typeof agentsModule.getTraceProcessors === "function" ? agentsModule.getTraceProcessors() : [];
-        agentsModule.setTraceProcessors([...existing, activeProcessor]);
-      } else {
-        Logger.warn(
-          "OpenAI Agents SDK does not expose addTraceProcessor or setTraceProcessors.",
-          "Tracing integration may not work."
-        );
-        activeProcessor = null;
-        activeTracer = null;
-        return this;
+      switch (strategy) {
+        case "replace":
+          if (typeof agentsModule.getTraceProcessors === "function") {
+            originalProcessors = agentsModule.getTraceProcessors();
+          }
+          agentsModule.setTraceProcessors([activeProcessor]);
+          didReplaceProcessors = true;
+          Logger.debug("OpenAI Agents native tracing disabled \u2014 traces will only be sent to Netra.");
+          break;
+        case "append":
+          if (canAdd) {
+            agentsModule.addTraceProcessor(activeProcessor);
+          } else {
+            Logger.warn("OpenAI Agents SDK does not expose addTraceProcessor or setTraceProcessors.");
+            activeProcessor = null;
+            activeTracer = null;
+            return this;
+          }
+          if (mode === "netra") {
+            Logger.warn(
+              "Cannot exclusively replace native trace processors in this @openai/agents version.",
+              "Traces may still be sent to OpenAI."
+            );
+          }
+          break;
+        case "skip":
+          Logger.warn(
+            'nativeTracing is "netra-strict" but the installed @openai/agents version',
+            "does not support processor replacement. Skipping instrumentation."
+          );
+          activeProcessor = null;
+          activeTracer = null;
+          return this;
       }
     } catch (error) {
       Logger.warn("Failed to register trace processor with @openai/agents:", error);
@@ -9217,6 +9258,21 @@ var NetraOpenAIAgentsInstrumentor = class {
       activeProcessor.shutdown();
       activeProcessor = null;
     }
+    if (didReplaceProcessors && cachedAgentsModule) {
+      try {
+        if (originalProcessors && typeof cachedAgentsModule.setTraceProcessors === "function") {
+          cachedAgentsModule.setTraceProcessors(originalProcessors);
+          Logger.debug("Restored original OpenAI Agents trace processors");
+        } else if (typeof cachedAgentsModule.setDefaultOpenAITracingExporter === "function") {
+          cachedAgentsModule.setDefaultOpenAITracingExporter();
+          Logger.debug("Restored default OpenAI Agents tracing exporter");
+        }
+      } catch (error) {
+        Logger.debug("Failed to restore original trace processors:", error);
+      }
+    }
+    originalProcessors = null;
+    didReplaceProcessors = false;
     activeTracer = null;
     cachedAgentsModule = null;
     isInstrumented6 = false;
@@ -10099,7 +10155,9 @@ function initInstrumentations(config2, instruments, blockInstruments, rootInstru
     mistral: false,
     langgraph: false,
     googleGenAI: false,
-    anthropic: false};
+    anthropic: false,
+    openAiAgents: false
+  };
   const resolved = enableAll ? new Set(Object.values(NetraInstruments).filter((v) => v !== "__all__" /* ALL */)) : instruments && instruments.size > 0 ? instruments : DEFAULT_INSTRUMENTS;
   instrumentModules.google_vertexai = false;
   instrumentModules.langchain = false;
@@ -10147,6 +10205,9 @@ function initInstrumentations(config2, instruments, blockInstruments, rootInstru
   if (resolved.has("anthropic" /* ANTHROPIC */)) {
     customInstrumentModules.anthropic = true;
   }
+  if (resolved.has("openai_agents" /* OPENAI_AGENTS */)) {
+    customInstrumentModules.openAiAgents = true;
+  }
   if (blockInstruments && blockInstruments.size > 0) {
     const blockAll = blockInstruments.has("__all__" /* ALL */);
     if (blockAll || blockInstruments.has("openai" /* OPENAI */)) customInstrumentModules.openai = false;
@@ -10155,6 +10216,7 @@ function initInstrumentations(config2, instruments, blockInstruments, rootInstru
     if (blockAll || blockInstruments.has("langgraph" /* LANGGRAPH */)) customInstrumentModules.langgraph = false;
     if (blockAll || blockInstruments.has("google_genai" /* GOOGLE_GENERATIVE_AI */)) customInstrumentModules.googleGenAI = false;
     if (blockAll || blockInstruments.has("anthropic" /* ANTHROPIC */)) customInstrumentModules.anthropic = false;
+    if (blockAll || blockInstruments.has("openai_agents" /* OPENAI_AGENTS */)) customInstrumentModules.openAiAgents = false;
     if (blockAll || blockInstruments.has("vertexai" /* VERTEX_AI */)) instrumentModules.google_vertexai = false;
     if (blockAll || blockInstruments.has("langchain" /* LANGCHAIN */)) instrumentModules.langchain = false;
     if (blockAll || blockInstruments.has("llama_index" /* LLAMA_INDEX */)) instrumentModules.llamaIndex = false;
@@ -10277,7 +10339,7 @@ async function initCustomInstrumentationsAsync(config2, tracerProvider, customIn
       Logger.debug("Failed to initialize custom Anthropic instrumentation:", e);
     }
   }
-  if (customInstrumentModules.openaiAgents && !blockInstruments?.has("openai_agents" /* OPENAI_AGENTS */)) {
+  if (customInstrumentModules.openAiAgents && !blockInstruments?.has("openai_agents" /* OPENAI_AGENTS */)) {
     try {
       await openaiAgentsInstrumentor.instrument({ tracerProvider });
       Logger.debug("Custom OpenAI Agents SDK instrumentation enabled");
@@ -10526,7 +10588,130 @@ async function uninstrumentAll() {
     Logger.debug("Failed to uninstrument undici:", e);
   }
 }
+
+// src/simulation/task.ts
+var BaseTask = class {
+};
+
+// src/simulation/utils.ts
 var LOG_PREFIX = "netra.simulation";
+var DEFAULT_FILE_DOWNLOAD_TIMEOUT_S = 30;
+var MAX_FILE_DOWNLOAD_WORKERS = 8;
+var _cachedFileDownloadTimeoutMs = null;
+function validateSimulationInputs(datasetId, task2) {
+  if (!datasetId) {
+    Logger.error(`${LOG_PREFIX}: dataset_id is required`);
+    return false;
+  }
+  if (!(task2 instanceof BaseTask)) {
+    Logger.error(`${LOG_PREFIX}: task must be a BaseTask instance`);
+    return false;
+  }
+  return true;
+}
+function _getFileDownloadTimeout() {
+  if (_cachedFileDownloadTimeoutMs !== null) {
+    return _cachedFileDownloadTimeoutMs;
+  }
+  const envVal = process.env.NETRA_SIMULATION_FILE_DOWNLOAD_TIMEOUT;
+  if (envVal) {
+    const parsed = parseFloat(envVal);
+    if (!isNaN(parsed) && parsed > 0) {
+      _cachedFileDownloadTimeoutMs = parsed * 1e3;
+      return _cachedFileDownloadTimeoutMs;
+    }
+    Logger.warn(
+      `${LOG_PREFIX}: Invalid file download timeout '${envVal}', using default ${DEFAULT_FILE_DOWNLOAD_TIMEOUT_S}s`
+    );
+  }
+  _cachedFileDownloadTimeoutMs = DEFAULT_FILE_DOWNLOAD_TIMEOUT_S * 1e3;
+  return _cachedFileDownloadTimeoutMs;
+}
+async function _downloadSingleFile(fileData, timeoutMs, signal) {
+  try {
+    const response = await axios.get(fileData.downloadUrl, {
+      responseType: "arraybuffer",
+      timeout: timeoutMs,
+      signal
+    });
+    const encoded = Buffer.from(response.data).toString("base64");
+    return {
+      fileName: fileData.fileName,
+      contentType: fileData.contentType,
+      description: fileData.description,
+      data: encoded
+    };
+  } catch (error) {
+    if (axios.isCancel(error)) {
+      throw new Error(
+        `Download of '${fileData.fileName}' was cancelled`
+      );
+    }
+    const status = axios.isAxiosError(error) ? error.response?.status : void 0;
+    const reason = status ? `HTTP ${status}` : error instanceof Error ? error.message : String(error);
+    Logger.error(
+      `${LOG_PREFIX}: Failed to download file '${fileData.fileName}': ${reason}`
+    );
+    throw new Error(
+      `Failed to download file '${fileData.fileName}': ${reason}`
+    );
+  }
+}
+function parseFiles(rawFiles) {
+  if (!rawFiles) {
+    return [];
+  }
+  const parsed = [];
+  for (const entry of rawFiles) {
+    const fileName = entry.fileName || "";
+    const downloadUrl = entry.downloadUrl || "";
+    if (!fileName || !downloadUrl) {
+      Logger.warn(
+        `${LOG_PREFIX}: Skipping malformed file attachment (missing fileName or downloadUrl)`
+      );
+      continue;
+    }
+    parsed.push({
+      fileName,
+      contentType: entry.contentType || "",
+      description: entry.description || void 0,
+      downloadUrl
+    });
+  }
+  return parsed;
+}
+async function processFiles(files) {
+  if (!files || files.length === 0) {
+    return null;
+  }
+  const timeoutMs = _getFileDownloadTimeout();
+  const limit = pLimit(MAX_FILE_DOWNLOAD_WORKERS);
+  const controller = new AbortController();
+  const downloadPromises = files.map(
+    (file) => limit(() => _downloadSingleFile(file, timeoutMs, controller.signal))
+  );
+  try {
+    return await Promise.all(downloadPromises);
+  } catch (error) {
+    controller.abort();
+    limit.clearQueue();
+    throw error;
+  }
+}
+async function executeTask2(task2, message, sessionId, rawFiles) {
+  const processedFiles = rawFiles && rawFiles.length > 0 ? await processFiles(rawFiles) : null;
+  const result = task2.run(message, sessionId, processedFiles);
+  const resolvedResult = result instanceof Promise ? await result : result;
+  if (typeof resolvedResult === "object" && resolvedResult !== null && "message" in resolvedResult && "sessionId" in resolvedResult) {
+    return [resolvedResult.message, resolvedResult.sessionId];
+  }
+  throw new Error(
+    `Task must return TaskResult, got ${typeof resolvedResult}`
+  );
+}
+
+// src/simulation/client.ts
+var LOG_PREFIX2 = "netra.simulation";
 var DEFAULT_TIMEOUT = 1e4;
 var SimulationHttpClient = class {
   constructor(config2) {
@@ -10539,7 +10724,7 @@ var SimulationHttpClient = class {
   _createClient(config2) {
     const endpoint = (config2.otlpEndpoint || "").trim();
     if (!endpoint) {
-      Logger.error(`${LOG_PREFIX}: NETRA_OTLP_ENDPOINT is required`);
+      Logger.error(`${LOG_PREFIX2}: NETRA_OTLP_ENDPOINT is required`);
       return null;
     }
     const baseURL = this._resolveBaseUrl(endpoint);
@@ -10561,7 +10746,7 @@ var SimulationHttpClient = class {
       );
       return instance;
     } catch (error) {
-      Logger.error(`${LOG_PREFIX}: Failed to create HTTP client:`, error);
+      Logger.error(`${LOG_PREFIX2}: Failed to create HTTP client:`, error);
       return null;
     }
   }
@@ -10596,7 +10781,7 @@ var SimulationHttpClient = class {
     const timeout = parseFloat(timeoutStr);
     if (isNaN(timeout)) {
       Logger.warn(
-        `${LOG_PREFIX}: Invalid timeout '${timeoutStr}', using default ${DEFAULT_TIMEOUT}ms`
+        `${LOG_PREFIX2}: Invalid timeout '${timeoutStr}', using default ${DEFAULT_TIMEOUT}ms`
       );
       return DEFAULT_TIMEOUT;
     }
@@ -10607,7 +10792,7 @@ var SimulationHttpClient = class {
    */
   async createRun(name, datasetId, context16) {
     if (!this.client) {
-      Logger.error(`${LOG_PREFIX}: Client not initialized`);
+      Logger.error(`${LOG_PREFIX2}: Client not initialized`);
       return null;
     }
     try {
@@ -10622,7 +10807,7 @@ var SimulationHttpClient = class {
       const responseData = data.data || {};
       const userMessages = responseData.userMessages || [];
       if (userMessages.length === 0) {
-        Logger.warn(`${LOG_PREFIX}: No user messages returned from create_run`);
+        Logger.warn(`${LOG_PREFIX2}: No user messages returned from create_run`);
         return null;
       }
       const runId = responseData.id || "";
@@ -10630,7 +10815,8 @@ var SimulationHttpClient = class {
         (msg) => ({
           runItemId: msg.testRunItemId || "",
           message: msg.userMessage || "",
-          turnId: msg.turnId || ""
+          turnId: msg.turnId || "",
+          files: parseFiles(msg.attachments)
         })
       );
       return {
@@ -10639,7 +10825,7 @@ var SimulationHttpClient = class {
       };
     } catch (error) {
       const errorMsg = this._extractErrorMessage(error);
-      Logger.error(`${LOG_PREFIX}: Failed to create simulation run:`, errorMsg);
+      Logger.error(`${LOG_PREFIX2}: Failed to create simulation run:`, errorMsg);
       return null;
     }
   }
@@ -10648,7 +10834,7 @@ var SimulationHttpClient = class {
    */
   async triggerConversation(message, turnId, sessionId, traceId) {
     if (!this.client) {
-      Logger.error(`${LOG_PREFIX}: Client not initialized`);
+      Logger.error(`${LOG_PREFIX2}: Client not initialized`);
       return null;
     }
     try {
@@ -10671,7 +10857,7 @@ var SimulationHttpClient = class {
       }
       const userMessages = responseData.userMessages || [];
       if (userMessages.length === 0) {
-        Logger.warn(`${LOG_PREFIX}: No user messages in continue response`);
+        Logger.warn(`${LOG_PREFIX2}: No user messages in continue response`);
         return null;
       }
       const nextMsg = userMessages[0];
@@ -10679,11 +10865,12 @@ var SimulationHttpClient = class {
         decision,
         nextTurnId: nextMsg.turnId || "",
         nextUserMessage: nextMsg.userMessage || "",
-        nextRunItemId: nextMsg.testRunItemId || ""
+        nextRunItemId: nextMsg.testRunItemId || "",
+        nextFiles: parseFiles(nextMsg.attachments)
       };
     } catch (error) {
       const errorMsg = this._extractErrorMessage(error);
-      Logger.error(`${LOG_PREFIX}: Failed to trigger conversation:`, errorMsg);
+      Logger.error(`${LOG_PREFIX2}: Failed to trigger conversation:`, errorMsg);
       return null;
     }
   }
@@ -10692,17 +10879,17 @@ var SimulationHttpClient = class {
    */
   async reportFailure(runId, runItemId, error) {
     if (!this.client) {
-      Logger.error(`${LOG_PREFIX}: Client not initialized`);
+      Logger.error(`${LOG_PREFIX2}: Client not initialized`);
       return;
     }
     try {
       const url = `/evaluations/run/${runId}/item/${runItemId}/status`;
       const payload = { status: "failed", failureReason: error };
       await this.client.patch(url, payload);
-      Logger.info(`${LOG_PREFIX}: Reported failure - ${error}`);
+      Logger.info(`${LOG_PREFIX2}: Reported failure - ${error}`);
     } catch (err) {
       const errorMsg = this._extractErrorMessage(err);
-      Logger.error(`${LOG_PREFIX}: Failed to report failure:`, errorMsg);
+      Logger.error(`${LOG_PREFIX2}: Failed to report failure:`, errorMsg);
     }
   }
   /**
@@ -10711,7 +10898,7 @@ var SimulationHttpClient = class {
   async postRunStatus(runId, status) {
     if (!this.client) {
       Logger.error(
-        `${LOG_PREFIX}: Client not initialized; cannot post run status`
+        `${LOG_PREFIX2}: Client not initialized; cannot post run status`
       );
       return { success: false };
     }
@@ -10721,14 +10908,14 @@ var SimulationHttpClient = class {
       const response = await this.client.post(url, payload);
       const data = response.data;
       if (data && typeof data === "object" && "data" in data) {
-        Logger.info(`${LOG_PREFIX}: Completed test run successfully`);
+        Logger.info(`${LOG_PREFIX2}: Completed test run successfully`);
         return data.data || {};
       }
       return data;
     } catch (error) {
       const errorMsg = this._extractErrorMessage(error);
       Logger.error(
-        `${LOG_PREFIX}: Failed to post run status for run '${runId}':`,
+        `${LOG_PREFIX2}: Failed to post run status for run '${runId}':`,
         errorMsg
       );
       return { success: false };
@@ -10752,34 +10939,6 @@ var SimulationHttpClient = class {
   }
 };
 
-// src/simulation/task.ts
-var BaseTask = class {
-};
-
-// src/simulation/utils.ts
-var LOG_PREFIX2 = "netra.simulation";
-function validateSimulationInputs(datasetId, task2) {
-  if (!datasetId) {
-    Logger.error(`${LOG_PREFIX2}: dataset_id is required`);
-    return false;
-  }
-  if (!(task2 instanceof BaseTask)) {
-    Logger.error(`${LOG_PREFIX2}: task must be a BaseTask instance`);
-    return false;
-  }
-  return true;
-}
-async function executeTask2(task2, message, sessionId) {
-  const result = task2.run(message, sessionId);
-  const resolvedResult = result instanceof Promise ? await result : result;
-  if (typeof resolvedResult === "object" && resolvedResult !== null && "message" in resolvedResult && "sessionId" in resolvedResult) {
-    return [resolvedResult.message, resolvedResult.sessionId];
-  }
-  throw new Error(
-    `Task must return TaskResult, got ${typeof resolvedResult}`
-  );
-}
-
 // src/simulation/api.ts
 var LOG_PREFIX3 = "netra.simulation";
 var SPAN_NAME = "Netra.Simulation.TestRun";
@@ -10913,17 +11072,18 @@ var Simulation = class {
    * Execute a multi-turn conversation for a single simulation item.
    */
   async _executeConversation(runId, runItem, task2) {
-    const { runItemId, message: initialMessage, turnId: initialTurnId } = runItem;
+    const { runItemId, message: initialMessage, turnId: initialTurnId, files: initialFiles } = runItem;
     let message = initialMessage;
     let turnId = initialTurnId;
     let sessionId = null;
+    let rawFiles = initialFiles ?? [];
     while (true) {
       const span2 = new SpanWrapper(SPAN_NAME, {}, LOG_PREFIX3);
       span2.start();
       try {
         const traceId = span2.getCurrentSpan()?.spanContext().traceId ?? "";
         const [responseMessage, taskSessionId] = await span2.withActive(
-          () => executeTask2(task2, message, sessionId)
+          () => executeTask2(task2, message, sessionId, rawFiles)
         );
         if (taskSessionId) {
           sessionId = taskSessionId;
@@ -10957,6 +11117,7 @@ var Simulation = class {
         }
         message = response.nextUserMessage;
         turnId = response.nextTurnId;
+        rawFiles = response.nextFiles || [];
       } catch (error) {
         const errorMsg = error instanceof Error ? error.message : String(error);
         Logger.error(