m4trixDocs

API Reference

AgentNetworkEvent

AgentNetworkEvent defines typed events with schema validation via Effect Schema.

Creating Events

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

Transient events

TypeScript
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), 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 may hold it.

Methods

.make(payload)

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

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

.makeBound(meta, payload)

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

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

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

.is(value)

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

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

Event Envelope

Every event has:

TypeScript
{
  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