Skip to content

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

TypeScript
15.5 KB
Raw Blame
import { config } from '../config.js'
import type { TraceContextV1 } from '../traceContext.js'
import { ResolvedServerConnection } from '../types.js'
import { readMutatingResponseBody } from './upstreamBody.js'

/**
 * Per-MCP-server health row as emitted by mcp-host and forwarded by rpc-proxy.
 * Mirrors `McpServerStatusEntry` in mcp-host/src/mcp/serverStatus.ts (the two
 * services cannot share types directly; keep these in sync).
 *
 * Spec: docs/plans/mcp-server-health-in-desktop.md §4.2
 */
export type McpServerState = 'connected' | 'connecting' | 'failed' | 'disabled' | 'unknown'

export type McpServerFailureReason =
  | 'auth_failed'
  | 'upstream_4xx'
  | 'upstream_5xx'
  | 'network'
  | 'handshake'
  | 'timeout'
  | 'not_ready'
  | 'unknown'

export type McpServerHealthRow = {
  name: string
  state: McpServerState
  expected: boolean
  toolCount: number
  reason: McpServerFailureReason | null
  message: string | null
  observedAt: string
}

export type HostRuntimeStatus = {
  hostRef: string
  agent: {
    state: string
    currentTaskId: string | null
    tasksProcessed: number
    tasksSucceeded: number
    tasksFailed: number
    uptime: number
  }
  queue: {
    pending: number
    processing: number
    completed: number
    failed: number
  }
  cronJobs: number
  pendingApprovalsCount: number
  /**
   * Per-MCP-server health. Absent when upstream mcp-host is an older build;
   * desktop treats absence as "unknown for every server" per spec §5.
   */
  mcpServers?: McpServerHealthRow[]
  /**
   * Non-null when the Host is degraded and refusing new tasks. Currently
   * the only emitted reason is `llm_key_missing`. Forward to consumers
   * verbatim so the Desktop App can render a banner and disable composer
   * input.
   */
  degraded?: {
    reason: 'llm_key_missing'
    message: string
  } | null
  observedAt: string
}

export type HostRuntimeHealth = {
  hostRef: string
  status: string
  observedAt: string
}

export type HostActivitySeverity = 'info' | 'warn' | 'error'
export type HostActivityType =
  | 'task.queued'
  | 'task.started'
  | 'task.completed'
  | 'task.failed'
  | 'llm.requested'
  | 'llm.responded'
  | 'llm.failed'
  | 'tool.call.started'
  | 'tool.call.completed'
  | 'tool.call.failed'
  | 'approval.requested'
  | 'approval.approved'
  | 'approval.denied'
  | 'safety.input_blocked'
  | 'safety.output_sanitized'
  | 'queue.depth.changed'
  | 'agent.state.changed'
export type HostActivityEvent = {
  version: '1.0'
  eventId: string
  hostRef: string
  ts: string
  taskId?: string
  type: HostActivityType
  title: string
  severity: HostActivitySeverity
  meta: Record<string, unknown>
  redactions: string[]
}
export type HostActivitySnapshot = {
  hostRef: string
  version: '1.0'
  items: HostActivityEvent[]
  nextCursor: string | null
}

export type HostRuntimeMessageRequest = {
  content: string
  channelType?: string
  sender?: string
  hostRef?: string
  // Stable idempotency identity for cross-delivery duplicate suppression at
  // mcp-host (MessageQueue.deliveryKeyOf keys on messageId). MUST be identical
  // across the first forward and the wake-and-hold retry so a re-forwarded turn
  // is deduped (replayed) instead of re-executed.
  messageId?: string
  traceContext?: TraceContextV1
  // Issue #666 — structured file references (`FileReferenceV1[]`), forwarded
  // verbatim. mcp-host owns the contract and answers 200 `success:false` with
  // a typed code for any malformed value.
  fileReferences?: unknown
  [key: string]: unknown
}

