Events Overview

Events are the runtime language of HPD Agent. They are how local apps, hosted clients, TUIs, bot adapters, middleware, sessions, workflows, and subagents observe what is happening during a run.

The simplest event experience is streaming text. The broader event model lets you build:

• transcripts from text and reasoning events
• tool timelines from tool-call events
• permission prompts from bidirectional interactive events
• workflow timelines from workflow events
• subagent and multi-agent views from metadata and child events
• trace views from trace/span fields
• branch replay from durable branch events

What To Read

Start here:

• Streaming Events: first local subscription.
• Event Streams And Hierarchies: the mental model for flat streams and nested projections.
• Render An Event Stream: practical rendering guidance for UIs and clients.
• Tool And Function Events: render tool calls and emit progress from tool code.
• Bidirectional Events: request/response event flows for permissions, clarification, and host decisions.
• TypeScript Client Events: consume live streams, branch history, custom events, and interactive requests from TypeScript apps.
• Custom Events: define app-specific events, emit them from middleware, and stream them through the serializer.
• Serialization And Registration: live envelopes, custom discriminators, and AOT metadata.
• Live Vs Durable Events: what streams live and what becomes branch history.
• Lifecycle, Retry, And Error Events: turn lifecycle, retries, and failure rendering.
• Testing Event-Driven Code: capture and assert event-driven behavior.
• Logging And Telemetry: export agent events and usage into logs and metrics.

Then use focused pages:

• Workflow Events: render workflow progress, nodes, layers, and routes.
• Permissions Middleware: answer bidirectional permission events.
• Hosted Streaming API: receive events over SSE or WebSocket.
• Branch History And Forking: read durable branch event history.
• Events Reference: event families, envelopes, and persistence caveats.

Core Rule

HPD sends events linearly. Your app projects them into the shape it needs.

live event stream
  -> transcript
  -> tool timeline
  -> permission queue
  -> workflow tree
  -> subagent view
  -> trace/debug log

For hierarchy, use the most specific correlation fields available: MessageId for message content, CallId for tools, request ids such as PermissionId for bidirectional flows, workflow node ids for workflows, agent metadata for child-agent labels, and trace/span fields for trace views.

Do not treat live rendering as persistence. Durable branch history only includes events that are mapped or opt in to branch persistence.