> Documentation index for m4trix: https://m4trix.dev/llms.txt. Every page is available as Markdown by appending `.md` to its URL.

# AgentNetworkEvent

Source: https://m4trix.dev/docs/api-reference/agent-network-event

`AgentNetworkEvent` defines typed events with schema validation via [Effect Schema](https://effect.website/).

## Creating Events

```ts
AgentNetworkEvent.of(name, schema)
```

```ts
const myEvent = AgentNetworkEvent.of('my-event', S.Struct({ value: S.Number }));
```

### Transient events

```ts
const tokenDelta = AgentNetworkEvent.of('token-delta', S.Struct({ text: S.String }), {
  transient: true,
});
```

`transient` (default `false`) marks events that may be dropped under back-pressure, such as token deltas or progress ticks. When an agent's mailbox for a run is full, a new transient event replaces the oldest buffered transient event instead of making the publisher wait (and is dropped if there is none to replace). Durable events always wait for room. Transient events are streamed and traced but never written to the network's store, so they never appear in `ctx.history`. The flag is readable as `myEvent.transient`.

A plane knows an event is transient when an agent or aggregator started on it declares its definition (with `transient: true`) in `listensTo` or `emits`. An event only published from outside (e.g. `plane.publish`) whose definition no agent or aggregator of the network declares is treated as durable.

Only a transient event may carry a secret (`S.Redacted`): it is never stored, and streams send each `Redacted` value as `"<redacted>"`, the rest of the payload encoded with its schema as usual (a payload the schema cannot encode is sent as `"<redacted>"` as a whole). A durable event whose schema holds `S.Redacted` anywhere fails `AgentNetwork.setup()` ([`durable-event-redacted`](https://m4trix.dev/docs/api-reference/agent-network.md#wiring-check)), since its encoded form, the one stored and streamed, is the secret in clear.

## Stored and streamed form

Inside the network a payload is a value of the schema's type: what `make` returns, what agents emit and receive as `triggerEvent`, what fold handlers get. The store, and everything that leaves the network (SSE streams, outbound proxies, `ctx.history`), carry it **encoded** with the schema (`S.encode`), as JSON: a `Date` under `S.Date` as an ISO string, `S.NumberFromString` as a string, an `Option` as `{ _tag, value }`. For a schema without transformations (strings, numbers, booleans, literals, structs, arrays) both forms are the same. So an emitted payload must encode to JSON, as `JSON.stringify` writes it: a value with a `toJSON` method in an `S.Unknown` field is stored as what that returns (a `Date` from a database row as its ISO string, which is what folds, history and streams see), but a `Map`, `Set`, `Error` or class instance without one, and a field typed `S.DateFromSelf` (its ISO string is no `Date`), make the emit throw `EmitValidationError`; give such values a schema that encodes them, or convert them first. `.is` checks the decoded form, so for events read from history or a stream it **silently returns `false`** when the schema transforms (no error): decode them with `.decode` (or `S.decodeUnknownSync(myEvent.payload)(event.payload)`). In the encoded form a field renamed with `S.fromKey` is under its encoded key and an `Option` is `{ _tag, value }` (no `_id`). `S.Redacted` would be the secret itself, in clear, so only [transient events](#transient-events) may hold it.

## Methods

### `.make(payload)`

Creates an unbound event (name + payload) for use with `emit`. Meta is injected by the runtime when emitted.

```ts
emit(myEvent.make({ value: 42 }));
```

### `.makeBound(meta, payload)`

Creates a full envelope for tests or manual triggers. Sync, throws on invalid data.

```ts
const envelope = myEvent.makeBound(
  { runId: crypto.randomUUID() },
  { value: 42 },
);
```

### `.makeEffect(payload)`

Effect version of `make`. Use in Effect pipelines.

### `.makeBoundEffect(meta, payload)`

Effect version of `makeBound`.

### `.decode(unknown)`

Decodes an unknown value into a validated event envelope. Useful for parsing incoming requests.

```ts
const result = Effect.runSync(myEvent.decode(rawData));
```

### `.is(value)`

Type guard that checks whether an unknown value matches this event's shape.

```ts
if (myEvent.is(someValue)) {
  console.log(someValue.payload.value);
}
```

## Event Envelope

Every event has:

```ts
{
  name: string;           // Event name
  meta: {
    runId: string;
    contextId: string;
    eventId?: string;       // Unique id; set on publish when missing
    correlationId?: string; // Shared by an emitAndAwait request and its replies
    causationId?: string;   // eventId of the event whose handling emitted this one
    ts?: number;            // Publish time (epoch ms); set on publish when missing
    depth?: number;         // Hops from the run's start event (0); checked against maxDepth
  };
  payload: T;            // Validated against schema
}
```

## See Also

- [Events (Concepts)](https://m4trix.dev/docs/concepts/events.md)
- [Channels](https://m4trix.dev/docs/api-reference/channel-api.md)