// REST host runtime submit path:
// rpc-proxy accepts a REST body from desktop and submits to mcp-host runtime REST.
// This function is intentionally separate from stream/status forwarding logic.
export async function forwardHostMessageToHost(
  host: ResolvedServerConnection,
  message: HostRuntimeMessageRequest,
  options?: { async?: boolean; timeoutMs?: number }
): Promise<Record<string, unknown>> {
  const payload = {
    ...message,
    hostRef: String(message.hostRef || host.name).trim(),
  }
  const baseUrl = host.url.replace(/\/+$/, '')
  const query = options?.async ? '?async=true' : ''
  const abortController = new AbortController()
  const timeout = setTimeout(() => {
    abortController.abort()
  }, options?.timeoutMs ?? config.upstreamTimeoutMs)
  try {
    const response = await fetch(`${baseUrl}/v1/runtime/messages${query}`, {
      method: 'POST',
      headers: {
        'content-type': 'application/json',
        accept: 'application/json',
        ...host.headers,
      },
      body: JSON.stringify(payload),
      signal: abortController.signal,
    })
    const rawBody = await response.text()
    if (!response.ok) {
      throw new UpstreamHostError(response.status, rawBody.slice(0, 300))
    }

    let body: Record<string, unknown> = {}
    if (rawBody.trim()) {
      let parsed: unknown
      let parseError: string | undefined
      try {
        parsed = JSON.parse(rawBody) as unknown
      } catch (error) {
        parseError = error instanceof Error ? error.name : 'unknown'
      }
      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
        body = parsed as Record<string, unknown>
      } else {
        // mcp-host answers every accepted message with a JSON object, so this is
        // a broken or foreign upstream. The message may already be admitted, so
        // the answer stays an empty ack instead of an error that would invite a
        // resend; the log is the trace of what was received.
        console.warn(
          JSON.stringify({
            event: 'host_message_ack_unreadable',
            hostRef: payload.hostRef,
            messageId: payload.messageId,
            status: response.status,
            contentType: response.headers.get('content-type'),
            reason: parseError ?? 'not_an_object',
            bodyLength: rawBody.length,
            bodySnippet: rawBody.slice(0, 300),
          })
        )
      }
    }
    return body
  } finally {
    clearTimeout(timeout)
  }
}

export async function forwardTaskResultFromHost(
  host: ResolvedServerConnection,
  taskId: string,
  timeoutMs = config.upstreamTimeoutMs
): Promise<Record<string, unknown> | null> {
  const baseUrl = host.url.replace(/\/+$/, '')
  const abortController = new AbortController()
  const timeout = setTimeout(() => abortController.abort(), timeoutMs)
  try {
    const response = await fetch(
      `${baseUrl}/v1/runtime/tasks/${encodeURIComponent(taskId)}/result`,
      {
        method: 'GET',
        headers: {
          accept: 'application/json',
          ...host.headers,
        },
        signal: abortController.signal,
      }
    )
    if (response.status === 404) return null
    const rawBody = await response.text()
    // The body carries mcp-host's `host_draining` fence, which is what makes a
    // draining 503 wake-eligible (isHostDrainingError reads bodySnippet).
    if (!response.ok) throw new UpstreamHostError(response.status, rawBody.slice(0, 300))
    if (!rawBody.trim()) return null
    try {
      const parsed = JSON.parse(rawBody) as unknown
      return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
        ? (parsed as Record<string, unknown>)
        : null
    } catch {
      return null
    }
  } finally {
    clearTimeout(timeout)
  }
}

export type CancelUpstreamResult = {
  status: number
  body: string
  contentType: string | null
}

/**
 * Task cancel is a mutating POST without an idempotency key, so it owns no
 * deadline: the caller's `signal` carries the client disconnect and, on a
 * wake-and-hold retry only, the hold deadline (rpc.ts `mutatingCallSignal`).
 */
