elasticdash-sdk 0.2.0 → 0.2.5

package/src/interceptors/telemetry-push.ts

@@ -1,5 +1,6 @@
 import { AsyncLocalStorage } from 'node:async_hooks'
 import { randomUUID } from 'node:crypto'
+import { gunzipSync } from 'node:zlib'
 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'
@@ -175,6 +176,85 @@ export function getHttpRunContext(): HttpRunContext | undefined {
   return httpRunAls.getStore() ?? (g[GLOBAL_CTX_KEY] as HttpRunContext | undefined)
 }
 
+/**
+ * Option-A inbound bridge for HTTP-mode workflows.
+ *
+ * The elasticdash CLI subprocess attaches `x-elasticdash-mock-config` to
+ * outbound fetches when `--mock-config-file` is in effect (see
+ * `interceptors/http.ts`). Call this once at request entry inside the
+ * receiving Next.js / Express / Hono / Fastify handler — the function
+ * reads that header, decodes the base64-JSON payload, and seeds an
+ * HttpRunContext so every `wrapTool` / `wrapAI` call in the same request
+ * honors the mocks. After this, no further per-route plumbing is needed.
+ *
+ * Behavior:
+ *   - No header → no-op, normal live execution
+ *   - Existing HttpRunContext (e.g. from a prior `initHttpRunContext`
+ *     call for dashboard mode) → merges in the inbound mocks on top
+ *   - No existing context → creates a fresh one with just the mocks
+ *
+ * Accepts any object exposing a Headers-like `headers.get(name)`. Works
+ * with `NextRequest`, `Request`, and Node's `IncomingMessage` (via
+ * `req.headers` as a plain object).
+ */
+export function applyInboundMockConfig(req: unknown): void {
+  if (!req || typeof req !== 'object') return
+  const HEADER = 'x-elasticdash-mock-config'
+
+  // Polymorphic read across Request-like, NextRequest, and Node http.
+  let raw: string | null | undefined
+  const r = req as { headers?: unknown }
+  if (r.headers && typeof r.headers === 'object') {
+    const h = r.headers as { get?: (name: string) => string | null } & Record<string, string | string[] | undefined>
+    if (typeof h.get === 'function') {
+      raw = h.get(HEADER)
+    } else {
+      const v = h[HEADER] ?? h[HEADER.toUpperCase()]
+      raw = Array.isArray(v) ? v[0] : v
+    }
+  }
+  if (!raw) return
+
+  // Header format:
+  //   "gz1:<base64-gzip>" — current SDK (>=0.2.5) — gzipped JSON, used to
+  //     stay under Node's default 8KB header limit when configs include
+  //     large trace-derived outputs.
+  //   "<base64-json>" — legacy plain base64 (back-compat with earlier SDKs).
+  let payload: { toolMockConfig?: Record<string, ToolMockEntry>; aiMockConfig?: Record<string, AIMockEntry>; strict?: boolean }
+  try {
+    let json: string
+    if (raw.startsWith('gz1:')) {
+      json = gunzipSync(Buffer.from(raw.slice(4), 'base64')).toString('utf-8')
+    } else {
+      json = Buffer.from(raw, 'base64').toString('utf-8')
+    }
+    payload = JSON.parse(json)
+  } catch {
+    debugLog(`[elasticdash] applyInboundMockConfig: failed to decode ${HEADER} header`)
+    return
+  }
+
+  const existing = getHttpRunContext()
+  const ctx = existing
+    ? {
+        ...existing,
+        // Merge — inbound mocks layer over any dashboard-supplied ones.
+        toolMockConfig: { ...(existing.toolMockConfig ?? {}), ...(payload.toolMockConfig ?? {}) },
+        aiMockConfig: { ...(existing.aiMockConfig ?? {}), ...(payload.aiMockConfig ?? {}) },
+      }
+    : buildContext('inbound-mock', '', [], {}, payload.toolMockConfig, payload.aiMockConfig)
+  // `enterWith` scopes the context to the rest of this async chain — i.e.
+  // the current HTTP request. Do NOT set GLOBAL_CTX_KEY here: that would
+  // leak the mocks into other requests on the same server. Concurrent
+  // requests with different mock configs need full per-request isolation.
+  httpRunAls.enterWith(ctx)
+
+  // Strict mode: still a global. Scope it to this request via try/finally
+  // in the caller if you need it isolated; for now we set it as long as
+  // any inbound request says so. Follow-up: per-request strict on the ctx.
+  if (payload.strict === true) g['__ELASTICDASH_STRICT__'] = true
+}
+
 /** 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)

package/src/interceptors/tool.ts

@@ -3,6 +3,7 @@ import { getCurrentTrace } from '../trace-adapter/context.js'
 import { rawDateNow } from './side-effects.js'
 import { getHttpRunContext, getHttpFrozenEvent, getHttpToolMock, pushTelemetryEvent, tryAutoInitHttpContext, getObservabilityContext } from './telemetry-push.js'
 import { getEdReplayContext, replayCall } from '../ci/replay.js'
+import { resolveMock } from '../internals/mock-resolver.js'
 import { debugLog } from '../utils/debug.js'
 
 const TOOL_WRAPPER_ACTIVE_KEY = '__elasticdash_tool_wrapper_active__'
@@ -220,10 +221,41 @@ export function wrapTool<Args extends unknown[], R>(
       return replayed
     }
 
+    // Module-imported mock dispatch: check __ELASTICDASH_TOOL_MOCKS__ globals.
+    // For HTTP mode the same check happens in the no-capture branch above
+    // (getHttpToolMock); in CLI/capture mode we route through resolveMock so
+    // the same mock-config-file shape works for both paths. resolveMock also
+    // enforces __ELASTICDASH_STRICT__ — when strict + no entry, it throws
+    // ElasticdashStrictModeError, which we record as a tool error event so
+    // the envelope still carries the failed call for the MCP to surface.
+    const start = rawDateNow()
+    let mock: { mocked: true; result: unknown } | { mocked: false }
+    try {
+      mock = resolveMock(name)
+    } catch (e) {
+      const durationMs = rawDateNow() - start
+      const errorEvent = { id, type: 'tool' as const, name, input, output: { error: String(e) }, timestamp: start, durationMs }
+      recorder.record(errorEvent)
+      if (httpCtx) pushTelemetryEvent(errorEvent)
+      if (trace && typeof trace.recordToolCall === 'function') {
+        trace.recordToolCall({ name, args: toTraceArgs(input), result: { error: String(e) }, workflowEventId: id, durationMs })
+      }
+      throw e
+    }
+    if (mock.mocked) {
+      const durationMs = rawDateNow() - start
+      const mockEvent = { id, type: 'tool' as const, name, input, output: mock.result, timestamp: start, durationMs }
+      recorder.record(mockEvent)
+      if (httpCtx) pushTelemetryEvent(mockEvent)
+      if (trace && typeof trace.recordToolCall === 'function') {
+        trace.recordToolCall({ name, args: toTraceArgs(input), result: mock.result, workflowEventId: id, durationMs })
+      }
+      return mock.result as R
+    }
+
     const g = globalThis as Record<string, unknown>
     const prev = g[TOOL_WRAPPER_ACTIVE_KEY]
     g[TOOL_WRAPPER_ACTIVE_KEY] = true
-    const start = rawDateNow()
 
     try {
       const output = await fn(...args)

package/src/internals/errors.ts

@@ -0,0 +1,14 @@
+/**
+ * Thrown when strict mode is active and a tool is called that has no
+ * matching mock entry and no replay history. Lets callers (the workflow
+ * runner, tests, the MCP) detect strict-mode violations precisely.
+ */
+export class ElasticdashStrictModeError extends Error {
+  readonly tool_name: string
+
+  constructor(toolName: string) {
+    super(`tool "${toolName}" called but no mock entry. Add it to live_tools or to mocked_tools.`)
+    this.name = 'ElasticdashStrictModeError'
+    this.tool_name = toolName
+  }
+}

