elasticdash-sdk 0.2.0

package/src/interceptors/telemetry-push.ts

@@ -0,0 +1,537 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { randomUUID } from 'node:crypto'
+import type { WorkflowEvent } from '../capture/event.js'
+import { extractSystemPrompt, replaceSystemPrompt, extractUserPrompts, replaceUserPrompt, lookupMockEntry, normaliseMockResult } from '../internals/mock-resolver.js'
+import type { AIMockEntry, UserPromptMockEntry } from '../internals/mock-resolver.js'
+import { debugLog } from '../utils/debug.js'
+import { notifyLicenseError } from '../utils/license-error.js'
+import type { TelemetryBatcher } from '../telemetry-batcher.js'
+
+interface ToolMockEntry {
+  mode: 'live' | 'mock-all' | 'mock-specific'
+  callIndices?: number[]
+  mockData?: Record<number, unknown>
+}
+
+type MockResult = { mocked: true; result: unknown } | { mocked: false }
+
+export interface HttpRunContext {
+  runId: string
+  dashboardUrl: string
+  nextId: () => number
+  frozenEvents: Map<number, WorkflowEvent>
+  /** System-prompt-keyed overrides: original system prompt → replacement system prompt */
+  promptMocks: Map<string, string>
+  /** User prompt mock configuration (keyed by original user message text) */
+  userPromptMocks?: Record<string, UserPromptMockEntry>
+  /** Tool output mock configuration (keyed by tool name) */
+  toolMockConfig?: Record<string, ToolMockEntry>
+  /** AI output mock configuration (keyed by model name) */
+  aiMockConfig?: Record<string, AIMockEntry>
+  /** Per-tool call counters for mock resolution (scoped to this request) */
+  toolCallCounters: Record<string, number>
+  /** Per-model call counters for AI mock resolution (scoped to this request) */
+  aiCallCounters: Record<string, number>
+  /** Per-user-prompt-text call counters for user prompt mock resolution */
+  userPromptCallCounters: Record<string, number>
+}
+
+export interface ObservabilityContext {
+  sessionId: string
+  serverUrl: string
+  apiKey?: string
+  batcher: TelemetryBatcher
+  nextId: () => number
+  sampleRate: number
+  redactKeys: string[]
+  traceId: string
+  /** The default workflow name discovered from ed_workflows.ts, used as traceId prefix */
+  defaultWorkflowName: string
+  /** When true, events captured during trigger rerun execution are marked as isRerun */
+  isRerun?: boolean
+  /** When set, pushTelemetryEvent also collects events here (used by trace capture) */
+  eventCollector?: WorkflowEvent[]
+}
+
+const g = globalThis as Record<string, unknown>
+const HTTP_RUN_ALS_KEY = '__elasticdash_http_run_als__'
+const GLOBAL_CTX_KEY = '__elasticdash_global_http_ctx__'
+const OBS_ALS_KEY = '__elasticdash_obs_als__'
+const GLOBAL_OBS_KEY = '__elasticdash_global_obs_ctx__'
+
+const httpRunAls: AsyncLocalStorage<HttpRunContext | undefined> =
+  (g[HTTP_RUN_ALS_KEY] as AsyncLocalStorage<HttpRunContext | undefined>) ??
+  new AsyncLocalStorage<HttpRunContext | undefined>()
+if (!g[HTTP_RUN_ALS_KEY]) g[HTTP_RUN_ALS_KEY] = httpRunAls
+
+const obsAls: AsyncLocalStorage<ObservabilityContext | undefined> =
+  (g[OBS_ALS_KEY] as AsyncLocalStorage<ObservabilityContext | undefined>) ??
+  new AsyncLocalStorage<ObservabilityContext | undefined>()
+if (!g[OBS_ALS_KEY]) g[OBS_ALS_KEY] = obsAls
+
+export function setObservabilityContext(ctx: ObservabilityContext): void {
+  obsAls.enterWith(ctx)
+  g[GLOBAL_OBS_KEY] = ctx
+}
+
+export function getObservabilityContext(): ObservabilityContext | undefined {
+  return obsAls.getStore() ?? (g[GLOBAL_OBS_KEY] as ObservabilityContext | undefined)
+}
+
+export function clearObservabilityContext(): void {
+  obsAls.enterWith(undefined)
+  g[GLOBAL_OBS_KEY] = undefined
+}
+
+function buildContext(
+  runId: string,
+  dashboardUrl: string,
+  frozenEvents: WorkflowEvent[],
+  promptMocksRecord: Record<string, string> = {},
+  toolMockConfig?: Record<string, ToolMockEntry>,
+  aiMockConfig?: Record<string, AIMockEntry>,
+  userPromptMocks?: Record<string, UserPromptMockEntry>,
+): HttpRunContext {
+  let counter = 0
+  const frozenMap = new Map<number, WorkflowEvent>()
+  for (const e of frozenEvents) frozenMap.set(e.id, e)
+  const promptMocksMap = new Map<string, string>(Object.entries(promptMocksRecord))
+  return {
+    runId, dashboardUrl, nextId: () => ++counter, frozenEvents: frozenMap, promptMocks: promptMocksMap,
+    userPromptMocks, toolMockConfig, aiMockConfig,
+    toolCallCounters: {}, aiCallCounters: {}, userPromptCallCounters: {},
+  }
+}
+
+/**
+ * Sets a global (non-ALS) fallback context that `getHttpRunContext` checks when
+ * ALS returns `undefined`. Use this in streaming frameworks where ALS context is
+ * lost after the handler returns a ReadableStream.
+ */
+export function setGlobalHttpContext(ctx: HttpRunContext): void {
+  g[GLOBAL_CTX_KEY] = ctx
+}
+
+/**
+ * Clears the global fallback context. Call this at the start of non-ElasticDash
+ * requests (or when a stream closes) to prevent stale context from leaking.
+ */
+export function clearGlobalHttpContext(): void {
+  g[GLOBAL_CTX_KEY] = undefined
+}
+
+/** Synchronous setup — use when there are no frozen events (live run with no replay). */
+export function setHttpRunContext(runId: string, dashboardUrl: string): void {
+  const ctx = buildContext(runId, dashboardUrl, [], {})
+  httpRunAls.enterWith(ctx)
+  g[GLOBAL_CTX_KEY] = ctx
+  ensureInterceptorsInstalled().catch(() => {})
+}
+
+/**
+ * Async setup — fetches frozen events from the dashboard then sets the ALS context.
+ * Use this in request handlers instead of setHttpRunContext when step freezing is needed.
+ * Falls back to a live (no-replay) context if the fetch fails or returns nothing.
+ */
+export async function initHttpRunContext(runId: string, dashboardUrl: string): Promise<void> {
+  let frozenEvents: WorkflowEvent[] = []
+  let promptMocks: Record<string, string> = {}
+  let toolMockConfig: Record<string, ToolMockEntry> | undefined
+  let aiMockConfig: Record<string, AIMockEntry> | undefined
+  let userPromptMocks: Record<string, UserPromptMockEntry> | undefined
+  try {
+    if (!dashboardUrl) {
+      debugLog(`[elasticdash] initHttpRunContext: no dashboardUrl, skipping config fetch`)
+    } else {
+    const res = await fetch(`${dashboardUrl}/api/run-configs/${runId}`)
+    if (res.ok) {
+      const data = await res.json() as { frozenEvents?: WorkflowEvent[]; promptMocks?: Record<string, string>; toolMockConfig?: Record<string, ToolMockEntry>; aiMockConfig?: Record<string, AIMockEntry>; userPromptMocks?: Record<string, UserPromptMockEntry> }
+      frozenEvents = Array.isArray(data.frozenEvents) ? data.frozenEvents : []
+      promptMocks = (data.promptMocks && typeof data.promptMocks === 'object' && !Array.isArray(data.promptMocks))
+        ? data.promptMocks : {}
+      if (data.toolMockConfig && typeof data.toolMockConfig === 'object' && !Array.isArray(data.toolMockConfig)) {
+        toolMockConfig = data.toolMockConfig
+      }
+      if (data.aiMockConfig && typeof data.aiMockConfig === 'object' && !Array.isArray(data.aiMockConfig)) {
+        aiMockConfig = data.aiMockConfig
+      }
+      if (data.userPromptMocks && typeof data.userPromptMocks === 'object' && !Array.isArray(data.userPromptMocks)) {
+        userPromptMocks = data.userPromptMocks as Record<string, UserPromptMockEntry>
+      }
+    } else if (res.status === 402) {
+      notifyLicenseError(res.status, 'run-config')
+    }
+    } // end dashboardUrl guard
+  } catch {
+    // Dashboard unreachable or run config not registered — proceed with live execution
+  }
+  const ctx = buildContext(runId, dashboardUrl, frozenEvents, promptMocks, toolMockConfig, aiMockConfig, userPromptMocks)
+  httpRunAls.enterWith(ctx)
+  g[GLOBAL_CTX_KEY] = ctx
+  await ensureInterceptorsInstalled()
+}
+
+export function getHttpRunContext(): HttpRunContext | undefined {
+  return httpRunAls.getStore() ?? (g[GLOBAL_CTX_KEY] as HttpRunContext | undefined)
+}
+
+/** Returns the frozen WorkflowEvent for the given event id, or undefined if not frozen. */
+export function getHttpFrozenEvent(id: number): WorkflowEvent | undefined {
+  return getHttpRunContext()?.frozenEvents.get(id)
+}
+
+/**
+ * If a prompt mock is configured for the system prompt found in `input`, returns
+ * a copy of `input` with the system prompt replaced. Otherwise returns `undefined`.
+ */
+export function getHttpPromptMock(input: unknown): unknown | undefined {
+  const ctx = getHttpRunContext()
+  if (!ctx || ctx.promptMocks.size === 0) {
+    debugLog(`[elasticdash] getHttpPromptMock: skip — promptMocks.size=${ctx?.promptMocks.size ?? 'no ctx'}`)
+    return undefined
+  }
+  const systemPrompt = extractSystemPrompt(input)
+  if (systemPrompt === undefined) {
+    const inputKeys = (input && typeof input === 'object') ? Object.keys(input as object).join(',') : typeof input
+    debugLog(`[elasticdash] getHttpPromptMock: no system prompt found in input (keys: ${inputKeys})`)
+    return undefined
+  }
+  const newSystemPrompt = ctx.promptMocks.get(systemPrompt)
+  debugLog(`[elasticdash] getHttpPromptMock: extracted system prompt (len=${systemPrompt.length}, first50=${JSON.stringify(systemPrompt.slice(0,50))}) — mock found=${newSystemPrompt !== undefined}`)
+  if (newSystemPrompt !== undefined) {
+    debugLog(`[elasticdash] getHttpPromptMock: available mock keys=${JSON.stringify([...ctx.promptMocks.keys()].map(k => k.slice(0,50)))}`)
+  }
+  if (newSystemPrompt === undefined) {
+    debugLog(`[elasticdash] getHttpPromptMock: no mock for this prompt. Available mock keys (first 50 chars each): ${JSON.stringify([...ctx.promptMocks.keys()].map(k => k.slice(0,50)))}`)
+    return undefined
+  }
+  return replaceSystemPrompt(input, newSystemPrompt)
+}
+
+/**
+ * If user prompt mocks are configured, applies all matching replacements to `input`.
+ * Returns modified input or `undefined` if no replacements applied.
+ * Uses fuzzy matching (strip/add JSON quotes) to handle serialization mismatches.
+ */
+export function getHttpUserPromptMock(input: unknown): unknown | undefined {
+  const ctx = getHttpRunContext()
+  if (!ctx?.userPromptMocks || Object.keys(ctx.userPromptMocks).length === 0) return undefined
+
+  const userPrompts = extractUserPrompts(input)
+  if (userPrompts.length === 0) return undefined
+
+  const mocks = ctx.userPromptMocks
+  const counters = ctx.userPromptCallCounters
+  const uniqueTexts = Array.from(new Set(userPrompts))
+  let modified = false
+  let result = input
+
+  for (const text of uniqueTexts) {
+    const match = lookupMockEntry(mocks, text)
+    if (!match || match.entry.mode === 'live') continue
+    const entry = match.entry
+
+    counters[match.key] = (counters[match.key] ?? 0) + 1
+    const callNumber = counters[match.key]
+
+    if (entry.mode === 'replace-all') {
+      result = replaceUserPrompt(result, text, entry.replacement)
+      modified = true
+    } else if (entry.mode === 'replace-specific') {
+      const indices = entry.callIndices ?? []
+      if (indices.includes(callNumber)) {
+        result = replaceUserPrompt(result, text, entry.replacement)
+        modified = true
+      }
+    }
+  }
+
+  return modified ? result : undefined
+}
+
+/**
+ * Resolves whether the current HTTP-mode call to `toolName` should be mocked.
+ * Mirrors `resolveMock()` but reads from the per-request HttpRunContext.
+ */
+export function getHttpToolMock(toolName: string): MockResult {
+  const ctx = getHttpRunContext()
+  if (!ctx?.toolMockConfig) return { mocked: false }
+  const entry = ctx.toolMockConfig[toolName]
+  if (!entry || entry.mode === 'live') return { mocked: false }
+
+  ctx.toolCallCounters[toolName] = (ctx.toolCallCounters[toolName] ?? 0) + 1
+  const callNumber = ctx.toolCallCounters[toolName]
+
+  if (entry.mode === 'mock-all') {
+    const data = entry.mockData ?? {}
+    const raw = data[callNumber] !== undefined ? data[callNumber] : data[0]
+    return { mocked: true, result: normaliseMockResult(raw) }
+  }
+  if (entry.mode === 'mock-specific') {
+    const indices = entry.callIndices ?? []
+    if (indices.includes(callNumber)) {
+      const data = entry.mockData ?? {}
+      return { mocked: true, result: normaliseMockResult(data[callNumber]) }
+    }
+    return { mocked: false }
+  }
+  return { mocked: false }
+}
+
+/**
+ * Resolves whether the current HTTP-mode call to `modelName` should be mocked.
+ * Mirrors `resolveAIMock()` but reads from the per-request HttpRunContext.
+ */
+export function getHttpAIMock(modelName: string): MockResult {
+  const ctx = getHttpRunContext()
+  if (!ctx?.aiMockConfig) return { mocked: false }
+  const entry = ctx.aiMockConfig[modelName]
+  if (!entry || entry.mode === 'live') return { mocked: false }
+
+  ctx.aiCallCounters[modelName] = (ctx.aiCallCounters[modelName] ?? 0) + 1
+  const callNumber = ctx.aiCallCounters[modelName]
+
+  if (entry.mode === 'mock-all') {
+    const data = entry.mockData ?? {}
+    const raw = data[callNumber] !== undefined ? data[callNumber] : data[0]
+    return { mocked: true, result: normaliseMockResult(raw) }
+  }
+  if (entry.mode === 'mock-specific') {
+    const indices = entry.callIndices ?? []
+    if (indices.includes(callNumber)) {
+      const data = entry.mockData ?? {}
+      return { mocked: true, result: normaliseMockResult(data[callNumber]) }
+    }
+    return { mocked: false }
+  }
+  return { mocked: false }
+}
+
+export function pushTelemetryEvent(event: WorkflowEvent, explicitCtx?: { runId: string; dashboardUrl: string }): void {
+  // Observability mode: route to batcher with sampling
+  const obsCtx = getObservabilityContext()
+  if (obsCtx && !explicitCtx) {
+    if (obsCtx.sampleRate < 1 && Math.random() >= obsCtx.sampleRate) return
+    if (!event.traceId && obsCtx.traceId) {
+      event.traceId = obsCtx.traceId
+    }
+    // Mark events captured during trigger rerun execution
+    if (obsCtx.isRerun) {
+      (event as WorkflowEvent & { isRerun?: boolean }).isRerun = true
+    }
+    if (obsCtx.eventCollector) {
+      obsCtx.eventCollector.push({ ...event })
+      debugLog(`[elasticdash] pushTelemetryEvent: collected event type=${event.type} name=${('name' in event ? event.name : '?')} (total: ${obsCtx.eventCollector.length})`)
+    }
+    obsCtx.batcher.enqueue(event)
+    return
+  }
+
+  const ctx = explicitCtx ?? getHttpRunContext()
+  if (!ctx) {
+    debugLog(`[elasticdash] pushTelemetryEvent: no HTTP context, dropping event type=${event.type} name=${('name' in event ? event.name : '?')}`)
+    return
+  }
+  const { runId, dashboardUrl } = ctx
+  if (!dashboardUrl) {
+    debugLog(`[elasticdash] pushTelemetryEvent: no dashboardUrl, dropping event type=${event.type} name=${('name' in event ? event.name : '?')}`)
+    return
+  }
+  debugLog(`[elasticdash] pushTelemetryEvent: posting event type=${event.type} name=${('name' in event ? event.name : '?')} runId=${runId} to ${dashboardUrl}`)
+  try {
+    fetch(`${dashboardUrl}/api/trace-events`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ runId, event }),
+    }).then(r => {
+      if (r.status === 402) notifyLicenseError(r.status, 'telemetry')
+      debugLog(`[elasticdash] pushTelemetryEvent: response status=${r.status} for type=${event.type} name=${('name' in event ? event.name : '?')}`)
+    }).catch(e => {
+      debugLog(`[elasticdash] pushTelemetryEvent: fetch failed: ${e instanceof Error ? e.message : String(e)}`)
+    })
+  } catch (e) {
+    debugLog(`[elasticdash] pushTelemetryEvent: fetch threw: ${e instanceof Error ? e.message : String(e)}`)
+  }
+}
+
+const INTERCEPTORS_KEY = '__elasticdash_interceptors_installed__'
+
+/**
+ * Ensures fetch (HTTP + AI) and DB interceptors are installed globally.
+ * Uses dynamic imports to avoid circular dependencies. Safe to call multiple
+ * times — only the first call does actual work.
+ */
+async function ensureInterceptorsInstalled(): Promise<void> {
+  if (g[INTERCEPTORS_KEY]) return
+  g[INTERCEPTORS_KEY] = true
+  try {
+    const [httpMod, aiMod, dbMod] = await Promise.all([
+      import('./http.js'),
+      import('./ai-interceptor.js'),
+      import('./db-auto.js'),
+    ])
+    httpMod.interceptFetch()
+    aiMod.installAIInterceptor()
+    await dbMod.installDBAutoInterceptor()
+  } catch {
+    // Non-fatal: interceptors may already be installed or deps missing
+  }
+}
+
+const AUTO_INIT_KEY = '__elasticdash_auto_init_promise__'
+
+/**
+ * Lazily initialises an HTTP run context from environment variables when none
+ * has been set up explicitly. Only activates when `ELASTICDASH_SERVER` is set.
+ *
+ * - If `ELASTICDASH_RUN_ID` is also set, calls `initHttpRunContext` so that
+ *   frozen steps are fetched from the dashboard (enables step freezing).
+ * - Otherwise calls `setHttpRunContext` with a fresh UUID (live/telemetry mode).
+ *
+ * The initialisation runs at most once per process — subsequent calls are
+ * no-ops once the context is established. Errors (e.g. dashboard unreachable)
+ * are swallowed so that live execution always continues unaffected.
+ *
+ * Typical usage: set `ELASTICDASH_SERVER=http://localhost:4573` and optionally
+ * `ELASTICDASH_RUN_ID=<id>` before starting your server or script. Every
+ * `wrapTool` / `wrapAI` call will then auto-connect to the dashboard without
+ * any explicit `initHttpRunContext` call in your code.
+ */
+/**
+ * Runs `callback` inside a fresh HTTP run context scoped to `runId` / `dashboardUrl`.
+ * Uses `als.run()` which guarantees the store is inherited by all async descendants of
+ * `callback`, even when intermediate code (e.g. Langfuse / OTel) spawns its own async
+ * contexts via `als.run()`. Prefer this over `setHttpRunContext` when wrapping a long-lived
+ * async pipeline such as a streaming route handler.
+ */
+export async function runInHttpContext<T>(
+  runId: string,
+  dashboardUrl: string,
+  callback: () => Promise<T>,
+): Promise<T> {
+  await ensureInterceptorsInstalled()
+  const ctx = buildContext(runId, dashboardUrl, [], {})
+  g[GLOBAL_CTX_KEY] = ctx
+  try {
+    return await httpRunAls.run(ctx, callback)
+  } finally {
+    g[GLOBAL_CTX_KEY] = undefined
+  }
+}
+
+/**
+ * Fetches frozen events and prompt mocks from the dashboard, then runs `callback`
+ * inside an HTTP run context using `als.run()`. This is the preferred function for
+ * streaming route handlers that sit behind Langfuse / OTel instrumentation:
+ *
+ * - `als.run()` guarantees the elasticdash store is inherited through any nested
+ *   `als.run()` calls made by third-party libraries (e.g. `startActiveObservation`).
+ * - Frozen events and prompt mocks are fetched before the callback so step replay
+ *   and prompt mocking work correctly on reruns.
+ *
+ * Falls back to an empty context (live execution, no replay) if the dashboard is
+ * unreachable or the run config is not found.
+ */
+export async function runWithInitializedHttpContext<T>(
+  runId: string,
+  dashboardUrl: string,
+  callback: () => Promise<T>,
+): Promise<T> {
+  let frozenEvents: WorkflowEvent[] = []
+  let promptMocks: Record<string, string> = {}
+  let toolMockConfig: Record<string, ToolMockEntry> | undefined
+  let aiMockConfig: Record<string, AIMockEntry> | undefined
+  let userPromptMocks: Record<string, UserPromptMockEntry> | undefined
+  try {
+    if (!dashboardUrl) {
+      debugLog(`[elasticdash] runWithInitializedHttpContext: no dashboardUrl, skipping config fetch`)
+    } else {
+    const res = await fetch(`${dashboardUrl}/api/run-configs/${runId}`)
+    if (res.ok) {
+      const data = await res.json() as { frozenEvents?: WorkflowEvent[]; promptMocks?: Record<string, string>; toolMockConfig?: Record<string, ToolMockEntry>; aiMockConfig?: Record<string, AIMockEntry>; userPromptMocks?: Record<string, UserPromptMockEntry> }
+      frozenEvents = Array.isArray(data.frozenEvents) ? data.frozenEvents : []
+      promptMocks = (data.promptMocks && typeof data.promptMocks === 'object' && !Array.isArray(data.promptMocks))
+        ? data.promptMocks : {}
+      if (data.toolMockConfig && typeof data.toolMockConfig === 'object' && !Array.isArray(data.toolMockConfig)) {
+        toolMockConfig = data.toolMockConfig
+      }
+      if (data.aiMockConfig && typeof data.aiMockConfig === 'object' && !Array.isArray(data.aiMockConfig)) {
+        aiMockConfig = data.aiMockConfig
+      }
+      if (data.userPromptMocks && typeof data.userPromptMocks === 'object' && !Array.isArray(data.userPromptMocks)) {
+        userPromptMocks = data.userPromptMocks as Record<string, UserPromptMockEntry>
+      }
+      const mockKeys = Object.keys(promptMocks)
+      const userMockKeys = Object.keys(userPromptMocks ?? {})
+      debugLog(`[elasticdash] runWithInitializedHttpContext: fetched ${mockKeys.length} prompt mocks, ${userMockKeys.length} user prompt mocks, ${frozenEvents.length} frozen events`)
+      if (mockKeys.length > 0) {
+        debugLog(`[elasticdash] runWithInitializedHttpContext: mock keys (first 80 chars each): ${JSON.stringify(mockKeys.map(k => k.slice(0,80)))}`)
+      }
+    } else {
+      if (res.status === 402) notifyLicenseError(res.status, 'run-config')
+      debugLog(`[elasticdash] runWithInitializedHttpContext: run-configs fetch returned ${res.status}`)
+    }
+    } // end dashboardUrl guard
+  } catch {
+    // Dashboard unreachable or run config not registered — proceed with live execution
+  }
+  await ensureInterceptorsInstalled()
+  const ctx = buildContext(runId, dashboardUrl, frozenEvents, promptMocks, toolMockConfig, aiMockConfig, userPromptMocks)
+  g[GLOBAL_CTX_KEY] = ctx
+  try {
+    return await httpRunAls.run(ctx, callback)
+  } finally {
+    g[GLOBAL_CTX_KEY] = undefined
+  }
+}
+
+export async function tryAutoInitHttpContext(): Promise<void> {
+  // Fast path: already initialised in this async context
+  if (getHttpRunContext()) return
+  if (getObservabilityContext()) return
+
+  // Check for observability mode first (ELASTICDASH_API_URL)
+  const apiUrl = (typeof process !== 'undefined' && process.env?.ELASTICDASH_API_URL) ?? ''
+  if (apiUrl) {
+    const obsInitKey = '__elasticdash_obs_auto_init__'
+    if (!g[obsInitKey]) {
+      g[obsInitKey] = (async () => {
+        try {
+          // Dynamic import to avoid circular dependency at module load time
+          const { initObservability } = await import('../observability.js')
+          initObservability({
+            serverUrl: apiUrl,
+            apiKey: process.env.ELASTICDASH_API_KEY,
+            sessionId: process.env.ELASTICDASH_SESSION_ID,
+          })
+        } catch (err) {
+          debugLog(`[elasticdash] Observability auto-init failed: ${err instanceof Error ? err.message : String(err)}`)
+        }
+      })()
+    }
+    await (g[obsInitKey] as Promise<void>)
+    return
+  }
+
+  // Fall back to HTTP run context (ELASTICDASH_SERVER — dashboard/test mode)
+  const serverUrl = (typeof process !== 'undefined' && process.env?.ELASTICDASH_SERVER) ?? ''
+  if (!serverUrl) return
+
+  // Deduplicate concurrent first calls within the same process
+  if (!g[AUTO_INIT_KEY]) {
+    g[AUTO_INIT_KEY] = (async () => {
+      try {
+        const runId = (typeof process !== 'undefined' && process.env?.ELASTICDASH_RUN_ID) ?? ''
+        if (runId) {
+          await initHttpRunContext(runId, serverUrl)
+        } else {
+          setHttpRunContext(randomUUID(), serverUrl)
+        }
+      } catch {
+        // Dashboard unreachable — fall through to live execution
+      }
+    })()
+  }
+
+  await (g[AUTO_INIT_KEY] as Promise<void>)
+}