Skip to content

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

TypeScript
12.1 KB
Raw Blame
import { logger } from '../../logger'
import {
  extractToolIntent,
  getDisplayName,
  sanitizeError,
} from '../../progress/intentExtraction.js'
import type { ToolCallTokens } from '../../progress/types.js'
import { ToolError } from '../errors'
import type { ExecutionContext } from '../interfaces'
import { RingBuffer } from '../tools/ringBuffer'
import type { TokenUsage, ToolCall, ToolResult } from '../types'
import type { LoopConfig } from './loopConfig'
import { executeWithTimeout } from './toolExecutionTimeout'
import { buildOutputPreview, extractInputPreview } from './toolUseLoopPreviews'

export async function executeSingleTool(
  call: ToolCall,
  config: Pick<
    LoopConfig,
    | 'toolRegistry'
    | 'toolOutputProcessor'
    | 'safety'
    | 'events'
    | 'toolTimeout'
    | 'progressReporter'
    | 'toolProgressInterval'
    | 'spilloverStorage'
    | 'taskId'
    | 'visualInput'
    | 'abortSignal'
    | 'measureToolMessage'
  >,
  iteration?: number,
  transformResult?: (result: ToolResult) => Promise<ToolResult>
): Promise<ToolResult> {
  const { toolRegistry, toolOutputProcessor, events, toolTimeout } = config

  // Post-result hooks see error results too and observe failed calls. A thrown
  // upstream message can carry a secret, so the error text first goes through
  // the tool-output sanitizer the success path applies (`toolOutputProcessor`
  // delegates to `config.safety.sanitizeOutput`), unwrapped: error text keeps
  // its plain shape for the model.
  const errorResult = async (content: string): Promise<ToolResult> => {
    const result: ToolResult = {
      tool_call_id: call.id,
      name: call.name,
      content: config.safety.sanitizeOutput(call.name, content).content,
      is_error: true,
    }
    return transformResult ? transformResult(result) : result
  }

  const tool = toolRegistry.get(call.name)
  let validation = toolOutputProcessor.beforeExecution(call.name, call.arguments)
  if (validation.is_valid) {
    // The execution boundary also receives transformed parameters and frozen
    // approved calls. Validate the effective values, not only pre-policy input.
    validation = (await tool?.validateParams?.(call.arguments)) ?? validation
  }
  if (!validation.is_valid) {
    events.emit({
      type: 'safety:input_blocked',
      data: {
        toolName: call.name,
        errors: validation.errors,
        ...(iteration !== undefined && { iteration }),
      },
      timestamp: new Date(),
    })
    return errorResult(`Parameter validation failed: ${validation.errors.join(', ')}`)
  }

  if (!tool) return errorResult(`Tool not found: ${call.name}`)

  const renderContent = (content: string): string => {
    if (!tool.requiresSanitization()) return content
    if (!toolOutputProcessor.previewForLlm) {
      throw new Error('measureResult requires ToolOutputProcessor.previewForLlm')
    }
    return toolOutputProcessor.previewForLlm(call.name, content)
  }
  const measureContent = (content: string): number => {
    if (!config.measureToolMessage)
      throw new Error('measureToolMessage is required for bounded native output')
    return config.measureToolMessage({
      role: 'tool',
      name: call.name,
      tool_call_id: call.id,
      content,
    })
  }

  events.emit({
    type: 'tool:called',
    data: { toolName: call.name, toolCallId: call.id },
    timestamp: new Date(),
  })

  let ringBuffer: RingBuffer | null = null
  const executionContext: ExecutionContext = {
    onOutput: chunk => ringBuffer?.append(chunk),
    visualInput: config.visualInput,
    measureResult: config.measureToolMessage
      ? content => measureContent(renderContent(content))
      : undefined,
  }
  let watcherId: NodeJS.Timeout | null = null
  const watcherStartedAt = Date.now()

  let wantsWatcher = false
  let finalizingResult = false
  try {
    wantsWatcher =
      typeof tool.supportsProgressOutput === 'function' &&
      tool.supportsProgressOutput() === true &&
      !!config.progressReporter &&
      (config.toolProgressInterval ?? 0) > 0
  } catch {
    wantsWatcher = false
  }

  if (wantsWatcher) {
    ringBuffer = new RingBuffer(64 * 1024)
    const buf = ringBuffer
    watcherId = setInterval(() => {
      try {
        const snapshot = buf.snapshot()
        const sanitized = snapshot
          ? config.safety.sanitizeOutput(call.name, snapshot).content
          : undefined
        const outputPreview = sanitized ? buildOutputPreview(sanitized) : undefined
        config.progressReporter!.reportToolProgress({
          taskId: '',
          toolCallId: call.id,
          toolName: call.name,
          elapsedMs: Date.now() - watcherStartedAt,
          outputPreview,
        })
      } catch {
        // Observability failure is not a task failure.
      }
    }, config.toolProgressInterval)
  }

  try {
    const execStart = Date.now()
    const output = await executeWithTimeout(
      tool,
      call.arguments,
      executionContext,
      toolTimeout,
      config.abortSignal
    )
    logger.debug(
      { toolName: call.name, durationMs: Date.now() - execStart, isError: output.is_error },
      'Tool execution finished'
    )

    const attachments = output.is_error ? undefined : output.attachments
    if (!output.is_error) {
      for (const attachment of attachments ?? []) {
        if (attachment.kind === 'image' && !attachment.visualSource)
          config.visualInput?.budget.observeExternalImage(attachment.dataBase64)
      }
    }
    let wrappedContent: string
    if (tool.requiresSanitization()) {
      wrappedContent = toolOutputProcessor.afterExecution(call.name, output)
      if (wrappedContent !== output.content) {
        events.emit({
          type: 'safety:output_sanitized',
          data: {
            toolName: call.name,
            originalLength: output.content.length,
            sanitizedLength: wrappedContent.length,
            ...(iteration !== undefined && { iteration }),
          },
          timestamp: new Date(),
        })
      }
    } else {
      wrappedContent = output.content
    }

    const traceDescriptor = tool.traceDescriptor?.(call.arguments, output) ?? {
      kind: 'internal_tool' as const,
      sourceRef: 'mcp-host',
    }
    events.emit({
      type: 'tool:completed',
      data: {
        toolName: call.name,
        toolCallId: call.id,
        duration_ms: output.duration_ms,
        is_error: output.is_error,
        toolKind: traceDescriptor.kind,
        toolSourceRef: traceDescriptor.sourceRef,
      },
      timestamp: new Date(),
    })

    // T1.5 — Spillover. If the sanitized output exceeds the configured byte
    // threshold (and is not an error), persist the blob out-of-band and
    // replace `content` with a rich JSON summary. The lateral `spillover_ref`
    // field carries the URI (P0-002 Opción D) so the resume path can resolve
    // in O(1) without re-parsing the LLM-bound JSON body.
    //
    // A tool whose output is already bounded by its own contract declares
    // `spilloverExempt()` (`clerum__spillover_read` reads back a blob that was
    // spilled once; `clerum__attachment_read` returns the page the caller
    // asked for) and is shipped inline whatever its size (#666, #678).
    //
    // `rawContent` keeps the original blob untouched so the progress reporter
    // (and the workflow read-only fallbacks) still see the real output.
    let finalContent = wrappedContent
    let spilloverRef: string | undefined
    if (
      config.spilloverStorage &&
      config.taskId &&
      !output.is_error &&
      tool.spilloverExempt?.() !== true
    ) {
      try {
        const summary = await config.spilloverStorage.maybePersist({
          taskId: config.taskId,
          toolCallId: call.id,
          toolName: call.name,
          content: wrappedContent,
          isError: false,
        })
        if (summary) {
          finalContent = JSON.stringify(summary)
          spilloverRef = summary.spillover_ref
          events.emit({
            type: 'spillover:persisted',
            data: {
              toolName: call.name,
              byteSize: summary.byte_size,
              ref: summary.spillover_ref,
            },
            timestamp: new Date(),
          })
        }
      } catch (err) {
        // Spillover is an optimization; persistence failure must NOT lose the
        // tool result. Log and fall through with the inline content.
        logger.error({ toolName: call.name, err }, 'Spillover persistence failed')
      }
    }

    let result: ToolResult = {
      tool_call_id: call.id,
      name: call.name,
      content: finalContent,
      is_error: output.is_error,
      attachments,
      metadata: output.metadata,
      rawContent: output.content,
      spillover_ref: spilloverRef,
    }
    // Post-result hooks execute once. Measure after them; a preview never
    // repeats a hook, tool execution, progress event or spillover write.
    finalizingResult = true
    if (transformResult) result = await transformResult(result)
    if (config.measureToolMessage) {
      result = { ...result, emittedMessageCost: measureContent(result.content) }
    }
    if (tool.finalizeResult) {
      result = await tool.finalizeResult(result, { measureContent, renderContent })
      const finalCost = measureContent(result.content)
      if (result.emittedMessageCost !== finalCost) {
        throw new Error('Final tool-message measurement does not match its budget debit')
      }
    }
    return result
  } catch (err) {
    // A result-policy/finalization failure must stop publication. Turning it
    // into an ordinary tool error could make the model repeat completed work.
    if (finalizingResult) throw err
    const errorMessage =
      err instanceof ToolError ? err.message : `Tool execution failed: ${(err as Error).message}`

    logger.error({ toolName: call.name, err }, 'Tool execution failed')

    return await errorResult(errorMessage)
  } finally {
    if (watcherId) {
      clearInterval(watcherId)
      watcherId = null
    }
  }
}

