Enum Effect 

#[non_exhaustive]
pub enum Effect {
    Llm(LlmRequest),
    Tool {
        name: String,
        args: Value,
    },
    Graph {
        graph: Box<Graph>,
        input: Value,
        mode: GraphEffectMode,
    },
    Sleep(Duration),
    Custom {
        kind: String,
        payload: Value,
    },
}

Something the runtime does on a step’s behalf.

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.

Llm(LlmRequest)

Call a language model.

Tool

Invoke a registered tool.

Fields

name: String

The name the tool was registered under — a ToolSpec::name.

args: Value

Arguments, as JSON shaped by the tool’s ToolSpec::input_schema.

Graph

Run a Soma graph and hand back its output.

This is the bridge that makes a computational pipeline a first-class tool for an agent: it runs through the ordinary compiler and executor, with the ordinary cache, and the agent just sees a result.

Fields

graph: Box<Graph>

The graph to run. Structure travels in the effect itself, so the handler needs no registry lookup to know what it is performing — only the node implementations are resolved on the other side.

input: Value

The input handed to the sub-graph’s root nodes.

mode: GraphEffectMode

Forward with the states already fitted, or fit first.

Sleep(Duration)

Wait. Journaled like anything else, so a replay does not sleep again.

Custom

An effect this runtime doesn’t know about, for host-supplied handlers.

Fields

kind: String

Which handler this is meant for — the string EffectHandler::handles implementations match on.

payload: Value

Whatever that handler expects.

Implementations

impl Effect

pub fn label(&self) -> String

A short label for events and logs. Never includes the payload — a prompt is not something to leak into a log line.

pub fn is_pure(&self) -> bool

Is this effect safe to memoize by content?

Pure effects are cached like any filter output: same input, same result, reused forever. Impure ones are still journaled — recorded once per (node, turn) so a replay is faithful — but never reused across runs, because “the same question asked twice” is genuinely a different event for a model call or a clock read.

pub fn cache_key(&self) -> Result<CacheKey>

Content hash, used as the journal key for this effect.

Canonical CBOR, not raw serializer output: an effect carries user-supplied JSON (Tool { args }, Custom { payload }), and two encodings of the same object must not produce two journal keys.

Fallible on purpose. The previous encoding fell back to empty bytes, which gave every unserializable effect the same key — a replay would then serve one effect’s recorded result to another. A key that cannot be computed has to mean “not journalable”, never a guess.

Trait Implementations

impl Clone for Effect

fn clone(&self) -> Effect

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Effect

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Effect

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Effect

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

where __S: Serializer,

Serialize this value into the given Serde serializer.