Enum AgentEvent 

#[non_exhaustive]
pub enum AgentEvent {
    TextDelta(String),
    TurnCompleted,
    ToolCallStarted {
        id: String,
        name: String,
        arguments: String,
    },
    ToolCallCompleted {
        id: String,
        name: String,
        output: String,
        is_error: bool,
    },
    CacheWarning {
        message: String,
    },
    Usage(Usage),
    BackgroundOutput {
        job_id: String,
        chunk: String,
        truncated: bool,
    },
}

Streaming events emitted by a native runtime agent as a turn unfolds.

Attach an EventSink to a runtime configuration to observe these live — for example to render tokens to a terminal as they arrive, or to surface tool activity in a UI.

#[non_exhaustive] because new event kinds will be added over time; match with a _ arm so a new variant is not a breaking change.

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.

TextDelta(String)

A chunk of assistant text was produced.

TurnCompleted

The assistant finished a text/tool turn (one round-trip to the model).

ToolCallStarted

The model requested a tool call (fired before the tool runs).

Fields

id: String

Provider-assigned call id.

name: String

Tool name.

arguments: String

Raw JSON argument string as sent by the model.

ToolCallCompleted

A tool finished running.

Fields

id: String

Provider-assigned call id.

name: String

Tool name.

output: String

The tool’s textual output (truncated for display upstream if needed).

is_error: bool

Whether the tool reported an error.

CacheWarning

UX-26 (B7-warn): the turn that just completed likely paid a full-price prompt-cache miss despite reuse being expected under an imported-prefix cache plan. Emitted at most once per turn, only when cache warnings are enabled (default on) and reuse was genuinely expected (never on a first/establishing request, a same-turn tool-schema-tier bust, or under a disabled cache plan — so this never fires as a false positive on a cold-by-design request).

Fields

message: String

Ready-to-print, human-readable warning line (no trailing newline).

Usage(Usage)

UX-23: token accounting for the request that just completed (one per model round-trip — a multi-tool-call turn emits one of these per round-trip, same cadence as AgentEvent::TurnCompleted, which this is always emitted immediately before). Reuses the provider completion’s usage return rather than introducing a second accounting path, so --trace/stream-json consumers see exactly the numbers the provider reported — never a derived estimate.

BackgroundOutput

P5-6 (COMPOSABLE-HARNESS-DESIGN.md §2 module 4 tools.background, D1 “monitor/event feed”): new output a background job (spawned via the background_exec intrinsic) has produced since the last background_status poll — the “event feed” capabilities. tools_background promises. Emitted from the runtime agent’s background-status operation, at most once per poll, only when there IS new output (an idle poll of a still-running job with nothing new to report emits nothing).

Fields

job_id: String

The job id background_exec returned.

chunk: String

The newly captured text since the previous poll (never a repeat of already-emitted output).

truncated: bool

Whether this job’s RETAINED capture has hit capabilities.tools_background.max_output_bytes — chunk itself is never truncated mid-character, but once this is true no further output from this job will ever be retained or emitted, even though the process may still be producing it.

Implementations

impl AgentEvent

pub fn tool_started(call: &ToolCall) -> Self

Build the event emitted immediately before a tool call executes.

pub fn to_json(&self) -> Value

P5-8 (§2 module 31 server, completing Obligation 9’s “partial” core commitment): the canonical {"type": ..., ...} JSONL projection of this event — field names mirror the enum’s own (id/name/arguments/output/is_error/prompt_tokens/…) rather than a hand-maintained parallel vocabulary, so the wire shape can never silently drift from the enum it projects.

Shared by the CLI’s --output-format stream-json sink (UX-23) and the server module’s RPC/SSE event-notification channel, so both out-of-process surfaces stay byte-identical for the same event instead of maintaining two hand-written projections that could silently diverge.

Match is exhaustive with NO wildcard arm on purpose: #[non_exhaustive] only affects callers OUTSIDE this crate (it forced the CLI’s old, external copy of this projection to carry a {"type":"unknown"} fallback arm) — from INSIDE the crate that defines the enum, adding a future AgentEvent variant makes this fail to COMPILE until it’s given a real projection here, which is strictly safer than silently falling back to an opaque "unknown" line for a new event kind.

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.