elasticdash-test 0.1.17 → 0.1.18-alpha

package/src/observability.ts

@@ -0,0 +1,281 @@
+import { randomUUID } from 'node:crypto'
+import { TelemetryBatcher } from './telemetry-batcher.js'
+import {
+  setObservabilityContext,
+  getObservabilityContext,
+  clearObservabilityContext,
+  pushTelemetryEvent,
+} from './interceptors/telemetry-push.js'
+import type { ObservabilityContext } from './interceptors/telemetry-push.js'
+import { installAIInterceptor } from './interceptors/ai-interceptor.js'
+import { interceptFetch } from './interceptors/http.js'
+import { installDBAutoInterceptor } from './interceptors/db-auto.js'
+import { executeTrigger } from './trigger-executor.js'
+import { scanTools, scanWorkflows } from './execution/tool-runner.js'
+import { debugLog } from './utils/debug.js'
+
+export interface ObservabilityOptions {
+  serverUrl?: string
+  apiKey?: string
+  serviceId?: string
+  sessionId?: string
+  batchIntervalMs?: number
+  maxBatchSize?: number
+  heartbeatIntervalMs?: number
+  sampleRate?: number
+  redactKeys?: string[]
+}
+
+export interface ObservabilityHandle {
+  sessionId: string
+  shutdown: () => Promise<void>
+}
+
+let heartbeatTimer: ReturnType<typeof setInterval> | null = null
+let shutdownRegistered = false
+
+/**
+ * Initialise active observability mode. All `wrapTool` / `wrapAI` calls will
+ * automatically record and stream trace events to the configured backend.
+ *
+ * Reads from environment variables as fallback:
+ * - `ELASTICDASH_API_URL` — backend API URL (required)
+ * - `ELASTICDASH_API_KEY` — project auth token
+ * - `ELASTICDASH_SERVICE_ID` — service/app identifier
+ * - `ELASTICDASH_SESSION_ID` — session identifier (auto-generated if omitted)
+ */
+export function initObservability(options?: ObservabilityOptions): ObservabilityHandle {
+  const serverUrl = options?.serverUrl ?? process.env.ELASTICDASH_API_URL ?? ''
+  if (!serverUrl) {
+    throw new Error('[elasticdash] initObservability: serverUrl is required (set ELASTICDASH_API_URL or pass serverUrl option)')
+  }
+
+  const apiKey = options?.apiKey ?? process.env.ELASTICDASH_API_KEY
+  const serviceId = options?.serviceId ?? process.env.ELASTICDASH_SERVICE_ID ?? 'unknown-service'
+  const sessionId = options?.sessionId ?? process.env.ELASTICDASH_SESSION_ID ?? randomUUID()
+  const sampleRate = options?.sampleRate ?? 1.0
+  const redactKeys = options?.redactKeys ?? []
+  const heartbeatIntervalMs = options?.heartbeatIntervalMs ?? 30_000
+
+  const batcher = new TelemetryBatcher({
+    serverUrl,
+    apiKey,
+    sessionId,
+    serviceId,
+    batchIntervalMs: options?.batchIntervalMs,
+    maxBatchSize: options?.maxBatchSize,
+    redactKeys,
+    onTrigger: async (trigger) => {
+      await executeTrigger(serverUrl, apiKey, trigger)
+    },
+  })
+
+  let counter = 0
+  const traceId = `${serviceId}::${Date.now()}::${randomUUID().slice(0, 8)}`
+  const ctx: ObservabilityContext = {
+    sessionId,
+    serviceId,
+    serverUrl,
+    apiKey,
+    batcher,
+    nextId: () => ++counter,
+    sampleRate,
+    redactKeys,
+    traceId,
+  }
+
+  setObservabilityContext(ctx)
+  installAIInterceptor()
+  interceptFetch()
+  installDBAutoInterceptor().catch(() => {})
+
+  // Heartbeat
+  heartbeatTimer = setInterval(() => {
+    batcher.enqueue({
+      id: ctx.nextId(),
+      type: 'side_effect',
+      name: '__heartbeat__',
+      input: { sessionId, serviceId },
+      output: { uptime: process.uptime() },
+      timestamp: Date.now(),
+      durationMs: 0,
+      schemaVersion: 1,
+    })
+  }, heartbeatIntervalMs)
+  if (heartbeatTimer && typeof heartbeatTimer === 'object' && 'unref' in heartbeatTimer) {
+    heartbeatTimer.unref()
+  }
+
+  // Register process exit hooks (once)
+  if (!shutdownRegistered) {
+    shutdownRegistered = true
+    const onExit = () => { shutdownObservability().catch(() => {}) }
+    process.once('beforeExit', onExit)
+    process.once('SIGTERM', onExit)
+    process.once('SIGINT', onExit)
+  }
+
+  debugLog(`[elasticdash] Observability initialised — sessionId=${sessionId} serviceId=${serviceId} server=${serverUrl}`)
+
+  // Push workflow/tool catalog to backend (fire-and-forget)
+  pushCatalog(serverUrl, apiKey).catch(() => {})
+
+  return {
+    sessionId,
+    shutdown: () => shutdownObservability(),
+  }
+}
+
+/**
+ * Scan ed_workflows.ts and ed_tools.ts, then POST the catalog to the backend
+ * so it registers the real function names instead of falling back to serviceId.
+ */
+async function pushCatalog(serverUrl: string, apiKey?: string): Promise<void> {
+  const cwd = process.cwd()
+  const workflows = scanWorkflows(cwd)
+  const tools = scanTools(cwd)
+
+  if (workflows.length === 0 && tools.length === 0) return
+
+  const body: Record<string, unknown> = {}
+  if (workflows.length > 0) body.workflows = workflows.map(w => ({ name: w.name }))
+  if (tools.length > 0) body.tools = tools.map(t => ({ name: t.name }))
+
+  const headers: Record<string, string> = { 'Content-Type': 'application/json' }
+  if (apiKey) headers['Authorization'] = `Bearer ${apiKey}`
+
+  try {
+    const res = await fetch(`${serverUrl.replace(/\/$/, '')}/api/observability/catalog`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body),
+    })
+    debugLog(`[elasticdash] Catalog pushed: ${workflows.length} workflows, ${tools.length} tools (status ${res.status})`)
+  } catch (err) {
+    debugLog(`[elasticdash] Catalog push failed: ${err instanceof Error ? err.message : String(err)}`)
+  }
+}
+
+/**
+ * Gracefully shut down observability: flush remaining events, send session_end,
+ * stop heartbeat, and clear context.
+ */
+export async function shutdownObservability(): Promise<void> {
+  const ctx = getObservabilityContext()
+  if (!ctx) return
+
+  // Stop heartbeat
+  if (heartbeatTimer) {
+    clearInterval(heartbeatTimer)
+    heartbeatTimer = null
+  }
+
+  // Send session_end event
+  ctx.batcher.enqueue({
+    id: ctx.nextId(),
+    type: 'side_effect',
+    name: '__session_end__',
+    input: { sessionId: ctx.sessionId, serviceId: ctx.serviceId },
+    output: { uptime: process.uptime() },
+    timestamp: Date.now(),
+    durationMs: 0,
+    schemaVersion: 1,
+  })
+
+  // Flush and shut down the batcher
+  await ctx.batcher.shutdown()
+
+  clearObservabilityContext()
+  debugLog(`[elasticdash] Observability shut down — sessionId=${ctx.sessionId}`)
+}
+
+/**
+ * Start a new trace for the current request/operation.
+ *
+ * Call this at the start of each request handler to group all tool/AI events
+ * under one trace, identified by the workflow name.
+ *
+ * The generated traceId encodes the workflow name and timestamp for easy
+ * parsing by the backend: `{workflowName}::{timestamp}::{shortId}`
+ *
+ * @param workflowName — the workflow/function being executed (e.g. 'chatStreamHandler')
+ * @returns The new traceId
+ *
+ * @example
+ * ```ts
+ * // In a route handler:
+ * startTrace('chatStreamHandler')
+ * // All subsequent wrapTool/wrapAI calls get traceId = "chatStreamHandler::1712851200000::a1b2c3d4"
+ * ```
+ */
+export function startTrace(workflowName?: string): string {
+  const ctx = getObservabilityContext()
+  if (!ctx) throw new Error('[elasticdash] startTrace: observability not initialised')
+  const timestamp = Date.now()
+  const shortId = randomUUID().slice(0, 8)
+  if (workflowName) {
+    ctx.traceId = `${workflowName}::${timestamp}::${shortId}`
+  } else {
+    ctx.traceId = `${ctx.serviceId}::${timestamp}::${shortId}`
+  }
+  return ctx.traceId
+}
+
+/**
+ * Wrap a workflow function so that every invocation automatically starts a new
+ * trace with the workflow name. All tool/AI calls within the function execution
+ * are grouped under that trace.
+ *
+ * Use this in `ed_workflows.ts` to automatically tag each workflow execution:
+ *
+ * @example
+ * ```ts
+ * export const chatStreamHandler = wrapWorkflow('chatStreamHandler', async (input) => {
+ *   const result = await fetchUser(input.userId)
+ *   const reply = await generateReply(result)
+ *   return reply
+ * })
+ * ```
+ */
+export function wrapWorkflow<Args extends unknown[], R>(
+  name: string,
+  fn: (...args: Args) => Promise<R>,
+): (...args: Args) => Promise<R> {
+  return async (...args: Args): Promise<R> => {
+    const ctx = getObservabilityContext()
+    if (ctx) {
+      startTrace(name)
+      const start = Date.now()
+      let result: R
+      try {
+        result = await fn(...args)
+      } catch (err) {
+        // Emit workflow event with error output
+        pushTelemetryEvent({
+          id: ctx.nextId(),
+          type: 'workflow',
+          name,
+          input: args.length === 1 ? args[0] : args,
+          output: { error: err instanceof Error ? err.message : String(err) },
+          timestamp: start,
+          durationMs: Date.now() - start,
+          schemaVersion: 1,
+        })
+        throw err
+      }
+      // Emit workflow event with successful output
+      pushTelemetryEvent({
+        id: ctx.nextId(),
+        type: 'workflow',
+        name,
+        input: args.length === 1 ? args[0] : args,
+        output: result,
+        timestamp: start,
+        durationMs: Date.now() - start,
+        schemaVersion: 1,
+      })
+      return result
+    }
+    return fn(...args)
+  }
+}

