Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
import type { TaskBrakeTrip } from '../../budget/taskBrake'
import { logger } from '../../logger'
import { clerumCompactionTotal } from '../extensions/contextManager'
import type {
Attachment,
ChatMessage,
LoopResult,
ReasoningContext,
RespondResult,
TokenUsage,
ToolDefinition,
ToolResult,
} from '../types'
import type { LoopConfig } from './loopConfig'
import { isRetryableLlmTransportError } from './toolUseLoopIntentRecovery'
const LLM_TRANSPORT_RETRY_DELAY_MS = 350
export async function manageMessagesForIteration(
config: LoopConfig,
messages: ChatMessage[],
iteration: number,
tools: ToolDefinition[],
logCompaction = false
): Promise<ChatMessage[]> {
// IronClaw invariant #1 (P.3 §4.1): if the conversation has a pending_approval,
// the snapshot frozen at suspend time is the source of truth. Compaction here
// would mutate `messages` and invalidate the snapshot. Skip silently and emit a
// typed event for observability. `logCompaction` doubles as the pre-LLM (true)
// vs post-tool (false) phase discriminator at the two call sites.
if (config.skipContextManager) {
config.events.emit({
type: 'compaction:skipped',
data: {
reason: 'pending_approval',
iteration,
phase: logCompaction ? 'pre_llm' : 'post_tool',
},
timestamp: new Date(),
})
// T1.4 / P.3 cross-plan: the loop owns the `skipped:pending_approval` counter
// increment (cross-plan discovery 2026-05-22). The manager's own outcomes
// (`ok`/`thrashing`) are mutually exclusive with this one.
clerumCompactionTotal.inc({ tier: 'none', outcome: 'skipped:pending_approval' })
return messages
}
const beforeCount = messages.length
// P.5: the canonical signature requires the conversation so the manager's
// defensive guard and tier selection can see `pending_approval`/state.
// R21-1: pressure counts the tools this iteration presents, which in Codex
// discovery mode or under the bridge latch exclude the deferred MCP schemas.
const managed = await config.contextManager.manage(messages, config.conversation, {
tools,
systemPrompt: config.systemPromptFor?.(tools),
})
if (managed.length < beforeCount) {
if (logCompaction) {
logger.debug({ beforeCount, afterCount: managed.length, iteration }, 'Context compacted')
}
config.events.emit({
type: 'context:compacted',
data: {
beforeCount,
afterCount: managed.length,
droppedCount: beforeCount - managed.length,
iteration,
},
timestamp: new Date(),
})
}
return managed
}
export async function callReasoningForIteration(
config: LoopConfig,
context: ReasoningContext,
lastToolResults: ToolResult[] | null,
iteration: number
): Promise<{ result: RespondResult; continuingFromToolResults: boolean }> {
const callStartedAt = Date.now()
const heartbeatInterval = config.progressReporter
? setInterval(() => {
try {
config.progressReporter!.reportLlmInProgress({
taskId: '',
iteration,
elapsedMs: Date.now() - callStartedAt,
})
} catch {
// Reporter errors are non-fatal.
}
}, 10_000)
: null
try {
const continuingFromToolResults = Boolean(lastToolResults)
const callReasoning = async (): Promise<RespondResult> => {
if (lastToolResults) {
logger.debug(
{ iteration, resultCount: lastToolResults.length },
'Continuing with tool results'
)
return config.reasoning.continueWithToolResults(context, lastToolResults)
}
logger.debug({ iteration }, 'Requesting model response')
return config.reasoning.respondWithTools(context)
}
let result = await callReasoning()
if (
result.type === 'error' &&
isRetryableLlmTransportError(result.error) &&
!config.abortSignal?.aborted
) {
logger.warn({ iteration, err: result.error }, 'Retrying model transport failure')
await delay(LLM_TRANSPORT_RETRY_DELAY_MS, config.abortSignal)
if (!config.abortSignal?.aborted) {
result = await callReasoning()
}
}
// Latency attribution — one event per reasoning roundtrip (covers the
// single transport retry above when it fires). Consumed by the
// TaskExecutor [TurnTiming] recorder; with no subscriber this is a no-op.
config.events.emit({
type: 'llm:completed',
data: { iteration, durationMs: Date.now() - callStartedAt },
timestamp: new Date(),
})
return { result, continuingFromToolResults }
} finally {
if (heartbeatInterval) clearInterval(heartbeatInterval)
}
}
async function delay(ms: number, signal?: AbortSignal): Promise<void> {
if (signal?.aborted) return
await new Promise<void>(resolve => {
const timeout = setTimeout(resolve, ms)
signal?.addEventListener(
'abort',
() => {
clearTimeout(timeout)
resolve()
},
{ once: true }
)
})
}
export function responseResult(
config: LoopConfig,
iteration: number,
content: string,
usage: TokenUsage,
attachments: Attachment[],
logMessage: string
): LoopResult {
logger.debug({ message: logMessage }, 'Loop response')
config.events.emit({
type: 'loop:completed',
data: { iteration, resultType: 'response' },
timestamp: new Date(),
})
return {
type: 'response',
content,
usage,
attachments: attachments.length > 0 ? attachments : undefined,
}
}
/**
* User-facing message returned when the P2 per-task budget brake trips. The
* brake fires BETWEEN iterations (before the next LLM call), so any work
* already produced (tool results, attachments) is preserved and returned
* alongside this notice.
*/
export const TASK_BUDGET_BRAKE_MESSAGE =
'This task reached its per-task usage budget and was stopped before the next ' +
'model call. Any results produced so far are included above.'
/**
* P2 token budgets (§5.2) — terminate the loop cleanly when the per-task brake
* trips. Modeled on `exhaustionResult` (a graceful "limit hit" exit that
* preserves collected work) rather than `cancelled` (which would scrub the
* turn): the task completes normally with the brake notice + any attachments,
* so the work done up to the cut is not lost.
*/
export function taskBrakeResult(
config: LoopConfig,
iteration: number,
trip: TaskBrakeTrip,
attachments: Attachment[]
): LoopResult {
logger.info(
{ unit: trip.unit, spent: trip.spent, limit: trip.limit, iteration },
'Task budget brake reached'
)
config.events.emit({
type: 'loop:completed',
data: { iteration, resultType: 'task_brake', brakeUnit: trip.unit },
timestamp: new Date(),
})
return {
type: 'exhaustion',
reason: 'task_budget',
message: TASK_BUDGET_BRAKE_MESSAGE,
iterations: iteration,
attachments: attachments.length > 0 ? attachments : undefined,
}
}
/**
* A15 U1 — a trusted tool result ended the turn (`ToolResult.stopTurn`). Like
* the task brake, the task completes normally: `message` is the reply and the
* attachments collected so far are kept. No further model call is made.
*/
export function turnStopResult(
config: LoopConfig,
iterations: number,
message: string,
attachments: Attachment[]
): LoopResult {
logger.info({ iterations }, 'Turn stopped by a tool result')
config.events.emit({
type: 'loop:completed',
data: { iteration: iterations, resultType: 'turn_stop' },
timestamp: new Date(),
})
return {
type: 'exhaustion',
reason: 'turn_stop',
message,
iterations,
attachments: attachments.length > 0 ? attachments : undefined,
}
}
export function exhaustionResult(
config: LoopConfig,
maxIterations: number,
message: string,
attachments: Attachment[]
): LoopResult {
logger.info({ iterations: maxIterations }, 'Loop iteration limit reached')
config.events.emit({
type: 'loop:completed',
data: { iteration: maxIterations, resultType: 'exhaustion' },
timestamp: new Date(),
})
return {
type: 'exhaustion',
reason: 'iteration_limit',
message,
iterations: maxIterations,
attachments: attachments.length > 0 ? attachments : undefined,
}
}