Enum AgentEvent 

#[non_exhaustive]
pub enum AgentEvent {
    Start {
        prompt: String,
    },
    AgentModeChanged {
        mode: String,
        agent: String,
        description: String,
    },
    TurnStart {
        turn: usize,
    },
    TextDelta {
        text: String,
    },
    ReasoningDelta {
        text: String,
    },
    ToolStart {
        id: String,
        name: String,
    },
    ToolInputDelta {
        id: Option<String>,
        delta: String,
    },
    ToolExecutionStart {
        id: String,
        name: String,
        args: Value,
    },
    ToolEnd {
        id: String,
        name: String,
        args: Option<Value>,
        output: String,
        exit_code: i32,
        metadata: Option<Value>,
        error_kind: Option<ToolErrorKind>,
    },
    ToolOutputDelta {
        id: String,
        name: String,
        delta: String,
    },
    TurnEnd {
        turn: usize,
        usage: TokenUsage,
    },
    End {
        text: String,
        usage: TokenUsage,
        verification_summary: Box<VerificationSummary>,
        meta: Option<LlmResponseMeta>,
    },
    Error {
        message: String,
    },
    ConfirmationRequired {
        tool_id: String,
        tool_name: String,
        args: Value,
        timeout_ms: u64,
    },
    ConfirmationReceived {
        tool_id: String,
        approved: bool,
        reason: Option<String>,
    },
    ConfirmationTimeout {
        tool_id: String,
        action_taken: String,
    },
    ExternalTaskPending {
        task_id: String,
        session_id: String,
        lane: SessionLane,
        command_type: String,
        payload: Value,
        timeout_ms: u64,
    },
    ExternalTaskCompleted {
        task_id: String,
        session_id: String,
        success: bool,
    },
    PermissionDenied {
        tool_id: String,
        tool_name: String,
        args: Value,
        reason: String,
    },
    ContextResolving {
        providers: Vec<String>,
    },
    ContextResolved {
        total_items: usize,
        total_tokens: usize,
    },
    CommandDeadLettered {
        command_id: String,
        command_type: String,
        lane: String,
        error: String,
        attempts: u32,
    },
    CommandRetry {
        command_id: String,
        command_type: String,
        lane: String,
        attempt: u32,
        delay_ms: u64,
    },
    QueueAlert {
        level: String,
        alert_type: String,
        message: String,
    },
    TaskUpdated {
        session_id: String,
        tasks: Vec<Task>,
    },
    MemoryStored {
        memory_id: String,
        memory_type: String,
        importance: f32,
        tags: Vec<String>,
    },
    MemoryRecalled {
        memory_id: String,
        content: String,
        relevance: f32,
    },
    MemoriesSearched {
        query: Option<String>,
        tags: Vec<String>,
        result_count: usize,
    },
    MemoryCleared {
        tier: String,
        count: u64,
    },
    SubagentStart {
        task_id: String,
        session_id: String,
        parent_session_id: String,
        agent: String,
        description: String,
        started_ms: u64,
    },
    SubagentProgress {
        task_id: String,
        session_id: String,
        status: String,
        metadata: Value,
    },
    SubagentEnd {
        task_id: String,
        session_id: String,
        agent: String,
        output: String,
        success: bool,
        finished_ms: u64,
    },
    PlanningStart {
        prompt: String,
    },
    PlanningEnd {
        plan: ExecutionPlan,
        estimated_steps: usize,
    },
    StepStart {
        step_id: String,
        description: String,
        step_number: usize,
        total_steps: usize,
    },
    StepEnd {
        step_id: String,
        status: TaskStatus,
        step_number: usize,
        total_steps: usize,
    },
    GoalExtracted {
        goal: AgentGoal,
    },
    GoalProgress {
        goal: String,
        progress: f32,
        completed_steps: usize,
        total_steps: usize,
    },
    GoalAchieved {
        goal: String,
        total_steps: usize,
        duration_ms: i64,
    },
    ContextCompacted {
        session_id: String,
        before_messages: usize,
        after_messages: usize,
        percent_before: f32,
        summary: Option<String>,
    },
    PersistenceFailed {
        session_id: String,
        operation: String,
        error: String,
    },
    BudgetThresholdHit {
        resource: String,
        kind: String,
        consumed: f64,
        limit: f64,
        message: Option<String>,
    },
    PassivationRequested {
        reason: String,
        deadline_ms: Option<u64>,
    },
    PeerInvocation {
        from_session_id: String,
        from_tenant_id: Option<String>,
        correlation_id: Option<String>,
    },
}

