Skip to content

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

TypeScript
13.6 KB
Raw Blame
/**
 * Issue #666 — structured file references on an incoming message.
 *
 * `parseIncomingFileReferences` is the route-level contract check: shape,
 * count, uniqueness and GFS identity, with no I/O. `resolveFileReferences`
 * re-authorizes every GFS reference under the Host principal with gfsc
 * `resolve` (JSON metadata only, never bytes) and reports one availability per
 * reference. The model reads an available file later with `clerum__gfs_read`,
 * which the Host pins to the reference's version.
 */
import { type FileReferenceV1, parseFileReferenceV1 } from '@clerum/gfs-interaction-policy'
import { FileReferenceErrorCode } from '../core/errors'
import type { TurnContextReferencedFile } from '../core/orchestration/turnContext'
import { GfscHttpError } from '../internalTools/gfsClient'
import { GFS_FILE_LIMITS } from '../internalTools/gfsFilePolicy'
import { logger } from '../logger'
import { VISUAL_INPUT_LIMITS } from '../visualInput/policy'
import {
  type GfsSurfaceRuntimeCapability,
  classifyGfsReferenceSurfaces,
} from './gfsReferenceSurfaces'

export type FileReferenceAvailability =
  | 'available'
  | 'not_found'
  | 'denied'
  | 'stale'
  | 'not_a_file'
  | 'too_large'
  | 'unsupported'

export interface FileReferenceResolution {
  availability: FileReferenceAvailability
  reference: FileReferenceV1
  /** The version gfsc reports now, when it differs from the reference's. */
  resolvedVersion?: number
  /** Delivery surfaces proven for this Host/runtime; absent on old resolutions. */
  surfaces?: ReturnType<typeof classifyGfsReferenceSurfaces>
}

/** The code each unavailable reference is reported under (log and turn block). */
export const FILE_REFERENCE_AVAILABILITY_CODES: Record<
  Exclude<FileReferenceAvailability, 'available'>,
  FileReferenceErrorCode
> = {
  not_found: FileReferenceErrorCode.NotFound,
  denied: FileReferenceErrorCode.Denied,
  stale: FileReferenceErrorCode.Stale,
  not_a_file: FileReferenceErrorCode.NotAFile,
  too_large: FileReferenceErrorCode.TooLarge,
  unsupported: FileReferenceErrorCode.Unsupported,
}

/** The `referenced_file` entries for the turn-context block, in message order. */
export function referencedFilesForTurnContext(
  resolutions: readonly FileReferenceResolution[] | undefined
): TurnContextReferencedFile[] {
  return (resolutions ?? []).map(({ availability, reference, resolvedVersion }) => {
    const { source } = reference
    return {
      referenceId: reference.id,
      name: reference.name,
      class: reference.class,
      byteLength: reference.byteLength,
      sourceKind: source.kind,
      ...(source.kind === 'gfs'
        ? { gfs: { drive: source.drive, resourceId: source.resourceId, version: source.version } }
        : {}),
      availability,
      ...(availability === 'available'
        ? {}
        : { code: FILE_REFERENCE_AVAILABILITY_CODES[availability] }),
      ...(resolvedVersion === undefined ? {} : { currentVersion: resolvedVersion }),
    }
  })
}

export type ParsedIncomingFileReferences =
  | { ok: true; references: FileReferenceV1[] }
  | {
      ok: false
      code: FileReferenceErrorCode.SchemaVersionUnsupported | FileReferenceErrorCode.Invalid
      message: string
    }

function normalizeRid(value: string): string | null {
  const normalized = value.replace(/-/g, '').toLowerCase()
  return /^[a-f0-9]{32}$/.test(normalized) ? normalized : null
}

/** `undefined` is a message without references; anything else must be a list. */
export function parseIncomingFileReferences(
  value: unknown,
  maxCount: number
): ParsedIncomingFileReferences {
  if (value === undefined) return { ok: true, references: [] }
  const invalid = (message: string): ParsedIncomingFileReferences => ({
    ok: false,
    code: FileReferenceErrorCode.Invalid,
    message,
  })
  if (!Array.isArray(value)) return invalid('fileReferences must be a list.')
  if (value.length > maxCount) return invalid(`A message can reference at most ${maxCount} files.`)
  const references: FileReferenceV1[] = []
  const ids = new Set<string>()
  const gfsFiles = new Set<string>()
  for (const entry of value) {
    const parsed = parseFileReferenceV1(entry)
    if (!parsed.ok) {
      return {
        ok: false,
        code:
          parsed.code === 'FILE_REFERENCE_SCHEMA_VERSION_UNSUPPORTED'
            ? FileReferenceErrorCode.SchemaVersionUnsupported
            : FileReferenceErrorCode.Invalid,
        message: parsed.message,
      }
    }
    const reference = parsed.value
    // A GFS file is keyed by drive and resource, whatever the version: two
    // references to the same file would leave its read pin ambiguous. The
    // contract guarantees gfsUri is gfs://<drive>/<normalized rid>.
    const key = reference.source.kind === 'gfs' ? reference.source.gfsUri : reference.id
    const seen = reference.source.kind === 'gfs' ? gfsFiles : ids
    if (seen.has(key)) return invalid('Each file reference must appear once.')
    seen.add(key)
    references.push(reference)
  }
  return { ok: true, references }
}

