Skip to content

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

TypeScript
10.6 KB
Raw Blame
/**
 * Context-files tools — read-only access to SharedFileSystems mounted into
 * the mcp-host pod by HCC. The pod sees one PVC per Context-referenced
 * SharedFileSystem (mounted at the path the Context spec asked for) plus a
 * JSON manifest in `CLERUM_CONTEXT_FILES_MOUNTS` that maps SFS name → mountPath.
 *
 * The LLM sees a virtual unified root keyed by SharedFileSystem name:
 *
 *   <sfs-name>/<path-inside-sfs>
 *
 * So if the Host's Context references "team-mission" mounted at
 * /context-files/team-mission, the LLM uses paths like
 * `team-mission/docs/runbook.md` regardless of where the volume actually
 * landed inside the container. This keeps the tool surface stable across
 * Hosts and decouples the LLM's mental model from k8s mount paths.
 *
 * Why "list" + "read" only:
 *   - The mcp-host volumes are mounted RO; writes are out of scope here
 *     and are mediated by the per-SFS workspace-files-controller.
 *   - Symlinks, directories, and oversize files are refused by name so the
 *     LLM never accidentally exfiltrates a path-traversal foothold.
 */
import type { Stats } from 'node:fs'
import * as fs from 'node:fs/promises'
import * as path from 'node:path'
import type { InternalToolDefinition, InternalToolResult } from './types'

interface ContextFilesMount {
  /** Logical name (SFS metadata.name); used as the top-level key in the virtual root. */
  name: string
  /** SharedFileSystem CRD namespace (always "mcp-host" in v1). */
  namespace: string
  /** Absolute path inside the container where the PVC is mounted (RO). */
  mountPath: string
  /** Underlying PVC name — surfaced for diagnostics; the LLM does not use it. */
  pvcName: string
}

const DEFAULT_MAX_READ_BYTES = 10 * 1024 * 1024 // 10 MiB
const DEFAULT_MAX_LIST_ENTRIES = 1000
const FORBIDDEN_PATH_CHARS = /[\\\x00-\x1f\x7f]/

function maxReadBytes(): number {
  const raw = process.env.CLERUM_CONTEXT_FILES_MAX_READ_BYTES
  const n = raw ? parseInt(raw, 10) : NaN
  return Number.isFinite(n) && n > 0 ? n : DEFAULT_MAX_READ_BYTES
}

function maxListEntries(): number {
  const raw = process.env.CLERUM_CONTEXT_FILES_MAX_LIST_ENTRIES
  const n = raw ? parseInt(raw, 10) : NaN
  return Number.isFinite(n) && n > 0 ? n : DEFAULT_MAX_LIST_ENTRIES
}

/**
 * Parse `CLERUM_CONTEXT_FILES_MOUNTS` (set by the host reconciler) into a
 * deduplicated, sorted list. Returns [] if the env is missing or malformed
 * — callers see "no SFS mounted" rather than crash.
 */
export function loadContextFilesMounts(env: NodeJS.ProcessEnv = process.env): ContextFilesMount[] {
  const raw = env.CLERUM_CONTEXT_FILES_MOUNTS
  if (!raw || raw.trim().length === 0) return []
  let parsed: unknown
  try {
    parsed = JSON.parse(raw)
  } catch {
    return []
  }
  if (!Array.isArray(parsed)) return []
  const out: ContextFilesMount[] = []
  const seen = new Set<string>()
  for (const item of parsed) {
    if (!item || typeof item !== 'object') continue
    const m = item as Partial<ContextFilesMount>
    if (
      typeof m.name !== 'string' ||
      typeof m.mountPath !== 'string' ||
      typeof m.namespace !== 'string' ||
      typeof m.pvcName !== 'string'
    ) {
      continue
    }
    if (seen.has(m.name)) continue
    seen.add(m.name)
    out.push({ name: m.name, namespace: m.namespace, mountPath: m.mountPath, pvcName: m.pvcName })
  }
  out.sort((a, b) => a.name.localeCompare(b.name))
  return out
}

