Skip to content

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

TypeScript
12.9 KB
Raw Blame
/**
 * Per-Step MCP Server Router.
 *
 * Manages MCP client connections for a single step execution.
 * Stateless between steps — connections opened at step start, closed at step end.
 *
 * Security invariant: per-step isolation — no connection reuse across steps.
 *
 * Source of truth: STAGE-2-STEP-EXECUTION-ENGINE.md §4.3–§4.4
 */
import { logger } from '../logger'
import { VisualInputBudget } from '../visualInput/policy'
import { argumentValidator, checkToolArguments } from './argumentGate'
import { projectInternalToolResult } from './internalToolProjection'
import {
  AllowedToolsConfig,
  InternalToolDefinition,
  StepMcpServerRef,
  ToolCallRecord,
} from './types'

// ─── Tool Definition (simplified from MCP SDK) ─────────────────────────

export interface ToolDefinition {
  name: string // prefixed: serverName__toolName
  description?: string
  inputSchema?: Record<string, unknown>
}

export interface ToolResult {
  content: unknown
  isError?: boolean
}

// ─── Errors ─────────────────────────────────────────────────────────────

export class StepRouterConnectionError extends Error {
  failedServers: string[]
  constructor(failedServers: string[]) {
    super(`Failed to connect to MCP servers: ${failedServers.join(', ')}`)
    this.name = 'StepRouterConnectionError'
    this.failedServers = failedServers
  }
}

export class ToolDispatchError extends Error {
  toolName: string
  constructor(toolName: string) {
    super(`Unknown tool: '${toolName}' — no matching server prefix`)
    this.name = 'ToolDispatchError'
    this.toolName = toolName
  }
}

export class ToolArgsValidationError extends Error {
  toolName: string
  validationErrors: string
  constructor(toolName: string, validationErrors: string) {
    super(`Invalid arguments for '${toolName}': ${validationErrors}`)
    this.name = 'ToolArgsValidationError'
    this.toolName = toolName
    this.validationErrors = validationErrors
  }
}

// ─── MCP Client Interface (for DI/mocking) ─────────────────────────────

export interface McpClientConnection {
  connect(options?: { timeoutMs?: number; signal?: AbortSignal }): Promise<void>
  listTools(options?: {
    timeoutMs?: number
    signal?: AbortSignal
  }): Promise<Array<{ name: string; description?: string; inputSchema?: Record<string, unknown> }>>
  callTool(
    toolName: string,
    args: Record<string, unknown>,
    options?: { timeoutMs?: number; signal?: AbortSignal }
  ): Promise<ToolResult>
  disconnect(): Promise<void>
}

export type McpClientFactory = (server: StepMcpServerRef) => McpClientConnection

/**
 * Error text the model receives when it calls a tool outside the step's
 * allowedTools. Recoverable: the step continues and the model may retry with
 * an offered tool (spec §3.1.2).
 */
function toolNotAllowedError(toolName: string): string {
  return `Tool '${toolName}' is not allowed in this step and was not run. Use only the tools provided for this step.`
}

// ─── StepMcpRouter ──────────────────────────────────────────────────────

export class StepMcpRouter {
  private readBudget = new VisualInputBudget()
  private connections = new Map<string, McpClientConnection>()
  private toolMap = new Map<string, { serverName: string; rawToolName: string }>()
  private internalToolMap = new Map<string, InternalToolDefinition>()
  private allTools: ToolDefinition[] = []
  private readonly clientFactory: McpClientFactory
  private outputDir = '/output'
  // Names callTool() may dispatch when the step declares a non-empty
  // allowedTools.include. null = no allowlist in effect (every registered tool
  // is callable — the pre-§3.1.2 behaviour, kept for absent/empty include).
  // Deliberately NOT cleared by disconnect(): a restriction must never lapse
  // into "everything callable" on reuse; the caller re-applies it per step.
  private callableToolNames: Set<string> | null = null

  constructor(clientFactory: McpClientFactory) {
    this.clientFactory = clientFactory
  }

