@doclo/core 0.1.5

package/dist/observability/index.js

@@ -0,0 +1,630 @@
+// src/observability/hook-executor.ts
+var DEFAULT_HOOK_TIMEOUT = 5e3;
+async function executeHook(hook, options) {
+  const { hookName, config, context, fireAndForget = false } = options;
+  if (!hook) {
+    return;
+  }
+  if (config.enabled === false) {
+    return;
+  }
+  if (fireAndForget || config.fireAndForget) {
+    executeHookWithErrorHandling(hook, hookName, context, config).catch(() => {
+    });
+    return;
+  }
+  const timeout = config.hookTimeout ?? DEFAULT_HOOK_TIMEOUT;
+  try {
+    await executeHookWithTimeout(hook, context, timeout, hookName, config);
+  } catch (error) {
+  }
+}
+async function executeHookWithErrorHandling(hook, hookName, context, config) {
+  try {
+    const result = hook(context);
+    if (result && typeof result.then === "function") {
+      await result;
+    }
+  } catch (error) {
+    handleHookError(error, hookName, context, config);
+  }
+}
+async function executeHookWithTimeout(hook, context, timeoutMs, hookName, config) {
+  const timeoutPromise = new Promise((_, reject) => {
+    setTimeout(() => {
+      reject(new Error(`Hook '${hookName}' exceeded timeout of ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+  const hookPromise = executeHookWithErrorHandling(hook, hookName, context, config);
+  try {
+    await Promise.race([hookPromise, timeoutPromise]);
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("exceeded timeout")) {
+      handleHookError(error, hookName, context, config);
+    }
+  }
+}
+function handleHookError(error, hookName, context, config) {
+  const hookError = {
+    hookName,
+    error,
+    context,
+    timestamp: Date.now()
+  };
+  if (config.onHookError) {
+    try {
+      config.onHookError(hookError);
+    } catch (onHookErrorError) {
+      console.error("[Observability] onHookError handler failed:", onHookErrorError);
+      console.error("[Observability] Original hook error:", hookError);
+    }
+  } else {
+    console.warn(`[Observability] Hook '${hookName}' failed:`, error);
+  }
+  if (config.failOnHookError) {
+    throw error;
+  }
+}
+async function executeHooksSerial(hooks) {
+  for (const { hook, options } of hooks) {
+    await executeHook(hook, options);
+  }
+}
+function isObservabilityEnabled(config) {
+  if (config.enabled === false) {
+    return false;
+  }
+  if (config.samplingRate === void 0 || config.samplingRate === 1) {
+    return true;
+  }
+  if (config.samplingRate === 0) {
+    return false;
+  }
+  return Math.random() < config.samplingRate;
+}
+
+// src/runtime/crypto.ts
+function getRandomBytes(length) {
+  const bytes = new Uint8Array(length);
+  if (typeof globalThis !== "undefined" && globalThis.crypto?.getRandomValues) {
+    globalThis.crypto.getRandomValues(bytes);
+    return bytes;
+  }
+  throw new Error(
+    "Web Crypto API not available. This SDK requires:\n- Node.js 18.0.0 or later (has globalThis.crypto)\n- Edge Runtime (Vercel, Cloudflare)\n- Modern browsers"
+  );
+}
+function bytesToHex(bytes) {
+  return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function randomHex(byteLength) {
+  const bytes = getRandomBytes(byteLength);
+  return bytesToHex(bytes);
+}
+function randomUUID() {
+  if (typeof globalThis !== "undefined" && globalThis.crypto?.randomUUID) {
+    return globalThis.crypto.randomUUID();
+  }
+  const bytes = getRandomBytes(16);
+  bytes[6] = bytes[6] & 15 | 64;
+  bytes[8] = bytes[8] & 63 | 128;
+  const hex = bytesToHex(bytes);
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+
+// src/observability/trace-context.ts
+var TRACE_CONTEXT_VERSION = "00";
+var TRACE_FLAGS_SAMPLED = 1;
+var TRACE_FLAGS_NOT_SAMPLED = 0;
+function generateTraceId() {
+  return randomHex(16);
+}
+function generateSpanId() {
+  return randomHex(8);
+}
+function generateExecutionId() {
+  return randomUUID();
+}
+function createTraceContext(config, sampled) {
+  const traceIdGenerator = config.generateTraceId ?? generateTraceId;
+  const spanIdGenerator = config.generateSpanId ?? generateSpanId;
+  if (config.traceContext) {
+    const input = config.traceContext;
+    return {
+      traceId: input.traceId,
+      spanId: spanIdGenerator(),
+      parentSpanId: input.parentSpanId,
+      traceFlags: input.traceFlags ?? (sampled ? TRACE_FLAGS_SAMPLED : TRACE_FLAGS_NOT_SAMPLED),
+      traceState: input.traceState
+    };
+  }
+  return {
+    traceId: traceIdGenerator(),
+    spanId: spanIdGenerator(),
+    traceFlags: sampled ? TRACE_FLAGS_SAMPLED : TRACE_FLAGS_NOT_SAMPLED
+  };
+}
+function createChildSpanContext(parent, config) {
+  const spanIdGenerator = config?.generateSpanId ?? generateSpanId;
+  return {
+    traceId: parent.traceId,
+    spanId: spanIdGenerator(),
+    parentSpanId: parent.spanId,
+    traceFlags: parent.traceFlags,
+    traceState: parent.traceState
+  };
+}
+function formatTraceparent(context) {
+  const flags = context.traceFlags.toString(16).padStart(2, "0");
+  return `${TRACE_CONTEXT_VERSION}-${context.traceId}-${context.spanId}-${flags}`;
+}
+function parseTraceparent(traceparent) {
+  const parts = traceparent.split("-");
+  if (parts.length !== 4) {
+    return null;
+  }
+  const [version, traceId, spanId, flags] = parts;
+  if (version !== TRACE_CONTEXT_VERSION) {
+    return null;
+  }
+  if (!/^[0-9a-f]{32}$/.test(traceId)) {
+    return null;
+  }
+  if (!/^[0-9a-f]{16}$/.test(spanId)) {
+    return null;
+  }
+  if (!/^[0-9a-f]{2}$/.test(flags)) {
+    return null;
+  }
+  return {
+    traceId,
+    parentSpanId: spanId,
+    traceFlags: parseInt(flags, 16)
+  };
+}
+function formatTracestate(context) {
+  return context.traceState;
+}
+function isTraceSampled(context) {
+  return (context.traceFlags & TRACE_FLAGS_SAMPLED) === TRACE_FLAGS_SAMPLED;
+}
+function isValidTraceId(traceId) {
+  if (!/^[0-9a-f]{32}$/.test(traceId)) {
+    return false;
+  }
+  if (traceId === "00000000000000000000000000000000") {
+    return false;
+  }
+  return true;
+}
+function isValidSpanId(spanId) {
+  if (!/^[0-9a-f]{16}$/.test(spanId)) {
+    return false;
+  }
+  if (spanId === "0000000000000000") {
+    return false;
+  }
+  return true;
+}
+var TraceContextManager = class {
+  traceContext = null;
+  config;
+  constructor(config) {
+    this.config = config;
+  }
+  /**
+   * Initialize trace context for new execution
+   */
+  initialize(sampled) {
+    this.traceContext = createTraceContext(this.config, sampled);
+    return this.traceContext;
+  }
+  /**
+   * Get current trace context
+   */
+  getTraceContext() {
+    return this.traceContext;
+  }
+  /**
+   * Create child span context
+   */
+  createChildSpan() {
+    if (!this.traceContext) {
+      throw new Error("Trace context not initialized");
+    }
+    return createChildSpanContext(this.traceContext, this.config);
+  }
+  /**
+   * Get traceparent header value
+   */
+  getTraceparent() {
+    if (!this.traceContext) {
+      return null;
+    }
+    return formatTraceparent(this.traceContext);
+  }
+  /**
+   * Reset trace context (for testing)
+   */
+  reset() {
+    this.traceContext = null;
+  }
+};
+
+// src/observability/otel-attributes.ts
+var GEN_AI_SYSTEMS = {
+  openai: "openai",
+  "openai-compatible": "openai",
+  anthropic: "anthropic",
+  google: "vertex_ai",
+  // Google uses Vertex AI
+  "google-ai": "vertex_ai",
+  cohere: "cohere",
+  huggingface: "huggingface",
+  openrouter: "openrouter",
+  // Custom system
+  ollama: "ollama"
+  // Custom system
+};
+function mapProviderToSystem(provider) {
+  const normalized = provider.toLowerCase();
+  return GEN_AI_SYSTEMS[normalized] ?? normalized;
+}
+function buildOtelAttributes(data) {
+  const attributes = {};
+  if (data.provider) {
+    attributes["gen_ai.system"] = mapProviderToSystem(data.provider);
+  }
+  if (data.stepType) {
+    attributes["gen_ai.operation.name"] = data.stepType;
+  }
+  if (data.model) {
+    attributes["gen_ai.request.model"] = data.model;
+  }
+  if (data.modelUsed) {
+    attributes["gen_ai.response.model"] = data.modelUsed;
+  }
+  if (data.inputTokens !== void 0) {
+    attributes["gen_ai.usage.input_tokens"] = data.inputTokens;
+  }
+  if (data.outputTokens !== void 0) {
+    attributes["gen_ai.usage.output_tokens"] = data.outputTokens;
+  }
+  if (data.finishReason) {
+    attributes["gen_ai.response.finish_reason"] = data.finishReason;
+  }
+  if (data.temperature !== void 0) {
+    attributes["gen_ai.request.temperature"] = data.temperature;
+  }
+  if (data.maxTokens !== void 0) {
+    attributes["gen_ai.request.max_tokens"] = data.maxTokens;
+  }
+  if (data.topP !== void 0) {
+    attributes["gen_ai.request.top_p"] = data.topP;
+  }
+  if (data.topK !== void 0) {
+    attributes["gen_ai.request.top_k"] = data.topK;
+  }
+  return attributes;
+}
+function buildProviderRequestAttributes(data) {
+  return buildOtelAttributes({
+    provider: data.provider,
+    model: data.model,
+    temperature: data.config?.temperature,
+    maxTokens: data.config?.maxTokens,
+    topP: data.config?.topP,
+    topK: data.config?.topK
+  });
+}
+function buildProviderResponseAttributes(data) {
+  return buildOtelAttributes({
+    provider: data.provider,
+    model: data.model,
+    modelUsed: data.modelUsed,
+    inputTokens: data.inputTokens,
+    outputTokens: data.outputTokens,
+    finishReason: data.finishReason
+  });
+}
+function buildStepAttributes(data) {
+  return buildOtelAttributes({
+    stepType: data.stepType,
+    provider: data.provider,
+    model: data.model,
+    modelUsed: data.modelUsed,
+    inputTokens: data.inputTokens,
+    outputTokens: data.outputTokens,
+    finishReason: data.finishReason,
+    temperature: data.config?.temperature,
+    maxTokens: data.config?.maxTokens,
+    topP: data.config?.topP,
+    topK: data.config?.topK
+  });
+}
+var FINISH_REASON_MAPPING = {
+  // OpenAI
+  stop: "stop",
+  length: "length",
+  content_filter: "content_filter",
+  tool_calls: "tool_calls",
+  function_call: "function_call",
+  // Anthropic
+  end_turn: "stop",
+  max_tokens: "length",
+  stop_sequence: "stop",
+  // Google
+  STOP: "stop",
+  MAX_TOKENS: "length",
+  SAFETY: "content_filter",
+  RECITATION: "content_filter",
+  // Generic
+  complete: "stop",
+  truncated: "length",
+  filtered: "content_filter"
+};
+function normalizeFinishReason(reason) {
+  if (!reason) {
+    return void 0;
+  }
+  return FINISH_REASON_MAPPING[reason] ?? reason;
+}
+function addStandardSpanAttributes(attributes, data) {
+  if (data.spanKind) {
+    attributes["span.kind"] = data.spanKind;
+  }
+  if (data.serviceName) {
+    attributes["service.name"] = data.serviceName;
+  }
+  if (data.serviceVersion) {
+    attributes["service.version"] = data.serviceVersion;
+  }
+}
+function buildFullOtelContext(data) {
+  const attributes = buildOtelAttributes({
+    stepType: data.stepType,
+    provider: data.provider,
+    model: data.model,
+    modelUsed: data.modelUsed,
+    inputTokens: data.inputTokens,
+    outputTokens: data.outputTokens,
+    finishReason: data.finishReason,
+    temperature: data.config?.temperature,
+    maxTokens: data.config?.maxTokens,
+    topP: data.config?.topP,
+    topK: data.config?.topK
+  });
+  addStandardSpanAttributes(attributes, {
+    spanKind: data.spanKind,
+    serviceName: data.serviceName,
+    serviceVersion: data.serviceVersion
+  });
+  return attributes;
+}
+
+// src/observability/defaults.ts
+var DEFAULT_OBSERVABILITY_CONFIG = {
+  enabled: true,
+  samplingRate: 1,
+  samplingStrategy: "random",
+  asyncHooks: true,
+  fireAndForget: false,
+  hookTimeout: 5e3,
+  failOnHookError: false
+};
+function mergeConfig(userConfig) {
+  if (!userConfig) {
+    return { ...DEFAULT_OBSERVABILITY_CONFIG };
+  }
+  return {
+    ...DEFAULT_OBSERVABILITY_CONFIG,
+    ...userConfig
+  };
+}
+function shouldSample(config) {
+  if (config.samplingRate === void 0 || config.samplingRate === 1) {
+    return true;
+  }
+  if (config.samplingRate === 0) {
+    return false;
+  }
+  if (config.samplingStrategy === "custom" && config.customSampler) {
+    return true;
+  }
+  return Math.random() < config.samplingRate;
+}
+function validateConfig(config) {
+  const warnings = [];
+  const errors = [];
+  if (config.samplingRate !== void 0) {
+    if (config.samplingRate < 0 || config.samplingRate > 1) {
+      errors.push("samplingRate must be between 0.0 and 1.0");
+    }
+  }
+  if (config.hookTimeout !== void 0) {
+    if (config.hookTimeout <= 0) {
+      errors.push("hookTimeout must be positive");
+    }
+    if (config.hookTimeout > 6e4) {
+      warnings.push("hookTimeout > 60s may cause long execution delays");
+    }
+  }
+  if (config.samplingStrategy === "custom" && !config.customSampler) {
+    errors.push('customSampler required when samplingStrategy is "custom"');
+  }
+  if (config.traceContext) {
+    const { traceId, parentSpanId } = config.traceContext;
+    if (!/^[0-9a-f]{32}$/.test(traceId)) {
+      errors.push("traceContext.traceId must be 32 lowercase hex characters");
+    }
+    if (!/^[0-9a-f]{16}$/.test(parentSpanId)) {
+      errors.push("traceContext.parentSpanId must be 16 lowercase hex characters");
+    }
+    if (traceId === "00000000000000000000000000000000") {
+      errors.push("traceContext.traceId cannot be all zeros");
+    }
+    if (parentSpanId === "0000000000000000") {
+      errors.push("traceContext.parentSpanId cannot be all zeros");
+    }
+  }
+  if (config.asyncHooks === false && config.hookTimeout !== void 0) {
+    warnings.push("hookTimeout has no effect when asyncHooks is false");
+  }
+  if (config.fireAndForget === true && config.hookTimeout !== void 0) {
+    warnings.push("hookTimeout has no effect when fireAndForget is true");
+  }
+  if (config.enabled === false && Object.keys(config).length > 1) {
+    warnings.push("Observability is disabled, other config options have no effect");
+  }
+  return {
+    valid: errors.length === 0,
+    warnings,
+    errors
+  };
+}
+function getObservabilityVersion(config) {
+  return config?.observabilityVersion ?? "1.0.0";
+}
+function isObservabilityDisabled(config) {
+  return config.enabled === false || config.samplingRate === 0;
+}
+function hasAnyHooks(config) {
+  return !!(config.onFlowStart || config.onFlowEnd || config.onFlowError || config.onStepStart || config.onStepEnd || config.onStepError || config.onConsensusStart || config.onConsensusRunRetry || config.onConsensusRunComplete || config.onConsensusComplete || config.onBatchStart || config.onBatchItemStart || config.onBatchItemEnd || config.onBatchEnd || config.onProviderRequest || config.onProviderResponse || config.onProviderRetry || config.onCircuitBreakerTriggered || config.onLog);
+}
+function createMinimalConfig(overrides) {
+  return {
+    enabled: true,
+    samplingRate: 1,
+    asyncHooks: false,
+    // Faster for tests
+    fireAndForget: false,
+    hookTimeout: 1e3,
+    // Shorter for tests
+    failOnHookError: false,
+    ...overrides
+  };
+}
+
+// src/observability/logger.ts
+var Logger = class {
+  options;
+  constructor(options = {}) {
+    this.options = options;
+  }
+  /**
+   * Log a debug message
+   */
+  debug(message, data) {
+    this.log("debug", message, data);
+  }
+  /**
+   * Log an info message
+   */
+  info(message, data) {
+    this.log("info", message, data);
+  }
+  /**
+   * Log a warning message
+   */
+  warn(message, data) {
+    this.log("warn", message, data);
+  }
+  /**
+   * Log an error message
+   */
+  error(message, error, data) {
+    this.log("error", message, data, error instanceof Error ? error : void 0);
+  }
+  /**
+   * Internal log method that sends to onLog hook
+   */
+  log(level, message, data, error) {
+    const timestamp = Date.now();
+    const consoleMethod = level === "error" ? console.error : level === "warn" ? console.warn : console.log;
+    if (error) {
+      consoleMethod(`[${level.toUpperCase()}] ${message}`, data, error);
+    } else if (data !== void 0) {
+      consoleMethod(`[${level.toUpperCase()}] ${message}`, data);
+    } else {
+      consoleMethod(`[${level.toUpperCase()}] ${message}`);
+    }
+    if (this.options.observability?.onLog && this.options.traceContext) {
+      const combinedMetadata = {
+        ...this.options.metadata || {}
+      };
+      if (data !== void 0) {
+        combinedMetadata.data = data;
+      }
+      if (error) {
+        combinedMetadata.error = {
+          name: error.name,
+          message: error.message,
+          stack: error.stack
+        };
+      }
+      const logContext = {
+        flowId: this.options.flowId ?? "unknown",
+        executionId: this.options.executionId ?? "unknown",
+        stepId: this.options.stepId,
+        timestamp,
+        level,
+        message,
+        metadata: combinedMetadata,
+        traceContext: this.options.traceContext
+      };
+      executeHook(this.options.observability.onLog, {
+        hookName: "onLog",
+        config: this.options.observability,
+        context: logContext,
+        fireAndForget: true
+        // Special handling for onLog
+      }).catch(() => {
+      });
+    }
+  }
+};
+function createLogger(options = {}) {
+  return new Logger(options);
+}
+
+// src/observability/index.ts
+var OBSERVABILITY_VERSION = "1.0.0";
+export {
+  DEFAULT_OBSERVABILITY_CONFIG,
+  FINISH_REASON_MAPPING,
+  Logger,
+  OBSERVABILITY_VERSION,
+  TRACE_FLAGS_NOT_SAMPLED,
+  TRACE_FLAGS_SAMPLED,
+  TraceContextManager,
+  addStandardSpanAttributes,
+  buildFullOtelContext,
+  buildOtelAttributes,
+  buildProviderRequestAttributes,
+  buildProviderResponseAttributes,
+  buildStepAttributes,
+  createChildSpanContext,
+  createLogger,
+  createMinimalConfig,
+  createTraceContext,
+  executeHook,
+  executeHooksSerial,
+  formatTraceparent,
+  formatTracestate,
+  generateExecutionId,
+  generateSpanId,
+  generateTraceId,
+  getObservabilityVersion,
+  hasAnyHooks,
+  isObservabilityDisabled,
+  isObservabilityEnabled,
+  isTraceSampled,
+  isValidSpanId,
+  isValidTraceId,
+  mergeConfig,
+  normalizeFinishReason,
+  parseTraceparent,
+  shouldSample,
+  validateConfig
+};
+//# sourceMappingURL=index.js.map