Struct LoopDriver 

pub struct LoopDriver<S>
where
    S: ModelSession,
{ /* private fields */ }

The runtime driver that advances the agent loop step by step.

Obtained from Agent::start with the builder’s preloaded transcript and pending-input queue baked in. The typical usage pattern is:

1. Call next to advance the loop.
2. Handle the returned LoopStep:
   • LoopStep::Finished – the turn completed, inspect the result.
   • LoopStep::Interrupt – resolve the interrupt via the bound Pending* handle, then call next again.

Example

use agentkit_core::{Item, ItemKind};
use agentkit_loop::{LoopDriver, LoopStep};

let step = driver.next().await?;
match step {
    LoopStep::Finished(result) => println!("Done: {:?}", result.finish_reason),
    LoopStep::Interrupt(interrupt) => {
        // Resolve via the pending handle, then call next() again.
        println!("Interrupted: {interrupt:?}");
    }
}

Implementations

impl<S> LoopDriver<S>

where S: ModelSession,

pub fn submit_input(&mut self, input: Vec<Item>) -> Result<(), LoopError>

Internal entry point for buffering user input. Reachable only via InputRequest::submit (resolves an AwaitingInput interrupt, including the very first one after Agent::start) and ToolRoundInfo::submit (interjects between tool rounds). Prior transcript items — the passive starting state of a session — are preloaded via AgentBuilder::transcript; an opening user turn for one-shot calls is preloaded via AgentBuilder::input. New input after start-up always flows through one of the typed submit handles.

pub fn set_next_turn_cache( &mut self, cache: PromptCacheRequest, ) -> Result<(), LoopError>

Override the prompt cache request for the next model turn.

The override is consumed the next time the driver starts a model turn. Session-level defaults still apply to later turns.

pub fn resolve_approval_for( &mut self, call_id: ToolCallId, decision: ApprovalDecision, ) -> Result<(), LoopError>

Resolve a pending LoopInterrupt::ApprovalRequest.

After calling this, invoke next to continue the loop. If the decision is ApprovalDecision::Approve the tool call executes; if denied, an error result is fed back to the model.

Errors

Returns LoopError::InvalidState if no approval is pending.

pub fn resolve_approval_for_with_patched_input( &mut self, call_id: ToolCallId, input: Value, ) -> Result<(), LoopError>

Resolve a pending LoopInterrupt::ApprovalRequest with a patched input that replaces the model’s original tool arguments.

Equivalent to calling [resolve_approval_for] with ApprovalDecision::Approve except the tool sees input instead of what the model emitted. The transcript still records the model’s original call.

Errors

Returns LoopError::InvalidState if no approval is pending for call_id.

pub fn resolve_approval( &mut self, decision: ApprovalDecision, ) -> Result<(), LoopError>

Resolve a pending LoopInterrupt::ApprovalRequest when exactly one approval is outstanding.

pub fn cancel_pending_approval_for( &mut self, call_id: ToolCallId, ) -> Result<(), LoopError>

Cancel a pending approval interrupt for a specific tool call.

This clears the blocking approval and appends an error tool result so the transcript remains provider-valid if the host continues the turn.

pub async fn cancel_pending_approvals( &mut self, ) -> Result<Option<LoopStep>, LoopError>

Cancel every pending approval interrupt.

This is useful when the host cancels the containing turn rather than an individual approval prompt. Each pending approval is resolved as denied and receives an error tool result so the transcript remains valid.

pub fn snapshot(&self) -> LoopSnapshot

Take a read-only snapshot of the driver’s current transcript and input queue.

pub async fn next(&mut self) -> Result<LoopStep, LoopError>

Advance the loop by one step.

This is the main method for driving the agent. It processes pending interrupt resolutions, consumes queued input, starts a model turn, executes tool calls, and returns once the turn finishes or an interrupt occurs.

If no input is queued and no interrupt is pending, returns LoopStep::Interrupt(LoopInterrupt::AwaitingInput(..)). This is the steady state after Agent::start when no input was preloaded via AgentBuilder::input: the prior transcript loaded via AgentBuilder::transcript is passive, so the first call surfaces AwaitingInput and waits for the host to supply input via InputRequest::submit before any model turn is dispatched. If input was preloaded, the first call dispatches the model directly.

Errors

Returns LoopError::InvalidState if called while an unresolved interrupt is pending, or propagates provider / tool / compaction errors.