Enum AgentEvent 

pub enum AgentEvent {
    AgentMessageChunk {
        session_id: String,
        content: String,
    },
    AgentThoughtChunk {
        session_id: String,
        content: String,
    },
    ToolCall {
        session_id: String,
        tool_call_id: String,
        tool_name: String,
        kind: Option<ToolKind>,
        status: ToolCallStatus,
        raw_input: Value,
        parsing: Option<bool>,
        audit: Option<MutationSessionRecord>,
    },
    ToolCallUpdate {

        session_id: String,
        tool_call_id: String,
        tool_name: String,
        status: ToolCallStatus,
        raw_output: Option<Value>,
        error: Option<String>,
        duration_ms: Option<u64>,
        execution_duration_ms: Option<u64>,
        error_category: Option<ToolCallErrorCategory>,
        executor: Option<ToolExecutor>,
        parsing: Option<bool>,
        raw_input: Option<Value>,
        raw_input_partial: Option<String>,
        audit: Option<MutationSessionRecord>,
    
},
    Plan {
        session_id: String,
        plan: Value,
    },
    TurnStart {
        session_id: String,
        iteration: usize,
    },
    TurnEnd {
        session_id: String,
        iteration: usize,
        turn_info: Value,
    },
    JudgeDecision {
        session_id: String,
        iteration: usize,
        verdict: String,
        reasoning: String,
        next_step: Option<String>,
        judge_duration_ms: u64,
    },
    TypedCheckpoint {
        session_id: String,
        checkpoint: Value,
    },
    FeedbackInjected {
        session_id: String,
        kind: String,
        content: String,
    },
    BudgetExhausted {
        session_id: String,
        max_iterations: usize,
    },
    LoopStuck {
        session_id: String,
        max_nudges: usize,
        last_iteration: usize,
        tail_excerpt: String,
    },
    DaemonWatchdogTripped {
        session_id: String,
        attempts: usize,
        elapsed_ms: u64,
    },
    SkillActivated {
        session_id: String,
        skill_name: String,
        iteration: usize,
        reason: String,
    },
    SkillDeactivated {
        session_id: String,
        skill_name: String,
        iteration: usize,
    },
    SkillScopeTools {
        session_id: String,
        skill_name: String,
        allowed_tools: Vec<String>,
    },
    ToolSearchQuery {
        session_id: String,
        tool_use_id: String,
        name: String,
        query: Value,
        strategy: String,
        mode: String,
    },
    ToolSearchResult {
        session_id: String,
        tool_use_id: String,
        promoted: Vec<String>,
        strategy: String,
        mode: String,
    },
    TranscriptCompacted {
        session_id: String,
        mode: String,
        strategy: String,
        archived_messages: usize,
        estimated_tokens_before: usize,
        estimated_tokens_after: usize,
        snapshot_asset_id: Option<String>,
    },
    Handoff {
        session_id: String,
        artifact_id: String,
        handoff: Box<HandoffArtifact>,
    },
    FsWatch {
        session_id: String,
        subscription_id: String,
        events: Vec<FsWatchEvent>,
    },
    WorkerUpdate {
        session_id: String,
        worker_id: String,
        worker_name: String,
        worker_task: String,
        worker_mode: String,
        event: WorkerEvent,
        status: String,
        metadata: Value,
        audit: Option<Value>,
    },
    HitlRequested {
        session_id: String,
        request_id: String,
        kind: String,
        payload: Value,
    },
    HitlResolved {
        session_id: String,
        request_id: String,
        kind: String,
        outcome: String,
    },
    LoopControlDecision {
        session_id: String,
        iteration: usize,
        action: String,
        old_limit: usize,
        new_limit: usize,
        reason: String,
        status: String,
    },
    AgentLoopStallWarning {
        session_id: String,
        warning: Value,
    },
    ToolCallAudit {
        session_id: String,
        tool_call_id: String,
        tool_name: String,
        audit: Value,
    },
}

Events emitted by the agent loop. The first five variants map 1:1 to ACP sessionUpdate variants; the last three are harn-internal.

Variants

AgentMessageChunk

Fields

session_id: String

content: String

AgentThoughtChunk

Fields

session_id: String

content: String

ToolCall

Fields

session_id: String

tool_call_id: String

tool_name: String

kind: Option<ToolKind>

status: ToolCallStatus

raw_input: Value

parsing: Option<bool>

