Skip to content

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

TypeScript
4.2 KB
Raw Blame
import { quotePromptValue } from '@clerum/gfs-interaction-policy'
import type { ComposerReferenceAttachment } from '../uiTypes'

function normalizeComposerReferenceName(value: string): string {
  return value.trim()
}

/**
 * Each value is a JSON string literal in which control, format, separator and
 * default-ignorable characters are escaped, so a name cannot add a line or an
 * entry to this section.
 * parseChatMessageDisplay reads the same form back.
 */
function quotedList(values: string[]): string {
  return values.map(quotePromptValue).join(', ')
}

function formatAgentFileReference(
  reference: Extract<ComposerReferenceAttachment, { type: 'agent_file' }>
): string {
  const filesystemName = normalizeComposerReferenceName(reference.filesystemName)
  const path = normalizeComposerReferenceName(reference.path)
  if (!filesystemName || !path) return ''
  return `${filesystemName}${path.startsWith('/') ? path : `/${path}`}`
}

/**
 * Only the label: the gfs:// URI reaches the model through the structured
 * fileReferences in the Host's turn context, never through message content.
 * An entry without a label is left out of this line.
 */
function formatGlobalFileReference(
  reference: Extract<ComposerReferenceAttachment, { type: 'global_file' }>
): string {
  return normalizeComposerReferenceName(reference.label)
}

export function buildComposerReferencesPromptSection(
  references: ComposerReferenceAttachment[]
): string | null {
  if (!references.length) return null

  const plugins = references
    .filter(
      (reference): reference is Extract<ComposerReferenceAttachment, { type: 'plugin' }> =>
        reference.type === 'plugin'
    )
    .map(reference => {
      const namespace = normalizeComposerReferenceName(reference.namespace)
      const name = normalizeComposerReferenceName(reference.name)
      return namespace && name ? `${namespace}/${name}` : ''
    })
    .filter(Boolean)

  const connectors = references
    .filter(
      (reference): reference is Extract<ComposerReferenceAttachment, { type: 'connector' }> =>
        reference.type === 'connector'
    )
    .map(reference => normalizeComposerReferenceName(reference.name))
    .filter(Boolean)

  const agentFiles = references
    .filter(
      (reference): reference is Extract<ComposerReferenceAttachment, { type: 'agent_file' }> =>
        reference.type === 'agent_file'
    )
    .map(formatAgentFileReference)
    .filter(Boolean)

  const globalFiles = references
    .filter(
      (reference): reference is Extract<ComposerReferenceAttachment, { type: 'global_file' }> =>
        reference.type === 'global_file'
    )
    .map(formatGlobalFileReference)
    .filter(Boolean)

  if (!plugins.length && !connectors.length && !agentFiles.length && !globalFiles.length) {
    return null
  }

  const lines = [
    'USER-ATTACHED CONTEXT: The user selected these capabilities/files for this message. Prefer them when they are relevant to the request. Every quoted name below is a JSON string literal: pass its decoded value, without the surrounding quotes or escapes, when you use it in a tool call.',
  ]

  if (plugins.length) {
    lines.push(
      `Plugins: ${quotedList(plugins)}. Use workflow tools for these plugin names when the user asks to run or use a plugin.`
    )
  }

  if (connectors.length) {
    lines.push(
      `Connectors: ${quotedList(connectors)}. Use MCP tools whose prefix before "__" exactly matches one of these connector names.`
    )
  }

  if (agentFiles.length) {
    lines.push(
      `Agent Files: ${quotedList(agentFiles)}. Use clerum__context_files_list and clerum__context_files_read to inspect these paths before relying on their contents.`
    )
  }

  if (globalFiles.length) {
    // The files travel as structured fileReferences (#666); the Host lists them
    // in the turn context with how to read them, so this line only names them.
    lines.push(
      `Global Files: ${quotedList(globalFiles)}. These files were explicitly selected by the user.`
    )
  }

  return lines.join('\n')
}

export function buildComposerRequestContent(
  content: string,
  references: ComposerReferenceAttachment[]
): string {
  const referencesPrompt = buildComposerReferencesPromptSection(references)
  return [content, referencesPrompt].filter(Boolean).join('\n\n')
}