  /**
   * Register internal tools (clerum__*) that execute locally without MCP connection.
   * Must be called before connect() so they appear in getFilteredTools().
   *
   * The tool's `parameters` JSON Schema is compiled here into the validator
   * that runs before each dispatch (argumentGate.ts, shared with chat). Bad LLM
   * output (wrong type, missing required, unknown enum value) is rejected
   * before reaching `execute()`.
   */
  registerInternalTools(tools: InternalToolDefinition[], outputDir: string): void {
    this.outputDir = outputDir
    for (const tool of tools) {
      this.allTools.push({
        name: tool.name,
        description: tool.description,
        inputSchema: tool.parameters,
      })
      this.internalToolMap.set(tool.name, tool)
      // Compiled now so a schema that fails to compile is reported at
      // registration; dispatch then falls through to the tool's own checks.
      argumentValidator(tool)
      // Also register in toolMap for consistent dispatch
      this.toolMap.set(tool.name, {
        serverName: 'clerum',
        rawToolName: tool.name.replace('clerum__', ''),
      })
    }
  }

  /**
   * Connect to all servers declared for this step.
   * Throws StepRouterConnectionError if any server is unreachable.
   */
  async connect(
    servers: StepMcpServerRef[],
    options: { timeoutMs?: number; signal?: AbortSignal } = {}
  ): Promise<void> {
    if (this.readBudget.isClosed) this.readBudget = new VisualInputBudget()
    if (servers.length === 0) return

    const failed: string[] = []
    for (const server of servers) {
      const client = this.clientFactory(server)
      try {
        await client.connect(options)
        this.connections.set(server.name, client)
      } catch {
        failed.push(server.name)
      }
    }

    if (failed.length > 0) {
      // Disconnect any that succeeded before throwing
      await this.disconnect()
      throw new StepRouterConnectionError(failed)
    }

    // Preserve internal tools registered before connect()
    const savedInternalTools = [...this.allTools.filter(t => this.internalToolMap.has(t.name))]
    const savedToolMapEntries = [...this.toolMap.entries()].filter(([k]) =>
      this.internalToolMap.has(k)
    )

    // Build tool index from all connected servers
    this.allTools = [...savedInternalTools]
    this.toolMap.clear()
    for (const [k, v] of savedToolMapEntries) this.toolMap.set(k, v)
    const listFailed: string[] = []
    for (const [serverName, client] of this.connections) {
      try {
        const tools = await client.listTools(options)
        for (const tool of tools) {
          const prefixed = `${serverName}__${tool.name}`
          this.allTools.push({
            name: prefixed,
            description: tool.description,
            inputSchema: tool.inputSchema,
          })
          this.toolMap.set(prefixed, { serverName, rawToolName: tool.name })
        }
      } catch {
        listFailed.push(serverName)
      }
    }
    if (listFailed.length > 0) {
      await this.disconnect()
      throw new StepRouterConnectionError(listFailed)
    }
  }

  /**
   * Return merged tool list from all connected servers.
   * Filter to only tools in allowedTools.include (if non-empty).
   */
  getFilteredTools(allowedTools?: AllowedToolsConfig): ToolDefinition[] {
    const include = allowedTools?.include
    if (!include || include.length === 0) {
      return [...this.allTools]
    }
    const includeSet = new Set(include)
    return this.allTools.filter(t => includeSet.has(t.name))
  }

  /**
   * Enforce the step's allowlist at dispatch time (spec §3.1.2).
   *
   * - include absent or empty: no restriction. Every registered tool stays
   *   callable, matching getFilteredTools(), which offers every tool then.
   * - include non-empty: callTool() dispatches only names that are both listed
   *   and registered, i.e. exactly what getFilteredTools() offers the model.
   *   Any other name gets a recoverable tool-error result and never runs.
   *
   * Membership is checked against the live registry on each call, so this may
   * be applied before or after connect().
   */
  setAllowedTools(allowedTools?: AllowedToolsConfig): void {
    const include = allowedTools?.include
    this.callableToolNames = include && include.length > 0 ? new Set(include) : null
  }