/**
 * Split a virtual path of the form `<sfs-name>/<rest>` into its sfs name
 * and the rest. Returns null if the path is empty or only "/" (which means
 * "list the virtual root"). Throws when:
 *   - the input contains a `..` segment (traversal)
 *   - the input contains backslash or ASCII control characters
 *   - the sfs name is unknown to the current pod
 *   - the resolved real path isn't the SFS mountPath or below it
 *     (defense-in-depth — symlink-on-disk could otherwise escape)
 */
export function resolveVirtualPath(
  input: string,
  mounts: ContextFilesMount[]
): { mount: ContextFilesMount; absPath: string; rel: string } | null {
  const trimmed = input.replace(/^\/+/, '').replace(/\/+$/, '')
  if (trimmed.length === 0) return null
  if (FORBIDDEN_PATH_CHARS.test(trimmed)) {
    throw new Error('path is invalid: contains backslash or ASCII control characters')
  }
  const segments = trimmed.split('/').filter(s => s.length > 0)
  if (segments.length === 0) return null
  if (segments.some(s => s === '..')) {
    throw new Error('path is invalid: contains ".."')
  }
  const [sfsName, ...rest] = segments
  const mount = mounts.find(m => m.name === sfsName)
  if (!mount) {
    throw new Error(
      `sharedFileSystem "${sfsName}" is not mounted in this Host. Known: ${
        mounts.map(m => m.name).join(', ') || '(none)'
      }`
    )
  }
  const rel = rest.join('/')
  const mountRoot = path.posix.resolve(mount.mountPath)
  const mountRootWithSep = mountRoot.endsWith('/') ? mountRoot : `${mountRoot}/`
  const absPath = path.posix.resolve(mountRoot, rel)
  if (absPath !== mountRoot && !absPath.startsWith(mountRootWithSep)) {
    throw new Error('path resolved outside of the SharedFileSystem mount')
  }
  return { mount, absPath, rel }
}

interface VirtualEntry {
  name: string
  path: string
  kind: 'file' | 'directory' | 'sharedfilesystem' | 'other'
  size?: number
  mtime?: string
}

async function entryFromStat(
  name: string,
  abs: string,
  virtualPath: string
): Promise<VirtualEntry | null> {
  let st: Stats
  try {
    st = await fs.lstat(abs)
  } catch {
    return null
  }
  if (st.isSymbolicLink()) return null // never expose symlinks
  if (st.isFile()) {
    return {
      name,
      path: virtualPath,
      kind: 'file',
      size: st.size,
      mtime: st.mtime.toISOString(),
    }
  }
  if (st.isDirectory()) {
    return { name, path: virtualPath, kind: 'directory', mtime: st.mtime.toISOString() }
  }
  return { name, path: virtualPath, kind: 'other' }
}

