Skip to content

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

TypeScript
10.4 KB
Raw Blame
/**
 * Shared types for the MCP Host.
 */
import type { ApprovalConfig } from './core/extensions/approvalTypes'
import type { GuardrailsConfig } from './core/guardrails/config'
import type { LlmProvider } from './llm/registryCore'

/**
 * Model configuration.
 */
export interface ModelConfig {
  provider: LlmProvider
  name: string
  connectionRef?: string
}

/** Phase 7–8: Workspace memory configuration. */
export interface MemoryConfig {
  enabled: boolean
  workspacePath?: string // default: /workspace (prod) or ./workspace (dev)
}

/** Phase 7–8: Identity & personalization configuration. */
export interface PersonalizationConfig {
  enabled: boolean
  identity?: string // seed content for IDENTITY.md
  soul?: string // seed content for SOUL.md
  agents?: string // seed content for AGENTS.md
  user?: string // seed content for USER.md
}

/** Phase 9: Heartbeat configuration. */
export interface HeartbeatConfig {
  enabled: boolean
  interval?: string // cron expression, e.g. "*/30 * * * *"
  maxFailures?: number
  notifyChannel?: 'telegram' | 'email' | 'slack' | 'teams'
  notifyChannelId?: string
  notifyUserId?: string
}

/**
 * Host CRD spec.
 */
export interface HostSpec {
  host: string
  contextRef: string
  secretRef?: string
  channels?: string[]
  model?: ModelConfig
  /** Phase 6: Tool approval configuration. */
  approval?: ApprovalConfig
  /** Phase 7–8: Workspace memory. */
  memory?: MemoryConfig
  /** Phase 7–8: Identity & personalization. */
  personalization?: PersonalizationConfig
  /** Phase 9: Heartbeat. */
  heartbeat?: HeartbeatConfig
  /**
   * R5 — provider-fallback policy. RAW shape as delivered by the K8s API (the
   * CRD schema is owned by the separate CRD block; mcp-host only CONSUMES it).
   * Normalized via `parseLlmPolicy` before use — absent/malformed = no failover
   * = byte-identical to today. Kept loosely typed on purpose: the source of
   * truth for the parsed shape is `llm/failover/types.ts#LlmPolicy`.
   */
  llmPolicy?: RawLlmPolicy
  /**
   * T3a — per-host model subset. The operator's GLOBAL allowlist (the
   * `clerum-llm-allowed-models` ConfigMap) is the catalog; this flat array is
   * the subset THIS host offers (⊆ global). Absent/empty = the host offers the
   * full global allowlist (back-compat, additive). Consumed live-intersected
   * with the global allowlist by the R2 model endpoints — a pair here that is
   * NOT enabled in the global disappears (fail-closed). Read directly off the
   * CR like `spec.model`; hot-reloads with the rest of the spec.
   */
  allowedModels?: HostAllowedModel[]
  /**
   * Guardrails — the admin-authored `Host.spec.guardrails` block (spec §5).
   * mcp-host CONSUMES it; the CRD schema is owned by the CRD chart. Absent/empty
   * = no guardrails = byte-identical to today (no-config compatibility, spec §5).
   * Phase 1: only `rules` + `limits` are interpreted.
   */
  guardrails?: GuardrailsConfig
}

/**
 * One entry of the per-host model subset (`spec.allowedModels`). Flat
 * (provider, model) pair, matching the CRD schema in
 * `charts/clerum-crds/crds/host.yaml`.
 */
export interface HostAllowedModel {
  provider: string
  model: string
}

/**
 * The untyped-ish `spec.llmPolicy` object as it arrives from the Host CR (all
 * fields optional; validated + defaulted by `parseLlmPolicy`).
 */
export interface RawLlmPolicy {
  cooldownSeconds?: number
  triggerOn?: string[]
  fallbacks?: Array<{ provider?: string; model?: string; credentialSlot?: string }>
}

/**
 * Host CRD.
 */
export interface HostCRD {
  name: string
  namespace: string
  spec: HostSpec
}

/**
 * Credential values for a single provider, keyed by the registry slot
 * `dataKey` (e.g. `openai-api-key`, or the `aws-access-key-id` /
 * `aws-secret-access-key` pair for Bedrock). Multi-slot (R4): single-key
 * providers carry one entry; Bedrock carries two; Vertex one (its JSON).
 */
export type ProviderCredentials = Record<string, string>

/**
 * API credentials loaded from the LLM Secret, keyed by provider id (currently
 * `openai`, `claude`, `zai`, `bailian`, `vertex`, `bedrock`). Each value is a
 * per-provider {@link ProviderCredentials} bag so a provider that needs more
 * than one secret slot (Bedrock) is representable without a second transport.
 * Derived from the provider registry so the key set tracks the provider set.
 */
export type ApiKeys = Partial<Record<LlmProvider, ProviderCredentials>>

// ─── MCP Server Info (from skill-mapper API) ────────────────────────────────
// These types match the curated response from the skill-mapper.
// They contain only what the mcp-host needs to connect to MCP servers,
// plus deployment status that only the operator knows.

/**
 * McpServer transport configuration.
 */
export interface McpServerTransport {
  type: 'sse' | 'streamableHttp' | 'stdio'
  url?: string
  port?: number
}

/**
 * McpServer authentication configuration.
 */
export interface McpServerAuth {
  type: 'none' | 'bearer' | 'basic' | 'apiKey' | 'oauth'
  secretRef?: string
  secretKey?: string
}

