#[non_exhaustive]pub enum Episode {
Show 13 variants
Started {
agent: String,
},
LlmCall {
tokens: u32,
latency_ms: u32,
provider: Option<String>,
model: Option<String>,
prompt_tokens: Option<u32>,
completion_tokens: Option<u32>,
},
ToolCall {
name: String,
args: Value,
result: ToolResult,
},
BusPublish {
subject: String,
},
BusReceive {
subject: String,
},
BusCausalLink {
subject: String,
caused_by_run: String,
},
Completed,
Failed {
error: String,
},
SummaryCheckpoint {
input_message_count: u32,
summary_chars: u32,
latency_ms: u32,
tokens: u32,
},
Ops(Value),
RunAttributed {
tenant_label: String,
},
RunOrigin {
parent_anchor: String,
},
MemoryRecall {
query: String,
k: u32,
returned_fact_ids: Vec<FactId>,
},
}Expand description
One event in the episodic event stream of a single agent run.
Marked #[non_exhaustive] so additive variants (e.g.
Self::SummaryCheckpoint) can be introduced without forcing a
SemVer-major bump. Match arms in downstream crates must include a
fallback _ => ….
Variants (Non-exhaustive)§
This enum is marked as non-exhaustive
Started
Run started.
LlmCall
LLM call completed.
provider/model/prompt_tokens/completion_tokens are
Option so legacy emit sites can leave them None; downstream
projectors fall back to the LlmIo sidecar in klieo-runlog
when the structured fields are absent.
Fields
provider: Option<String>Provider identifier — e.g. "ollama", "openai",
"anthropic", "gemini". None for older records or
providers that don’t expose a stable name.
#[serde(default)] so legacy episodes serialised under
klieo 0.6.x deserialise as None.
ToolCall
Tool call completed.
BusPublish
Agent published a bus message.
BusReceive
Agent received a bus message.
BusCausalLink
Causal link: this run received a bus message caused by another run’s
publish. Recorded by AgentContext::record_received when the publisher
threaded its run id via the klieo-causation-run bus header. Additive —
absent on records from publishers that did not thread the causation header.
Fields
Completed
Run completed successfully.
Failed
Run failed.
SummaryCheckpoint
Summarizer checkpoint completed.
Emitted by crate::summarize::summarize_history in lieu of
Self::LlmCall so the audit trail can distinguish summarizer
overhead from substantive agent reasoning. Downstream
observability (e.g. klieo-runlog) typically projects this as
a separate step kind so cost / latency attribution stays
faithful.
Fields
Ops(Value)
Operational-layer event (klieo-ops). Body is an opaque
serde_json::Value to keep klieo-core free of an ops dependency.
klieo-ops provides typed serde conversion helpers via OpsEvent.
RunAttributed
Non-PII tenant attribution stamped at run entry when an external caller drives the run.
tenant_label is a derived identifier (e.g. truncated SHA-256
of the caller’s sub) — never the raw principal, which lives
only in server-side tracing/authorization. Emitted at most once
per run, adjacent to Self::Started, so the audit trail can
attribute each run to its driving tenant without admitting PII
into agent memory or LLM-visible context.
RunOrigin
Cross-hop provenance origin stamped at run entry when an authenticated external caller supplies a parent-chain anchor.
parent_anchor is the caller’s own provenance chain-entry id (or
its run’s episodic-root hash) — recorded verbatim so the value
equals the caller’s identifier and downstream tooling can stitch
klieo→klieo lineage across deployments. It is a caller-asserted,
unverified claim (klieo does not own or validate the caller’s
chain); it is co-recorded with Self::RunAttributed so the
claim is attributable to the authenticated principal that made it.
Emitted at most once per run, adjacent to Self::Started; never
admitted into agent memory or LLM-visible context.
MemoryRecall
A graphRAG recall performed during the run. Recorded by the
recall-recording wrapper so the run view can surface — and
deep-link — retrieval calls. query is redacted + length-bounded
at the recording boundary before it reaches this episode.
Implementations§
Source§impl Episode
impl Episode
Sourcepub fn llm_call(tokens: u32, latency_ms: u32) -> Self
pub fn llm_call(tokens: u32, latency_ms: u32) -> Self
Construct an Episode::LlmCall with the legacy two-field shape
(tokens + latency_ms), leaving the 0.7-added
provider/model/prompt_tokens/completion_tokens fields as
None.
Use this when the emit site does not have the enriched fields to hand — e.g. test fixtures, providers that only report total tokens, or call sites being migrated incrementally. For full 0.7 emit semantics, construct the struct variant directly.
use klieo_core::Episode;
let ep = Episode::llm_call(42, 17);
match ep {
Episode::LlmCall { tokens, latency_ms, provider, .. } => {
assert_eq!(tokens, 42);
assert_eq!(latency_ms, 17);
assert!(provider.is_none());
}
_ => unreachable!(),
}