export const contextFilesList: InternalToolDefinition = {
  name: 'clerum__context_files_list',
  description:
    'List entries in the virtual context-files root. Pass an empty path or "/" to list available SharedFileSystems mounted into this Host. ' +
    'Pass "<sharedFileSystemName>" or "<sharedFileSystemName>/<subdir>" to list inside a SharedFileSystem. ' +
    'Symlinks are filtered out. Read-only.',
  parameters: {
    type: 'object',
    properties: {
      path: {
        type: 'string',
        description:
          'Virtual path to list. Empty / "/" lists the SharedFileSystems available in this Host; otherwise "<sfs-name>/<subdir>".',
      },
    },
    required: [],
  },
  execute: async (args: Record<string, unknown>): Promise<InternalToolResult> => {
    try {
      const mounts = loadContextFilesMounts()
      const inputRaw = typeof args.path === 'string' ? args.path : ''
      const input = inputRaw.trim()
      // Top-level virtual root: list SharedFileSystems.
      if (input === '' || input === '/') {
        const entries: VirtualEntry[] = mounts.map(m => ({
          name: m.name,
          path: m.name,
          kind: 'sharedfilesystem',
        }))
        return {
          success: true,
          content: JSON.stringify(
            { path: '', entries, mountedSharedFileSystems: mounts.length },
            null,
            2
          ),
        }
      }
      const resolved = resolveVirtualPath(input, mounts)
      if (!resolved) {
        return { success: false, error: `path "${inputRaw}" is empty or invalid` }
      }
      const lst = await fs.lstat(resolved.absPath)
      if (lst.isSymbolicLink()) {
        return { success: false, error: 'symlinks are not allowed' }
      }
      if (!lst.isDirectory()) {
        return { success: false, error: 'path is not a directory' }
      }
      const cap = maxListEntries()
      const dirents = await fs.readdir(resolved.absPath, { withFileTypes: true })
      const truncated = dirents.length > cap
      const slice = truncated ? dirents.slice(0, cap) : dirents
      const entries: VirtualEntry[] = []
      for (const dirent of slice) {
        const childAbs = path.posix.join(resolved.absPath, dirent.name)
        const childVirtual = path.posix.join(resolved.mount.name, resolved.rel, dirent.name)
        const e = await entryFromStat(dirent.name, childAbs, childVirtual)
        if (e) entries.push(e)
      }
      return {
        success: true,
        content: JSON.stringify({ path: input, entries, truncated }, null, 2),
      }
    } catch (err) {
      return { success: false, error: err instanceof Error ? err.message : String(err) }
    }
  },
}

export const contextFilesRead: InternalToolDefinition = {
  name: 'clerum__context_files_read',
  description:
    'Read a UTF-8 text file from a SharedFileSystem mounted into this Host. Path is "<sharedFileSystemName>/<file-path>". ' +
    'Caps file size at CLERUM_CONTEXT_FILES_MAX_READ_BYTES (default 10 MiB). Refuses directories and symlinks. Read-only.',
  parameters: {
    type: 'object',
    properties: {
      path: {
        type: 'string',
        description: 'Virtual path "<sfs-name>/<file>" of the file to read.',
      },
    },
    required: ['path'],
  },
  execute: async (args: Record<string, unknown>): Promise<InternalToolResult> => {
    try {
      const mounts = loadContextFilesMounts()
      const inputRaw = typeof args.path === 'string' ? args.path : ''
      const resolved = resolveVirtualPath(inputRaw.trim(), mounts)
      if (!resolved) {
        return { success: false, error: 'path is required and must be "<sfs-name>/<file>"' }
      }
      const lst = await fs.lstat(resolved.absPath)
      if (lst.isSymbolicLink()) {
        return { success: false, error: 'symlinks are not allowed' }
      }
      if (lst.isDirectory()) {
        return { success: false, error: 'path is a directory; use clerum__context_files_list' }
      }
      if (!lst.isFile()) {
        return { success: false, error: 'path is not a regular file' }
      }
      const cap = maxReadBytes()
      if (lst.size > cap) {
        return {
          success: false,
          error: `file size ${lst.size} exceeds CLERUM_CONTEXT_FILES_MAX_READ_BYTES (${cap})`,
        }
      }
      const content = await fs.readFile(resolved.absPath, { encoding: 'utf8' })
      return {
        success: true,
        content: JSON.stringify(
          {
            path: inputRaw,
            sharedFileSystem: resolved.mount.name,
            size: lst.size,
            mtime: lst.mtime.toISOString(),
            content,
          },
          null,
          2
        ),
      }
    } catch (err) {
      return { success: false, error: err instanceof Error ? err.message : String(err) }
    }
  },
}

export const CONTEXT_FILES_TOOLS: InternalToolDefinition[] = [contextFilesList, contextFilesRead]