/**
 * OAuth broker configuration for an mcp-server (auth.type === 'oauth').
 *
 * Mirrors the separate `spec.oauth` block on the CRD (projected by HCC). Only
 * `grantScope` is strictly required for the mcp-host connection seam (dispatch
 * of the per-connection partition); the rest is carried for the token-provider
 * factory / diagnostics. `grantScope` defaults to 'user' when absent.
 */
export interface McpServerOAuth {
  id?: string
  provider?: string
  grantScope?: 'user' | 'context'
  scopes?: string[]
  backgroundAccess?: boolean
}

/**
 * Deployment status of an MCP server (reported by the skill-mapper operator).
 */
export interface McpServerStatus {
  /** Whether the Deployment resource exists in the cluster. */
  deployed: boolean
  /** Whether the Deployment has at least one ready replica. */
  ready: boolean
  /**
   * Whether ready/deployed came from a current-identity, current-generation
   * source. Explicit false means admission status is unknown and must not
   * revoke a live connection. Undefined preserves legacy producer semantics.
   */
  authoritative?: boolean
  /** Human-readable status message. */
  message?: string
}

/**
 * MCP server info as provided by the skill-mapper API.
 * Contains only what the mcp-host needs to discover and connect to servers.
 */
export interface McpServerInfo {
  name: string
  description?: string
  /**
   * Present only for development/legacy in-process configuration. The HCC v2
   * Host inventory deliberately omits Context identity: HCC derives it from
   * the authenticated Host JWT and never returns it to the caller.
   */
  contextRef?: string
  transport: McpServerTransport
  /** Legacy development shape. HCC v2 returns only authRequired. */
  auth?: McpServerAuth
  /**
   * OAuth broker config; present iff auth.type === 'oauth'. Carries `grantScope`
   * so the manager can dispatch the per-connection partition (user vs shared).
   */
  oauth?: McpServerOAuth
  /** Whether the scoped HCC credential route must return a bearer. */
  authRequired?: boolean
  /**
   * Opaque HCC authority revision. It changes when the authorized server,
   * auth selector, or referenced Secret identity/resourceVersion changes.
   */
  credentialRevision?: string
  /**
   * Non-secret credential-mode policy emitted by the HCC v2 inventory. Drives the
   * token-provider dispatch in the mcp-host seam (mini-spec §3.2): `static` uses
   * the revision-locked getAuthToken route; `oauth-user`/`oauth-context` build a
   * broker provider. Absent → treated as `static` (fail-closed). It carries NO
   * authority (never contextRef/secretRef/token) — that is the invariant (I1)
   * keeping it on the policy side of the decoder's forbidden-metadata guard.
   */
  authKind?: 'static' | 'oauth-user' | 'oauth-context'
  /**
   * Non-secret policy: `true` iff this is a REMOTE MCP server (an off-cluster,
   * spec-compliant upstream reached over its published `transport.url`, e.g.
   * Slack/Notion). It carries NO authority (like `authKind`, it stays on the
   * policy side of the decoder's forbidden-metadata guard). Absent → local
   * (in-cluster/own-image), the historical default. A remote oauth server is
   * spec-compliant and 401s already at `initialize`, so mcp-host must (a) populate
   * its catalog authenticated (never token-less), (b) connect to `transport.url`
   * as the in-cluster HCC egress-proxy hop (http) — NOT as an external target to
   * SSRF-guard: the external `baseUrl` is validated by control-api/HCC and never
   * projected here — and (c) bypass the in-cluster MCP_PROXY_URL rail, because its
   * egress goes through the HCC's own auth-passthrough proxy.
   */
  remote?: boolean
  /**
   * Non-secret transport quirk (mini-spec 19 §D-8, DEC-22/DEC-24): `true` iff the
   * remote OAuth resource advertises `bearer_methods_supported:["body"]` (e.g.
   * SEMrush) — the access token must ride the request BODY, not the
   * `Authorization: Bearer` header. Sibling of `remote`: policy only, no
   * authority, off the decoder's forbidden-metadata denylist, fail-safe to absent
   * (= header, the historical default). The flag is wired end-to-end here; the
   * actual body injection in client.ts is deferred pending a real wire contract
   * (see the note at McpClient.createTransport).
   */
  bearerInBody?: boolean
  enabled: boolean
  status: McpServerStatus
}

/**
 * Tool definition from MCP server.
 */
export interface McpTool {
  name: string
  description?: string
  inputSchema: Record<string, unknown>
  serverName: string // Which MCP server this tool belongs to
}

/**
 * Tool call result.
 */
export interface ToolCallResult {
  toolName: string
  result: unknown
  isError: boolean
  /**
   * U5 reactive-consent marker. Present iff `manager.callTool` caught an
   * `McpAuthError` with `status===401` on a server whose `auth.type==='oauth'`
   * (both per-user and shared grantScope='context'): a live tool call surfaced a
   * real 401 after the client's single forced-refresh retry, so the user must
   * (re)connect. NEVER set for 403 (insufficient scope — terminal) nor for
   * static/non-oauth servers. `toolRegistryAdapter` maps it to
   * `metadata.connect_required`, which the tool-use loop turns into a durable
   * `connect_required` suspension (spec §U5). Kept as a typed field so the marker
   * is NOT flattened into an opaque error.
   */
  connectRequired?: {
    mcpServerName: string
  }
}