Skip to content

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

TypeScript
18.9 KB
Raw Blame
import { evaluateTaskBrake } from '../../budget/taskBrake'
import { logger } from '../../logger'
import { projectGfsApproval } from '../../visualInput/suspension'
import type {
  Attachment,
  ChatMessage,
  LoopResult,
  ReasoningContext,
  TokenUsage,
  ToolDefinition,
  ToolResult,
} from '../types'
import type { LoopConfig } from './loopConfig'
import {
  handleLoopErrorRecovery,
  hasToolResultForCurrentUserTurn,
  hasWorkflowListResultForCurrentUserTurn,
  hasWorkflowTriggerResultForCurrentUserTurn,
} from './toolUseLoopErrorRecovery'
import {
  isWorkflowArtifactIntent,
  isWorkflowListIntent,
  latestUserText,
  shouldRecoverWorkflowArtifactTextResponse,
  shouldRecoverWorkflowTriggerTextResponse,
} from './toolUseLoopIntentRecovery'
import { validateToolLinkages } from './toolUseLoopLinkages'
import { appendToolResults, loopInjectedUserMessage, markLoopInjected } from './toolUseLoopMessages'
import {
  callReasoningForIteration,
  exhaustionResult,
  manageMessagesForIteration,
  responseResult,
  taskBrakeResult,
  turnStopResult,
} from './toolUseLoopRuntime'
import { executeToolCalls } from './toolUseLoopToolBatch'
import {
  buildWorkflowListFallbackWhenResponseOmitsNames,
  buildWorkflowToolFailureResponse,
  buildWorkflowToolSuccessFallbackResponse,
  isWorkflowSuccessFallbackToolName,
} from './toolUseLoopWorkflowFallbacks'
import {
  buildWorkflowTriggerImmediateFallbackResponse,
  buildWorkflowTriggerNonRunFallbackWhenResponseOmitsClarification,
} from './toolUseLoopWorkflowTriggerFallbacks'

export { executeSingleTool } from './toolUseLoopSingleTool'
export { buildOutputPreview, extractInputPreview } from './toolUseLoopPreviews'
export { validateToolLinkages } from './toolUseLoopLinkages'

/**
 * The tool-use loop: the central algorithm of the agent.
 *
 * This function does not build prompts or interpret model semantics. It executes
 * tools, preserves tool-result linkages, manages context pressure, and applies
 * deterministic workflow fallbacks when the model cannot safely summarize tool output.
 */