Events emitted during agent execution

Subscribe via crate::AgentSession::stream. New variants may be added in minor releases — always include a wildcard arm (_ => {}) when matching.

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.

Start

Agent started processing

Fields

prompt: String

AgentModeChanged

Runtime agent style/mode selected for the current execution.

Fields

mode: String

Stable UI/runtime mode label, e.g. “general”, “planning”, “explore”.

agent: String

Canonical built-in agent name associated with this mode.

description: String

Human-readable explanation of the selected style.

TurnStart

LLM turn started. The same turn number is emitted again when an interrupted response stream is retried; consumers should roll back provisional output from that turn before applying replacement deltas.

Fields

turn: usize

TextDelta

Text delta from streaming

Fields

text: String

ReasoningDelta

Reasoning/thinking delta from streaming (for models like kimi, deepseek)

Fields

text: String

ToolStart

The model started preparing a streamed tool call.

Fields

id: String

name: String

ToolInputDelta

Tool input delta from streaming (partial JSON arguments)

Fields

id: Option<String>

delta: String

ToolExecutionStart

A fully prepared tool call passed safety/confirmation and began execution.

Fields

id: String

name: String

args: Value

ToolEnd

Tool execution completed

Fields

id: String

name: String

args: Option<Value>

output: String

exit_code: i32

metadata: Option<Value>

error_kind: Option<ToolErrorKind>

Structured discriminant set by tools that mapped their failure into a typed ToolErrorKind (e.g. edit / patch on a WorkspaceError::VersionConflict). None on success or untyped failure.

ToolOutputDelta

Intermediate tool output (streaming delta)

Fields

id: String

name: String

delta: String

TurnEnd

LLM turn completed

Fields

turn: usize

usage: TokenUsage

End

Agent completed

Fields

text: String

usage: TokenUsage

verification_summary: Box<VerificationSummary>

meta: Option<LlmResponseMeta>

Error

Error occurred

Fields

message: String

ConfirmationRequired

Tool execution requires confirmation (HITL)

Fields

tool_id: String

tool_name: String

args: Value

timeout_ms: u64

ConfirmationReceived

Confirmation received from user (HITL)

Fields

tool_id: String

approved: bool

reason: Option<String>

ConfirmationTimeout

Confirmation timed out (HITL)

Fields

tool_id: String

action_taken: String

ExternalTaskPending

External task pending (needs SDK processing)

Fields

task_id: String

session_id: String

lane: SessionLane

command_type: String

payload: Value

timeout_ms: u64

ExternalTaskCompleted

External task completed

Fields

task_id: String

session_id: String

success: bool

PermissionDenied

Tool execution denied by permission policy

Fields

tool_id: String

tool_name: String

args: Value

reason: String

ContextResolving

Context resolution started

Fields

providers: Vec<String>

ContextResolved

Context resolution completed

Fields

total_items: usize

total_tokens: usize

CommandDeadLettered

Command moved to dead letter queue after exhausting retries

Fields

command_id: String

command_type: String

lane: String

error: String

attempts: u32

CommandRetry

Command retry attempt

Fields

command_id: String

command_type: String

lane: String

attempt: u32

delay_ms: u64

QueueAlert

Queue alert (depth warning, latency alert, etc.)

Fields

level: String

alert_type: String

message: String

TaskUpdated

Task list updated

Fields

session_id: String

tasks: Vec<Task>

MemoryStored

Memory stored

Fields

memory_id: String

memory_type: String

importance: f32

tags: Vec<String>

MemoryRecalled

Memory recalled

Fields

memory_id: String

content: String

relevance: f32

MemoriesSearched

Memories searched

Fields

query: Option<String>

tags: Vec<String>

result_count: usize

MemoryCleared

Memory cleared

Fields

tier: String

count: u64

SubagentStart

Subagent task started

Fields

task_id: String

Unique task identifier

session_id: String

Child session ID

parent_session_id: String

Parent session ID

agent: String

Agent type (e.g., “explore”, “general”)

description: String

Short description of the task

