> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# events

> `protected` `readonly` **events**: [`EventLog`](/docs/agent-sdk/interface/events)

The agent's persistent progress-event stream.

An append-only, count-bounded log ordered by an assigned monotonic `seq`.
Events committed via [`emit`](/docs/agent-sdk/interface/events#emit) are pushed live to
connected clients subscribed to the `events` stream — no broadcast call
needed. See [EventLog](/docs/agent-sdk/interface/events) for emitting, cursor reads, and retention.

## emit()

> **emit**(`type`, `payload`): `Promise`\<`number`>

Append one event; returns its assigned seq. Atomic (counter + row +
pruning). If the log is at its retention bound, the oldest row(s) are
pruned in the same transaction.

**Parameters**

| Parameter | Type |
| - | - |
| `type` | `string` |
| `payload` | `unknown` |

**Returns**

`Promise`\<`number`>

## read()

> **read**(`afterSeq?`, `limit?`): `Promise`\<[`StoredEvent`](/docs/agent-sdk/interface/events#storedevent)\[]>

Read retained events in seq order. `afterSeq` is an exclusive cursor:
only events with `seq > afterSeq` are returned (default 0 = from the
start). `limit` caps the number of rows; omitted = all retained rows
(paginates internally past the per-list cap).

**Parameters**

| Parameter | Type | Default value |
| - | - | - |
| `afterSeq` | `number` | `0` |
| `limit?` | `number` | `undefined` |

**Returns**

`Promise`\<[`StoredEvent`](/docs/agent-sdk/interface/events#storedevent)\[]>

## count()

> **count**(): `Promise`\<`number`>

Total events ever emitted (the current seq high-water mark).

**Returns**

`Promise`\<`number`>

## new EventLog()

> **new EventLog**(`storage`, `options?`, `onEmit?`): [`EventLog`](/docs/agent-sdk/interface/events)

Create a log over the actor's persistent storage — typically once, as a
class field, so the log shares the actor's persistence and single-writer
guarantees. One actor can hold several logs for unrelated streams; each
instance keys its rows independently.

```ts theme={null}
class ResearchAgent extends Agent<MyEnv> {
  private readonly activity = new EventLog(this.ctx.storage, { retain: 500 });
}
```

**Parameters**

| Parameter | Type | Description |
| - | - | - |
| `storage` | [`ActorStorage`](/docs/edge-compute/stateful-actors/api-reference/storage) | The actor's persistent storage. |
| `options` | [`EventLogOptions`](/docs/agent-sdk/interface/events#eventlogoptions) | Retention configuration — see [EventLogOptions](/docs/agent-sdk/interface/events#eventlogoptions). |
| `onEmit?` | (`event`) => `void` | Optional hook fired after each emit **commits**, with the stored event exactly as persisted. The `Agent` base class uses it to push committed events to connected clients; hook failures propagate to the emitting caller. |

**Returns**

[`EventLog`](/docs/agent-sdk/interface/events)

## StoredEvent

A progress event as persisted: assigned a monotonic seq + wall-clock stamp.

**Properties**

**at**

> **at**: `Date`

Wall-clock stamp at emit time; informational only (ordering is by `seq`).

***

**payload**

> **payload**: `unknown`

Arbitrary payload. MUST be codec-safe (JSON-native + Date/Map/Set/
ArrayBuffer/TypedArray/Buffer/BigInt/RegExp) — it is stored via
`ctx.storage.put`, which throws `CodecError` on functions, class instances,
or circular refs.

***

**seq**

> **seq**: `number`

Monotonic sequence number, assigned on emit — never reused, only moves forward.

***

**type**

> **type**: `string`

Caller-chosen event kind (e.g. "progress").

## EventLogOptions

Options for the event log.

**Properties**

**retain?**

> `optional` **retain?**: `number`

Maximum number of event rows kept (count-based retention). Once the log
holds this many rows, each new emit prunes the oldest. Default 1000.