/** The gfsc surface resolution needs: one JSON metadata call. */
export interface FileReferenceGfscClient {
  resolve(
    args: { uri: string },
    call: { signal: AbortSignal; deadlineMs: number }
  ): Promise<unknown>
}

/**
 * Why a check could not produce resolutions.
 * - `transient`: gfsc was unavailable, slow or rate-limited; the client may resend.
 * - `invalid`: gfsc refused the reference as malformed, or it misstates the file's size.
 * - `contract`: gfsc answered with a status or a body the Host does not understand.
 * - `credentials`: the Host's own GFS token is unreadable, undecodable or refused.
 */
export type FileReferenceCheckFailure = 'transient' | 'invalid' | 'contract' | 'credentials'

/** What failed, from a closed set of names; never an error message. */
export type FileReferenceCheckErrorClass =
  | 'GfscHttpError'
  | 'AbortError'
  | 'TimeoutError'
  | 'TypeError'
  | 'SyntaxError'
  | 'TokenReadError'
  | 'TokenDecodeError'
  | 'UnexpectedMetadata'
  | 'SizeMismatch'

export type FileReferenceResolutionResult =
  | { ok: true; resolutions: FileReferenceResolution[] }
  | {
      ok: false
      failure: FileReferenceCheckFailure
      errorClass: FileReferenceCheckErrorClass
      /** The gfsc HTTP status, when gfsc answered. */
      status?: number
    }

class ResolutionFailure extends Error {
  constructor(
    readonly failure: FileReferenceCheckFailure,
    readonly errorClass: FileReferenceCheckErrorClass,
    readonly status?: number
  ) {
    super(`file reference resolution failed: ${failure}`)
    this.name = 'ResolutionFailure'
  }
}

// The error the gfsc client raises for an empty mounted token file.
const EMPTY_TOKEN_FILE_MESSAGE = 'MCP_HOST_GFS_TOKEN_FILE is empty'

function isTokenReadError(error: Error): boolean {
  if (error.message === EMPTY_TOKEN_FILE_MESSAGE) return true
  // A failed read of the mounted token file is a Node system error.
  const { code, syscall } = error as NodeJS.ErrnoException
  return typeof code === 'string' && typeof syscall === 'string'
}

/**
 * Maps a failed gfsc `resolve` call that is not an availability. An error of a
 * class outside this table is rethrown: it is a defect, not a check result.
 * Every gfsc status is classified, because a rethrown GfscHttpError would
 * carry gfsc's response body into the route's 500 answer.
 */
function checkFailure(error: unknown): ResolutionFailure {
  if (error instanceof GfscHttpError) {
    const { status } = error
    if (status === 401) return new ResolutionFailure('credentials', 'GfscHttpError', status)
    if (status === 429 || (status >= 500 && status <= 599))
      return new ResolutionFailure('transient', 'GfscHttpError', status)
    // Any other status, 4xx or the 3xx that redirect:'error' lets through, is
    // one the Host does not understand.
    return new ResolutionFailure('contract', 'GfscHttpError', status)
  }
  if (error instanceof Error) {
    if (error.name === 'AbortError' || error.name === 'TimeoutError')
      return new ResolutionFailure('transient', error.name)
    if (error instanceof SyntaxError) return new ResolutionFailure('contract', 'SyntaxError')
    if (isTokenReadError(error)) return new ResolutionFailure('credentials', 'TokenReadError')
    // fetch reports every transport or URL failure as a TypeError carrying the
    // underlying failure as its cause: a Node system error with a code, or a
    // port/address/URL failure that carries only a message ("bad port",
    // ERR_INVALID_URL). With redirect:'error' it reports a 3xx as a cause
    // saying "unexpected redirect". A TypeError without an Error cause is a
    // Host defect and falls through to the rethrow below.
    if (error instanceof TypeError) {
      const cause = (error as { cause?: unknown }).cause
      if (cause instanceof Error) {
        if (cause.message === 'unexpected redirect')
          return new ResolutionFailure('contract', 'TypeError')
        return new ResolutionFailure('transient', 'TypeError')
      }
    }
  }
  throw error
}

interface ResolvedView {
  kind: 'file' | 'directory'
  version: number
  bytes: number
}