started_ms: u64

Wall-clock start timestamp in milliseconds since Unix epoch.

SubagentProgress

Subagent task progress update

Fields

task_id: String

Task identifier

session_id: String

Child session ID

status: String

Progress status message

metadata: Value

Additional metadata

SubagentEnd

Subagent task completed

Fields

task_id: String

Task identifier

session_id: String

Child session ID

agent: String

Agent type

output: String

Task output/result

success: bool

Whether the task succeeded

finished_ms: u64

Wall-clock finish timestamp in milliseconds since Unix epoch.

PlanningStart

Planning phase started

Fields

prompt: String

PlanningEnd

Planning phase completed

Fields

plan: ExecutionPlan

estimated_steps: usize

StepStart

Step execution started

Fields

step_id: String

description: String

step_number: usize

total_steps: usize

StepEnd

Step execution completed

Fields

step_id: String

status: TaskStatus

step_number: usize

total_steps: usize

GoalExtracted

Goal extracted from prompt

Fields

goal: AgentGoal

GoalProgress

Goal progress update

Fields

goal: String

progress: f32

completed_steps: usize

total_steps: usize

GoalAchieved

Goal achieved

Fields

goal: String

total_steps: usize

duration_ms: i64

ContextCompacted

Context automatically compacted due to high usage

Fields

session_id: String

before_messages: usize

after_messages: usize

percent_before: f32

summary: Option<String>

Cumulative continuation summary when message history was reduced. Prune-only compactions omit this field.

PersistenceFailed

Session persistence failed — SDK clients should handle this

Fields

session_id: String

operation: String

error: String

BudgetThresholdHit

A budget threshold was crossed for this session/tenant.

Emitted by a host BudgetGuard impl when LLM/tool spend hits a soft or hard threshold. The session is not automatically halted — kind lets in-session policy decide (e.g. fast-compact at “soft”, refuse next LLM call at “hard”).

Fields

resource: String

Logical resource: “llm_tokens”, “tool_calls”, “wall_time”, “usd_cost”, or host-defined.

kind: String

“soft” or “hard”; host-defined semantics beyond that.

consumed: f64

Current consumed amount in the same unit as limit.

limit: f64

Threshold that was crossed.

message: Option<String>

Optional explanation for logs / UI.

PassivationRequested

The host is asking the session to release in-memory state.

Emitted before the host calls session.close() or moves the session to another node. Session code that holds large caches can react (flush to memory store, drop derived state). The framework does not act on this event itself.

Fields

reason: String

“idle_reaper”, “node_drain”, “migration”, “manual”, or host-defined.

deadline_ms: Option<u64>

Optional deadline (Unix epoch ms) before forced close.

PeerInvocation

Another session in the cluster has invoked this one.

Lets in-session hooks distinguish “human-driven send” from “peer-driven send” without inspecting prompts. The host routes the actual prompt through the normal send / stream path; this event is metadata only.

Fields

from_session_id: String

Session id of the invoking peer (cluster-stable).

from_tenant_id: Option<String>

Optional tenant of the invoking peer.

correlation_id: Option<String>

Distributed-trace correlation id linking the two sessions.

Implementations

impl AgentEvent

pub const fn event_type_v1(&self) -> &'static str

Return the canonical version-1 wire type for this event.

This match is deliberately exhaustive. Adding an AgentEvent variant without assigning it a stable wire name is a compile error rather than an SDK event named unknown.

Trait Implementations

impl Clone for AgentEvent

fn clone(&self) -> AgentEvent

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for AgentEvent

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for AgentEvent

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for AgentEvent

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl TryFrom<&AgentEvent> for EventEnvelopeV1

type Error = EventProtocolError

The type returned in the event of a conversion error.

fn try_from(event: &AgentEvent) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<&AgentEvent> for AgentEventProjectionV1

type Error = EventProtocolError

The type returned in the event of a conversion error.

fn try_from(event: &AgentEvent) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<AgentEvent> for EventEnvelopeV1

type Error = EventProtocolError

The type returned in the event of a conversion error.

fn try_from(event: AgentEvent) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<AgentEvent> for AgentEventProjectionV1

type Error = EventProtocolError

The type returned in the event of a conversion error.

fn try_from(event: AgentEvent) -> Result<Self, Self::Error>

Performs the conversion.