Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
6.6 KB
Raw Blame
import { randomUUID } from 'node:crypto'
import * as fs from 'node:fs/promises'
import { WorkflowSDKInitError } from '../errors'
import { createFileRuntimeTokenProvider } from '../runtime-token-provider/provider'
import type { WorkflowConfig, WorkflowRecipeSpec, WorkflowTraceContext } from './types'

const DEFAULT_SPEC_VOLUME_PATH = '/etc/workflow/config.json'
const STEP_RUN_KEYS = new Set(['type', 'language', 'code', 'capabilities'])

function requireEnv(name: string): string {
  const value = process.env[name]
  if (!value) throw new WorkflowSDKInitError(name)
  return value
}

function resolveTraceContext(): WorkflowTraceContext {
  const workflowRunId = process.env.CLERUM_WORKFLOW_RUN_ID?.trim()
  const correlationId = process.env.CLERUM_CORRELATION_ID?.trim()

  // WRC marks workflow executions with CLERUM_WORKFLOW_RUN_ID. Preserve the
  // legacy UUID fallback only for callers outside that run-scoped contract.
  if (process.env.CLERUM_WORKFLOW_RUN_ID !== undefined) {
    if (!workflowRunId) throw new WorkflowSDKInitError('CLERUM_WORKFLOW_RUN_ID')
    if (!correlationId) throw new WorkflowSDKInitError('CLERUM_CORRELATION_ID')
    if (correlationId !== workflowRunId) {
      throw new Error('CLERUM_CORRELATION_ID must match CLERUM_WORKFLOW_RUN_ID for workflow execution')
    }
    return { origin: 'workflow_runtime', runId: workflowRunId, correlationId }
  }

  return {
    origin: 'workflow_runtime',
    runId: null,
    correlationId: correlationId || randomUUID(),
  }
}

export class ConfigLoader {
  private readonly config: WorkflowConfig
  private specCache: WorkflowRecipeSpec | null = null

  constructor() {
    const workflowName = requireEnv('CLERUM_WORKFLOW_NAME')
    const namespace = requireEnv('CLERUM_NAMESPACE')
    const wrcUrl = requireEnv('CLERUM_WRC_URL')
    const wrcTokenFile = requireEnv('WRC_TOKEN_FILE')
    const mcpHostTokenFile = process.env.MCP_HOST_TOKEN_FILE
    const snippetRunnerTokenFile = process.env.SNIPPET_RUNNER_TOKEN_FILE
    if (process.env.CLERUM_MCPHOST_URL && !mcpHostTokenFile) {
      throw new WorkflowSDKInitError('MCP_HOST_TOKEN_FILE')
    }
    if (process.env.CLERUM_SNIPPET_RUNNER_URL && !snippetRunnerTokenFile) {
      throw new WorkflowSDKInitError('SNIPPET_RUNNER_TOKEN_FILE')
    }
    const traceContext = resolveTraceContext()
    this.config = {
      workflowName,
      namespace,
      wrcUrl,
      wrcTokenFile,
      mcpHostUrl: process.env.CLERUM_MCPHOST_URL,
      mcpHostTokenFile,
      snippetRunnerUrl: process.env.CLERUM_SNIPPET_RUNNER_URL,
      snippetRunnerTokenFile,
      tokenProvider: createFileRuntimeTokenProvider({
        wrcTokenFile,
        mcpHostTokenFile,
        snippetRunnerTokenFile,
      }),
      correlationId: traceContext.correlationId,
      traceContext,
      signalPollIntervalMs: ConfigLoader.parseInterval(process.env.CLERUM_SIGNAL_POLL_INTERVAL_MS),
      restPort: ConfigLoader.parsePort(process.env.CLERUM_SDK_REST_PORT),
      registryUrl: process.env.CLERUM_REGISTRY_URL,
      storageEndpoint: process.env.CLERUM_STORAGE_ENDPOINT,
    }
  }

