Struct TurnOptions 

pub struct TurnOptions {

    pub max_steps: Option<usize>,
    pub max_tool_concurrency: usize,
    pub capability_mode: CapabilityMode,
    pub cancel: CancellationToken,
    pub deadline: Option<Deadline>,
    pub session_id: Option<SessionId>,
    pub agent_id: Option<AgentId>,
    pub cwd: Option<PathBuf>,
    pub compaction: Option<Arc<dyn CompactionStrategy>>,
    pub approval: Arc<dyn ApprovalGate>,
    pub approval_policy: ApprovalPolicy,
    pub stop_gates: Option<Arc<GateChain>>,
    pub metrics: SharedMetrics,
    pub spawn_depth: Option<u32>,
    pub max_output_tokens: Option<u32>,
    pub use_stream: bool,
    pub contributors: Arc<dyn TurnLifecycleContributor>,
    pub interject_rx: Option<Arc<Mutex<UnboundedReceiver<Message>>>>,
    pub context_window_tokens: Option<u32>,
    pub context_overflow_ratio: f32,
    pub fail_on_context_overflow: bool,
}

Options for a single turn.

Fields

max_steps: Option<usize>

Hard step ceiling (defaults to agent max_steps).

max_tool_concurrency: usize

Tool concurrency.

capability_mode: CapabilityMode

Capability mode for tools.

cancel: CancellationToken

Cancel token.

deadline: Option<Deadline>

Deadline.

session_id: Option<SessionId>

Session id for context.

agent_id: Option<AgentId>

Agent id for context.

cwd: Option<PathBuf>

Working directory for path tools.

compaction: Option<Arc<dyn CompactionStrategy>>

Compaction strategy applied before each sample when present.

approval: Arc<dyn ApprovalGate>

Approval gate for tools.

approval_policy: ApprovalPolicy

When to consult approval.

stop_gates: Option<Arc<GateChain>>

Optional override stop-gate chain (default: from agent definition).

metrics: SharedMetrics

Metrics sink (default no-op).

spawn_depth: Option<u32>

Nesting depth when this turn is a host-spawned agent (None = top-level session).

max_output_tokens: Option<u32>

Optional max output tokens for the sampler.

use_stream: bool

Prefer LlmSampler::sample_stream and aggregate into a full response.

contributors: Arc<dyn TurnLifecycleContributor>

Lifecycle contributors (W3.5).

interject_rx: Option<Arc<Mutex<UnboundedReceiver<Message>>>>

Optional mid-turn user interjections drained before each sample (W3.6).

context_window_tokens: Option<u32>

Context window size for preflight overflow (tokens). None disables check.

context_overflow_ratio: f32

Soft threshold ratio of context window (default 0.9).

fail_on_context_overflow: bool

When true, overflow after compaction is a hard error; else continue.

Implementations

impl TurnOptions

pub fn with_max_messages(self, max: usize) -> Result<Self, MachiError>

Cap conversation length via MaxMessages strategy.

Errors

Returns error when max == 0.

pub fn with_compaction(self, strategy: Arc<dyn CompactionStrategy>) -> Self

Install a compaction strategy.

pub fn with_cwd(self, cwd: impl Into<PathBuf>) -> Self

Set cwd for tools.

pub const fn with_capability(self, mode: CapabilityMode) -> Self

Set capability mode.

pub const fn with_max_steps(self, max_steps: usize) -> Self

Set max steps.

pub fn with_cancel(self, cancel: CancellationToken) -> Self

Set cancel token.

pub fn with_approval(self, gate: Arc<dyn ApprovalGate>) -> Self

Set approval gate.

pub const fn with_approval_policy(self, policy: ApprovalPolicy) -> Self

Set approval policy.

pub fn with_metrics(self, metrics: SharedMetrics) -> Self

Set metrics sink.

pub const fn with_deadline(self, deadline: Deadline) -> Self

Set absolute deadline for the turn (sample + tools).

pub const fn with_stream(self, use_stream: bool) -> Self

Prefer streaming sample aggregation for this turn.

pub fn with_stop_gates(self, gates: Arc<GateChain>) -> Self

Override stop-gate chain.

pub fn with_contributors( self, contributors: Arc<dyn TurnLifecycleContributor>, ) -> Self

Install lifecycle contributors (W3.5).

pub fn with_interject_rx( self, rx: Arc<Mutex<UnboundedReceiver<Message>>>, ) -> Self

Mid-turn interjection channel drained before each sample (W3.6).

pub const fn with_context_window(self, tokens: u32) -> Self

Enable preflight context overflow checks (W3.2).

Trait Implementations

impl Clone for TurnOptions

fn clone(&self) -> TurnOptions

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for TurnOptions

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

Formats the value using the given formatter.

impl Default for TurnOptions

fn default() -> Self

Returns the “default value” for a type.