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
• thread replay from durable thread 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, thread 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: event envelopes, custom discriminators, and AOT metadata.
• Canonical And Process-Local Events: choose between replayable thread facts and process-local activity.
• 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: read control state and receive committed events over resumable SSE.
• Thread History And Forking: read durable thread event history.
• Events Reference: event families, envelopes, and publication semantics.

Core Rule

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

ordered 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.

Thread-scoped projectable events commit to the canonical journal before publication. Process-local diagnostics, metrics, and high-volume samples use their dedicated runtime surfaces. Choose the publication surface according to whether the event must participate in replay and thread reconstruction.