Draft — not yet ratified. This document is published for review. It
describes the intended 1.0 behaviour, its wording is not final, and nothing
here is covered by a compatibility promise until a version is frozen. Do not
cite it as a stable reference.
Events
STATE_SNAPSHOT
Replaces the agent state wholesale. Sent when a delta cannot express the
change, or to resynchronise a consumer. A consumer MUST replace its state with
snapshot — no merging.
STATE_DELTA
Amends the current state with an RFC 6902 patch. The baseline is the
consumer’s current state: at the start of a run, the input’s state; after
that, whatever the run’s own snapshots and deltas have made of it. Everything
the pattern says about patches —
atomic application, open operations, failure handling, resynchronisation —
applies unchanged.
MESSAGES_SNAPSHOT
The complete set of messages the producer owns, in order.
It is conversation-wide rather than a plain overwrite, because a consumer may
hold messages of its own that no producer tracks. Reconciliation:
- A message in the snapshot replaces the consumer’s copy with the same id —
in place: the consumer keeps its existing position for a message it
already holds. A snapshot message the consumer has never seen is appended,
in snapshot order. The snapshot’s order is therefore authoritative only for
messages the consumer meets for the first time; it does not reorder what the
consumer already has.
- A consumer-held message absent from the snapshot is dropped — the producer
is declaring the complete set — except client-only material the producer
cannot know about: activity messages, which
never travel to the producer, and reasoning messages, which most producers
do not track.
- The exception is per-role and self-revoking: a snapshot that itself carries
any activity message is declaring the complete activity set, and the
consumer’s activity messages not in it are dropped like anything else. The
same rule holds for reasoning messages.
Being conversation-wide, the snapshot carries no subagentRunId of its own;
it establishes each message’s ownership through the messages it contains.
Cross-run behaviour
State persists across runs on a thread until an event replaces it, and the
next run’s input carries it back as the starting value — the loop that keeps
both sides agreed. Messages accumulate the same way;
MESSAGES_SNAPSHOT is the producer’s way of restating that accumulation
outright.
Message Flow
Data Types
StateSnapshotEvent, StateDeltaEvent and MessagesSnapshotEvent are defined
by the schema reference, with State deliberately
unconstrained — any JSON value, not only an object — and deltas as
JsonPatch.
Error Handling
A structurally malformed patch is fatal; a well-formed patch that fails to
apply is warned about and skipped, per the
pattern.
Security Considerations
State events are remote writes into application state. An application MUST
validate what it reads out of state before acting on it — rendering it,
executing it, granting anything because of it — exactly as it would validate
any other input that crossed a trust boundary. A producer, in turn, SHOULD NOT
put secrets in state: it round-trips through the consumer and back on every
run.
