Skip to content

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

TypeScript
9.7 KB
Raw Blame
import { randomUUID } from 'node:crypto'
import { FILE_REFERENCE_MAX_COUNT } from '@clerum/gfs-interaction-policy'
import type { FileReferenceV1 } from '@clerum/gfs-interaction-policy'
import type { LoopConfig } from '../core/orchestration/loopConfig'
import { admitToolCall, executeAdmittedTool } from '../core/orchestration/toolCallPolicy'
import type {
  GfsPreparationFailure,
  PreparedGfsFile,
  PreparedGfsUsage,
} from '../core/orchestration/turnContext'
import type { ToolOutput } from '../core/types'
import { normalizeRid } from '../internalTools/gfsContentRead'
import { GFS_FILE_LIMITS } from '../internalTools/gfsFilePolicy'
import { GFS_LOCAL_PROCESSING_GUIDANCE } from '../internalTools/gfsReadTypes'
import { gfsStoreSpaceGuidance } from '../internalTools/gfsSpaceGuidance'
import type { FileReferenceResolution } from './fileReferenceResolver'
import type { TaskExecutionBudget } from './taskExecutionBudget'

const DOWNLOAD_TOOL = 'clerum__gfs_download'
const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
const SHA256_RE = /^[0-9a-f]{64}$/

export function hasLargeAvailableGfsReferences(
  resolutions?: readonly FileReferenceResolution[]
): boolean {
  return (
    resolutions?.some(
      ({ availability, reference }) =>
        availability === 'available' &&
        reference.source.kind === 'gfs' &&
        reference.byteLength > GFS_FILE_LIMITS.inlineTextBytes
    ) === true
  )
}

function failureCode(content: string): GfsPreparationFailure {
  // Read only the producer's fixed public error envelope; never forward its text.
  if (Buffer.byteLength(content, 'utf8') > GFS_FILE_LIMITS.errorBytes) return 'download_failed'
  const http = /^Error: GFS read failed \(gfsc (\d{3}): [a-z_]+(?:, retry after \d+s)?\)$/.exec(
    content
  )
  if (http) {
    const status = Number(http[1])
    if (status === 401) return 'unauthenticated'
    if (status === 403) return 'denied'
    if (status === 404 || status === 410) return 'missing'
    if (status === 409 || status === 412) return 'stale'
    if (status === 413) return 'limit_exceeded'
    return 'download_failed'
  }
  // A store space refusal carries its fixed guidance as an exact second line;
  // any other second line is not a recognised envelope.
  const space = /^Error: GFS download store failed \((disk_full|host_quota_exceeded)\)\n/.exec(
    content
  )
  if (space) {
    const code = space[1] as 'disk_full' | 'host_quota_exceeded'
    if (content.slice(space[0].length) !== gfsStoreSpaceGuidance(code)) return 'download_failed'
    return code === 'disk_full' ? 'disk_full' : 'quota_exceeded'
  }
  const fixed = /^Error: GFS (?:download(?: store)?|read) failed \(([a-z_]+)\)$/.exec(content)?.[1]
  if (fixed === 'version_conflict') return 'stale'
  if (fixed === 'download_missing' || fixed === 'download_expired') return 'missing'
  if (fixed === 'disk_full') return 'disk_full'
  if (fixed === 'host_quota_exceeded') return 'quota_exceeded'
  // Carries no guidance: only the bare envelope maps here; with any second line
  // the anchored envelope does not match and the result is download_failed.
  if (fixed === 'volume_unmeasurable') return 'volume_unmeasurable'
  if (fixed === 'workspace_unavailable') return 'workspace_unavailable'
  if (fixed === 'limit_exceeded') return 'limit_exceeded'
  if (fixed === 'timeout') return 'timeout'
  if (fixed === 'invalid_response' || fixed === 'identity_mismatch') return 'invalid_response'
  return 'download_failed'
}

function record(value: unknown): Record<string, unknown> | undefined {
  return value !== null && typeof value === 'object' && !Array.isArray(value)
    ? (value as Record<string, unknown>)
    : undefined
}

