AgentKit Studio
Reference

Session events

The 16 DSH session events and 3 assistant stream frames: when they fire, how they pair and what is persisted.

Event vocabulary

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.

EventFamilyWhen it firesSource
turn/startturnTurn starts: the user message is admitted and the model round begins.src/host/dsh-session-contract.mjs:3
turn/endturnTurn ends, carrying the terminal state and usage.src/host/dsh-session-contract.mjs:4
step/startstepA step starts: the boundary between one model output and its tool calls.src/host/dsh-session-contract.mjs:5
step/endstepA step ends.src/host/dsh-session-contract.mjs:6
system/messagesystemA system message is injected: policy, context or instructions.src/host/dsh-session-contract.mjs:7
request/headerrequestRequest header: model, route and protocol version.src/host/dsh-session-contract.mjs:8
request/contextrequestRequest context: workspace, execution policy and frozen runtime.src/host/dsh-session-contract.mjs:9
user/messageuserA user message.src/host/dsh-session-contract.mjs:10
assistant/messageassistantAssistant message: the final output of a turn.src/host/dsh-session-contract.mjs:11
assistant/attemptassistantOne attempt: a retried turn emits several of these.src/host/dsh-session-contract.mjs:12
tool/calltoolA tool call request, carrying the call id.src/host/dsh-session-contract.mjs:13
tool/resulttoolA tool result, paired with the call id.src/host/dsh-session-contract.mjs:14
approval/askedapprovalApproval asked: a tool needs authorization before it runs.src/host/dsh-session-contract.mjs:15
approval/decidedapprovalApproval decided: allow, deny or timeout.src/host/dsh-session-contract.mjs:16
agent/inbox/splicedagentThe Agent inbox is spliced with a new event (concurrent message).src/host/dsh-session-contract.mjs:17
agent-preset/selectedagent-presetThe session selected an Agent preset.src/host/dsh-session-contract.mjs:18

Families

An event name is segmented on the first slash. The family decides projection ordering.

FamilySizeEvents
turn2turn/start turn/end
step2step/start step/end
system1system/message
request2request/header request/context
user1user/message
assistant2assistant/message assistant/attempt
tool2tool/call tool/result
approval2approval/asked approval/decided
agent1agent/inbox/spliced
agent-preset1agent-preset/selected

Assistant stream frames

The process-local assistant stream has three frames, ordered start → chunk* → end. They are never persisted and only drive streaming render.

FrameSource
startsrc/host/dsh-session-contract.mjs:22
chunksrc/host/dsh-session-contract.mjs:22
endsrc/host/dsh-session-contract.mjs:22

Ordering and pairing

turn/start → request/header → request/context → step/start
  → assistant/attempt → (tool/call → approval/asked → approval/decided → tool/result)*
  → step/end → assistant/message → turn/end
EventOrdering rule
turn/startThe single entry point of a turn.
turn/endThe only guaranteed terminal event; its absence means the connection dropped.
step/startA step carries at least one assistant/attempt.
step/endPairs one-to-one with step/start.
system/messageMay appear anywhere without changing turn state.
request/headerFollows turn/start; once per turn.
request/contextFollows request/header.
user/messageUsually once at the start of a turn.
assistant/messageAt most one per turn, from the last attempt.
assistant/attemptRepeats within a turn when retried.
tool/callPairs with tool/result by call id.
tool/resultAlways after the matching tool/call.
approval/askedOnly when a tool needs authorization.
approval/decidedMust pair with approval/asked.
agent/inbox/splicedSignals concurrent writes; projections must merge in order.
agent-preset/selectedUsually before a turn starts.

Version and compatibility

ItemValueNotes
Session events16A subset of the DSH vocabulary; do not extend it
Stream frames3start / chunk / end
Families10Segmented on the first slash
PersistenceSession events onlyStream frames are never persisted

Developer entry points

ItemSource
Session event vocabularysrc/host/dsh-session-contract.mjs
Runtime contractsrc/runtime-contract.mjs
Session adaptersrc/session-adapter.mjs
Native turn contractpackages/harness/src/native/dsh-turn-contract.ts

Related tests:

Test fileLocation
runtime-contract.test.mjstests/runtime-contract.test.mjs
session-adapter.test.mjstests/session-adapter.test.mjs

On this page