package/src/internals/mock-resolver.ts

@@ -6,8 +6,15 @@
  * wrapped function calls `resolveMock` / `resolveAIMock` at its entry point.
  * The worker writes the mock config to `__ELASTICDASH_TOOL_MOCKS__` /
  * `__ELASTICDASH_AI_MOCKS__` before the workflow runs and clears it after.
+ *
+ * Strict mode (`__ELASTICDASH_STRICT__ === true`) makes any non-replay,
+ * non-mock tool call throw `ElasticdashStrictModeError`. Replay is enforced
+ * upstream by `wrapTool`'s capture context, so by the time `resolveMock`
+ * runs we are on the live path and any miss is a strict-mode violation.
  */
 
+import { ElasticdashStrictModeError } from './errors.js'
+
 interface ToolMockEntry {
   mode: 'live' | 'mock-all' | 'mock-specific'
   callIndices?: number[]
@@ -69,12 +76,25 @@ export function normaliseMockResult(value: unknown): unknown {
  */
 export function resolveMock(toolName: string): MockResult {
   const g = globalThis as Record<string, unknown>
+  const strict = g['__ELASTICDASH_STRICT__'] === true
 
   const mocks = g['__ELASTICDASH_TOOL_MOCKS__'] as Record<string, ToolMockEntry> | undefined
-  if (!mocks) return { mocked: false }
+  if (!mocks) {
+    if (strict) throw new ElasticdashStrictModeError(toolName)
+    return { mocked: false }
+  }
 
   const entry = mocks[toolName]
-  if (!entry || entry.mode === 'live') return { mocked: false }
+  // `mode: 'live'` is the explicit live-allowlist marker — emitted by the MCP
+  // (or hand-set by the user) to say "this tool is in live_tools, run it live
+  // and don't trip strict mode." Without an entry at all, strict still throws.
+  if (entry && entry.mode === 'live') {
+    return { mocked: false }
+  }
+  if (!entry) {
+    if (strict) throw new ElasticdashStrictModeError(toolName)
+    return { mocked: false }
+  }
 
   // Initialise counters map if not yet present
   if (!g['__ELASTICDASH_TOOL_CALL_COUNTERS__']) {
@@ -96,10 +116,12 @@ export function resolveMock(toolName: string): MockResult {
       const data = entry.mockData ?? {}
       return { mocked: true, result: normaliseMockResult(data[callNumber]) }
     }
-    // Counter already incremented; this specific call runs live
+    // Counter already incremented; this specific call runs live (or trips strict)
+    if (strict) throw new ElasticdashStrictModeError(toolName)
     return { mocked: false }
   }
 
+  if (strict) throw new ElasticdashStrictModeError(toolName)
   return { mocked: false }
 }
 

package/src/observability.ts

@@ -53,6 +53,16 @@ let shutdownRegistered = false
  * fall back to 'unknown-workflow'.
  */
 function resolveDefaultWorkflowName(cwd: string, workflows: ReturnType<typeof scanWorkflows>): string {
+  // Explicit override from the caller (e.g. `elasticdash run-workflow <name>`
+  // sets ELASTICDASH_WORKFLOW_NAME before initialising observability). When
+  // present, this wins — the scanner is only used as a fallback heuristic
+  // when no one knows the workflow name yet.
+  const envName = process.env.ELASTICDASH_WORKFLOW_NAME
+  if (envName && envName.trim()) {
+    debugLog(`[elasticdash] Workflow name from ELASTICDASH_WORKFLOW_NAME: ${envName}`)
+    return envName.trim()
+  }
+
   // Filter out SDK utility functions that users commonly export from ed_workflows.ts
   const UTILITY_PREFIXES = ['edStartTrace', 'edEndTrace', 'setElasticDashModule', 'setElasticDash']
   const candidates = workflows.filter(w => !UTILITY_PREFIXES.some(p => w.name === p))

package/src/workflow-runner-worker.ts

@@ -27,6 +27,7 @@ import { pathToFileURL } from 'node:url'
 import type { TraceHandle } from './trace-adapter/context.js'
 import type { WorkflowEvent } from './capture/event.js'
 import type { AgentState } from './types/agent.js'
+import { ElasticdashStrictModeError } from './internals/errors.js'
 import fs from 'node:fs'
 
 const TOOL_WRAPPER_ACTIVE_KEY = '__elasticdash_tool_wrapper_active__'
@@ -95,6 +96,7 @@ async function loadAndWrapTools(
   toolsModulePath: string,
   trace: TraceHandle,
   toolMockConfig?: ToolMockConfig,
+  strict?: boolean,
 ): Promise<Record<string, (...a: unknown[]) => unknown>> {
   try {
     // Use absolute file URL for ESM import
@@ -156,6 +158,16 @@ async function loadAndWrapTools(
             toolCallCounters[name]++
           }
 
+          // Strict mode: no replay match, no mock hit → fail closed and
+          // record the failed call so envelopes/trace surfaces show why.
+          if (strict) {
+            const err = new ElasticdashStrictModeError(name)
+            const durationMs = rawDateNow() - start
+            if (ctx) ctx.recorder.record({ id, type: 'tool', name, input: recordedArgs, output: { error: err.message }, timestamp: start, durationMs })
+            trace.recordToolCall({ name, args: recordedArgs, result: { error: err.message }, workflowEventId: id, durationMs })
+            throw err
+          }
+
           const g = globalThis as Record<string, unknown>
           const prev = g[TOOL_WRAPPER_ACTIVE_KEY]
           const restoreWrapperFlag = () => {
@@ -227,6 +239,8 @@ async function main() {
     promptMockConfig?: Record<string, unknown>
     /** Optional user prompt mock config: keyed by original user message text */
     userPromptMockConfig?: Record<string, { mode: 'live' | 'replace-all' | 'replace-specific'; replacement: string; callIndices?: number[] }>
+    /** Fail-closed mode: throw ElasticdashStrictModeError for any non-replay, non-mock tool call. */
+    strict?: boolean
   }
   try {
     payload = JSON.parse(raw)
@@ -236,7 +250,7 @@ async function main() {
     return
   }
 
-  const { workflowsModulePath, toolsModulePath, workflowName, args, input, replayMode = false, checkpoint = 0, history = [], agentState, toolMockConfig, aiMockConfig, promptMockConfig, userPromptMockConfig } = payload
+  const { workflowsModulePath, toolsModulePath, workflowName, args, input, replayMode = false, checkpoint = 0, history = [], agentState, toolMockConfig, aiMockConfig, promptMockConfig, userPromptMockConfig, strict } = payload
 
   const { context, finalise } = startTraceSession()
   setCurrentTrace(context.trace)
@@ -254,7 +268,7 @@ async function main() {
   let wrappedTools: Record<string, (...a: unknown[]) => unknown> = {}
 
   if (toolsModulePath) {
-    wrappedTools = await loadAndWrapTools(toolsModulePath, context.trace, toolMockConfig)
+    wrappedTools = await loadAndWrapTools(toolsModulePath, context.trace, toolMockConfig, strict)
     for (const [name, fn] of Object.entries(wrappedTools)) {
       originalValues[name] = globals[name]
       globals[name] = fn
@@ -284,6 +298,7 @@ async function main() {
     ;(globalThis as any).__ELASTICDASH_PROMPT_CALL_COUNTERS__ = {}
     ;(globalThis as any).__ELASTICDASH_USER_PROMPT_MOCKS__ = userPromptMockConfig ?? {}
     ;(globalThis as any).__ELASTICDASH_USER_PROMPT_CALL_COUNTERS__ = {}
+    ;(globalThis as any).__ELASTICDASH_STRICT__ = strict === true
 
     await installDBAutoInterceptor()
     installAIInterceptor()
@@ -350,6 +365,7 @@ async function main() {
     delete (globalThis as any).__ELASTICDASH_PROMPT_CALL_COUNTERS__
     delete (globalThis as any).__ELASTICDASH_USER_PROMPT_MOCKS__
     delete (globalThis as any).__ELASTICDASH_USER_PROMPT_CALL_COUNTERS__
+    delete (globalThis as any).__ELASTICDASH_STRICT__
   }
 
   await recorder.flush()

package/src/workflow-runner.ts

@@ -47,6 +47,15 @@ export async function runWorkflow<T = unknown>(
     const trace = recorder.toTrace()
     await maybeCaptureTrace(trace.events, trace.traceId)
     return { result, trace }
+  } catch (e) {
+    // Attach the partial trace so the caller can include any events recorded
+    // before the throw (e.g. strict-mode tool calls that fail-closed).
+    try {
+      await recorder.flush()
+      const trace = recorder.toTrace()
+      ;(e as { trace?: WorkflowTrace }).trace = trace
+    } catch { /* best-effort */ }
+    throw e
   } finally {
     if (interceptHttp) restoreFetch()
     if (interceptSideEffects) {