package/src/portal-executor.ts

@@ -0,0 +1,335 @@
+import { callProviderLLM } from './matchers/index.js'
+import {
+  scanTools,
+  resolveRuntimeModule,
+  buildToolArgs,
+  runToolInSubprocess,
+} from './execution/tool-runner.js'
+import type { ToolInfo } from './execution/tool-runner.js'
+import type { PortalTask, PortalTaskResult } from './types/portal.js'
+import { debugLog } from './utils/debug.js'
+
+type SupportedProvider = 'openai' | 'claude' | 'gemini' | 'grok' | 'kimi'
+
+/** Provider → required env var name */
+const PROVIDER_API_KEY_ENV: Record<SupportedProvider, string> = {
+  openai: 'OPENAI_API_KEY',
+  claude: 'ANTHROPIC_API_KEY',
+  gemini: 'GEMINI_API_KEY',
+  grok: 'GROK_API_KEY',
+  kimi: 'KIMI_API_KEY',
+}
+
+// ---------------------------------------------------------------------------
+// Prompt extraction (mirrors dashboard-server.ts logic)
+// ---------------------------------------------------------------------------
+
+function normalizeMessageContent(content: unknown): string {
+  if (typeof content === 'string') return content
+  if (Array.isArray(content)) {
+    return content
+      .map((part) => {
+        if (typeof part === 'string') return part
+        if (part && typeof part === 'object' && typeof (part as any).text === 'string') return (part as any).text
+        try { return JSON.stringify(part) } catch { return String(part) }
+      })
+      .join('\n')
+  }
+  if (content && typeof content === 'object') {
+    if (typeof (content as any).text === 'string') return (content as any).text
+    try { return JSON.stringify(content) } catch { return String(content) }
+  }
+  return content == null ? '' : String(content)
+}
+
+function extractPromptFromInput(input: unknown): { prompt: string; systemPrompt?: string } {
+  if (typeof input === 'string') return { prompt: input }
+
+  const messages = Array.isArray(input)
+    ? input
+    : input && typeof input === 'object' && Array.isArray((input as any).messages)
+      ? (input as any).messages
+      : null
+
+  if (messages && messages.length > 0) {
+    const systemParts: string[] = []
+    const promptParts: string[] = []
+    for (const message of messages as Array<any>) {
+      const role = typeof message?.role === 'string' ? message.role : 'user'
+      const content = normalizeMessageContent(message?.content).trim()
+      if (!content) continue
+      if (role === 'system') systemParts.push(content)
+      else promptParts.push(`${role}: ${content}`)
+    }
+    return {
+      prompt: promptParts.join('\n\n') || systemParts.join('\n\n') || JSON.stringify(input),
+      systemPrompt: systemParts.length > 0 ? systemParts.join('\n\n') : undefined,
+    }
+  }
+
+  if (input && typeof input === 'object' && typeof (input as any).prompt === 'string') {
+    return {
+      prompt: (input as any).prompt,
+      systemPrompt: typeof (input as any).systemPrompt === 'string' ? (input as any).systemPrompt : undefined,
+    }
+  }
+
+  try { return { prompt: JSON.stringify(input) } }
+  catch { return { prompt: String(input ?? '') } }
+}
+
+function inferProvider(task: PortalTask): SupportedProvider {
+  const provider = task.provider?.toLowerCase()
+  if (provider === 'openai' || provider === 'claude' || provider === 'gemini' || provider === 'grok' || provider === 'kimi') {
+    return provider
+  }
+  const model = (task.model ?? task.name)?.toLowerCase() ?? ''
+  if (model.includes('claude')) return 'claude'
+  if (model.includes('gemini')) return 'gemini'
+  if (model.includes('grok')) return 'grok'
+  if (model.includes('kimi')) return 'kimi'
+  return 'openai'
+}
+
+// ---------------------------------------------------------------------------
+// Availability checks (used by trigger-executor for pre-validation)
+// ---------------------------------------------------------------------------
+
+export interface AvailabilityResult {
+  available: boolean
+  reason?: string
+}
+
+/**
+ * Check if a tool is available for execution.
+ * Returns { available: true } or { available: false, reason: "..." }.
+ */
+export function checkToolAvailability(
+  name: string,
+  cwd: string,
+  tools: ToolInfo[],
+): AvailabilityResult {
+  if (!name) {
+    return { available: false, reason: 'Missing tool name.' }
+  }
+  const toolsModulePath = resolveRuntimeModule(cwd, 'ed_tools')
+  if (!toolsModulePath) {
+    return { available: false, reason: 'Cannot find ed_tools.ts/js in workspace root.' }
+  }
+  const toolInfo = tools.find(t => t.name === name)
+  if (!toolInfo) {
+    const available = tools.map(t => t.name).join(', ') || '(none found)'
+    return { available: false, reason: `Tool not found: "${name}". Available tools: ${available}` }
+  }
+  return { available: true }
+}
+
+/**
+ * Check if an AI provider is available for execution (API key present).
+ * Returns { available: true } or { available: false, reason: "..." }.
+ */
+export function checkAIAvailability(
+  provider?: string,
+  model?: string,
+): AvailabilityResult {
+  const resolved = inferProviderFromArgs(provider, model)
+  const supportedProviders: SupportedProvider[] = ['openai', 'claude', 'gemini', 'grok', 'kimi']
+  if (!supportedProviders.includes(resolved)) {
+    return { available: false, reason: `Unsupported AI provider: "${provider ?? model}". Supported: ${supportedProviders.join(', ')}` }
+  }
+  const envVar = PROVIDER_API_KEY_ENV[resolved]
+  if (!process.env[envVar]) {
+    if (resolved === 'gemini' && process.env.GOOGLE_API_KEY) {
+      return { available: true }
+    }
+    return { available: false, reason: `Missing API key for provider "${resolved}". Expected environment variable: ${envVar}` }
+  }
+  return { available: true }
+}
+
+function inferProviderFromArgs(provider?: string, model?: string): SupportedProvider {
+  const p = provider?.toLowerCase()
+  if (p === 'openai' || p === 'claude' || p === 'gemini' || p === 'grok' || p === 'kimi') return p
+  const m = (model ?? '')?.toLowerCase()
+  if (m.includes('claude')) return 'claude'
+  if (m.includes('gemini')) return 'gemini'
+  if (m.includes('grok')) return 'grok'
+  if (m.includes('kimi')) return 'kimi'
+  return 'openai'
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute a portal task (tool or AI rerun). Returns a structured result with
+ * output, duration, usage, and error information.
+ *
+ * Error handling:
+ * - Tool not found in ed_tools → ok:false with descriptive error
+ * - ed_tools.ts/js missing → ok:false with descriptive error
+ * - AI provider unsupported → ok:false with error
+ * - AI provider API key missing → ok:false with error naming the expected env var
+ * - Subprocess crash → ok:false with stderr excerpt
+ * - Any other exception → ok:false with error message
+ */
+export async function executePortalTask(
+  task: PortalTask,
+  cwd: string,
+  tools: ToolInfo[],
+): Promise<PortalTaskResult> {
+  const start = Date.now()
+  try {
+    if (task.type === 'tool') {
+      return await executeToolTask(task, cwd, tools)
+    }
+    if (task.type === 'ai') {
+      return await executeAITask(task)
+    }
+    return {
+      taskId: task.taskId,
+      ok: false,
+      output: null,
+      error: `Unknown task type: ${task.type}`,
+      durationMs: Date.now() - start,
+      metadata: task.metadata,
+    }
+  } catch (e) {
+    return {
+      taskId: task.taskId,
+      ok: false,
+      output: null,
+      error: e instanceof Error ? e.message : String(e),
+      durationMs: Date.now() - start,
+      metadata: task.metadata,
+    }
+  }
+}
+
+async function executeToolTask(
+  task: PortalTask,
+  cwd: string,
+  tools: ToolInfo[],
+): Promise<PortalTaskResult> {
+  const start = Date.now()
+
+  if (!task.name) {
+    return { taskId: task.taskId, ok: false, output: null, error: 'Missing tool name on task.', durationMs: 0, metadata: task.metadata }
+  }
+
+  // Check tool exists in the scanned tool list
+  const toolInfo = tools.find(t => t.name === task.name)
+  if (!toolInfo) {
+    const available = tools.map(t => t.name).join(', ') || '(none found)'
+    return {
+      taskId: task.taskId, ok: false, output: null,
+      error: `Tool not found: "${task.name}". Available tools: ${available}`,
+      durationMs: 0, metadata: task.metadata,
+    }
+  }
+
+  // Resolve ed_tools module
+  const toolsModulePath = resolveRuntimeModule(cwd, 'ed_tools')
+  if (!toolsModulePath) {
+    return {
+      taskId: task.taskId, ok: false, output: null,
+      error: 'Cannot find ed_tools.ts/js in workspace root.',
+      durationMs: 0, metadata: task.metadata,
+    }
+  }
+
+  // Parse input
+  let parsedInput = task.input
+  if (typeof parsedInput === 'string') {
+    try { parsedInput = JSON.parse(parsedInput) } catch { /* use as-is */ }
+  }
+
+  const args = buildToolArgs(parsedInput, toolInfo)
+  debugLog(`[elasticdash portal] Executing tool: ${task.name}`, { args })
+
+  const result = await runToolInSubprocess(toolsModulePath, task.name, args)
+  const durationMs = result.currentDurationMs ?? (Date.now() - start)
+
+  return {
+    taskId: task.taskId,
+    ok: result.ok,
+    output: result.currentOutput ?? null,
+    error: result.error,
+    durationMs,
+    usage: result.currentUsage,
+    metadata: task.metadata,
+  }
+}
+
+async function executeAITask(task: PortalTask): Promise<PortalTaskResult> {
+  const start = Date.now()
+
+  // Infer provider
+  const provider = inferProvider(task)
+  const supportedProviders: SupportedProvider[] = ['openai', 'claude', 'gemini', 'grok', 'kimi']
+  if (!supportedProviders.includes(provider)) {
+    return {
+      taskId: task.taskId, ok: false, output: null,
+      error: `Unsupported AI provider: "${task.provider}". Supported: ${supportedProviders.join(', ')}`,
+      durationMs: 0, metadata: task.metadata,
+    }
+  }
+
+  // Check API key is available
+  const envVar = PROVIDER_API_KEY_ENV[provider]
+  if (!process.env[envVar]) {
+    // Gemini also accepts GOOGLE_API_KEY
+    if (provider === 'gemini' && process.env.GOOGLE_API_KEY) {
+      // ok, fallback key available
+    } else {
+      return {
+        taskId: task.taskId, ok: false, output: null,
+        error: `Missing API key for provider "${provider}". Expected environment variable: ${envVar}`,
+        durationMs: 0, metadata: task.metadata,
+      }
+    }
+  }
+
+  // Extract prompt from input
+  const { prompt, systemPrompt } = extractPromptFromInput(task.input)
+  if (!prompt.trim()) {
+    return {
+      taskId: task.taskId, ok: false, output: null,
+      error: 'AI task input is empty; cannot execute.',
+      durationMs: 0, metadata: task.metadata,
+    }
+  }
+
+  const model = task.model ?? task.name
+  const temperature = typeof task.modelParameters?.temperature === 'number' ? task.modelParameters.temperature : 0
+  const maxTokens = typeof task.modelParameters?.max_tokens === 'number' ? task.modelParameters.max_tokens : 512
+
+  debugLog(`[elasticdash portal] Executing AI: provider=${provider} model=${model}`)
+
+  try {
+    const result = await callProviderLLM(
+      prompt,
+      { provider, model },
+      systemPrompt ?? 'You are a helpful assistant.',
+      maxTokens,
+      temperature,
+    )
+
+    return {
+      taskId: task.taskId,
+      ok: true,
+      output: result.content,
+      durationMs: result.durationMs ?? (Date.now() - start),
+      usage: result.usage,
+      metadata: task.metadata,
+    }
+  } catch (e) {
+    return {
+      taskId: task.taskId, ok: false, output: null,
+      error: `AI execution failed: ${e instanceof Error ? e.message : String(e)}`,
+      durationMs: Date.now() - start,
+      metadata: task.metadata,
+    }
+  }
+}