export async function forwardCancelToHost(
  host: ResolvedServerConnection,
  taskId: string,
  userId: string,
  signal: AbortSignal
): Promise<CancelUpstreamResult> {
  // mcp-host applies its ownership check to this userId, so it must be the
  // caller's own subject; a stand-in identity would be checked instead.
  if (!userId) throw new Error('task cancel requires the caller subject')
  const baseUrl = host.url.replace(/\/+$/, '')
  const upstreamBody = { userId }
  const response = await fetch(`${baseUrl}/v1/runtime/tasks/${encodeURIComponent(taskId)}/cancel`, {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      ...host.headers,
    },
    body: JSON.stringify(upstreamBody),
    signal,
  })
  // Cancel is a mutating POST without an idempotency key: a body failure
  // after the headers must not re-issue it through the wake path.
  const body = await readMutatingResponseBody(response)
  return {
    status: response.status,
    body,
    contentType: response.headers.get('content-type'),
  }
}

function asObject(input: unknown): Record<string, unknown> | null {
  if (!input || typeof input !== 'object' || Array.isArray(input)) return null
  return input as Record<string, unknown>
}

function asNumber(input: unknown): number {
  return typeof input === 'number' && Number.isFinite(input) ? input : 0
}

function asString(input: unknown): string {
  return typeof input === 'string' ? input : ''
}

function asNullableString(input: unknown): string | null {
  return typeof input === 'string' && input.trim() ? input : null
}

const VALID_MCP_STATES: ReadonlySet<McpServerState> = new Set([
  'connected',
  'connecting',
  'failed',
  'disabled',
  'unknown',
])

const VALID_MCP_REASONS: ReadonlySet<McpServerFailureReason> = new Set([
  'auth_failed',
  'upstream_4xx',
  'upstream_5xx',
  'network',
  'handshake',
  'timeout',
  'not_ready',
  'unknown',
])

function normalizeMcpServerRow(raw: unknown): McpServerHealthRow | null {
  const row = asObject(raw)
  if (!row) return null
  const name = asString(row.name)
  if (!name) return null

  const stateCandidate = asString(row.state) as McpServerState
  const state: McpServerState = VALID_MCP_STATES.has(stateCandidate) ? stateCandidate : 'unknown'

  const reasonCandidate = asString(row.reason) as McpServerFailureReason
  const reason: McpServerFailureReason | null =
    row.reason === null || row.reason === undefined
      ? null
      : VALID_MCP_REASONS.has(reasonCandidate)
        ? reasonCandidate
        : 'unknown'

  return {
    name,
    state,
    expected: row.expected === true,
    toolCount: Math.max(0, Math.floor(asNumber(row.toolCount))),
    reason,
    message: asNullableString(row.message),
    observedAt: asString(row.observedAt) || new Date(0).toISOString(),
  }
}

function normalizeMcpServers(raw: unknown): McpServerHealthRow[] | undefined {
  if (!Array.isArray(raw)) return undefined // absent / malformed → undefined (spec §5)
  const rows: McpServerHealthRow[] = []
  for (const entry of raw) {
    const row = normalizeMcpServerRow(entry)
    if (row) rows.push(row)
  }
  return rows
}

function normalizeHostStatusPayload(hostRef: string, raw: unknown): HostRuntimeStatus | null {
  const root = asObject(raw)
  if (!root) return null
  const agentRaw = asObject(root.agent)
  const queueRaw = asObject(root.queue)
  if (!agentRaw || !queueRaw) return null

  const pendingApprovals = Array.isArray(root.pendingApprovals) ? root.pendingApprovals : []
  const mcpServers = normalizeMcpServers(root.mcpServers)
  const degraded = normalizeDegraded(root.degraded)
  return {
    hostRef,
    agent: {
      state: asString(agentRaw.state) || 'unknown',
      currentTaskId: asNullableString(agentRaw.currentTaskId),
      tasksProcessed: asNumber(agentRaw.tasksProcessed),
      tasksSucceeded: asNumber(agentRaw.tasksSucceeded),
      tasksFailed: asNumber(agentRaw.tasksFailed),
      uptime: asNumber(agentRaw.uptime),
    },
    queue: {
      pending: asNumber(queueRaw.pending),
      processing: asNumber(queueRaw.processing),
      completed: asNumber(queueRaw.completed),
      failed: asNumber(queueRaw.failed),
    },
    cronJobs: asNumber(root.cronJobs),
    pendingApprovalsCount: pendingApprovals.length,
    ...(mcpServers !== undefined ? { mcpServers } : {}),
    ...(degraded !== undefined ? { degraded } : {}),
    observedAt: new Date().toISOString(),
  }
}