export function reportToolStart(
  config: LoopConfig,
  call: ToolCall,
  iteration: number,
  stepIndex: number,
  totalSteps: number,
  llmTextContent?: string
): number {
  const displayName = getDisplayName(call.name)
  const progressStart = Date.now()
  config.progressReporter?.reportToolStart({
    taskId: '',
    toolCallId: call.id,
    toolName: call.name,
    displayName,
    intentSummary:
      extractToolIntent(llmTextContent ?? null, call.name) ?? `Using ${displayName}...`,
    iteration,
    stepIndex,
    totalSteps,
    inputPreview: extractInputPreview(call.name, call.arguments),
  })
  return progressStart
}

export function reportToolComplete(
  config: LoopConfig,
  call: ToolCall,
  toolResult: ToolResult,
  progressStart: number,
  iteration: number,
  stepIndex: number,
  totalSteps: number,
  usage?: TokenUsage
): void {
  if (!config.progressReporter) return
  const rawForPreview = toolResult.rawContent ?? toolResult.content
  const previewContent = config.safety.sanitizeOutput(call.name, rawForPreview).content
  config.progressReporter.reportToolComplete({
    taskId: '',
    toolCallId: call.id,
    toolName: call.name,
    displayName: getDisplayName(call.name),
    durationMs: Date.now() - progressStart,
    isError: toolResult.is_error ?? false,
    errorSummary: toolResult.is_error ? sanitizeError(toolResult.content) : undefined,
    iteration,
    stepIndex,
    totalSteps,
    outputPreview: buildOutputPreview(previewContent),
    metadata: toolResult.metadata,
    tokens: projectToolCallTokens(usage),
  })
}

export function projectToolCallTokens(usage?: TokenUsage): ToolCallTokens | undefined {
  if (!usage) return undefined
  if (usage.input_tokens + usage.output_tokens === 0) return undefined
  const tokens: ToolCallTokens = {
    input: usage.input_tokens,
    output: usage.output_tokens,
  }
  // A defined cache_* field IS the "provider reports cache" signal (same
  // convention as projectTurnTokens): Anthropic's defined 0 is included,
  // OpenAI's undefined is omitted.
  if (usage.cache_read_tokens !== undefined || usage.cache_write_tokens !== undefined) {
    tokens.cacheRead = usage.cache_read_tokens ?? 0
    tokens.cacheWrite = usage.cache_write_tokens ?? 0
  }
  return tokens
}