Struct CompletionRunner 

pub struct CompletionRunner { /* private fields */ }

A iteration style executor for completion.

Implementations

impl CompletionRunner

pub fn unbound(self) -> Self

Enables unbound mode for the completion runner.

pub fn reserve_chat_history(self, chat_history: Vec<Message>) -> Self

Reserves the chat history for the completion runner.

pub fn append_chat_history(&mut self, messages: Vec<Message>)

Appends messages to the chat history.

pub fn chat_history_mut(&mut self) -> &mut [Message]

Returns mutable access to the accumulated chat history messages.

This allows callers to update already recorded messages in place while preserving message order. Use Self::append_chat_history to add new messages.

pub fn is_done(&self) -> bool

Returns whether the completion has finished.

pub fn is_idle(&self) -> bool

Returns whether the completion is idle, meaning it has no pending tasks.

pub fn no_pending_tool_calls(&self) -> bool

Returns whether there are no pending tool calls.

pub fn turns(&self) -> usize

Returns the number of turns executed.

pub fn ctx(&self) -> &AgentCtx

Returns the agent context driving this completion.

pub fn req(&self) -> &CompletionRequest

Get the original completion request.

pub fn model(&self) -> &Model

Get the model used for this completion.

pub fn chat_history(&self) -> &Vec<Message>

Returns the chat history of the completion so far.

pub fn total_usage(&self) -> &Usage

Get the total usage accumulated so far, including all intermediate steps.

pub fn current_usage(&self) -> &Usage

Get the usage from the most recent turn.

pub fn tools_usage(&self) -> &HashMap<String, Usage>

Returns the accumulated usage of the tools so far.

pub fn last_output(&self) -> Option<&AgentOutput>

Returns the most recent non-final output, when one is available.

pub fn merge_discovered_tools(&self) -> Option<bool>

Returns the discovered-tool merge policy.

Some(true) forces discovered tool definitions into later requests, Some(false) keeps them only in discovery-tool output context, and None lets the runner probe whether the current model needs request-side merging.

pub fn set_unbound(&mut self, unbound: bool)

Enables or disables unbound mode.

In unbound mode, reaching an idle boundary does not finalize the runner. The step still returns its latest AgentOutput, and later calls to Self::next return Ok(None) while the runner is idle until new input is queued via Self::follow_up or Self::steer. Terminal failures still finalize the runner.

This mode is primarily useful when driving CompletionRunner directly. A CompletionStream still terminates permanently after it yields None, per the Stream contract.

pub fn set_merge_discovered_tools( &mut self, merge_discovered_tools: Option<bool>, )

Sets the discovered-tool merge policy.

Some(true) adds definitions returned by discovery tools such as tools_search and tools_select to later request tool lists, and compacts discovery output kept in conversation context. Some(false) keeps discovered schemas only in discovery-tool output context. None enables the repeated-selection probe so the runner can discover whether the current model needs request-side merging.

pub fn set_allowed_callables(&mut self, allowed: Option<BTreeSet<String>>)

Restricts which callables (tools, agents, subagents) the runner may execute, regardless of the names the model emits.

None (the default) allows any registered callable. Some(set) permits only the lowercased names in set, plus any tool the model legitimately discovered through an allowed discovery tool (tracked in discovered_tools). An empty set therefore rejects every tool/agent call.

This is the enforcement point for subagent tool whitelists: constraining the definitions sent to the model is not sufficient, because the runner dispatches by name against the whole engine.

pub fn with_allowed_callables(self, allowed: Option<BTreeSet<String>>) -> Self

Builder variant of Self::set_allowed_callables.

pub fn steer(&mut self, message: impl Into<ContentPart>)

Queue a steering message to interrupt the agent mid-run. Delivered after current tool execution, skips remaining tools. No effect if the completion has finished.

pub fn steer_content(&mut self, content: Vec<ContentPart>)

Queue a steering message with multiple content parts to interrupt the agent mid-run.

pub fn steering_message_iter(&self) -> Iter<'_, ContentPart>

Returns the iter over the queued steering message content parts.

pub fn follow_up(&mut self, message: impl Into<ContentPart>)

