Enum GraphEvent 

#[non_exhaustive]
pub enum GraphEvent {
    UserMessage {
        content: Vec<ContentPart>,
        timestamp: DateTime<Utc>,
    },
    AssistantMessage {
        content: Vec<ContentPart>,
        usage: Option<Usage>,
        timestamp: DateTime<Utc>,
    },
    ContextCompacted {
        dropped_chars: usize,
        retained_chars: usize,
        timestamp: DateTime<Utc>,
    },
    ToolCall {
        id: String,
        name: String,
        input: Value,
        timestamp: DateTime<Utc>,
    },
    ToolResult {
        tool_use_id: String,
        name: String,
        content: ToolResultContent,
        is_error: bool,
        timestamp: DateTime<Utc>,
    },
    BranchCreated {
        branch_id: String,
        parent_event: usize,
        timestamp: DateTime<Utc>,
    },
    CheckpointMarker {
        checkpoint_id: String,
        thread_id: String,
        timestamp: DateTime<Utc>,
    },
    Warning {
        warning: ModelWarning,
        timestamp: DateTime<Utc>,
    },
    ThinkingDelta {
        text: String,
        provider_echoes: Vec<ProviderEchoSnapshot>,
        timestamp: DateTime<Utc>,
    },
    RateLimit {
        snapshot: RateLimitSnapshot,
        timestamp: DateTime<Utc>,
    },
    Interrupt {
        payload: Value,
        timestamp: DateTime<Utc>,
    },
    Cancelled {
        reason: String,
        timestamp: DateTime<Utc>,
    },
    SubAgentInvoked {
        agent_id: String,
        sub_thread_id: String,
        timestamp: DateTime<Utc>,
    },
    AgentHandoff {
        from: Option<String>,
        to: String,
        timestamp: DateTime<Utc>,
    },
    Resumed {
        from_checkpoint: String,
        timestamp: DateTime<Utc>,
    },
    MemoryRecall {
        tier: String,
        namespace_key: String,
        hits: usize,
        timestamp: DateTime<Utc>,
    },
    UsageLimitExceeded {
        breach: UsageLimitBreach,
        timestamp: DateTime<Utc>,
    },
    Error {
        class: String,
        message: String,
        timestamp: DateTime<Utc>,
    },
}

One audit-log entry.

Aggregating these (oldest-to-newest) reconstructs the full conversation trace for a thread. Branches and checkpoints are recorded inline so a single linear scan is enough for replay.

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.

UserMessage

User-authored input.

Fields

content: Vec<ContentPart>

Multi-part content (text, image, tool_result).

timestamp: DateTime<Utc>

Wall-clock time the event was appended.

AssistantMessage

Assistant reply (after stream aggregation).

Fields

content: Vec<ContentPart>

Multi-part content (text, tool_use).

usage: Option<Usage>

Token accounting if reported by the provider.

timestamp: DateTime<Utc>

Wall-clock time the event was appended.

ContextCompacted

An auto-compaction adapter trimmed the working message slice. dropped_chars is the character cost the compactor removed (or summarised away); retained_chars is the cost the post-compaction slice carries forward. The pair lets dashboards detect drift between the threshold the operator wired and the actual trim each invocation produces.

Fields

dropped_chars: usize

Character cost the compactor dropped.

retained_chars: usize

Character cost the post-compaction slice retained.

timestamp: DateTime<Utc>

Wall-clock time the event was appended.

ToolCall

A tool was dispatched by the assistant.

Fields

id: String

Stable tool-use id matching a future ToolResult.

name: String

Registered tool name.

input: Value

Tool input as JSON.

timestamp: DateTime<Utc>

Wall-clock time the event was appended.

ToolResult

The dispatched tool returned.

Fields

tool_use_id: String

ToolCall::id this result resolves.

name: String

ToolCall::name this result resolves — required by codecs whose wire format keys correlation by name (Gemini’s functionResponse) rather than id.

content: ToolResultContent

Result payload.

is_error: bool

True if the tool reported an error.

timestamp: DateTime<Utc>

Wall-clock time the event was appended.

BranchCreated

A branch was forked off this session at the indicated event index. The new branch’s thread id is recorded alongside.

Fields

branch_id: String

Identifier of the forked sub-session.

parent_event: usize

Index in events (0-based) the branch diverged at.

timestamp: DateTime<Utc>

Wall-clock time the event was appended.

CheckpointMarker

Marker tying this position in the audit log to a Checkpointer snapshot. Cross-tier reference for crash recovery flows that pair SessionGraph (Tier 2) with StateGraph checkpoints (Tier 1).

Fields

checkpoint_id: String

Stringified entelix_graph::CheckpointId.

thread_id: String

Thread the checkpoint was written under (typically same as the session’s thread).

timestamp: DateTime<Utc>

Wall-clock time the event was appended.

Warning

Codec / runtime advisory captured into the audit trail.

Fields

warning: ModelWarning

Underlying advisory.

timestamp: DateTime<Utc>

Wall-clock time the event was appended.

ThinkingDelta

Streaming thinking-content fragment captured into the audit trail. Aggregators fold consecutive deltas into a single ContentPart::Thinking when reconstructing a finalised message. Recording deltas individually keeps the audit log faithful to the wire — a replay that needs only the final block can fold the deltas, while a replay that needs per-token timing has the data.

Fields

text: String