Set to Some(true) by the streaming candidate detector (harn#692) when this event represents a tool-call shape detected in the model’s in-flight assistant text but whose arguments have not finished parsing yet. Clients can render a spinner / placeholder while the model writes the body. The detector follows up with a ToolCallUpdate { parsing: false, .. } carrying either status: pending (promoted) or status: failed with error_category: parse_aborted. None (the default) means “this is a normal post-parse tool call, no candidate phase was active” so the on-disk shape stays compatible with replays recorded before this field existed.

audit: Option<MutationSessionRecord>

Mutation-session audit context active when the tool was dispatched (see harn#699). Hosts use it to group every tool emission belonging to the same write-capable session.

ToolCallUpdate

Fields

session_id: String

tool_call_id: String

tool_name: String

status: ToolCallStatus

raw_output: Option<Value>

error: Option<String>

duration_ms: Option<u64>

Wall-clock milliseconds from the parse-to-execution boundary to the terminal Completed/Failed update. Includes the time spent in any wrapping orchestration logic (loop checks, post-tool hooks, microcompaction). Populated only on the terminal update — None on intermediate Pending / InProgress updates so clients can ignore the field until it shows up.

execution_duration_ms: Option<u64>

Milliseconds spent in the actual host/builtin/MCP dispatch call only (the inner dispatch_tool_execution window). Populated only on the terminal update; None otherwise.

error_category: Option<ToolCallErrorCategory>

Structured classification of the failure (when status is Failed). Paired with error so clients can render each category distinctly without parsing free-form strings. Always None for non-Failed updates and serialized as errorCategory in the ACP wire format.

executor: Option<ToolExecutor>

Where the tool actually ran. None only for events emitted from sites that pre-date the dispatch decision (e.g. the pending → in-progress transition the loop emits before the dispatcher picks a backend).

parsing: Option<bool>

Companion to ToolCall.parsing (harn#692). The streaming candidate detector emits the terminal candidate event as a ToolCallUpdate with parsing: Some(false) to retract the in-flight parsing: true chip — either by promoting the candidate (status: pending, populated raw_output: None, error: None) or aborting it (status: failed, error_category: parse_aborted). None means this update is not part of a candidate-phase transition.

raw_input: Option<Value>

Best-effort partial parse of the streamed tool-call arguments. Populated by the SSE transport on Pending updates as the model streams input_json_delta (Anthropic) or tool_calls[].function.arguments deltas (OpenAI). None on terminal updates and on emissions from non-streaming paths (#693). When the partial bytes are not yet parseable as JSON the transport falls back to raw_input_partial.

raw_input_partial: Option<String>

Raw concatenated bytes of the streamed tool-call arguments when a permissive parse failed (#693). Mutually exclusive with raw_input: clients render whichever is present.

audit: Option<MutationSessionRecord>

Mutation-session audit context for the tool call. Carries the same payload as on the paired ToolCall event so a host processing a single update doesn’t have to correlate against the prior pending event.

Plan

Fields

session_id: String

plan: Value

TurnStart

Fields

session_id: String

iteration: usize

TurnEnd

Fields

session_id: String

iteration: usize

turn_info: Value

JudgeDecision

Fields

session_id: String

iteration: usize

verdict: String

reasoning: String

next_step: Option<String>

judge_duration_ms: u64

TypedCheckpoint

Fields

session_id: String

checkpoint: Value

FeedbackInjected

Fields

session_id: String

kind: String

content: String

BudgetExhausted

Emitted when the agent loop exhausts max_iterations without any explicit break condition firing. Distinct from a natural “done” or a “stuck” nudge-exhaustion: this is strictly a budget cap.

Fields

session_id: String

max_iterations: usize

LoopStuck

Emitted when the loop breaks because consecutive text-only turns hit max_nudges. Parity with BudgetExhausted / TurnEnd for hosts that key off agent-terminal events.

Fields

session_id: String

max_nudges: usize

last_iteration: usize

tail_excerpt: String

DaemonWatchdogTripped

Emitted when the daemon idle-wait loop trips its watchdog because every configured wake source returned None for N consecutive attempts. Exists so a broken daemon doesn’t hang the session silently.

Fields

session_id: String

attempts: usize

elapsed_ms: u64

SkillActivated

Emitted when a skill is activated. Carries the match reason so replayers can reconstruct why a given skill took effect at this iteration.

Fields

session_id: String

skill_name: String

iteration: usize

reason: String

SkillDeactivated

Emitted when a previously-active skill is deactivated because the reassess phase no longer matches it.

Fields

session_id: String

skill_name: String

iteration: usize

SkillScopeTools

Emitted once per activation when the skill’s allowed_tools filter narrows the effective tool surface exposed to the model.

Fields

session_id: String

skill_name: String

allowed_tools: Vec<String>

ToolSearchQuery

Emitted when a tool_search query is issued by the model. Carries the raw query args, the configured strategy, and a mode tag distinguishing the client-executed fallback ("client") from provider-native paths ("anthropic" / "openai"). Mirrors the transcript event shape so hosts can render a search-in-progress chip in real time — the replay path walks the transcript after the turn, which is too late for live UX.

Fields

session_id: String

tool_use_id: String

name: String

query: Value

strategy: String

mode: String

ToolSearchResult

Emitted when tool_search resolves — carries the list of tool names newly promoted into the model’s effective surface for the next turn. Pair-emitted with ToolSearchQuery on every search.

Fields

session_id: String

tool_use_id: String

promoted: Vec<String>

strategy: String

mode: String

TranscriptCompacted

Fields

session_id: String

mode: String

strategy: String

archived_messages: usize

estimated_tokens_before: usize

estimated_tokens_after: usize

snapshot_asset_id: Option<String>

Handoff

Fields

session_id: String

artifact_id: String

handoff: Box<HandoffArtifact>

FsWatch

Fields

session_id: String

subscription_id: String

events: Vec<FsWatchEvent>

WorkerUpdate

Lifecycle update for a delegated/background worker. Carries the canonical typed event variant alongside the worker’s current status string and the structured metadata payload that worker_bridge_metadata builds (task, mode, timing, child run/snapshot paths, audit-session, etc.). The audit field is the same MutationSessionRecord JSON serialization carried on the bridge wire so ACP/A2A consumers don’t need to re-derive it.

One-to-one with the bridge-side worker_update session-update notification: ACP and A2A adapters subscribe to this variant and translate it into their respective wire formats. The session_id is the parent agent session that owns the worker (i.e. the session whose VM spawned the worker), so a single host stays subscribed to the same sink for both message and worker traffic.

Fields

session_id: String

worker_id: String

worker_name: String

worker_task: String

worker_mode: String

event: WorkerEvent

status: String

metadata: Value

audit: Option<Value>

HitlRequested

A human-in-the-loop primitive (ask_user, request_approval, dual_control, escalate) has just suspended the script and is waiting on a response. Hosts that bridge the VM onto a remote transport (ACP, A2A) translate this into a “paused / awaiting input” wire signal so the client knows the task isn’t stuck — it’s blocked on the human side. Pair-emitted with HitlResolved when the waitpoint completes/cancels/times out.

Fields

session_id: String

request_id: String

kind: String

payload: Value

HitlResolved

Companion to HitlRequested: the waitpoint has resolved (either a response arrived, the deadline elapsed, or the request was cancelled). outcome is one of "answered", "timeout", "cancelled". Hosts use this to flip task state back to working after an input-required pause.

Fields

session_id: String

request_id: String

kind: String

outcome: String

LoopControlDecision

Emitted by the agent loop’s adaptive iteration budget / loop_control policy when a budget extension or early stop fires. Generic enough to cover both shapes — action distinguishes them. Carries the iteration the decision applied to, the previous / resulting iteration limit, the policy reason string, and (for stops) the loop status.

Fields

session_id: String

iteration: usize

action: String

old_limit: usize

new_limit: usize

reason: String

status: String

AgentLoopStallWarning

Emitted when agent_loop detects adjacent repeated tool calls with identical arguments. The warning payload avoids raw arguments by default and carries digests so hosts can correlate repeats without exposing potentially sensitive tool inputs.

Fields

session_id: String

warning: Value

ToolCallAudit

Emitted when a tool_caller middleware (see std/llm/tool_middleware) attaches structured audit metadata to a tool call — typically a user-facing summary, a description, an ACP-style kind, an MCP hints block, a consent decision, the per-layer layers log, or free-form metadata keys (A2A-style extension slot).

One-to-one with the underlying tool-call: hosts can join on tool_call_id to render middleware-attached chips alongside the existing ToolCall / ToolCallUpdate stream. The audit payload is intentionally free-form JSON so middleware can carry whatever shape the harness author chooses without needing protocol-level changes per new middleware.

Fields

session_id: String

tool_call_id: String

tool_name: String

audit: Value

Implementations

impl AgentEvent

pub fn session_id(&self) -> &str

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.