pub enum AgentEvent {
Show 38 variants
Token {
content: String,
},
ReasoningToken {
content: String,
},
ToolToken {
tool_call_id: String,
content: String,
},
ToolStart {
tool_call_id: String,
tool_name: String,
arguments: Value,
},
ToolComplete {
tool_call_id: String,
result: ToolResult,
},
ToolError {
tool_call_id: String,
error: String,
},
ToolLifecycle {
tool_call_id: String,
tool_name: String,
phase: String,
elapsed_ms: Option<u64>,
is_mutating: bool,
auto_approved: bool,
summary: Option<String>,
error: Option<String>,
},
NeedClarification {
question: String,
options: Option<Vec<String>>,
tool_call_id: Option<String>,
tool_name: Option<String>,
allow_custom: bool,
},
TaskListUpdated {
task_list: TaskList,
},
TaskListItemProgress {
session_id: String,
item_id: String,
status: TaskItemStatus,
tool_calls_count: usize,
version: u64,
},
TaskListCompleted {
session_id: String,
completed_at: DateTime<Utc>,
total_rounds: u32,
total_tool_calls: usize,
},
TaskEvaluationStarted {
session_id: String,
items_count: usize,
},
TaskEvaluationCompleted {
session_id: String,
updates_count: usize,
reasoning: String,
},
GoldEvaluationStarted {
session_id: String,
checkpoint: GoldCheckpoint,
iteration: u32,
},
GoldEvaluationCompleted {
session_id: String,
checkpoint: GoldCheckpoint,
iteration: u32,
decision: GoldDecision,
confidence: GoldConfidence,
reasoning: String,
},
TokenBudgetUpdated {
usage: TokenBudgetUsage,
},
ContextCompressionStatus {
phase: String,
status: String,
},
ContextSummarized {
summary: String,
messages_summarized: usize,
tokens_saved: u32,
usage_before_percent: f64,
usage_after_percent: f64,
trigger_type: String,
},
ContextPressureNotification {
percent: f64,
level: String,
message: String,
},
SubAgentStarted {
parent_session_id: String,
child_session_id: String,
title: Option<String>,
},
SubAgentEvent {
parent_session_id: String,
child_session_id: String,
event: Box<AgentEvent>,
},
SubAgentHeartbeat {
parent_session_id: String,
child_session_id: String,
timestamp: DateTime<Utc>,
},
SubAgentCompleted {
parent_session_id: String,
child_session_id: String,
status: String,
error: Option<String>,
},
PlanModeEntered {
session_id: String,
reason: Option<String>,
pre_permission_mode: String,
entered_at: DateTime<Utc>,
status: PlanModeStatus,
plan_file_path: Option<String>,
},
PlanModeExited {
session_id: String,
approved: bool,
restored_mode: String,
plan: Option<String>,
},
PlanFileUpdated {
session_id: String,
file_path: String,
content_summary: String,
},
RunnerProgress {
session_id: String,
round_count: u32,
},
SessionTitleUpdated {
session_id: String,
title: String,
title_version: u64,
source: TitleSource,
updated_at: DateTime<Utc>,
},
SessionPinnedUpdated {
session_id: String,
pinned: bool,
updated_at: DateTime<Utc>,
},
SessionCreated {
session_id: String,
title: String,
kind: SessionKind,
created_at: DateTime<Utc>,
},
SessionDeleted {
session_id: String,
},
SessionCleared {
session_id: String,
},
MessageAppended {
session_id: String,
message_id: String,
role: Role,
content: String,
created_at: DateTime<Utc>,
},
ExecutionStarted {
run_id: String,
session_id: String,
started_at: String,
},
ToolApprovalRequested {
tool_call_id: String,
tool_name: String,
parameters: Value,
},
Complete {
usage: TokenUsage,
},
Cancelled {
message: Option<String>,
},
Error {
message: String,
},
}Expand description
Represents events emitted during agent execution.
These events are streamed to clients via SSE to provide real-time feedback on agent progress, tool execution, and completion.
§Variants
§Text Generation
Token- Streaming text tokenReasoningToken- Streaming reasoning/thinking token (separate channel)
§Tool Execution
ToolStart- Tool execution startedToolComplete- Tool finished successfullyToolError- Tool execution failed
§User Interaction
NeedClarification- Agent needs user input
§Progress Tracking
TaskListUpdated- Task list created or modifiedTaskListItemProgress- Individual item progressTaskListCompleted- All items completedTaskEvaluationStarted- Task evaluation beganTaskEvaluationCompleted- Task evaluation finishedGoldEvaluationStarted- Gold observe-only evaluation beganGoldEvaluationCompleted- Gold observe-only evaluation finished
§Context Management
TokenBudgetUpdated- Context budget changedContextCompressionStatus- Context compression lifecycle progressContextSummarized- Old messages summarized
§Sub-agents (Async Spawn)
SubAgentStarted- A child session is created and scheduled to runSubAgentEvent- Forwarded raw child event (full fidelity)SubAgentHeartbeat- Periodic heartbeat while the child is runningSubAgentCompleted- Child session finished (completed/cancelled/error)
§Terminal Events
Complete- Execution finished successfullyCancelled- Execution was cancelled by the userError- Execution failed
§Serialization
Events are serialized as JSON with a type field for discrimination:
{"type": "token", "content": "Hello"}
{"type": "complete", "usage": {"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15}}
{"type": "cancelled", "message": "Agent execution cancelled by user"}Variants§
Token
Text token generated by the LLM.
ReasoningToken
Reasoning/thinking token generated by the LLM.
This is streamed separately from assistant answer tokens so the UI can choose whether and how to display model reasoning traces.
ToolToken
Streaming output emitted while a specific tool call is running.
This is used to render “live output” inside a tool-call card in the UI without mixing tool output into the assistant’s main token stream.
Fields
ToolStart
Tool execution started.
Fields
ToolComplete
Tool execution completed successfully.
ToolError
Tool execution failed.
ToolLifecycle
Structured lifecycle event for tool execution tracking.
These events complement ToolStart/ToolComplete/ToolError with
richer metadata (mutability, auto-approval, wall-clock timing) and
are emitted by ToolEmitter (in bamboo-agent-tools).
Fields
NeedClarification
Agent needs clarification from the user.
Fields
TaskListUpdated
Emitted when task list is created or updated.
TaskListItemProgress
Emitted when a task item makes progress (delta update).
Fields
status: TaskItemStatusNew item status
TaskListCompleted
Emitted when all task items are completed.
Fields
TaskEvaluationStarted
Emitted when task evaluation starts.
TaskEvaluationCompleted
Emitted when task evaluation completes.
Fields
GoldEvaluationStarted
Emitted when gold observe-only evaluation starts.
Fields
checkpoint: GoldCheckpointEvaluation checkpoint
GoldEvaluationCompleted
Emitted when gold observe-only evaluation completes.
Fields
checkpoint: GoldCheckpointEvaluation checkpoint
decision: GoldDecisionGold decision for the current checkpoint
confidence: GoldConfidenceConfidence in the decision
TokenBudgetUpdated
Emitted when token budget is prepared (after context truncation)
Fields
usage: TokenBudgetUsageToken budget details
ContextCompressionStatus
Emitted when host-side context compression lifecycle changes.
Fields
ContextSummarized
Emitted when conversation context is summarized
Fields
ContextPressureNotification
Emitted when context pressure reaches warning or critical levels. Frontend should display this to the user as a proactive notification.
Fields
SubAgentStarted
A child session was spawned from a parent session (async background job).
Fields
SubAgentEvent
Forwarded raw child event to the parent session stream.
Child sessions are not allowed to spawn further sessions, so this should not nest.
SubAgentHeartbeat
Heartbeat emitted while a child session is running.
SubAgentCompleted
Child session finished (completed/cancelled/error).
Fields
PlanModeEntered
Plan mode was entered.
Fields
status: PlanModeStatusCurrent plan mode phase/status.
PlanModeExited
Plan mode was exited.
Fields
PlanFileUpdated
Plan file was updated.
Fields
RunnerProgress
Runner progress update emitted at the start of each agent turn.
Used to track live execution progress (round count, current activity) for diagnostic visibility, especially for child sessions.
SessionTitleUpdated
Session title was updated (auto-generated by backend or manually renamed via PATCH).
Fields
source: TitleSourceSessionPinnedUpdated
Session pinned flag was toggled via PATCH.
Replayable metadata event. pinned is an idempotent boolean so the
latest event wins; updated_at is used by the frontend to suppress
stale replays.
SessionCreated
A new session was created.
Change-feed event: durable, journaled, carried on the account /stream
feed so other clients can insert the session into their list without a
full GET /sessions poll.
SessionDeleted
A session was deleted.
Change-feed event: durable, journaled. Clients remove the session from their local list on receipt.
SessionCleared
A session’s message history was cleared (session kept).
Change-feed event: durable, journaled. Clients drop cached messages for the session and refetch lazily.
MessageAppended
A message was appended to a session.
Change-feed event: durable, journaled. The seq assigned to this event
on the account feed is the message’s feed coordinate (used by
GET /history/{id}?since={seq} to compute deltas). content is the
plain-text body matching what /history returns to the UI.
ExecutionStarted
Execution run has started and the runner is now active.
Emitted as the first event after a runner reservation succeeds,
before any token or tool events. Carries the run_id so the
frontend can correlate subsequent SSE events across reconnects.
Fields
ToolApprovalRequested
Tool execution requires user approval before proceeding.
Emitted when a permission checker determines that a tool call needs explicit user confirmation (e.g., mutating operations in restricted permission mode). The frontend should present the approval request and either grant or deny it.
Fields
Complete
Agent execution completed successfully.
Fields
usage: TokenUsageFinal token usage statistics
Cancelled
Agent execution was cancelled.
Error
Agent execution failed.
Implementations§
Source§impl AgentEvent
impl AgentEvent
Sourcepub fn session_id(&self) -> Option<&str>
pub fn session_id(&self) -> Option<&str>
Returns the session this event pertains to, when it carries one.
Used by the account change-feed to route each event to the right
client-side session without a per-session connection. For sub-agent
events the parent session id is returned (that is the session a client
observes in its list). Pure streaming/diagnostic variants (Token,
Complete, …) return None; those are ephemeral and never ride the
account feed anyway.
Sourcepub fn is_durable_change(&self) -> bool
pub fn is_durable_change(&self) -> bool
Whether this event belongs on the durable account change feed.
Durable change events are low-volume, journaled to disk, and resumable
via the account /stream feed. Ephemeral events — token-by-token
streaming (Token/ReasoningToken/ToolToken), heartbeats, live
budget/pressure gauges, and raw forwarded sub-agent events — return
false: they stay exclusively on the per-session /events/{id} stream.
Keeping them off the journal and the multiplexed feed is the core
data-transfer win. This method lives in core so both the server and the
engine forwarder can filter before cloning onto the feed.
Trait Implementations§
Source§impl Clone for AgentEvent
impl Clone for AgentEvent
Source§fn clone(&self) -> AgentEvent
fn clone(&self) -> AgentEvent
1.0.0 (const: unstable) · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read more