Skip to content

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

TypeScript
6.7 KB
Raw Blame
/**
 * Desktop-side pure logic for MCP server health.
 *
 *   - Merges the session-catalog `agents[].mcpServers` (names only) with the
 *     latest RPC snapshot per `hostRef` (HostRuntimeStatus.mcpServers) to
 *     produce a UI-ready row per configured server.
 *   - Applies staleness per spec §7.1 (STALE_AFTER_MS from last observedAt).
 *   - Derives a single UI label (Running / Degraded / Failed / Starting /
 *     Disabled / Unknown / Stale) from state + toolCount + freshness.
 *
 * Spec: docs/plans/mcp-server-health-in-desktop.md §4.4, §5, §6, §7
 */
import type {
  AgentWithMcpServers,
  HostRuntimeStatus,
  McpServerFailureReason,
  McpServerHealthRow,
  McpServerState,
} from './types'

/** Desktop polls the host-status endpoint every POLL_INTERVAL_MS (spec §6.1). */
export const POLL_INTERVAL_MS = 60_000

/**
 * While any row is `connecting`, desktop polls faster to avoid the
 * first-connect UX penalty (spec review item: cold-open latency).
 */
export const FAST_POLL_INTERVAL_MS = 5_000

/**
 * A row is stale when observedAt is older than STALE_AFTER_MS. Pinned to
 * `2 × POLL_INTERVAL_MS` so a single missed tick doesn't trip staleness.
 */
export const STALE_AFTER_MS = 2 * POLL_INTERVAL_MS

/** Max concurrent background pollers when the app has multiple agents open. */
export const MAX_CONCURRENT_POLLERS = 3

/**
 * Exact failure messages emitted by mcp-host. Exported so E2E tests can
 * assert against them by string equality (spec §9, scenario #1). Keep in
 * sync with mcp-host/src/mcp/serverStatus.ts.
 */
export const MCP_INIT_AUTH_FAILED_MESSAGE = 'initialize returned 401'
export const MCP_NOT_READY_MESSAGE = 'control plane reported server not ready'

export type McpServerUiLabel =
  | 'running'
  | 'degraded'
  | 'failed'
  | 'starting'
  | 'disabled'
  | 'unknown'
  | 'stale'

/** A health row annotated with the desktop-side derived UI label. */
export type MergedMcpServerRow = McpServerHealthRow & {
  label: McpServerUiLabel
  stale: boolean
}

/** Per-agent health table. `unknownFallback` is true when the host status
 * snapshot was absent or omitted `mcpServers` (old mcp-host) — the UI
 * should show a "waiting for status" hint instead of mis-labeling rows. */
export type AgentHealthTable = {
  hostRef: string
  contextRef: string | null
  rows: MergedMcpServerRow[]
  unknownFallback: boolean
}

/** Returns true if the row's observedAt is older than STALE_AFTER_MS.
 * Non-parseable timestamps are treated as stale. */
export function isStale(observedAt: string, nowMs: number, threshold = STALE_AFTER_MS): boolean {
  const t = Date.parse(observedAt)
  if (!Number.isFinite(t)) return true
  return nowMs - t > threshold
}

/**
 * Map a health row to a single UI label.
 *
 * Priority: `disabled` is operator intent and never goes stale. For all
 * other states, staleness takes precedence over state-derived labels since
 * stale data should not be trusted as live.
 */
export function classifyRowLabel(
  row: McpServerHealthRow,
  nowMs: number,
  threshold = STALE_AFTER_MS
): McpServerUiLabel {
  // `disabled` is operator intent and never goes stale.
  if (row.state === 'disabled') return 'disabled'
  // `unknown` is already the "no data yet" label; don't promote it to `stale`
  // just because the synthesized row carries an epoch timestamp.
  if (row.state === 'unknown') return 'unknown'

  if (isStale(row.observedAt, nowMs, threshold)) return 'stale'

  switch (row.state) {
    case 'connected':
      return row.toolCount > 0 ? 'running' : 'degraded'
    case 'connecting':
      return 'starting'
    case 'failed':
      return 'failed'
    default:
      return 'unknown'
  }
}

/**
 * Synthesize an "unknown" row for a catalog-listed server that has no
 * corresponding RPC row. Spec §5: catalog names missing from the RPC status
 * render as `state: "unknown"` — no empty-list regression.
 */
function unknownRow(name: string): McpServerHealthRow {
  return {
    name,
    state: 'unknown',
    expected: true,
    toolCount: 0,
    reason: null,
    message: null,
    // observedAt of 1970 → always "stale" unless threshold check is skipped.
    // classifyRowLabel short-circuits on state==='unknown' before staleness.
    observedAt: new Date(0).toISOString(),
  }
}

/**
 * Merge a single agent's catalog entry with the latest host-status snapshot.
 *
 *   - For each name in `agent.mcpServers`, bind the matching row from
 *     `status?.mcpServers` by name; synthesize an `unknown` row if absent.
 *   - Rows present in status but not in the catalog are ignored (spec §5).
 *   - `unknownFallback` is true when the caller has no status yet OR the
 *     status omits `mcpServers` — useful for the UI to show "awaiting status".
 */
export function mergeAgentHealth(
  agent: AgentWithMcpServers,
  status: HostRuntimeStatus | null | undefined,
  nowMs: number,
  threshold = STALE_AFTER_MS
): AgentHealthTable {
  const statusRows = status?.mcpServers
  const unknownFallback = statusRows === undefined

  const byName = new Map<string, McpServerHealthRow>()
  if (Array.isArray(statusRows)) {
    for (const r of statusRows) byName.set(r.name, r)
  }

  const rows: MergedMcpServerRow[] = agent.mcpServers.map(({ name }) => {
    const base = byName.get(name) ?? unknownRow(name)
    const label = classifyRowLabel(base, nowMs, threshold)
    return {
      ...base,
      label,
      stale: label === 'stale',
    }
  })

  return {
    hostRef: agent.name,
    contextRef: agent.contextRef,
    rows,
    unknownFallback,
  }
}

/**
 * Merge every agent in the session catalog with its latest status.
 * Returns one table per agent, keyed by hostRef (== agent name).
 */
export function mergeCatalogHealth(
  agents: readonly AgentWithMcpServers[],
  statusByHostRef: ReadonlyMap<string, HostRuntimeStatus | null | undefined>,
  nowMs: number,
  threshold = STALE_AFTER_MS
): AgentHealthTable[] {
  return agents.map(agent =>
    mergeAgentHealth(agent, statusByHostRef.get(agent.name), nowMs, threshold)
  )
}

/**
 * True when any merged row is in `connecting`/`starting`. Used by the poller
 * to switch to FAST_POLL_INTERVAL_MS until the state settles.
 */
export function hasConnectingRow(tables: readonly AgentHealthTable[]): boolean {
  for (const t of tables) {
    for (const r of t.rows) if (r.label === 'starting') return true
  }
  return false
}

/**
 * Pick an interval for the next poll. Fast while anything is `connecting`,
 * otherwise steady-state. Exposed as a pure function so the scheduler (M7)
 * and its tests can reuse the same decision.
 */
export function nextPollIntervalMs(tables: readonly AgentHealthTable[]): number {
  return hasConnectingRow(tables) ? FAST_POLL_INTERVAL_MS : POLL_INTERVAL_MS
}

/** Re-export for tests that want to assert on the reason taxonomy by name. */
export type { McpServerFailureReason, McpServerHealthRow, McpServerState }