Skip to content

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

TypeScript
10.6 KB
Raw Blame
import type { TaskBrakeConfig } from '../../budget/taskBrake'
import type { ProgressReporter } from '../../progress/types.js'
import type { VisualInputContext } from '../../visualInput/policy'
import type { ToolLaneGuardrail } from '../guardrails'
import {
  AgentEventEmitter,
  ContextManageOptions,
  ContextManager,
  LoopController,
  ReasoningPort,
  Safety,
  ToolOutputProcessor,
  ToolRegistry,
} from '../interfaces'
import { DefaultToolOutputProcessor } from '../safety/toolOutputProcessor'
import type { SpilloverStorage } from '../spillover'
import { Attachment, ChatMessage, Conversation, PendingApproval, ToolDefinition } from '../types'

/**
 * Configuration for the tool-use loop.
 *
 * All extension hooks have passthrough defaults. Override any subset.
 */
export interface LoopConfig {
  /** Preserve source identities only for chains whose request contract needs them. */
  imageSourceIdentity?: boolean
  // Core dependencies
  reasoning: ReasoningPort
  toolRegistry: ToolRegistry
  safety: Safety
  events: AgentEventEmitter

  /**
   * P.5: the Conversation that owns this loop execution. Required because the
   * context manager and downstream plans (T1.4 anti-thrash, T2.2 prompt cache)
   * need per-session state. Plumbed in from `TaskExecutor.buildLoopConfig()`.
   * Required (not optional) on purpose: making it optional would allow a
   * silent bypass where compaction state never gets written back.
   */
  conversation: Conversation

  // Extension points
  loopController: LoopController
  contextManager: ContextManager
  toolOutputProcessor: ToolOutputProcessor
  /** Synchronous estimate of the final model-visible tool message. Never network. */
  measureToolMessage?: (message: ChatMessage) => number

  /**
   * The system prompt `reasoning` sends with a request that presents `tools`,
   * including the daily-log snapshot. The loop calls it with the list it
   * presents on each iteration and hands the text to `contextManager` so
   * pressure counts it (R9-14, R21-1). Set by `TaskExecutor.buildLoopConfig()`;
   * absent means the caller sends no system prompt of its own.
   */
  systemPromptFor?: (tools: ToolDefinition[]) => string

  /**
   * Tool-lane guardrail (spec §6). Absent = no guardrails configured = today's
   * behavior (no-config compatibility, spec §5). Consulted in `executeToolCalls`
   * before approval/execution: deny → bounded error, ask → suspension,
   * allow/no_decision → the existing approval path.
   */
  guardrails?: ToolLaneGuardrail

  /**
   * Execution mode for the guardrail lane (spec §6.3): `unattended` when there is
   * no human to answer an approval (e.g. a cron/autonomous task). A guardrail
   * `ask` in unattended mode fails safe to deny (`approval_unavailable`).
   * Absent → treated as interactive.
   */
  executionMode?: 'interactive' | 'unattended'

  // Progress reporting
  progressReporter?: ProgressReporter

  // Limits
  maxIterations: number
  /** Retain trusted artifacts at tool completion and loop exit; consumers deduplicate. */
  onAttachments?: (attachments: Attachment[]) => void
  toolTimeout: number // ms per tool execution
  toolProgressInterval: number // ms between tool_progress snapshots; 0 disables streaming

  /** Optional abort signal. When aborted, the loop exits at the next checkpoint. */
  abortSignal?: AbortSignal
  visualInput?: VisualInputContext

  /**
   * P2 token budgets — per-task emergency brake (§5.2). When the P1 pre-task
   * budget check returned a per-task cap, `TaskExecutor` plumbs the caps + the
   * active price + a baseline snapshot of the conversation's lifetime token
   * counters (taken at task start) here. Before each LLM call the loop measures
   * the DELTA spent by THIS task (current counters − baseline, read off
   * `config.conversation`) and exits cleanly when it exceeds the cap.
   *
   * Absent when budgets are off or no per-task cap matched → the brake check is
   * a total no-op (a single short-circuiting `if`, zero network, zero overhead).
   */
  taskBrake?: TaskBrakeConfig

  /**
   * IronClaw invariant #1 (P.3): when true, PressureContextManager.manage()
   * is skipped for this loop run. Set by TaskExecutor.buildLoopConfig() when
   * the conversation has a pending_approval at config-build time.
   *
   * Fires both at suspend (the iteration that returns need_approval) and on
   * resume (the iteration that follows resumeAfterApproval). At suspend the
   * snapshot is frozen — compaction mid-iteration would mutate the messages
   * and invalidate the snapshot. On resume the messages reconstructed from
   * context_snapshot + completed_results MUST be passed verbatim to the LLM
   * or validateToolLinkages would tear the tool linkages.
   *
   * Emits `compaction:skipped` with `reason='pending_approval'` so observers
   * (activity hub, metrics) see the skipped path.
   */
  skipContextManager?: boolean

  /**
   * T1.5 — Tool-result spillover. When set, `executeSingleTool` calls
   * `spilloverStorage.maybePersist(...)` on every non-error output of a tool
   * that does not declare `spilloverExempt()` (`clerum__spillover_read` and
   * `clerum__attachment_read` do). Outputs over the threshold are persisted
   * out-of-band and the `tool` message ships a `SpilloverSummary` in
   * `content` plus the URI on the lateral `spillover_ref` field.
   *
   * When undefined, `executeSingleTool` returns inline content as before
   * (1:1 with the pre-T1.5 behavior).
   */
  spilloverStorage?: SpilloverStorage
  /**
   * T1.5 — Owner of any spilled blob. Required when `spilloverStorage` is set
   * so the URI carries the correct `<task_id>` segment. Plumbed from
   * `TaskExecutor.taskId`.
   */
  taskId?: string