  private rejectNotAllowed(
    toolName: string,
    args: Record<string, unknown>
  ): { result: ToolResult; record: ToolCallRecord } {
    const separator = toolName.indexOf('__')
    const errorResult = { success: false, error: toolNotAllowedError(toolName) }
    // Arguments are model output (and so attacker-shapeable); log the name only.
    logger.warn(
      { toolName: toolName.slice(0, 200) },
      'Workflow step tool call rejected: tool is not in allowedTools'
    )
    return {
      result: { content: errorResult, isError: true },
      record: {
        serverName: separator > 0 ? toolName.slice(0, separator) : 'unknown',
        toolName: separator > 0 ? toolName.slice(separator + 2) : toolName,
        args,
        result: errorResult,
        durationMs: 0,
      },
    }
  }

  /**
   * Dispatch a tool call to the correct server by tool name prefix.
   * Internal tools (clerum__*) are dispatched locally without MCP connection.
   * With a non-empty allowlist (setAllowedTools), names outside the offered set
   * return a recoverable tool-error result instead of dispatching.
   */
  async callTool(
    toolName: string,
    args: Record<string, unknown>,
    options: { timeoutMs?: number; signal?: AbortSignal } = {}
  ): Promise<{ result: ToolResult; record: ToolCallRecord }> {
    if (options.signal?.aborted) {
      const reason =
        typeof options.signal.reason === 'string' && options.signal.reason.trim()
          ? options.signal.reason
          : 'step-timeout'
      throw new Error(reason)
    }

    // Spec §3.1.2: with an allowlist in effect, anything outside the offered set
    // (unlisted, or listed but never registered) is answered with a recoverable
    // tool error and is never dispatched.
    if (
      this.callableToolNames &&
      !(this.callableToolNames.has(toolName) && this.toolMap.has(toolName))
    ) {
      return this.rejectNotAllowed(toolName, args)
    }

    // Check internal tools first
    const internalTool = this.internalToolMap.get(toolName)
    if (internalTool) {
      // The same check as on the chat path: unset nulls dropped, then the
      // schema. Failures come back as recoverable tool-error results (not
      // thrown) so the LLM can read the error and retry within the same step.
      // The record keeps what the model sent.
      const checked = checkToolArguments(internalTool, args)
      if (!checked.ok) {
        const errorResult = {
          success: false,
          error: checked.error,
        }
        const record: ToolCallRecord = {
          serverName: 'clerum',
          toolName: toolName.replace('clerum__', ''),
          args,
          result: errorResult,
          durationMs: 0,
        }
        return {
          result: { content: errorResult, isError: true },
          record,
        }
      }
      const start = Date.now()
      const internalResult = projectInternalToolResult(
        await internalTool.execute(checked.input, this.outputDir, {
          signal: options.signal,
          timeoutMs: options.timeoutMs,
          readBudget: this.readBudget,
        })
      )
      const durationMs = Date.now() - start
      const record: ToolCallRecord = {
        serverName: 'clerum',
        toolName: toolName.replace('clerum__', ''),
        args,
        result: internalResult,
        durationMs,
      }
      return {
        result: { content: internalResult, isError: !internalResult.success },
        record,
      }
    }

    const entry = this.toolMap.get(toolName)
    if (!entry) throw new ToolDispatchError(toolName)

    const client = this.connections.get(entry.serverName)
    if (!client) throw new ToolDispatchError(toolName)

    const start = Date.now()
    const result = await client.callTool(entry.rawToolName, args, options)
    const durationMs = Date.now() - start

    const record: ToolCallRecord = {
      serverName: entry.serverName,
      toolName: entry.rawToolName,
      args,
      result: result.content,
      durationMs,
    }

    return { result, record }
  }

  /**
   * Disconnect all servers. Safe to call on unconnected router.
   */
  async disconnect(): Promise<void> {
    this.readBudget.close()
    const disconnectPromises = [...this.connections.values()].map(client =>
      client.disconnect().catch(() => {
        /* swallow disconnect errors */
      })
    )
    await Promise.all(disconnectPromises)
    this.connections.clear()
    this.toolMap.clear()
    this.internalToolMap.clear()
    this.allTools = []
  }
}