  private static parseInterval(raw?: string): number {
    const parsed = parseInt(raw || '5000', 10)
    return Number.isFinite(parsed) && parsed >= 500 ? parsed : 5000
  }

  private static parsePort(raw?: string): number {
    const parsed = parseInt(raw || '8090', 10)
    return Number.isInteger(parsed) && parsed > 0 && parsed <= 65535 ? parsed : 8090
  }

  getConfig(): WorkflowConfig {
    return this.config
  }

  async getSpec(): Promise<WorkflowRecipeSpec> {
    if (this.specCache) return this.specCache

    let raw: string
    try {
      raw = await fs.readFile(ConfigLoader.specPath(), 'utf-8')
    } catch {
      // Volume not available — spec MUST be mounted as a volume.
      // There is no WRC REST fallback for spec retrieval.
      throw new Error(
        `Workflow spec not found at ${ConfigLoader.specPath()}. ` +
          'Ensure the WRC mounts the spec ConfigMap as a volume.'
      )
    }

    let parsed: unknown
    try {
      parsed = JSON.parse(raw)
    } catch {
      throw new Error('Workflow spec at /etc/workflow/config.json is not valid JSON')
    }

    ConfigLoader.validateSpec(parsed)
    this.specCache = parsed as WorkflowRecipeSpec
    return this.specCache
  }

  private static validateSpec(parsed: unknown): void {
    if (typeof parsed !== 'object' || parsed === null) {
      throw new Error('Workflow spec must be a JSON object')
    }
    const spec = parsed as Record<string, unknown>
    if (typeof spec.name !== 'string' || !spec.name) {
      throw new WorkflowSDKInitError('spec.name')
    }
    if (!Array.isArray(spec.steps)) {
      throw new Error('Workflow spec missing required field: steps (must be an array)')
    }
    const hasCustomCoordinator =
      typeof spec.coordinatorImage === 'string' && spec.coordinatorImage.trim() !== ''

    for (const step of spec.steps as unknown[]) {
      if (typeof step !== 'object' || step === null) {
        throw new Error('Each step in spec.steps must be an object')
      }
      const s = step as Record<string, unknown>
      if (typeof s.id !== 'string' || !s.id) {
        throw new Error('Each step must have a non-empty string id')
      }
      const hasRun = typeof s.run === 'object' && s.run !== null
      const hasInstruction = typeof s.instruction === 'string' && s.instruction.trim() !== ''
      if (hasRun && hasInstruction) {
        throw new Error(`Step "${s.id}" cannot declare both run and instruction`)
      }
      if (!hasCustomCoordinator && hasRun === hasInstruction) {
        throw new Error(`Step "${s.id}" must have exactly one of run or instruction`)
      }
      if (hasRun) {
        const run = s.run as Record<string, unknown>
        ConfigLoader.assertAllowedKeys(run, STEP_RUN_KEYS, `Step "${s.id}" run`)
        if (run.type !== 'snippet') {
          throw new Error(`Step "${s.id}" run.type must be snippet`)
        }
        if (run.language !== 'typescript') {
          throw new Error(`Step "${s.id}" snippet language must be typescript`)
        }
        if (typeof run.code !== 'string' || run.code.trim() === '') {
          throw new Error(`Step "${s.id}" snippet code must be a non-empty string`)
        }
      }
    }
  }

  private static assertAllowedKeys(
    value: Record<string, unknown>,
    allowedKeys: Set<string>,
    path: string
  ): void {
    for (const key of Object.keys(value)) {
      if (!allowedKeys.has(key)) {
        throw new Error(`${path} contains unsupported field "${key}"`)
      }
    }
  }

  private static specPath(): string {
    return (
      process.env.CLERUM_WORKFLOW_CONFIG_PATH ||
      process.env.WORKFLOW_CONFIG_PATH ||
      DEFAULT_SPEC_VOLUME_PATH
    )
  }
}