Events Reference

Purpose and Scope

The Events Reference explains the observable activity surface that Flue exposes for agents, workflows, conversations, streams, and runtime observation subscribers. It is intended for developers who need to build clients, dashboards, exporters, replay tools, or debugging utilities on top of the runtime rather than only invoking an agent or workflow. The central idea is that Flue work produces structured activity records, and those records have a durable format that consumers can rely on. When a workflow starts, resumes, or finishes, or when an agent loop begins and ends, the runtime emits records that describe what happened and how the activity relates to a durable execution context.

Sources: apps/docs/src/content/docs/api/events-reference.md

This page also clarifies an important boundary between stored runtime events and live observations. Stored events are the replayable history of a runtime context. Live observations are delivered to observation subscribers while the process is active and may include additional normalized details for telemetry. Both surfaces can contain sensitive information because they reflect real prompts, workflow inputs, model interactions, tool results, transport payloads, logs, and errors. Treat the event stream as an application data surface, not as automatically safe analytics output. Exporters should apply their own redaction and retention policy before forwarding events to an external observability or analytics system.

Relevant Source Files

• apps/docs/src/content/docs/api/events-reference.md — Defines the public Events Reference documentation, including the exported runtime types, global observation API, event version contract, replay behavior, sanitization requirements, image omission sentinel, and lifecycle event meanings.

Public API Components

Observable runtime types and the global observation API are exported from the runtime package. Import these names from the package root when implementing event consumers or observation subscribers:

import {
  type AttachedAgentEvent,
  type FlueEvent,
  type FlueEventContext,
  type FlueObservation,
  observe,
  type FlueObservationSubscriber,
} from '@flue/runtime';

The core event type is the union for observable runtime activity. A consumer that stores or displays runtime history should begin with that union, then narrow by event name and context identifiers. The context type describes the durable environment around an event, while the attached-agent event type is used for agent activity that is associated with a surrounding runtime context. The observation type and subscriber type belong to the live observation surface. They are useful for instrumentation code that wants to inspect activity as it happens, but they should not be confused with the durable stream protocol used for replaying stored events.

Sources: apps/docs/src/content/docs/api/events-reference.md

The observation API is global because instrumentation usually needs to be installed once for a runtime process rather than passed through every agent, workflow, or route. A typical observer subscribes early during application startup, normalizes or filters the events it cares about, and exports them to a telemetry sink. The documentation warns that live observations can include normalized tool arguments and telemetry detail, so the correct pattern is to sanitize inside the exporter. Do not assume that a logging backend, tracing vendor, or metrics bridge will understand which fields are private in a Flue-specific payload.

Runtime Event Contract

Each delivered event uses the durable format version with value three. That version marker is not advisory; runtime and SDK readers reject nonmatching events and provide upgrade guidance instead of attempting compatibility fallbacks. This design gives clients a clear safety boundary. A reader either understands the event format or it does not. It should not silently reinterpret an older or newer structure, because event payloads can drive replay, user-visible histories, debugging views, and telemetry exports. Consumers should therefore validate the version before processing any record and should surface a clear operational error when the version is unsupported.

Every event also carries a per-context index and a timestamp. The index is especially important for clients that page, resume, or replay a stream from a known offset. Because the index is scoped to the context, consumers should pair it with the relevant run, instance, session, or stream identity rather than treating it as a globally unique number. The timestamp supports display ordering and diagnostics, but the index is the stronger replay coordinate for durable stream reads. Event consumers should preserve both fields when copying records into another database or telemetry pipeline.

Sources: apps/docs/src/content/docs/api/events-reference.md

Context identifiers tell a reader what kind of work produced the event. Workflow invocations emit workflow-run events with a run identifier. Direct prompts and asynchronously dispatched agent inputs emit agent activity with an instance identifier. Dispatched activity can also carry a dispatch identifier. The documentation explicitly states that those direct prompt and dispatch interactions are not workflow runs, even though they are durable agent activity. That distinction matters when building dashboards: a workflow-run page should group by workflow run identity, while an agent activity page should group by agent instance and optionally by dispatch correlation.

Event Families and Lifecycle Signals

The visible lifecycle table in the documentation names the foundational workflow and agent lifecycle events. Workflow runs begin with a start event, may record a resume event after recovery continues admitted work, and finish with an end event that includes result or error state and duration. Agent loops similarly emit start and end events. The resume event is particularly subtle: it records that recovery continued handling an admitted workflow run after interruption, but it does not mean workflow code resumed or retried. It can even be the first persisted lifecycle event when interruption occurs after admission but before the normal start event is stored.

