AgentEvent

Category: Core

Source: agent_event.dart

Events emitted by the agent loop that the surface (UI, ACP, web) subscribes to.

Status: part of the proposed core data model — see docs/plans/2026-04-29-harness-layers.md. Originally lived in agent/agent_core.dart. This is the current agent-event vocabulary; the richer [SessionEvent] hierarchy in session_event.dart is the proposed future contract.

Classes

sealed AgentEvent

Events emitted by the agent that the UI subscribes to.

AgentTextDelta

A delta of generated text forwarded to the UI.

Constructor

AgentTextDelta(this.delta)

Properties

Property	Type	Description
delta	String

AgentThinkingDelta

A delta of streaming reasoning/"thinking" content forwarded to the UI. Only emitted by reasoning-capable models. Renderers should style this distinctly from [AgentTextDelta] (typically dim + italic) so users see the reasoning as an aside, not as the final answer.

Constructor

AgentThinkingDelta(this.delta)

Properties

Property	Type	Description
delta	String

AgentToolCallPending

Notification that a tool call is being prepared.

Constructor

AgentToolCallPending({required this.id, required this.name})

Properties

Property	Type	Description
id	ToolCallId
name	String

AgentToolCall

A fully-formed tool call ready for execution.

Constructor

AgentToolCall(this.call)

Properties

Property	Type	Description
call	ToolCall

AgentToolResult

The result of an executed tool call.

Constructor

AgentToolResult(this.result)

Properties

Property	Type	Description
result	ToolResult

AgentDone

Signals that the agent has finished its response.

AgentUsage

Token usage reported by the LLM for one call. Forwarded as an [AgentEvent] so [AgentRunner], surfaces, and the session log can aggregate per-call costs without poking inside [AgentCore].

Constructor

AgentUsage(this.usage)

Properties

Property	Type	Description
usage	UsageInfo

AgentError

An error encountered during the agent loop.

Constructor

AgentError(this.error)

Properties

Property	Type	Description
error	Object

AgentNotice

Non-fatal informational message addressed to the user via the transcript surface. Use for soft-degradation announcements — e.g. "tools disabled for this session because the model doesn't support them" — where the agent loop kept running but the user should know something changed.

Every new surface (TUI, ACP, JSON, print) must learn to render this — it's not optional. The fallback behaviour is to skip the notice silently, which masks soft degradation from users.

Constructor

AgentNotice(this.message, {this.kind = 'info'})

Properties

Property	Type	Description
message	String	Single-line human-readable text. No leading marker glyph — surfaces add their own (TUI uses markerInfo/markerWarn, --print uses ! on stderr).
kind	String	info (default) for "FYI" messages, warning for soft-degradation announcements the user should react to. Forward-compatible string rather than an enum so adding new kinds doesn't break compile.