function resolvedView(
  body: unknown,
  source: Extract<FileReferenceV1['source'], { kind: 'gfs' }>
): ResolvedView {
  const envelope = body as { ok?: unknown; data?: unknown } | null
  if (
    !envelope ||
    typeof envelope !== 'object' ||
    envelope.ok !== true ||
    !envelope.data ||
    typeof envelope.data !== 'object'
  )
    throw new ResolutionFailure('contract', 'UnexpectedMetadata')
  const data = envelope.data as Record<string, unknown>
  const rid = normalizeRid(source.resourceId)
  if (
    typeof data.resourceId !== 'string' ||
    normalizeRid(data.resourceId) !== rid ||
    data.rid !== rid ||
    data.drive !== source.drive ||
    data.gfsUri !== source.gfsUri ||
    (data.kind !== 'file' && data.kind !== 'directory') ||
    !Number.isSafeInteger(data.version) ||
    (data.version as number) < 0 ||
    !Number.isSafeInteger(data.bytes) ||
    (data.bytes as number) < 0
  )
    throw new ResolutionFailure('contract', 'UnexpectedMetadata')
  return { kind: data.kind, version: data.version as number, bytes: data.bytes as number }
}

async function resolveOne(
  reference: FileReferenceV1,
  client: FileReferenceGfscClient | null,
  call: { signal: AbortSignal; deadlineMs: number },
  runtimeSurfaces: GfsSurfaceRuntimeCapability
): Promise<FileReferenceResolution> {
  const source = reference.source
  if (source.kind !== 'gfs' || !client) return { availability: 'unsupported', reference }
  let body: unknown
  try {
    body = await client.resolve({ uri: source.gfsUri }, call)
  } catch (error) {
    if (error instanceof GfscHttpError) {
      // gfsc checks the grant before the lookup, so a missing resource usually
      // answers 403 too; 404/410 only reach a principal that could read it.
      if (error.status === 403) return { availability: 'denied', reference }
      if (error.status === 404 || error.status === 410)
        return { availability: 'not_found', reference }
      if (error.status === 400) throw new ResolutionFailure('invalid', 'GfscHttpError', 400)
    }
    throw checkFailure(error)
  }
  const view = resolvedView(body, source)
  if (view.kind === 'directory') return { availability: 'not_a_file', reference }
  if (view.version !== source.version)
    return { availability: 'stale', reference, resolvedVersion: view.version }
  // Same version, so the same bytes: a different size is a reference that
  // misstates the file, not a change to it.
  if (view.bytes !== reference.byteLength) throw new ResolutionFailure('invalid', 'SizeMismatch')
  if (view.bytes > GFS_FILE_LIMITS.maxFileBytes) return { availability: 'too_large', reference }
  return {
    availability: 'available',
    reference,
    surfaces: classifyGfsReferenceSurfaces(reference, runtimeSurfaces),
  }
}

/**
 * Resolves every reference in parallel under one deadline. The first failure
 * aborts the calls still in flight.
 */
export async function resolveFileReferences(
  references: readonly FileReferenceV1[],
  client: FileReferenceGfscClient | null,
  timeoutMs: number = VISUAL_INPUT_LIMITS.validationTimeoutMs,
  runtimeSurfaces: GfsSurfaceRuntimeCapability = {
    workspaceFile: false,
    localExecutor: false,
    visual: false,
  }
): Promise<FileReferenceResolutionResult> {
  const controller = new AbortController()
  const timer = setTimeout(() => controller.abort(), timeoutMs)
  const call = { signal: controller.signal, deadlineMs: Date.now() + timeoutMs }
  try {
    const resolutions = await Promise.all(
      references.map(reference => resolveOne(reference, client, call, runtimeSurfaces))
    )
    return { ok: true, resolutions }
  } catch (error) {
    if (error instanceof ResolutionFailure)
      return {
        ok: false,
        failure: error.failure,
        errorClass: error.errorClass,
        ...(error.status === undefined ? {} : { status: error.status }),
      }
    // R4-M3 — undici puts the header value or a credentialed URL in the message
    // of a causeless TypeError, and the message route answers error.message
    // verbatim. Wrap the rethrow so only this fixed text can leave the Host;
    // the cause keeps the original error for a caller that inspects it. The
    // route logs the wrapper through the Host logger, whose serializer keeps only
    // name, code and status of an Error and does not follow `cause`, so the
    // original class would be lost. Log the original here instead: the same
    // serializer reduces it to name, code and status and drops its message.
    logger.error({ err: error }, '[FileReferences] unexpected error while resolving references')
    throw new Error('file reference resolution failed: unexpected Host error', { cause: error })
  } finally {
    clearTimeout(timer)
    controller.abort()
  }
}