@deepagents/context 0.30.0 → 0.32.0

package/dist/lib/tracing/index.js

@@ -0,0 +1,661 @@
+// packages/context/src/lib/tracing/batch-processor.ts
+var BatchTraceProcessor = class {
+  #exporter;
+  #maxQueueSize;
+  #maxBatchSize;
+  #scheduleDelayMs;
+  #exportTimeoutMs;
+  #flushThreshold;
+  #queue = [];
+  #flushTimer;
+  #flushPromise;
+  #shutdown = false;
+  constructor(exporter, options = {}) {
+    this.#exporter = exporter;
+    this.#maxQueueSize = options.maxQueueSize ?? 8192;
+    this.#maxBatchSize = options.maxBatchSize ?? 128;
+    this.#scheduleDelayMs = options.scheduleDelayMs ?? 5e3;
+    this.#exportTimeoutMs = options.exportTimeoutMs ?? 3e4;
+    this.#flushThreshold = Math.max(
+      1,
+      Math.floor(this.#maxQueueSize * (options.exportTriggerRatio ?? 0.7))
+    );
+  }
+  start() {
+    if (this.#shutdown || this.#flushTimer != null) {
+      return;
+    }
+    this.#flushTimer = setInterval(() => {
+      void this.forceFlush();
+    }, this.#scheduleDelayMs);
+    this.#flushTimer.unref?.();
+  }
+  onTraceEnd(trace) {
+    this.#enqueue(trace);
+  }
+  onSpanEnd(span) {
+    this.#enqueue(span);
+  }
+  async forceFlush() {
+    if (this.#flushPromise != null) {
+      await this.#flushPromise;
+      return;
+    }
+    if (this.#queue.length === 0) {
+      return;
+    }
+    this.#flushPromise = this.#flush();
+    try {
+      await this.#flushPromise;
+    } finally {
+      this.#flushPromise = void 0;
+    }
+  }
+  async shutdown() {
+    this.#shutdown = true;
+    if (this.#flushTimer != null) {
+      clearInterval(this.#flushTimer);
+      this.#flushTimer = void 0;
+    }
+    await this.forceFlush();
+  }
+  #enqueue(item) {
+    if (this.#queue.length >= this.#maxQueueSize) {
+      return;
+    }
+    this.#queue.push(item);
+    if (this.#queue.length >= this.#flushThreshold) {
+      void this.forceFlush();
+    }
+  }
+  async #flush() {
+    while (this.#queue.length > 0) {
+      const batch = this.#queue.slice(0, this.#maxBatchSize);
+      await this.#exporter.export(
+        batch,
+        AbortSignal.timeout(this.#exportTimeoutMs)
+      );
+      this.#queue.splice(0, batch.length);
+    }
+  }
+};
+
+// packages/context/src/lib/tracing/exporter.ts
+var OpenAIExportError = class extends Error {
+  status;
+  constructor(status, body) {
+    super(`OpenAI traces export failed (${status}): ${body}`);
+    this.name = "OpenAIExportError";
+    this.status = status;
+  }
+};
+var OpenAITracesExporter = class {
+  #apiKey;
+  #endpoint;
+  #organization;
+  #project;
+  #maxRetries;
+  #baseDelayMs;
+  #maxDelayMs;
+  constructor(options = {}) {
+    this.#apiKey = options.apiKey ?? process.env.OPENAI_API_KEY ?? "";
+    this.#endpoint = options.endpoint ?? `${options.baseURL ?? "https://api.openai.com"}/v1/traces/ingest`;
+    this.#organization = options.organization;
+    this.#project = options.project;
+    this.#maxRetries = options.maxRetries ?? 3;
+    this.#baseDelayMs = options.baseDelayMs ?? 1e3;
+    this.#maxDelayMs = options.maxDelayMs ?? 3e4;
+  }
+  async export(items, signal) {
+    if (items.length === 0) return;
+    const apiKey = await this.#resolveApiKey();
+    if (!apiKey) {
+      throw new Error(
+        "OpenAI API key is required. Set OPENAI_API_KEY or pass apiKey option."
+      );
+    }
+    const headers = {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiKey}`,
+      "OpenAI-Beta": "traces=v1"
+    };
+    if (this.#organization) {
+      headers["OpenAI-Organization"] = this.#organization;
+    }
+    if (this.#project) {
+      headers["OpenAI-Project"] = this.#project;
+    }
+    const body = JSON.stringify({ data: items });
+    await this.#fetchWithRetry(this.#endpoint, {
+      method: "POST",
+      headers,
+      body,
+      signal
+    });
+  }
+  async #resolveApiKey() {
+    return typeof this.#apiKey === "function" ? await this.#apiKey() : this.#apiKey;
+  }
+  async #fetchWithRetry(url, init) {
+    let lastError;
+    for (let attempt = 0; attempt < this.#maxRetries; attempt++) {
+      try {
+        const response = await fetch(url, init);
+        if (response.ok) return response;
+        if (response.status >= 400 && response.status < 500) {
+          const text = await response.text().catch(() => "");
+          throw new OpenAIExportError(response.status, text);
+        }
+        lastError = new Error(`Server error ${response.status}`);
+      } catch (error) {
+        if (error instanceof OpenAIExportError) {
+          throw error;
+        }
+        lastError = error;
+      }
+      if (attempt < this.#maxRetries - 1) {
+        const delay = Math.min(
+          this.#baseDelayMs * 2 ** attempt,
+          this.#maxDelayMs
+        );
+        const jitter = delay * (0.9 + Math.random() * 0.2);
+        await new Promise((r) => setTimeout(r, jitter));
+      }
+    }
+    throw lastError;
+  }
+};
+
+// packages/context/src/lib/tracing/ids.ts
+import { randomUUID } from "node:crypto";
+function traceId() {
+  return `trace_${randomUUID().replace(/-/g, "")}`;
+}
+function spanId() {
+  return `span_${randomUUID().replace(/-/g, "").slice(0, 24)}`;
+}
+function groupId() {
+  return `group_${randomUUID().replace(/-/g, "").slice(0, 24)}`;
+}
+
+// packages/context/src/lib/tracing/processor.ts
+var CompositeTraceProcessor = class {
+  #processors;
+  constructor(processors) {
+    this.#processors = processors.filter(Boolean);
+  }
+  async start() {
+    for (const processor of this.#processors) {
+      await processor.start?.();
+    }
+  }
+  async onTraceStart(trace) {
+    for (const processor of this.#processors) {
+      await processor.onTraceStart?.(trace);
+    }
+  }
+  async onTraceEnd(trace) {
+    for (const processor of this.#processors) {
+      await processor.onTraceEnd?.(trace);
+    }
+  }
+  async onSpanStart(span) {
+    for (const processor of this.#processors) {
+      await processor.onSpanStart?.(span);
+    }
+  }
+  async onSpanEnd(span) {
+    for (const processor of this.#processors) {
+      await processor.onSpanEnd?.(span);
+    }
+  }
+  async forceFlush() {
+    for (const processor of this.#processors) {
+      await processor.forceFlush?.();
+    }
+  }
+  async shutdown() {
+    for (const processor of this.#processors) {
+      await processor.shutdown?.();
+    }
+  }
+};
+function createTracingProcessor(processors) {
+  if (processors == null) {
+    return void 0;
+  }
+  const list = Array.isArray(processors) ? processors : [processors];
+  if (list.length === 0) {
+    return void 0;
+  }
+  return list.length === 1 ? list[0] : new CompositeTraceProcessor(list);
+}
+
+// packages/context/src/lib/tracing/serialization.ts
+function normalizeForJson(value) {
+  if (value == null) {
+    return value;
+  }
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "bigint") {
+    return value.toString();
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (value instanceof Error) {
+    return errorToSpanError(value);
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizeForJson(item)).filter((item) => item !== void 0);
+  }
+  if (typeof value === "object") {
+    const normalized = {};
+    for (const [key, entry] of Object.entries(
+      value
+    )) {
+      const result = normalizeForJson(entry);
+      if (result !== void 0) {
+        normalized[key] = result;
+      }
+    }
+    return normalized;
+  }
+  return String(value);
+}
+function normalizeRecordArray(value) {
+  const normalized = normalizeForJson(value);
+  if (!Array.isArray(normalized)) {
+    return void 0;
+  }
+  return normalized.map(
+    (item) => typeof item === "object" && item != null ? item : { value: item }
+  );
+}
+function normalizeUsage(usage) {
+  if (usage == null) {
+    return void 0;
+  }
+  const details = {};
+  if (hasDefinedValue(usage.inputTokenDetails)) {
+    details.input_token_details = normalizeForJson({
+      no_cache_tokens: usage.inputTokenDetails.noCacheTokens,
+      cache_read_tokens: usage.inputTokenDetails.cacheReadTokens,
+      cache_write_tokens: usage.inputTokenDetails.cacheWriteTokens
+    });
+  }
+  if (hasDefinedValue(usage.outputTokenDetails)) {
+    details.output_token_details = normalizeForJson({
+      text_tokens: usage.outputTokenDetails.textTokens,
+      reasoning_tokens: usage.outputTokenDetails.reasoningTokens
+    });
+  }
+  if (usage.raw != null) {
+    details.raw = normalizeForJson(usage.raw);
+  }
+  if (usage.reasoningTokens !== void 0) {
+    details.reasoning_tokens = usage.reasoningTokens;
+  }
+  if (usage.cachedInputTokens !== void 0) {
+    details.cached_input_tokens = usage.cachedInputTokens;
+  }
+  return {
+    input_tokens: usage.inputTokens,
+    output_tokens: usage.outputTokens,
+    total_tokens: usage.totalTokens,
+    ...Object.keys(details).length > 0 ? { details } : {}
+  };
+}
+function errorToSpanError(error) {
+  if (error instanceof Error) {
+    const data = normalizeForJson({
+      name: error.name,
+      stack: error.stack,
+      cause: error.cause
+    });
+    return {
+      message: error.message,
+      ...Object.keys(data).length > 0 ? { data } : {}
+    };
+  }
+  return {
+    message: String(error)
+  };
+}
+function hasDefinedValue(value) {
+  if (value == null) {
+    return false;
+  }
+  return Object.values(value).some((entry) => entry !== void 0);
+}
+
+// packages/context/src/lib/tracing/openai-traces-integration.ts
+function createOpenAITracesIntegration(options = {}) {
+  if (process.env.OPENAI_AGENTS_DISABLE_TRACING === "1") {
+    return {};
+  }
+  const exporter = options.exporter ?? new OpenAITracesExporter({
+    apiKey: options.apiKey,
+    baseURL: options.baseURL,
+    endpoint: options.endpoint,
+    organization: options.organization,
+    project: options.project
+  });
+  const processor = createTracingProcessor(options.processor) ?? new BatchTraceProcessor(exporter, options.batch);
+  const includeSensitive = options.includeSensitiveData ?? process.env.OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA !== "0";
+  const openRuns = [];
+  const responseIdToRun = /* @__PURE__ */ new Map();
+  const toolCallIdToRun = /* @__PURE__ */ new Map();
+  void processor.start?.();
+  return {
+    onStart: async (event) => {
+      const trace = {
+        object: "trace",
+        id: traceId(),
+        workflow_name: options.workflowName ?? event.functionId ?? "ai-sdk-workflow",
+        group_id: options.groupId ?? null,
+        metadata: normalizeMetadata({
+          ...options.metadata,
+          ...event.metadata
+        })
+      };
+      const rootSpan = {
+        object: "trace.span",
+        id: spanId(),
+        trace_id: trace.id,
+        parent_id: null,
+        started_at: now(),
+        span_data: {
+          type: "agent",
+          name: trace.workflow_name,
+          tools: event.tools ? Object.keys(event.tools) : void 0,
+          output_type: getOutputType(event.output)
+        }
+      };
+      const state = {
+        trace,
+        rootSpan,
+        functionId: event.functionId,
+        modelKey: toModelKey(event.model),
+        inputFingerprint: fingerprintInput({
+          system: event.system,
+          prompt: event.prompt,
+          messages: event.messages
+        }),
+        metadataRef: asObjectRef(event.metadata),
+        contextRef: asObjectRef(event.experimental_context),
+        abortSignal: event.abortSignal,
+        responseIds: /* @__PURE__ */ new Set(),
+        stepSpans: [],
+        spansById: /* @__PURE__ */ new Map([[rootSpan.id, rootSpan]]),
+        toolCallSpans: /* @__PURE__ */ new Map()
+      };
+      openRuns.push(state);
+      await processor.onTraceStart?.(trace);
+      await processor.onSpanStart?.(rootSpan);
+    },
+    onStepStart: async (event) => {
+      const state = resolveRunState(event);
+      if (state == null) {
+        return;
+      }
+      const span = {
+        object: "trace.span",
+        id: spanId(),
+        trace_id: state.trace.id,
+        parent_id: currentParentId(state),
+        started_at: now(),
+        span_data: {
+          type: "generation",
+          model: event.model.modelId,
+          model_config: normalizeMetadata({
+            provider: event.model.provider,
+            tool_choice: event.toolChoice,
+            active_tools: event.activeTools,
+            provider_options: event.providerOptions
+          }),
+          ...includeSensitive ? { input: normalizeRecordArray(event.messages) } : {}
+        }
+      };
+      state.stepSpans.push(span.id);
+      state.spansById.set(span.id, span);
+      await processor.onSpanStart?.(span);
+    },
+    onToolCallStart: async (event) => {
+      const state = resolveRunState(event);
+      if (state == null) {
+        return;
+      }
+      const span = {
+        object: "trace.span",
+        id: spanId(),
+        trace_id: state.trace.id,
+        parent_id: currentParentId(state),
+        started_at: now(),
+        span_data: {
+          type: "function",
+          name: event.toolCall.toolName,
+          ...includeSensitive ? {
+            input: normalizeForJson(event.toolCall.input)
+          } : {}
+        }
+      };
+      state.toolCallSpans.set(event.toolCall.toolCallId, span.id);
+      toolCallIdToRun.set(event.toolCall.toolCallId, state);
+      state.spansById.set(span.id, span);
+      await processor.onSpanStart?.(span);
+    },
+    onToolCallFinish: async (event) => {
+      const state = toolCallIdToRun.get(event.toolCall.toolCallId) ?? resolveRunState(event);
+      if (state == null) {
+        return;
+      }
+      const id = state.toolCallSpans.get(event.toolCall.toolCallId);
+      if (id == null) {
+        return;
+      }
+      state.toolCallSpans.delete(event.toolCall.toolCallId);
+      toolCallIdToRun.delete(event.toolCall.toolCallId);
+      const span = state.spansById.get(id);
+      if (span == null) {
+        return;
+      }
+      span.ended_at = now();
+      const data = span.span_data;
+      if (includeSensitive && event.success) {
+        data.output = normalizeForJson(event.output);
+      }
+      if (!event.success) {
+        span.error = errorToSpanError(event.error);
+      }
+      await processor.onSpanEnd?.(span);
+    },
+    onStepFinish: async (event) => {
+      const state = resolveRunState(event);
+      if (state == null) {
+        return;
+      }
+      const id = state.stepSpans.pop();
+      if (id == null) {
+        return;
+      }
+      const span = state.spansById.get(id);
+      if (span == null) {
+        return;
+      }
+      span.ended_at = now();
+      const data = span.span_data;
+      if (includeSensitive) {
+        data.output = normalizeRecordArray(event.response.messages);
+      }
+      data.usage = normalizeUsage(event.usage);
+      state.responseIds.add(event.response.id);
+      responseIdToRun.set(event.response.id, state);
+      await processor.onSpanEnd?.(span);
+    },
+    onFinish: async (event) => {
+      const state = resolveRunState(event);
+      if (state == null) {
+        return;
+      }
+      try {
+        while (state.stepSpans.length > 0) {
+          const openStepId = state.stepSpans.pop();
+          if (openStepId == null) {
+            continue;
+          }
+          const openStep = state.spansById.get(openStepId);
+          if (openStep == null || openStep.ended_at != null) {
+            continue;
+          }
+          openStep.ended_at = now();
+          await processor.onSpanEnd?.(openStep);
+        }
+        state.rootSpan.ended_at = now();
+        state.trace.metadata = normalizeMetadata({
+          ...state.trace.metadata,
+          total_usage: normalizeUsage(event.totalUsage),
+          steps: event.steps.length,
+          finish_reason: event.finishReason
+        });
+        await processor.onSpanEnd?.(state.rootSpan);
+        await processor.onTraceEnd?.(state.trace);
+        await processor.forceFlush?.();
+      } finally {
+        closeRunState(state);
+      }
+    }
+  };
+  function resolveRunState(event) {
+    if (event.response?.id != null) {
+      const state = responseIdToRun.get(event.response.id);
+      if (state != null) {
+        return state;
+      }
+    }
+    if (event.toolCall?.toolCallId != null) {
+      const state = toolCallIdToRun.get(event.toolCall.toolCallId);
+      if (state != null) {
+        return state;
+      }
+    }
+    if (openRuns.length === 0) {
+      return void 0;
+    }
+    if (openRuns.length === 1) {
+      return openRuns[0];
+    }
+    let bestState;
+    let bestScore = 0;
+    const eventMetadataRef = asObjectRef(event.metadata);
+    const eventContextRef = asObjectRef(event.experimental_context);
+    const eventModelKey = event.model != null ? toModelKey(event.model) : void 0;
+    const eventFingerprint = fingerprintInput({
+      system: event.system,
+      prompt: event.prompt,
+      messages: event.messages
+    });
+    for (const state of openRuns) {
+      let score = 0;
+      if (eventContextRef != null && state.contextRef === eventContextRef) {
+        score += 1e3;
+      }
+      if (eventMetadataRef != null && state.metadataRef === eventMetadataRef) {
+        score += 800;
+      }
+      if (event.abortSignal != null && state.abortSignal != null && state.abortSignal === event.abortSignal) {
+        score += 600;
+      }
+      if (event.functionId != null && state.functionId === event.functionId) {
+        score += 300;
+      }
+      if (eventModelKey != null && state.modelKey === eventModelKey) {
+        score += 100;
+      }
+      if (eventFingerprint != null && state.inputFingerprint != null && state.inputFingerprint === eventFingerprint) {
+        score += 200;
+      }
+      if (score > bestScore) {
+        bestScore = score;
+        bestState = state;
+      }
+    }
+    return bestState;
+  }
+  function closeRunState(state) {
+    const index = openRuns.indexOf(state);
+    if (index >= 0) {
+      openRuns.splice(index, 1);
+    }
+    for (const responseId of state.responseIds) {
+      responseIdToRun.delete(responseId);
+    }
+    for (const toolCallId of state.toolCallSpans.keys()) {
+      toolCallIdToRun.delete(toolCallId);
+    }
+  }
+}
+function currentParentId(state) {
+  return state.stepSpans[state.stepSpans.length - 1] ?? state.rootSpan.id;
+}
+function normalizeMetadata(metadata) {
+  if (metadata == null) {
+    return void 0;
+  }
+  const normalized = normalizeForJson(metadata);
+  if (normalized == null || typeof normalized !== "object" || Array.isArray(normalized)) {
+    return void 0;
+  }
+  return Object.keys(normalized).length > 0 ? normalized : void 0;
+}
+function getOutputType(output) {
+  if (output == null) {
+    return void 0;
+  }
+  if (typeof output === "object" && "type" in output && typeof output.type === "string") {
+    return output.type;
+  }
+  if (typeof output === "object" && output.constructor?.name != null) {
+    return output.constructor.name;
+  }
+  return typeof output;
+}
+function now() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function toModelKey(model) {
+  return `${model.provider}:${model.modelId}`;
+}
+function fingerprintInput(input) {
+  const normalizedMessages = input.messages ?? (typeof input.prompt === "string" ? [
+    {
+      role: "user",
+      content: [{ type: "text", text: input.prompt }]
+    }
+  ] : input.prompt);
+  const normalized = normalizeForJson({
+    system: input.system,
+    messages: normalizedMessages
+  });
+  if (normalized == null) {
+    return void 0;
+  }
+  return JSON.stringify(normalized);
+}
+function asObjectRef(value) {
+  return value != null && typeof value === "object" ? value : void 0;
+}
+export {
+  BatchTraceProcessor,
+  CompositeTraceProcessor,
+  OpenAIExportError,
+  OpenAITracesExporter,
+  createOpenAITracesIntegration,
+  createTracingProcessor,
+  groupId,
+  spanId,
+  traceId
+};
+//# sourceMappingURL=index.js.map