Queue a follow-up message for the next safe user turn. Delivered with the current pending tool-call results when they finish, or at the next idle boundary when no tools are pending. Steering still takes priority. No effect if the completion has finished.

pub fn follow_up_content(&mut self, content: Vec<ContentPart>)

Queue a follow-up message with multiple content parts for the next safe user turn.

pub fn follow_up_message_iter(&self) -> Iter<'_, ContentPart>

Returns the iter over the queued follow-up message content parts.

pub fn discard_in_flight_request(&mut self)

Drops the current in-flight request after a transport-level model failure.

This keeps accumulated chat history, usage, artifacts, and queued follow-up messages, but removes request content that was already sent to the failed completion. Long-lived callers can use this before processing newly queued input, so stale tool results are not resent. Pending, unexecuted tool calls are closed in the visible history before their raw provider history is pruned.

pub fn prune_req_raw_history(&mut self)

Prunes completed tool interactions from the accumulated provider raw history.

req.raw_history holds provider-native message JSON (OpenAI, Anthropic, and Gemini shapes all differ), so pruning rewrites the raw values in place rather than round-tripping through Message, which would drop or corrupt provider-specific formats. Tool-call requests, their results, and items left without meaningful content are removed; visible text and reasoning stay untouched.

Long-lived callers (for example subagent sessions) can invoke this at an idle boundary to reclaim context-window budget from tool payloads the model has already consumed. The call is a no-op unless the runner is idle, so an in-flight tool round is never left with an orphaned call or result.

pub fn stop_current_task(&mut self, output: AgentOutput) -> AgentOutput

Stops the current task while keeping the runner reusable for later input.

This drops in-flight request state, pending tools, queued steering, and queued follow-up text, but it does not mark the runner done. The returned output is recorded as the latest idle-state output and includes accumulated usage/history so observers can account for work already performed before the stop.

pub fn implicit_context(&mut self, message: Message)

Set an implicit context message that is automatically included in the next request.

pub fn set_model(&mut self, model: Option<String>)

Selects the model label to use for subsequent completion turns.

pub fn set_effort(&mut self, effort: Option<ModelEffort>)

Selects the reasoning/thinking effort to use for subsequent completion turns.

pub fn set_tools(&mut self, tools: Vec<FunctionDefinition>)

Selects the tool definitions to use for subsequent completion turns.

pub fn accumulate(&mut self, other: &Usage)

Accumulate usage from an intermediate step into the runner’s total usage.

pub fn accumulate_tools_usage(&mut self, other: &HashMap<String, Usage>)

Accumulate tool usage from an intermediate step into the runner’s total tools usage.

pub fn needs_compaction_with<F>(&self, pending_tokens: F) -> bool

where F: FnOnce() -> u64,

Returns whether the current runner should be compacted based on usage and turn count.

pub async fn next(&mut self) -> Result<Option<AgentOutput>, BoxError>

Execute the next step.

• Calls the model completion.
• Automatically handles tool/agent calls and writes the results back to the conversation history.
• If there are more steps, it constructs the next request and returns the current intermediate result.
• If completed or failed, it returns the final result; the next call will return Ok(None).
• In unbound mode, an idle boundary returns the latest step output without finalizing. A later call returns Ok(None) until new input is queued.

pub async fn handoff( &mut self, compaction_prompt: Option<String>, ) -> Result<(Self, AgentOutput), BoxError>

Summarizes the current conversation into a single handoff message and swaps in a fresh runner seeded with that summary, discarding the bloated history. Pending tool calls are executed first unless queued steering interrupts them; interrupted calls are closed before compaction so provider tool-call requirements are not stranded. Queued follow-up or steering input is preserved and delivered after the handoff so user intent is not folded into the compaction prompt.

pub async fn finalize( &mut self, prompt: Option<String>, ) -> Result<AgentOutput, BoxError>

Finalize the completion with an optional prompt.

Queued messages, plus the optional prompt, are processed through the normal runner flow. If the runner is already idle, finalization returns the latest intermediate output with accumulated usage, tool calls, artifacts, and chat history attached.