Token text appended to the in-progress thinking block.

provider_echoes: Vec<ProviderEchoSnapshot>

Vendor opaque round-trip tokens carried on this delta (Anthropic signature_delta, Gemini thought_signature on streamed parts, OpenAI Responses reasoning-item encrypted_content). Codecs pre-wrap into ProviderEchoSnapshot on decode; the audit log preserves the same opaque bytes for replay.

timestamp: DateTime<Utc>

Wall-clock time the event was appended.

RateLimit

Provider rate-limit snapshot at this position in the conversation. Operators reading the audit log can correlate a later throttling failure with the snapshot that warned them. Recorded inline rather than on a separate metric channel so the audit trail is self-contained for compliance review.

Fields

snapshot: RateLimitSnapshot

Snapshot the codec extracted from response headers.

timestamp: DateTime<Utc>

Wall-clock time the event was appended.

Interrupt

HITL pause point — the runtime asked the host application for input. The matching resume signal lands in entelix_graph::Command outside the audit log; this event records that the pause happened and what was visible to the human at the time.

Fields

payload: Value

Operator-supplied payload describing the pause point. Free-form JSON so the agent recipe owns the schema; the audit log just persists it.

timestamp: DateTime<Utc>

Wall-clock time the event was appended.

Cancelled

The run was cancelled — either via cancellation token or via a deadline elapsing. Recording the reason inline lets a replay reconstruct partial-run audit traces faithfully.

Fields

reason: String

Lean reason string. Human-readable; not parsed downstream.

timestamp: DateTime<Utc>

Wall-clock time the event was appended.

SubAgentInvoked

A sub-agent was dispatched from the parent’s run. The parent run_id (recorded on the surrounding AgentEvent::Started) scopes the audit trail; this event ties the parent’s position to the child’s sub_thread_id so a replay can walk from parent to child without keying on heuristic timing. Managed-agent shape — every Subagent::execute call surfaces here as the canonical “brain passes hand” audit boundary.

Fields

agent_id: String

Stable identifier the parent uses to refer to the sub-agent (typically the Subagent’s configured name).

sub_thread_id: String

Thread the sub-agent ran under. Same as the parent’s thread when the sub-agent shares state; a fresh value when the sub-agent runs in its own scope.

timestamp: DateTime<Utc>

Wall-clock time the event was appended.

AgentHandoff

A supervisor recipe handed control between named agents. Distinct from SubAgentInvoked — supervisor handoffs route inside one logical conversation, while sub-agent invocations open a child run.

Fields

from: Option<String>

Agent name that finished this turn (None on the first supervisor turn where no agent has spoken yet).

to: String

Agent name the supervisor routed to next.

timestamp: DateTime<Utc>

Wall-clock time the event was appended.

Resumed

A run resumed from a prior checkpoint — either via wake(thread_id) after a crash or via Command::Resume from a HITL pause. Pairs with the CheckpointMarker whose id is referenced so a single linear replay stays coherent across the suspend / resume seam.

Fields

from_checkpoint: String

CheckpointMarker::checkpoint_id the resume hydrated from. Empty string when the resume happened from a fresh state (operator built the resume payload by hand).

timestamp: DateTime<Utc>

Wall-clock time the event was appended.

MemoryRecall

A long-term memory tier returned hits to the agent. Records which tier was queried (semantic / entity / graph / caller-defined), the namespace key (operator identifier for the slice queried), and the number of hits returned. The hits themselves stay outside the audit log — the model-facing content already lands in AssistantMessage / ToolResult, and storing the full retrieved corpus inline would balloon the audit trail.

Fields

tier: String

Memory tier identifier (typically "semantic", "entity", "graph", or an operator-supplied label).

namespace_key: String

Rendered namespace key the query targeted.

hits: usize

Number of records returned to the agent.

timestamp: DateTime<Utc>

Wall-clock time the event was appended.

UsageLimitExceeded

An entelix_core::RunBudget axis hit its cap and short-circuited the run with entelix_core::Error::UsageLimitExceeded. Compliance and billing audits replay this to attribute breaches per-tenant per-run; the operator-facing Error continues to flow through the typed dispatch return as well, so the audit channel’s role here is the durable record, not the only breach signal.

Fields

breach: UsageLimitBreach

Typed axis-and-magnitude pair carried straight through from the matching Error::UsageLimitExceeded(breach). The axis variant carries its own magnitude shape (u64 for counts, Decimal for cost).

timestamp: DateTime<Utc>

Wall-clock time the event was appended.

Error

A failure surfaced from the model / tool / graph runtime. Errors that the agent recovers from internally are still recorded so post-mortems see the full picture.

Fields

class: String

Coarse classification matching entelix_core::Error variants ("provider", "invalid_request", "config", "auth", "interrupted", "cancelled", "serde", "transport"). Stable wire strings — dashboards key off these without the SDK leaking internal error layout.

message: String

Human-readable summary (Display form).

timestamp: DateTime<Utc>

Wall-clock time the event was appended.

Implementations

impl GraphEvent

pub const fn timestamp(&self) -> &DateTime<Utc>

Borrow the timestamp of any event variant.

Trait Implementations

impl Clone for GraphEvent

fn clone(&self) -> GraphEvent

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for GraphEvent

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for GraphEvent

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for GraphEvent

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for GraphEvent

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for GraphEvent

impl StructuralPartialEq for GraphEvent