  /**
   * F3 (dynamic-tool-loading) — context the `clerum__tool_call` bridge intercept
   * needs in `executeToolCalls`. Present whenever the 3 bridge tools are
   * registered: MCP discovery with an `McpManager` wired, or native `auto`
   * (#1003, with or without an `McpManager`). When undefined, the intercept is
   * inert: `clerum__tool_call` falls through to the native safety-net tool
   * (which errors), and there is no auto-recover scope gate.
   *
   * - `nativeNames` — the exact set of native tool names (incl. the 3 bridges).
   *   Used to reject recursion (LOCKED #11) and to distinguish native from
   *   deferrable MCP names (membership, NOT a string heuristic).
   * - `getDeferrableCatalogNames` — returns the live set of deferrable MCP tool
   *   names (`McpManager.getAllTools()` names, minus natives; empty without an
   *   `McpManager`). Re-derived per call so it tracks servers
   *   connecting/disconnecting (stateless; the scope gate, LOCKED #7 /
   *   Critical #7, rejects out-of-catalog names).
   * - `nativeTargets` — native `auto` (#1003): `clerum__tool_call` may target a
   *   native tool. False keeps the pre-#1003 rejection of native targets.
   */
  bridge?: {
    nativeNames: Set<string>
    getDeferrableCatalogNames: () => Set<string>
    nativeTargets: boolean
  }
}

/**
 * Default loop controller: all hooks are passthroughs.
 */
export class DefaultLoopController implements LoopController {
  shouldAccept(_content: string, _iteration: number): boolean {
    return true // Always accept text responses
  }

  onTextRejected(_content: string, _iteration: number): ChatMessage | null {
    return null // No nudge
  }

  beforeTool(
    _toolName: string,
    _params: Record<string, unknown>
  ): 'proceed' | 'skip' | { type: 'suspend'; approval: PendingApproval } {
    return 'proceed' // Always proceed
  }

  onExhaustion(iteration: number): string {
    return (
      `I've reached the maximum number of tool-use iterations (${iteration}). ` +
      `Please try a more specific request.`
    )
  }

  async refreshTools(currentTools: ToolDefinition[]): Promise<ToolDefinition[]> {
    return currentTools // No refresh
  }
}

/**
 * Default context manager: passthrough (no compaction).
 */
export class DefaultContextManager implements ContextManager {
  manage(
    messages: ChatMessage[],
    _conversation: Conversation,
    _options?: ContextManageOptions
  ): ChatMessage[] {
    return messages // No compaction
  }
}

/**
 * Check whether an object implements the full LoopController interface.
 */
function isFullLoopController(obj: Partial<LoopController>): obj is LoopController {
  return (
    typeof obj.shouldAccept === 'function' &&
    typeof obj.onTextRejected === 'function' &&
    typeof obj.beforeTool === 'function' &&
    typeof obj.onExhaustion === 'function' &&
    typeof obj.refreshTools === 'function'
  )
}

/**
 * Build a complete LoopConfig with sensible defaults.
 * Only override what you need.
 *
 * When a full LoopController implementation is passed (e.g. ApprovalController),
 * it is used directly to preserve `this` context for class-based controllers.
 */
export function buildLoopConfig(params: {
  reasoning: ReasoningPort
  toolRegistry: ToolRegistry
  safety: Safety
  events: AgentEventEmitter
  conversation: Conversation
  loopController?: Partial<LoopController>
  contextManager?: ContextManager
  toolOutputProcessor?: ToolOutputProcessor
  progressReporter?: ProgressReporter
  maxIterations?: number
  toolTimeout?: number
  toolProgressInterval?: number
  guardrails?: ToolLaneGuardrail
}): LoopConfig {
  const dc = new DefaultLoopController()

  // If a full LoopController is provided, use it directly to preserve `this` context.
  // Otherwise, build a plain object with per-method fallbacks.
  let resolvedController: LoopController
  if (params.loopController && isFullLoopController(params.loopController)) {
    resolvedController = params.loopController
  } else {
    const partial = params.loopController
    resolvedController = {
      shouldAccept: partial?.shouldAccept?.bind(partial) ?? dc.shouldAccept.bind(dc),
      onTextRejected: partial?.onTextRejected?.bind(partial) ?? dc.onTextRejected.bind(dc),
      beforeTool: partial?.beforeTool?.bind(partial) ?? dc.beforeTool.bind(dc),
      onExhaustion: partial?.onExhaustion?.bind(partial) ?? dc.onExhaustion.bind(dc),
      refreshTools: partial?.refreshTools?.bind(partial) ?? dc.refreshTools.bind(dc),
    }
  }

  return {
    reasoning: params.reasoning,
    toolRegistry: params.toolRegistry,
    safety: params.safety,
    events: params.events,
    conversation: params.conversation,
    loopController: resolvedController,
    contextManager: params.contextManager ?? new DefaultContextManager(),
    toolOutputProcessor:
      params.toolOutputProcessor ?? new DefaultToolOutputProcessor(params.safety),
    guardrails: params.guardrails,
    progressReporter: params.progressReporter,
    maxIterations: params.maxIterations ?? 10,
    toolTimeout: params.toolTimeout ?? 60000,
    toolProgressInterval: params.toolProgressInterval ?? 30000,
  }
}