Session events
GET /v1/sessions/{sessionID}/events, session.events.list() and
helmr session events read finite pages of the retained Session timeline.
The SDK exports SessionEvent, SessionEventKind and SessionEventPage. A record
has sessionId, nullable turnId, numeric sequence, createdAt, kind and JSON
data.
| Event kinds | Meaning |
|---|---|
turn.queued, turn.running |
Turn progress through admission, processing and settlement. |
turn.completed, turn.failed, turn.interrupted, turn.cancelled |
Terminal Turn outcome. |
turn.output |
One normalized Content fragment in data, such as [{ "type": "text", "text": "Working" }]. |
message.admitted, message.started, message.delivered, message.rejected |
Exact-Turn message acceptance and delivery facts. |
ask.created, ask.answered, ask.cancelled |
Question lifecycle; use exact ask reads for current prompt/control/answer. |
session.interrupt, session.resume, session.close |
Accepted Session controls. An idle close records only session.closed. |
session.closed |
The Session closed. how is close, cancel or idle. Cancel records only this event. |
session.process_stopped |
The Session’s process stopped. |
session.process_failed |
A counted process failure: processEpoch, reason (process_failed, stop_deadline_elapsed or execution_lost) and holdId, which is null until consecutive failures hold the Session. |
session.recovery_gap |
Restore point, Computer and affected completed requests for this conversation. holdId is set when this conversation is held for acknowledgement and null for a notice. |
session.storage_pressure |
A storage episode became paused, stopped or resolved. |
slack.delivery_unavailable |
The pinned Slack destination cannot currently deliver. |
When Computer loss interrupts a running request, turn.interrupted includes
reason: "computer_execution_lost", computerId, leaseEpoch and recoveryGap.
The latter records whether this conversation is held by the recovery gap of the
same loss, whose acknowledgement request then explains it. A Turn that exceeds maxTurnDuration ends with
reason: "turn_deadline_elapsed"; its process stops and queued Turns continue.
Other interruption causes keep their existing payloads. This outcome
does not replay the request or prevent otherwise eligible queued work from
continuing after recovery.
SDK pages contain records, nextAfter, hasMore and retainedAfter.
REST uses next_after, has_more and retained_after, with snake-case record
fields. Supply after as a nonnegative safe integer. Limits default to 100 and
range from 1 to 1000. Persist the sequence only after consuming its record.
Use the retention boundary to detect unavailable earlier history.
Events cover Turn admission, running/terminal status, authored output,
message admission/delivery/rejection, question creation/response/cancellation,
Session controls and process/lifecycle facts. turn.output is selected human
content. It is not arbitrary native diagnostics or a process stdout stream.
Read events concurrently with outcome observation so users see progress while
the handler runs. Completion does not wait for the background disk save. A finite page ending or hasMore: false does not establish
Turn completion. session.events.stream({ after }) follows pages; the observer’s
abort signal stops observation, not customer work.
Use retained Turn state or a terminal outcome for the final result and optional response. Reconnecting must not resubmit the input merely to recover history. A result path does not provide a platform-managed file download.