Enum CacheHint 

#[non_exhaustive]
pub enum CacheHint {
    None,
    StablePrefix {
        key: Option<String>,
    },
}

Provider-agnostic hint about caching a request’s stable prefix.

A multi-step turn re-sends a growing conversation behind an unchanging prefix — the system text plus the tool-spec block (built once per turn). This hint marks that prefix as stable so a provider that supports prompt caching can cache it and skip re-processing it on every step, the single biggest latency lever on multi-step turns. It is purely advisory: a provider maps it to its native mechanism, and a provider with no caching ignores it with no behavior change.

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.

None

No caching is requested; a provider processes the full prompt on every call. The default so auxiliary calls that bypass the answering loop never opt in accidentally.

StablePrefix

The request’s leading stable prefix (system text + tool-spec block) stays byte-identical across the steps of a turn — and across turns of a conversation — so a provider that supports prompt caching should cache it.

Fields

key: Option<String>

Optional stable per-conversation identifier a provider MAY use to pin cache routing (a provider maps it to its own cache-key field). A provider with only implicit prefix caching, or none at all, ignores it. None leaves routing to the provider’s implicit prefix match.

Implementations

impl CacheHint

pub fn from_key(key: String) -> Self

Reconstructs a hint from its flat single-string form: a non-empty key is a keyed CacheHint::StablePrefix; an empty one is CacheHint::None. The inverse of Self::key — together they carry the hint across a boundary that has one string field (the control-plane → harness turn input), which cannot express a keyless stable-prefix hint (the control plane always keys by conversation).

pub fn key(&self) -> Option<&str>

The cache-routing key this hint carries, if any. See Self::from_key for the flat form the pair round-trips.

Trait Implementations

impl Clone for CacheHint

fn clone(&self) -> CacheHint

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for CacheHint

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

Formats the value using the given formatter.

impl Default for CacheHint

fn default() -> CacheHint

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for CacheHint

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for CacheHint

impl PartialEq for CacheHint

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

Equality operator ==.

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

Inequality operator !=.

impl Serialize for CacheHint

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for CacheHint