export async function runToolUseLoop(
  config: LoopConfig,
  initialMessages: ChatMessage[],
  jobDescription?: string
): Promise<LoopResult> {
  const { toolRegistry, loopController, maxIterations } = config
  let messages = [...initialMessages]
  const totalUsage: TokenUsage = {
    input_tokens: 0,
    output_tokens: 0,
    total_tokens: 0,
  }
  let lastToolResults: ToolResult[] | null = null
  let lastCompletedToolResultsForFallback: ToolResult[] | null = null
  let emptyResponseAfterToolResultsRecovered = false
  let emptyInitialResponseRecovered = false
  let workflowListTextResponseRecovered = false
  let workflowArtifactIntentRecovered = false
  let workflowArtifactTextResponseRecovered = false
  let workflowTriggerTextResponseRecovered = false
  let workflowTriggerAfterListTextResponseRecovered = false
  const collectedAttachments: Attachment[] = []
  const userRequestText = latestUserText(initialMessages)

  const initialTools = toolRegistry.listDefinitions()
  logger.info(
    {
      component: 'Loop',
      maxIterations,
      toolCount: initialTools.length,
      messageCount: initialMessages.length,
    },
    'Loop started'
  )

  try {
    for (let iteration = 0; iteration < maxIterations; iteration++) {
      if (config.abortSignal?.aborted) return { type: 'cancelled', reason: 'signal_aborted' }

      // P2 token budgets (§5.2) — per-task emergency brake. Local, no network:
      // compares THIS task's token delta (current counters − the start-of-task
      // baseline) against the cap from the P1 verdict and exits BEFORE the next
      // LLM call (never interrupts a call in flight). On iteration 0 the delta is
      // 0, so the first call always proceeds. No-op when no cap is configured.
      if (config.taskBrake) {
        const trip = evaluateTaskBrake(config.taskBrake, config.conversation)
        if (trip) return taskBrakeResult(config, iteration, trip, collectedAttachments)
      }

      config.events.emit({
        type: 'loop:iteration',
        data: { iteration, messageCount: messages.length },
        timestamp: new Date(),
      })

      // R21-1: the presented list is selected before pressure is measured, so
      // the context manager counts the schemas this request actually carries.
      let tools: ToolDefinition[]
      try {
        tools = await loopController.refreshTools(toolRegistry.listDefinitions())
      } catch (error) {
        if (config.abortSignal?.aborted) return { type: 'cancelled', reason: 'signal_aborted' }
        // Presentation failures must not dump the entire local catalog into the
        // model request or bypass the controller's approved tool selection.
        return {
          type: 'error',
          error: error instanceof Error ? error : new Error('Tool presentation failed'),
        }
      }

      messages = await manageMessagesForIteration(config, messages, iteration, tools, true)

      const context: ReasoningContext = {
        messages,
        available_tools: tools,
        job_description: jobDescription,
        signal: config.abortSignal,
      }

      const { result, continuingFromToolResults } = await callReasoningForIteration(
        config,
        context,
        lastToolResults,
        iteration
      )
      if (continuingFromToolResults) lastToolResults = null
      if (config.abortSignal?.aborted) return { type: 'cancelled', reason: 'signal_aborted' }

      switch (result.type) {
        case 'text': {
          if (config.abortSignal?.aborted) return { type: 'cancelled', reason: 'signal_aborted' }

          const workflowListFallback = continuingFromToolResults
            ? buildWorkflowListFallbackWhenResponseOmitsNames(
                result.content,
                lastCompletedToolResultsForFallback
              )
            : null
          if (workflowListFallback) {
            return responseResult(
              config,
              iteration,
              workflowListFallback,
              totalUsage,
              collectedAttachments,
              `[NewCore:Loop] EXIT → workflow_list deterministic fallback, iterations=${iteration + 1}`
            )
          }

          const workflowTriggerNonRunFallback = continuingFromToolResults
            ? buildWorkflowTriggerNonRunFallbackWhenResponseOmitsClarification(
                result.content,
                lastCompletedToolResultsForFallback
              )
            : null
          if (workflowTriggerNonRunFallback) {
            return responseResult(
              config,
              iteration,
              workflowTriggerNonRunFallback,
              totalUsage,
              collectedAttachments,
              `[NewCore:Loop] EXIT → workflow_trigger non-run deterministic fallback, iterations=${iteration + 1}`
            )
          }

          const completedWorkflowListThisTurn =
            Array.isArray(lastCompletedToolResultsForFallback) &&
            lastCompletedToolResultsForFallback.some(result => result.name === 'workflow_list')
          if (
            continuingFromToolResults &&
            !workflowTriggerAfterListTextResponseRecovered &&
            !hasWorkflowTriggerResultForCurrentUserTurn(messages) &&
            completedWorkflowListThisTurn &&
            shouldRecoverWorkflowTriggerTextResponse(userRequestText, result.content)
          ) {
            workflowTriggerAfterListTextResponseRecovered = true
            logger.info(
              { component: 'Loop', iteration },
              'recovering workflow trigger text response after workflow_list'
            )
            messages.push({ role: 'assistant', content: result.content })
            messages.push(
              loopInjectedUserMessage(
                'The previous assistant response listed or described workflows but did not trigger the requested workflow. The user asked to run a named workflow recipe and provided any business inputs in the original message. Call workflow_trigger for that workflow with those inputs when it is available, or use workflow tools to prove it is not available. Do not only summarize workflow_list.'
              )
            )
            continue
          }

          if (
            !continuingFromToolResults &&
            !emptyResponseAfterToolResultsRecovered &&
            !emptyInitialResponseRecovered &&
            !workflowListTextResponseRecovered &&
            isWorkflowListIntent(userRequestText) &&
            tools.some(tool => tool.name === 'workflow_list') &&
            !hasToolResultForCurrentUserTurn(messages) &&
            !hasWorkflowListResultForCurrentUserTurn(messages)
          ) {
            workflowListTextResponseRecovered = true
            logger.info(
              { component: 'Loop', iteration },
              'recovering workflow list text response without tool call'
            )
            messages.push({ role: 'assistant', content: result.content })
            messages.push(
              loopInjectedUserMessage(
                'The previous assistant response answered a workflow recipe list request without calling workflow_list. Use workflow_list now and answer only from its current results. Do not reuse prior conversation workflow names.'
              )
            )
            continue
          }

          if (
            !continuingFromToolResults &&
            !workflowTriggerTextResponseRecovered &&
            !hasWorkflowTriggerResultForCurrentUserTurn(messages) &&
            shouldRecoverWorkflowTriggerTextResponse(userRequestText, result.content)
          ) {
            workflowTriggerTextResponseRecovered = true
            logger.info(
              { component: 'Loop', iteration },
              'recovering workflow trigger text response without tool call'
            )
            messages.push({ role: 'assistant', content: result.content })
            messages.push(
              loopInjectedUserMessage(
                'The previous assistant response did not trigger the requested workflow. The user asked to trigger a workflow recipe by name. Use workflow_trigger for the requested workflow and target when it is available, or use the workflow tools to prove that it is not available. Do not create or report a workflow run without workflow_trigger.'
              )
            )
            continue
          }

          if (
            !continuingFromToolResults &&
            !workflowArtifactTextResponseRecovered &&
            shouldRecoverWorkflowArtifactTextResponse(userRequestText)
          ) {
            workflowArtifactTextResponseRecovered = true
            logger.info(
              { component: 'Loop', iteration },
              'recovering workflow artifact text response without tool call'
            )
            messages.push({ role: 'assistant', content: result.content })
            messages.push(
              loopInjectedUserMessage(
                'The previous assistant response did not retrieve the requested workflow result artifact. The user asked for an existing workflow result artifact by name. Use workflow_result for the named workflow, or use the workflow tools to prove that it is unavailable. Do not invent artifact URLs, proof values, or run outputs.'
              )
            )
            continue
          }

          if (loopController.shouldAccept(result.content, iteration)) {
            return responseResult(
              config,
              iteration,
              result.content,
              totalUsage,
              collectedAttachments,
              `[NewCore:Loop] EXIT → response (text, ${result.content.length} chars), iterations=${iteration + 1}`
            )
          }

          const nudgeMsg = loopController.onTextRejected(result.content, iteration)
          if (nudgeMsg) {
            messages.push(
              { role: 'assistant', content: result.content },
              markLoopInjected(nudgeMsg)
            )
          }
          continue
        }

        case 'tool_calls': {
          const toolNames = result.calls.map(c => c.name)
          logger.info({ component: 'Loop', iteration, toolNames }, 'Tool calls selected')

          if (
            isWorkflowListIntent(userRequestText) &&
            result.calls.some(call => call.name === 'workflow_trigger')
          ) {
            const workflowListFallback = buildWorkflowToolSuccessFallbackResponse(
              lastCompletedToolResultsForFallback
            )
            if (workflowListFallback) {
              return responseResult(
                config,
                iteration,
                workflowListFallback,
                totalUsage,
                collectedAttachments,
                `[NewCore:Loop] EXIT → workflow_list deterministic fallback before mistaken trigger, iterations=${iteration + 1}`
              )
            }

            messages.push(
              loopInjectedUserMessage(
                'The user asked to list workflow recipes, not trigger one. Do not call workflow_trigger for workflow availability questions. Use workflow_list and answer only from its results.'
              )
            )
            continue
          }

          if (
            !workflowArtifactIntentRecovered &&
            isWorkflowArtifactIntent(userRequestText) &&
            result.calls.some(call => call.name === 'workflow_trigger')
          ) {
            workflowArtifactIntentRecovered = true
            messages.push(
              loopInjectedUserMessage(
                'The previous tool choice would trigger a workflow, but the user asked for an existing workflow result artifact. Do not call workflow_trigger for result, artifact, output, or download requests. Use workflow_result for the named workflow.'
              )
            )
            continue
          }

          messages.push({
            role: 'assistant',
            content: result.content ?? '',
            tool_calls: result.calls,
            reasoning_content: result.reasoning_content,
          })

          for (const message of messages) {
            for (const part of message.contentParts ?? []) {
              if (part.type === 'image' && part.source?.kind !== 'gfs')
                config.visualInput?.budget.observeExternalImage(part.data)
            }
          }
          const { toolResults, pendingApproval, cancelled, stopTurn } = await executeToolCalls(
            result.calls,
            config,
            iteration,
            messages,
            result.content,
            result.usage
          )
          if (cancelled) {
            appendToolResults(
              messages,
              toolResults,
              collectedAttachments,
              config.imageSourceIdentity === true
            )
            return { type: 'cancelled', reason: 'signal_aborted' }
          }
          if (pendingApproval) {
            if (collectedAttachments.length > 0) {
              pendingApproval.attachments = [
                ...(pendingApproval.attachments ?? []),
                ...collectedAttachments,
              ]
            }
            return { type: 'need_approval', approval: projectGfsApproval(pendingApproval) }
          }
          if (stopTurn) {
            // A15 U1 — a trusted tool ended the turn: keep the batch's results
            // and attachments, make no further model call.
            appendToolResults(
              messages,
              toolResults,
              collectedAttachments,
              config.imageSourceIdentity === true
            )
            return turnStopResult(config, iteration + 1, stopTurn.message, collectedAttachments)
          }

          const workflowFallbackResults = toolResults.filter(
            tr => tr.is_error !== true && isWorkflowSuccessFallbackToolName(tr.name)
          )
          if (workflowFallbackResults.length > 0) {
            lastCompletedToolResultsForFallback = workflowFallbackResults
          }

          const workflowTriggerImmediateFallback =
            buildWorkflowTriggerImmediateFallbackResponse(toolResults)
          if (workflowTriggerImmediateFallback) {
            return responseResult(
              config,
              iteration,
              workflowTriggerImmediateFallback,
              totalUsage,
              collectedAttachments,
              `[NewCore:Loop] EXIT → workflow_trigger deterministic fallback, iterations=${iteration + 1}`
            )
          }

          const workflowToolFailureResponse = buildWorkflowToolFailureResponse(toolResults)
          if (workflowToolFailureResponse) {
            return responseResult(
              config,
              iteration,
              workflowToolFailureResponse,
              totalUsage,
              collectedAttachments,
              `[NewCore:Loop] EXIT → workflow tool failure response, iterations=${iteration + 1}`
            )
          }

          appendToolResults(
            messages,
            toolResults,
            collectedAttachments,
            config.imageSourceIdentity === true
          )
          lastToolResults = toolResults
          messages = await manageMessagesForIteration(config, messages, iteration, tools)
          validateToolLinkages(messages)
          continue
        }

        case 'need_approval':
          logger.info({ component: 'Loop', iterations: iteration + 1 }, 'Loop requires approval')
          return { type: 'need_approval', approval: projectGfsApproval(result.approval) }
        case 'error': {
          const recovery = handleLoopErrorRecovery({
            error: result.error,
            continuingFromToolResults,
            emptyResponseAfterToolResultsRecovered,
            emptyInitialResponseRecovered,
            workflowTriggerTextResponseRecovered,
            lastCompletedToolResultsForFallback,
            messages,
            iteration,
            userRequestText,
          })

          if (recovery.type === 'continue') {
            emptyResponseAfterToolResultsRecovered =
              recovery.emptyResponseAfterToolResultsRecovered ??
              emptyResponseAfterToolResultsRecovered
            emptyInitialResponseRecovered =
              recovery.emptyInitialResponseRecovered ?? emptyInitialResponseRecovered
            workflowTriggerTextResponseRecovered =
              recovery.workflowTriggerTextResponseRecovered ?? workflowTriggerTextResponseRecovered
            messages = recovery.messages
            logger.info({ component: 'Loop', iteration }, 'recovering from LLM error')
            continue
          }

          if (recovery.type === 'response') {
            return responseResult(
              config,
              iteration,
              recovery.content,
              totalUsage,
              collectedAttachments,
              recovery.logMessage
            )
          }

          logger.error(
            { component: 'Loop', iterations: iteration + 1, err: result.error },
            'Loop failed'
          )
          return { type: 'error', error: result.error }
        }
      }
    }

    return exhaustionResult(
      config,
      maxIterations,
      loopController.onExhaustion(maxIterations),
      collectedAttachments
    )
  } finally {
    config.onAttachments?.(collectedAttachments)
  }
}