Struct TruncationPolicy 

pub struct TruncationPolicy {
    pub max_bytes: usize,
    pub head_ratio: HeadRatio,
    pub alignment: TruncationAlignment,
    pub marker_template: Option<String>,
    pub spill_sink: Option<Arc<dyn OutputSpillSink>>,
}

Configuration policy for middle-out string truncation.

Fields

max_bytes: usize

Maximum allowed bytes in the truncated output.

head_ratio: HeadRatio

Ratio of available content budget assigned to the head portion. Default is 50/50 balance between head and tail.

alignment: TruncationAlignment

Alignment boundary strategy.

marker_template: Option<String>

Optional custom marker template.

spill_sink: Option<Arc<dyn OutputSpillSink>>

Optional spill sink for retaining full un-truncated observations.

Implementations

impl TruncationPolicy

pub const fn for_context_window(remaining_context_tokens: usize) -> Self

Construct a TruncationPolicy whose max_bytes scales with remaining_context_tokens (30% of remaining tokens at 4 bytes/token, clamped between MIN_ADAPTIVE_TOOL_OUTPUT_BYTES and MAX_ADAPTIVE_TOOL_OUTPUT_BYTES).

pub const fn for_context_window_clamped( remaining_context_tokens: usize, min_bytes: usize, max_bytes: usize, ) -> Self

Construct a TruncationPolicy scaled to remaining_context_tokens with custom [min_bytes, max_bytes] bounds.

impl TruncationPolicy

pub const fn new(max_bytes: usize) -> Self

Create a new truncation policy with a specified max_bytes ceiling, balanced 50/50 head-tail ratio, and character boundary alignment.

pub fn with_head_ratio(self, ratio: impl Into<HeadRatio>) -> Self

Set the head budget ratio.

pub const fn with_alignment(self, alignment: TruncationAlignment) -> Self

Set the boundary alignment strategy.

pub fn with_marker(self, marker: impl Into<String>) -> Self

Set a custom marker template.

Placeholders {omitted_bytes}, {original_bytes}, {offset_start}, {offset_end}, and {ref} will be substituted. Legacy aliases {count}, {bytes}, and <N> are also supported.

pub fn with_spill_sink(self, sink: Arc<dyn OutputSpillSink>) -> Self

Set a spill sink for retaining un-truncated observations.

pub fn format_marker(&self, omitted_bytes: usize) -> String

Format the marker string for the given omitted bytes without sink reference.

Preserved for backwards compatibility with existing callers.

pub fn format_marker_detailed( &self, omitted_bytes: usize, original_bytes: usize, offset_start: usize, offset_end: usize, spill: &SpillDisposition, ) -> String

Format marker with full metadata substitutions including offsets and spill disposition.

When spill is SpillDisposition::Failed, the rendered marker always carries an in-band warning that the omitted bytes are unrecoverable — including for custom templates that do not mention the failure themselves — so retention loss can never pass unnoticed by the model reading the output.

pub fn truncate<'a>(&self, input: &'a str) -> Cow<'a, str>

Truncate input using this policy, returning a borrowed Cow when no truncation is needed, or an owned string when middle-out truncation occurs.

If input is a verified <tool_output_quarantine> envelope, the outer XML quarantine tags are preserved and only the inner payload is truncated. If input was already sanitized (contains no raw control tokens or breakout tags), any split token formed across the head/marker/tail cut boundary is neutralized.

If a configured OutputSpillSink fails, this method does not fail: the error is logged and rendered into the truncation marker, so the loss of the omitted bytes is visible to both the operator and the model. Callers that need to handle spill failure programmatically should use TruncationPolicy::truncate_detailed, which returns the SpillError.

pub fn truncate_sanitized<'a>(&self, input: &'a str) -> Cow<'a, str>

Sanitize and truncate input in a single pass, neutralizing all known LLM control tokens (DELIMITER_RULES) and breakout tags (including any split tokens formed across the head/marker/tail cut boundary) while ensuring the final sanitized result fits within self.max_bytes.

pub fn truncate_quarantined(&self, input: &str) -> String

Quarantine and truncate input, neutralizing all known LLM control tokens and wrapping the output in <tool_output_quarantine> tags while fitting the total envelope inside self.max_bytes (when self.max_bytes >= 70).

pub fn truncate_lossy_with_context<'a>( &self, input: &'a str, ctx: &SpillContext<'_>, ) -> TruncationOutcome<'a>

Infallible truncation that degrades visibly — rather than failing — when a configured OutputSpillSink returns an error.

pub fn truncate_sanitized_lossy_with_context<'a>( &self, input: &'a str, ctx: &SpillContext<'_>, ) -> TruncationOutcome<'a>

Infallible sanitize + truncate with caller-provided SpillContext.

pub fn truncate_quarantined_lossy_with_context<'a>( &self, input: &'a str, ctx: &SpillContext<'_>, ) -> TruncationOutcome<'a>

Infallible quarantine + truncate with caller-provided SpillContext.

pub fn truncate_detailed<'a>( &self, input: &'a str, ) -> Result<TruncationOutcome<'a>, SpillError>

Truncate input using an anonymous spill context, returning a detailed TruncationOutcome.

Errors

Returns SpillError if an OutputSpillSink is configured and fails.

pub fn truncate_detailed_with_context<'a>( &self, input: &'a str, ctx: &SpillContext<'_>, ) -> Result<TruncationOutcome<'a>, SpillError>

Truncate input with caller-provided SpillContext, returning a detailed TruncationOutcome.

Errors

Returns SpillError if an OutputSpillSink is configured and fails.

Trait Implementations

impl Clone for TruncationPolicy

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for TruncationPolicy

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

Formats the value using the given formatter.

impl Eq for TruncationPolicy

impl PartialEq for TruncationPolicy

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.