Enum LoopEvent 

#[non_exhaustive]
pub enum LoopEvent {
    TextDelta(String),
    ReasoningDelta(String),
    ToolCallStart {
        index: u32,
        id: String,
        name: String,
    },
    ToolCallDelta {
        index: u32,
        json_chunk: String,
    },
    ToolCallComplete {
        index: u32,
        call: ToolCall,
    },
    Usage(Usage),
    IterationStart {
        iteration: u32,
        message_count: usize,
    },
    ToolExecutionStart {
        call_id: String,
        tool_name: String,
        arguments: Value,
    },
    ToolExecutionEnd {
        call_id: String,
        tool_name: String,
        result: ToolResult,
        duration: Duration,
    },
    ToolResultProcessed {
        tool_name: String,
        original_tokens: u32,
        processed_tokens: u32,
    },
    ToolResultExtracted {
        tool_name: String,
        original_tokens: u32,
        extracted_tokens: u32,
    },
    ToolResultCached {
        tool_name: String,
        original_tokens: u32,
        summary_tokens: u32,
    },
    ObservationsMasked {
        masked_count: usize,
        tokens_saved: u32,
    },
    LoopDetected {
        tool_name: String,
        consecutive_count: u32,
        action: LoopAction,
    },
    Done(ToolLoopResult),
}

Unified event emitted during tool loop execution.

LoopEvent merges LLM streaming events (text deltas, tool call fragments) with loop-level lifecycle events (iteration boundaries, tool execution progress) into a single stream. This gives consumers a complete, ordered view of everything happening inside the loop.

The stream terminates with Done carrying the final ToolLoopResult.

Example

use llm_stack::tool::{tool_loop_stream, ToolLoopConfig, LoopEvent};
use futures::StreamExt;
use std::sync::Arc;

let mut stream = tool_loop_stream(provider, registry, params, ToolLoopConfig::default(), Arc::new(()));
while let Some(event) = stream.next().await {
    match event.unwrap() {
        LoopEvent::TextDelta(text) => print!("{text}"),
        LoopEvent::IterationStart { iteration, .. } => {
            println!("\n--- Iteration {iteration} ---");
        }
        LoopEvent::ToolExecutionStart { tool_name, .. } => {
            println!("[calling {tool_name}...]");
        }
        LoopEvent::ToolExecutionEnd { tool_name, duration, .. } => {
            println!("[{tool_name} completed in {duration:?}]");
        }
        LoopEvent::Done(result) => {
            println!("\nDone: {:?}", result.termination_reason);
            break;
        }
        _ => {}
    }
}

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

TextDelta(String)

A fragment of the model’s text output.

ReasoningDelta(String)

A fragment of the model’s reasoning (chain-of-thought) output.

ToolCallStart

Announces that a new tool call has started.

Fields

index: u32

Zero-based index identifying this call when multiple tools are invoked in parallel.

id: String

Provider-assigned identifier linking start → deltas → complete.

name: String

The name of the tool being called.

ToolCallDelta

A JSON fragment of the tool call’s arguments.

Fields

index: u32

The tool-call index this delta belongs to.

json_chunk: String

A chunk of the JSON arguments string.

ToolCallComplete

The fully assembled tool call, ready to execute.

Fields

index: u32

The tool-call index this completion corresponds to.

call: ToolCall

The complete, parsed tool call.

Usage(Usage)

Token usage information for this LLM call.

IterationStart

A new iteration of the tool loop is starting.

Fields

iteration: u32

The iteration number (1-indexed).

message_count: usize

Number of messages in the conversation so far.

ToolExecutionStart

About to execute a tool.

When parallel_tool_execution is true, events arrive in completion order (whichever tool finishes first), not the order the LLM listed the calls. Use call_id to correlate start/end pairs.

Fields

call_id: String

The tool call ID from the LLM.

tool_name: String

Name of the tool being called.

arguments: Value

Arguments passed to the tool.

ToolExecutionEnd

Tool execution completed.

When parallel_tool_execution is true, events arrive in completion order. Use call_id to correlate with the corresponding ToolExecutionStart.

Fields

call_id: String

The tool call ID from the LLM.

tool_name: String

Name of the tool that was called.

result: ToolResult

The result from the tool.

duration: Duration

How long the tool took to execute.

ToolResultProcessed

A tool result was post-processed (compressed, truncated, etc.).

Emitted when a ToolResultProcessor modifies a tool’s output before it enters the conversation context. Use this for monitoring compression ratios and token savings.

Fields

tool_name: String

Name of the tool whose result was processed.

original_tokens: u32

Estimated token count of the original output.

processed_tokens: u32

Estimated token count after processing.

ToolResultExtracted

A tool result was semantically extracted (condensed by an LLM).

Emitted when a ToolResultExtractor condenses a large tool result into task-relevant content using an async extraction call (typically a fast/cheap LLM like Haiku).

Fields

tool_name: String

Name of the tool whose result was extracted.

original_tokens: u32

Estimated token count before extraction.

extracted_tokens: u32

Estimated token count after extraction.

ToolResultCached

A tool result was cached out-of-context.

Emitted when a ToolResultCacher stores an oversized result externally and replaces it with a compact summary.

Fields

tool_name: String

Name of the tool whose result was cached.

original_tokens: u32

Estimated token count of the content that was cached.

summary_tokens: u32

Estimated token count of the summary that replaced it.

ObservationsMasked

Old tool results were masked before an LLM call.

Emitted when observation masking replaces old tool results with compact placeholders to reduce context size. The full results may still be available in the result cache.

Fields

masked_count: usize

Number of tool results masked in this pass.

tokens_saved: u32

Estimated total tokens saved by masking.

LoopDetected

A tool call loop was detected.

Emitted when the same tool is called with identical arguments for threshold consecutive times. Only emitted when LoopDetectionConfig is configured.

Fields

tool_name: String

Name of the tool being called repeatedly.

consecutive_count: u32

Number of consecutive identical calls detected.

action: LoopAction

The action being taken in response.

Done(ToolLoopResult)

The loop has finished. Carries the final ToolLoopResult with the accumulated response, usage, iteration count, and termination reason.

Trait Implementations

impl Clone for LoopEvent

fn clone(&self) -> LoopEvent

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for LoopEvent

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.