Skip to content

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

TypeScript
7.2 KB
Raw Blame
/**
 * T1.5 §4.4 — Structure hints attached to spillover summaries.
 *
 * Strict rules (plan §4.4):
 *   - Never call the LLM. Everything is regex / shape inspection.
 *   - Wrap each generator in try/catch; on failure return `null` (do not
 *     "invent" hints).
 *   - Cheap: bounded line scan (first 50 lines) for source code,
 *     bounded JSON parse for HTTP/JSON outputs.
 *
 * The hint is **advisory** for the LLM. It MUST never carry secrets or
 * full content — head/tail already cover that.
 */

const HEAD_LINES_FOR_SCAN = 50
const MAX_SYMBOLS = 20
const MAX_TOP_LEVEL_KEYS = 10

interface FileReadHint {
  language: string
  top_level: string[]
}

interface HttpHint {
  status?: number
  content_type?: string
  top_level_keys?: string[]
}

interface ShellHint {
  exit_code?: number
  looks_like_error?: boolean
}

const LANGUAGE_PATTERNS: Record<string, { regex: RegExp; language: string }> = {
  '.ts': {
    regex:
      /^\s*(?:export\s+)?(?:async\s+)?(function|class|const|let|var|interface|type|enum)\s+(\w+)/,
    language: 'typescript',
  },
  '.tsx': {
    regex:
      /^\s*(?:export\s+)?(?:async\s+)?(function|class|const|let|var|interface|type|enum)\s+(\w+)/,
    language: 'typescript',
  },
  '.js': {
    regex: /^\s*(?:export\s+)?(?:async\s+)?(function|class|const|let|var)\s+(\w+)/,
    language: 'javascript',
  },
  '.jsx': {
    regex: /^\s*(?:export\s+)?(?:async\s+)?(function|class|const|let|var)\s+(\w+)/,
    language: 'javascript',
  },
  '.py': {
    regex: /^\s*(class|def|async\s+def)\s+(\w+)/,
    language: 'python',
  },
  '.rs': {
    regex: /^\s*(?:pub\s+)?(fn|struct|enum|trait|impl)\s+(\w+)/,
    language: 'rust',
  },
  '.go': {
    regex: /^\s*func\s+(?:\(\s*\w+\s+[\w*]+\s*\)\s+)?(\w+)/,
    language: 'go',
  },
}

function inferExtension(toolName: string, params?: Record<string, unknown>): string | null {
  if (toolName === 'file_read' && params && typeof params['path'] === 'string') {
    const idx = (params['path'] as string).lastIndexOf('.')
    if (idx >= 0) return (params['path'] as string).slice(idx).toLowerCase()
  }
  return null
}

function topLevelJsonKeys(content: string): string[] | null {
  const trimmed = content.trimStart()
  if (!trimmed.startsWith('{')) return null
  try {
    const parsed = JSON.parse(trimmed)
    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
      return Object.keys(parsed).slice(0, MAX_TOP_LEVEL_KEYS)
    }
    return null
  } catch {
    return null
  }
}