These lifecycle records are useful anchors for richer event timelines. A workflow timeline can display input at the beginning, intermediate activity while the run is active, and a terminal result or error at the end. An agent timeline can show when the loop entered and exited, then nest prompts, model interactions, tool calls, logs, or stream updates around that span when those events are present. Consumers should avoid assuming that every run begins with the same first event because recovery and interruption can affect ordering. Instead, build timelines by reading the durable stream from an offset and rendering events according to their names and identifiers.

Sources: apps/docs/src/content/docs/api/events-reference.md

Durable Streams, Replay, and In-Process Delivery

Runtime events are durably stored in an event stream and can be replayed from any offset through the Durable Streams protocol. This makes the event system suitable for reconnecting clients, late subscribers, persisted audit views, and background processors that need to resume after a crash. A robust reader should keep track of the last accepted index for each context and request subsequent events from that point. Because records are durable, downstream processors should also be idempotent: receiving the same event again during replay should update or confirm state rather than duplicate user-visible entries.

One event is explicitly different: the turn request event is delivered only to in-process subscribers. It is not replayed from the durable stream. That exception prevents consumers from treating the observation surface and the replay surface as identical. If a feature depends on seeing a turn request, it must be installed as an active subscriber in the running process. If a feature needs to support historical reconstruction after reconnecting, it should use the durable event stream and avoid depending on in-process-only notifications. This separation is important for frontends, telemetry exporters, and tests that compare live behavior with replayed history.

Data Safety and Image Payload Rules

Flue events can contain highly sensitive material because they mirror the agent harness at runtime. Workflow inputs can include customer data. Provider and transport payloads can include service-specific messages. Prompts and system instructions can reveal task strategy or internal policy. Reasoning-bearing messages, logs, tool results, and terminal errors can expose secrets or personally identifiable information if application code includes them. The documentation therefore recommends an exporter-local sanitization policy for both stored events and live observations. Sanitization belongs near the exporter because different destinations have different privacy, compliance, and retention requirements.

Recognized image content blocks in framework event payloads follow a specific safety rule. They keep the media type, but the raw image bytes are replaced with the sentinel string for omitted image data. That sentinel is exported from both the runtime package and the SDK package, allowing servers and clients to recognize the placeholder consistently. This rule applies to framework-recognized image content blocks, not to arbitrary application-authored data payloads. If an application emits its own data event, that payload is persisted verbatim and is not automatically cleaned by the framework.

Sources: apps/docs/src/content/docs/api/events-reference.md

Attachment handling follows the same boundary. Canonical conversation records retain attachment references, while the private attachment store retains verified bytes for model context. Event consumers should present attachment references as references, not as proof that raw bytes are present in the event stream. Producers should avoid placing raw image bytes, secrets, or unsanitized personal data into application-authored data events. A safe client can render the media type and omission sentinel for recognized image blocks, then request attachments through an authenticated path designed for that purpose rather than scraping bytes from the event payload.

Implementation Guidance for Consumers

When implementing a reader, start by distinguishing workflow-run activity from agent-instance activity. Workflow invocations are keyed by a run identity, while direct prompts and dispatched agent inputs are keyed by an instance identity and may include dispatch correlation. Then validate the format version, preserve the context index, and process events in stream order. If the reader is a frontend, use the index as a reconnection checkpoint. If the reader is an exporter, use the same index to avoid duplicating logs or spans after a restart. If the reader is a test helper, assert on event names and context fields rather than brittle timestamps.

When implementing an observer, subscribe near process startup and keep the subscriber small. Observation callbacks should normalize, redact, and enqueue telemetry rather than performing slow network work inline. Because observations may include normalized tool arguments and telemetry detail, use a deny-by-default policy for fields that can carry prompts, inputs, transport payloads, or tool results. If you need long-term replay, pair observation output with the durable event stream rather than relying only on live callbacks. The event reference intentionally gives both surfaces names so applications can choose the right one for their operational goal.

Related Pages and Next Steps

Read the Agent API next when you need to understand how direct prompts, asynchronous dispatch, sessions, tools, and subagents create agent activity. Read the Workflow API when you need to understand how workflow definitions produce run identities and lifecycle events. Read the Streaming Protocol page when building a client that reconnects and replays durable activity from an offset. Read the Observability guide when connecting the observation API to OpenTelemetry or another exporter. For any exporter or client, finish by documenting the local sanitization policy, because Flue deliberately preserves application-authored data unless the producer or exporter removes it.