/**
 * Validate the optional `degraded` field shape. Older mcp-host builds omit
 * it; treat absence as undefined (caller passes through). Unknown reasons
 * are dropped to undefined so the contract stays narrow.
 */
function normalizeDegraded(
  raw: unknown
): { reason: 'llm_key_missing'; message: string } | null | undefined {
  if (raw === undefined) return undefined
  if (raw === null) return null
  const obj = asObject(raw)
  if (!obj) return undefined
  const reason = asString(obj.reason)
  const message = asString(obj.message)
  if (reason !== 'llm_key_missing') return undefined
  return { reason: 'llm_key_missing', message: message || 'Host degraded' }
}

// Exported for unit tests only.
export const __test__normalizeHostStatusPayload = normalizeHostStatusPayload

async function fetchHostRuntimeJson(
  host: ResolvedServerConnection,
  path: string
): Promise<unknown> {
  const baseUrl = host.url.replace(/\/+$/, '')
  const abortController = new AbortController()
  const timeout = setTimeout(() => abortController.abort(), config.upstreamTimeoutMs)
  try {
    const response = await fetch(`${baseUrl}${path}`, {
      method: 'GET',
      headers: {
        accept: 'application/json',
        ...host.headers,
      },
      signal: abortController.signal,
    })
    const rawBody = await response.text()
    if (!response.ok) {
      throw new UpstreamHostError(response.status, rawBody.slice(0, 300))
    }
    if (!rawBody.trim()) return {}
    return JSON.parse(rawBody) as unknown
  } finally {
    clearTimeout(timeout)
  }
}

/**
 * Thrown when the upstream mcp-host returns a non-2xx status. Carries the
 * status code so callers (e.g. the host-status SSE loop) can distinguish
 * auth failures (401/403) from transient errors and react accordingly —
 * stream auth-expired, count consecutive errors, etc.
 */
export class UpstreamHostError extends Error {
  constructor(
    public readonly status: number,
    public readonly bodySnippet: string
  ) {
    super(`Upstream host returned ${status}: ${bodySnippet}`)
    this.name = 'UpstreamHostError'
  }
}

// REST host runtime read path for status snapshots.
export async function forwardHostStatus(
  host: ResolvedServerConnection
): Promise<HostRuntimeStatus | null> {
  const raw = await fetchHostRuntimeJson(host, '/v1/runtime/status')
  return normalizeHostStatusPayload(host.name, raw)
}

// REST host runtime read path for health/liveness.
export async function forwardHostHealth(
  host: ResolvedServerConnection
): Promise<HostRuntimeHealth> {
  const raw = await fetchHostRuntimeJson(host, '/v1/runtime/health')
  const body = asObject(raw)
  return {
    hostRef: host.name,
    status: asString(body?.status) || 'unknown',
    observedAt: new Date().toISOString(),
  }
}

// REST host runtime read path for activity timeline snapshots.
export async function forwardHostActivity(
  host: ResolvedServerConnection,
  limit: number,
  sinceEventId?: string
): Promise<HostActivitySnapshot> {
  const params = new URLSearchParams()
  params.set('limit', String(Math.min(Math.max(limit || 50, 1), 200)))
  if (sinceEventId) params.set('sinceEventId', sinceEventId)
  const raw = await fetchHostRuntimeJson(host, `/v1/runtime/activity?${params.toString()}`)
  const body = asObject(raw)
  const itemsRaw = Array.isArray(body?.items) ? body?.items : []
  const items: HostActivityEvent[] = itemsRaw
    .filter(entry => entry && typeof entry === 'object' && !Array.isArray(entry))
    .map(entry => entry as HostActivityEvent)
  const nextCursor = typeof body?.nextCursor === 'string' ? body.nextCursor : null
  return {
    hostRef: typeof body?.hostRef === 'string' ? body.hostRef : host.name,
    version: '1.0',
    items,
    nextCursor,
  }
}