function fileReadHint(content: string, extension: string | null): FileReadHint | null {
  // Markdown headings.
  if (extension === '.md') {
    const headings: string[] = []
    const lines = content.split(/\r?\n/).slice(0, HEAD_LINES_FOR_SCAN)
    for (const line of lines) {
      const m = line.match(/^#\s+(.+)$/)
      if (m) headings.push(m[1].trim().slice(0, 80))
      if (headings.length >= MAX_SYMBOLS) break
    }
    if (headings.length === 0) return null
    return { language: 'markdown', top_level: headings }
  }

  // JSON: top-level keys when parseable.
  if (extension === '.json') {
    const keys = topLevelJsonKeys(content)
    if (!keys) return null
    return { language: 'json', top_level: keys }
  }

  // YAML: top-level keys ("^[a-zA-Z_][\w-]*\s*:") in first 50 lines.
  if (extension === '.yaml' || extension === '.yml') {
    const keys: string[] = []
    const lines = content.split(/\r?\n/).slice(0, HEAD_LINES_FOR_SCAN)
    for (const line of lines) {
      const m = line.match(/^([A-Za-z_][\w-]*)\s*:/)
      if (m) keys.push(m[1])
      if (keys.length >= MAX_TOP_LEVEL_KEYS) break
    }
    if (keys.length === 0) return null
    return { language: 'yaml', top_level: keys }
  }

  // Source code patterns.
  if (extension && LANGUAGE_PATTERNS[extension]) {
    const { regex, language } = LANGUAGE_PATTERNS[extension]
    const symbols: string[] = []
    const lines = content.split(/\r?\n/).slice(0, HEAD_LINES_FOR_SCAN)
    for (const line of lines) {
      const m = line.match(regex)
      if (m) {
        const kind = m[1] ?? 'symbol'
        const name = m[2] ?? m[1] ?? '?'
        symbols.push(`${kind} ${name}`)
      }
      if (symbols.length >= MAX_SYMBOLS) break
    }
    if (symbols.length === 0) return null
    return { language, top_level: symbols }
  }

  return null
}

function httpHint(content: string, contentType: string): HttpHint | null {
  // Try parse JSON body when content_type suggests JSON.
  const hint: HttpHint = {}
  if (contentType === 'application/json') {
    const keys = topLevelJsonKeys(content)
    if (keys) hint.top_level_keys = keys
    hint.content_type = contentType
  }
  // Try to pluck "HTTP/1.1 200 OK"-style first line if present (some tools prepend status).
  const firstLine = content.split(/\r?\n/, 1)[0] ?? ''
  const statusMatch = firstLine.match(/^HTTP\/[\d.]+\s+(\d{3})/)
  if (statusMatch) hint.status = Number(statusMatch[1])
  return Object.keys(hint).length === 0 ? null : hint
}

function shellHint(content: string): ShellHint | null {
  const hint: ShellHint = {}
  // Errorish heuristics on the *first* line — same as the LLM would skim.
  const firstLine = content.split(/\r?\n/, 1)[0] ?? ''
  if (
    /^(Traceback|Error|error|panic|fatal:|Exception:)/i.test(firstLine) ||
    /^[A-Z][\w.]*Error:/.test(firstLine)
  ) {
    hint.looks_like_error = true
  }
  // Exit code (some shell tools append "Exit: <N>").
  const exitMatch = content.match(/(?:^|\n)\s*(?:exit code|exit):\s*(\d+)/i)
  if (exitMatch) hint.exit_code = Number(exitMatch[1])
  return Object.keys(hint).length === 0 ? null : hint
}

/**
 * Public entry point. Dispatches by tool name + content_type.
 */
export function generateStructureHint(
  toolName: string,
  content: string,
  contentType: string,
  params?: Record<string, unknown>
): unknown | null {
  try {
    if (toolName === 'file_read') {
      const ext = inferExtension(toolName, params)
      return fileReadHint(content, ext)
    }
    if (toolName === 'http_request') {
      return httpHint(content, contentType)
    }
    if (toolName === 'shell_exec' || toolName === 'shell') {
      return shellHint(content)
    }
    // JSON content from any tool — best-effort top-level keys.
    if (contentType === 'application/json') {
      const keys = topLevelJsonKeys(content)
      if (keys) return { top_level_keys: keys }
    }
    return null
  } catch {
    return null
  }
}

/**
 * Heuristic content_type inference. Public for the storage layer; deliberately
 * dumb so callers can override when they know better (e.g. http_request tool
 * could pluck the real Content-Type header from a wrapped envelope).
 */
export function inferContentType(toolName: string, content: string): string {
  if (toolName === 'file_read') {
    const trimmed = content.trimStart()
    if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
      try {
        JSON.parse(trimmed)
        return 'application/json'
      } catch {
        // fall through
      }
    }
    if (/^#\s+/m.test(content)) return 'text/markdown'
    return 'text/plain'
  }
  if (toolName === 'http_request') {
    const trimmed = content.trimStart()
    if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
      try {
        JSON.parse(trimmed)
        return 'application/json'
      } catch {
        // fall through
      }
    }
    return 'text/plain'
  }
  return 'text/plain'
}