Reference
Session events
The 16 DSH session events and 3 assistant stream frames: when they fire, how they pair and what is persisted.
Studio Host projections consume 16 DSH session events plus 3 process-local assistant stream frames. Event names are DSH's stable vocabulary; Studio neither adds nor renames them.
| Event | Family | When it fires | Source |
|---|
turn/start | turn | Turn starts: the user message is admitted and the model round begins. | src/host/dsh-session-contract.mjs:3 |
turn/end | turn | Turn ends, carrying the terminal state and usage. | src/host/dsh-session-contract.mjs:4 |
step/start | step | A step starts: the boundary between one model output and its tool calls. | src/host/dsh-session-contract.mjs:5 |
step/end | step | A step ends. | src/host/dsh-session-contract.mjs:6 |
system/message | system | A system message is injected: policy, context or instructions. | src/host/dsh-session-contract.mjs:7 |
request/header | request | Request header: model, route and protocol version. | src/host/dsh-session-contract.mjs:8 |
request/context | request | Request context: workspace, execution policy and frozen runtime. | src/host/dsh-session-contract.mjs:9 |
user/message | user | A user message. | src/host/dsh-session-contract.mjs:10 |
assistant/message | assistant | Assistant message: the final output of a turn. | src/host/dsh-session-contract.mjs:11 |
assistant/attempt | assistant | One attempt: a retried turn emits several of these. | src/host/dsh-session-contract.mjs:12 |
tool/call | tool | A tool call request, carrying the call id. | src/host/dsh-session-contract.mjs:13 |
tool/result | tool | A tool result, paired with the call id. | src/host/dsh-session-contract.mjs:14 |
approval/asked | approval | Approval asked: a tool needs authorization before it runs. | src/host/dsh-session-contract.mjs:15 |
approval/decided | approval | Approval decided: allow, deny or timeout. | src/host/dsh-session-contract.mjs:16 |
agent/inbox/spliced | agent | The Agent inbox is spliced with a new event (concurrent message). | src/host/dsh-session-contract.mjs:17 |
agent-preset/selected | agent-preset | The session selected an Agent preset. | src/host/dsh-session-contract.mjs:18 |
An event name is segmented on the first slash. The family decides projection ordering.
| Family | Size | Events |
|---|
turn | 2 | turn/start turn/end |
step | 2 | step/start step/end |
system | 1 | system/message |
request | 2 | request/header request/context |
user | 1 | user/message |
assistant | 2 | assistant/message assistant/attempt |
tool | 2 | tool/call tool/result |
approval | 2 | approval/asked approval/decided |
agent | 1 | agent/inbox/spliced |
agent-preset | 1 | agent-preset/selected |
The process-local assistant stream has three frames, ordered start → chunk* → end. They are never persisted and only drive streaming render.
| Frame | Source |
|---|
start | src/host/dsh-session-contract.mjs:22 |
chunk | src/host/dsh-session-contract.mjs:22 |
end | src/host/dsh-session-contract.mjs:22 |
turn/start → request/header → request/context → step/start
→ assistant/attempt → (tool/call → approval/asked → approval/decided → tool/result)*
→ step/end → assistant/message → turn/end
| Event | Ordering rule |
|---|
turn/start | The single entry point of a turn. |
turn/end | The only guaranteed terminal event; its absence means the connection dropped. |
step/start | A step carries at least one assistant/attempt. |
step/end | Pairs one-to-one with step/start. |
system/message | May appear anywhere without changing turn state. |
request/header | Follows turn/start; once per turn. |
request/context | Follows request/header. |
user/message | Usually once at the start of a turn. |
assistant/message | At most one per turn, from the last attempt. |
assistant/attempt | Repeats within a turn when retried. |
tool/call | Pairs with tool/result by call id. |
tool/result | Always after the matching tool/call. |
approval/asked | Only when a tool needs authorization. |
approval/decided | Must pair with approval/asked. |
agent/inbox/spliced | Signals concurrent writes; projections must merge in order. |
agent-preset/selected | Usually before a turn starts. |
| Item | Value | Notes |
|---|
| Session events | 16 | A subset of the DSH vocabulary; do not extend it |
| Stream frames | 3 | start / chunk / end |
| Families | 10 | Segmented on the first slash |
| Persistence | Session events only | Stream frames are never persisted |
| Item | Source |
|---|
| Session event vocabulary | src/host/dsh-session-contract.mjs |
| Runtime contract | src/runtime-contract.mjs |
| Session adapter | src/session-adapter.mjs |
| Native turn contract | packages/harness/src/native/dsh-turn-contract.ts |
Related tests:
| Test file | Location |
|---|
| runtime-contract.test.mjs | tests/runtime-contract.test.mjs |
| session-adapter.test.mjs | tests/session-adapter.test.mjs |