Glossary
Canonical terms used across the product docs.
Name the artifact in a bug report
“The agent failed” hides whether the problem belongs to a protocol, endpoint, participant, transcript, journal, or trace. Use the narrower word; it points to the boundary that can actually change.
Protocol and projection
| Term | Definition |
|---|---|
| global conversation | The whole-session protocol among roles |
| endpoint protocol | One role's projected local type |
| projection | Deriving endpoints; refusing a blind choose |
Step | One send / choose / loop / repeat / par |
Shape | A ready-made protocol plus the messages it declares |
Roles and participants
| Term | Definition |
|---|---|
| role | Address in the protocol, from ap.roles(...) |
| participant | Spec that plays a role: Agent, Human, Machine, Policy, Script |
Session | Protocol + cast mapping + budget; a value |
Messages
| Term | Definition |
|---|---|
Message | Declared class: fields are the payload, docstring is the intent |
Transcript | The envelopes a run delivered |
Run | A live handle from Session.start |
Desk | A HumanIo that waits for submit |
What a run records
| Term | Definition |
|---|---|
| journal decision | Recorded authorship choice for replay |
| replay / resume | Re-run using journal decisions |
| trace event | Observation record; not a decision |
| allowance | Runtime bound on spend (steps/unfolds/tokens) |
Terms that are easy to confuse
| Pair | Distinction |
|---|---|
| protocol / transcript | A protocol describes what may happen; a transcript records what did happen in one run. |
| journal / trace | A journal stores decisions needed for replay; a trace observes execution without authoring it. |
| role / participant | A role is an address in the protocol; a participant is the object bound to that address. |
| class / instance | A message class defines a wire shape; an instance carries one payload. |
| choice / content | A choice selects a message type or branch; content is the data inside the selected message. |
| run / start | Session.start creates a run; Run is the handle used to observe or await that run. |
These distinctions matter when diagnosing a failure. If a transcript contains an unexpected message, inspect the protocol and the cast first. If the transcript is correct but a replay diverges, inspect journal decisions. If the run is correct but visibility, timing, or token usage is surprising, inspect the trace and allowance instead of changing the message model.
Vocabulary in code review
Use the narrower term when a review comment depends on it. “The protocol is wrong” could mean that a branch is not projectable, that a message field is not serializable, or that a participant was bound to the wrong role. “The run is wrong” could mean a failed send, a participant error, or a journal mismatch. Naming the artifact (protocol, endpoint, participant, transcript, journal, or trace) turns a broad observation into a change someone can locate and test.
See also protocol, sessions, and journals, replay, and tracing.