function checkedPreparation(
  output: ToolOutput,
  reference: FileReferenceV1
): PreparedGfsFile | undefined {
  if (
    reference.source.kind !== 'gfs' ||
    output.attachments?.length ||
    Buffer.byteLength(output.content, 'utf8') > GFS_FILE_LIMITS.metadataBytes
  )
    return undefined
  let parsed: unknown
  try {
    parsed = JSON.parse(output.content)
  } catch {
    return undefined
  }
  const receipt = record(parsed)
  // The native tool reports a pinned-version conflict as a successful metadata
  // availability result, not as a downloaded file or an error string.
  if (
    receipt?.availability === 'stale' &&
    receipt.drive === reference.source.drive &&
    receipt.resourceId === reference.source.resourceId &&
    receipt.expectedVersion === reference.source.version
  )
    return { referenceId: reference.id, status: 'unavailable', code: 'stale' }
  const source = record(receipt?.source)
  const usage = record(receipt?.usage)
  if (
    !receipt ||
    !source ||
    !usage ||
    receipt.delivery !== 'workspace_file' ||
    typeof receipt.id !== 'string' ||
    !UUID_RE.test(receipt.id) ||
    receipt.path !== `.gfs-downloads/input-${receipt.id}/source` ||
    receipt.sizeBytes !== reference.byteLength ||
    typeof receipt.sha256 !== 'string' ||
    !SHA256_RE.test(receipt.sha256) ||
    (reference.digest !== undefined && receipt.sha256 !== reference.digest.hex) ||
    typeof receipt.expiresAt !== 'string' ||
    receipt.expiresAt.length > 32 ||
    !Number.isFinite(Date.parse(receipt.expiresAt)) ||
    Date.parse(receipt.expiresAt) <= Date.now() ||
    source.kind !== 'gfs' ||
    source.drive !== reference.source.drive ||
    source.resourceId !== normalizeRid(reference.source.resourceId) ||
    source.gfsUri !== reference.source.gfsUri ||
    source.version !== reference.source.version ||
    typeof source.name !== 'string' ||
    source.name.length === 0 ||
    source.name.length > 1024 ||
    usage.pathSemantics !== 'relative-to-caller-workspace' ||
    usage.nextTool !== 'shell_exec_when_local_processing_is_needed' ||
    usage.visualDelivery !== 'not_included' ||
    usage.approval !== 'user-approval-required' ||
    usage.writeOutputsTo !== 'outputs/' ||
    usage.processLocally !== true ||
    usage.boundedOutputOnly !== true ||
    usage.wholeFileToContextAllowed !== false
  )
    return undefined
  // Explicit projection excludes unexpected bytes, image parts and transport data.
  const projectedUsage: PreparedGfsUsage = {
    pathSemantics: 'relative-to-caller-workspace',
    nextTool: 'shell_exec_when_local_processing_is_needed',
    visualDelivery: 'not_included',
    approval: 'user-approval-required',
    writeOutputsTo: 'outputs/',
    processLocally: true,
    boundedOutputOnly: true,
    wholeFileToContextAllowed: false,
    // Publish our trusted instructions, never instruction text from a tool result.
    processingInstructions: GFS_LOCAL_PROCESSING_GUIDANCE,
  }
  return {
    referenceId: reference.id,
    status: 'ready',
    receipt: {
      delivery: 'workspace_file',
      id: receipt.id,
      path: receipt.path,
      sizeBytes: reference.byteLength,
      sha256: receipt.sha256,
      expiresAt: receipt.expiresAt,
      source: {
        kind: 'gfs',
        drive: reference.source.drive,
        resourceId: source.resourceId as string,
        gfsUri: reference.source.gfsUri,
        version: reference.source.version,
        name: source.name,
      },
      usage: projectedUsage,
    },
  }
}

/** Use the cached, caller-bound native tool and its effective approval gate. */
export async function prepareGfsFiles(
  resolutions: readonly FileReferenceResolution[],
  context: {
    config: LoopConfig
    callerIdentity?: string
    toolTimeoutMs: number
    budget: Pick<TaskExecutionBudget, 'assertTime' | 'remainingDurationMs'>
  }
): Promise<PreparedGfsFile[]> {
  if (resolutions.length > FILE_REFERENCE_MAX_COUNT)
    throw new Error('Too many GFS file references to prepare')
  const prepared: PreparedGfsFile[] = []
  for (const { availability, reference, surfaces } of resolutions) {
    if (
      availability !== 'available' ||
      reference.source.kind !== 'gfs' ||
      reference.byteLength <= GFS_FILE_LIMITS.inlineTextBytes
    )
      continue
    context.config.abortSignal?.throwIfAborted()
    context.budget.assertTime()
    const unavailable = (code: GfsPreparationFailure): PreparedGfsFile => ({
      referenceId: reference.id,
      status: 'unavailable',
      code,
    })
    const tool = context.config.toolRegistry.get(DOWNLOAD_TOOL)
    if (!context.callerIdentity || surfaces?.workspace !== true || !tool) {
      prepared.push(unavailable('workspace_unavailable'))
      continue
    }
    const params = {
      drive: reference.source.drive,
      resourceId: reference.source.resourceId,
      expectedVersion: reference.source.version,
    }
    const timeoutMs = Math.max(
      1,
      Math.floor(Math.min(context.toolTimeoutMs, context.budget.remainingDurationMs))
    )
    try {
      const admission = await admitToolCall(
        { id: randomUUID(), name: DOWNLOAD_TOOL, arguments: params },
        context.config,
        0
      )
      if (admission.kind !== 'execute') {
        prepared.push(
          unavailable(admission.kind === 'result' ? 'policy_denied' : 'approval_required')
        )
        continue
      }
      const boundedConfig: LoopConfig = {
        ...context.config,
        toolTimeout: Math.min(context.config.toolTimeout, timeoutMs),
      }
      const toolResult = await executeAdmittedTool(admission, boundedConfig, 0)
      const output: ToolOutput = {
        content: toolResult.content,
        duration_ms: 0,
        is_error: toolResult.is_error ?? false,
        attachments: toolResult.attachments,
      }
      context.config.abortSignal?.throwIfAborted()
      context.budget.assertTime()
      prepared.push(
        output.is_error
          ? unavailable(failureCode(output.content))
          : (checkedPreparation(output, reference) ?? unavailable('invalid_response'))
      )
    } catch {
      context.config.abortSignal?.throwIfAborted()
      context.budget.assertTime()
      prepared.push(unavailable('download_failed'))
    }
  }
  return prepared
}