Events (Server-Sent Events)
Follow a venom serve session over Server-Sent Events, replay what you missed, and read the session, harness and server event types.
Everything a session does arrives on its event stream: model output as it streams, tool calls and their results, permission decisions, approval requests and the end of each prompt. GET /v1/sessions/{sessionId}/events (streamEvents) is a standard Server-Sent Events stream.
Read the stream
curl -N "http://127.0.0.1:8790/v1/sessions/$SID/events?after=0" -H "Authorization: Bearer $TOKEN"id: 42
event: message_update
data: {"seq":42,"source":"session","type":"message_update","assistantMessageEvent":{"type":"text_delta","delta":"The tests"}}
: pingEach event is id: <seq>, event: <type> and data: <json>. The JSON always has seq (increasing per session), source (session, harness or server) and type. : ping comments come every 15 seconds. The stream ends after session_closed.
for event in client.events(sid, after=0): # reconnects with Last-Event-ID by itself
if event["type"] == "tool_execution_start":
print("tool:", event["toolName"])
elif event["type"] == "prompt_end":
print(event["text"])for await (const e of client.events(sid, { after: 0 })) {
if (e.type === "tool_execution_start") console.log("tool:", e.toolName);
if (e.type === "prompt_end") console.log(e.text);
}Replay and reconnects
| Parameter | What |
|---|---|
after (query) |
Replay events with seq greater than this. |
Last-Event-ID (header) |
The same, as browsers and SSE libraries send it on reconnect. Wins over after. |
The server keeps each session's last 2000 events (at most 32 Mi characters of their JSON). A reconnect whose gap is older than that starts with an events_dropped event. A client that prompts and then opens the stream with ?after=<lastEventId> from the prompt response misses nothing.
A stream whose client stops reading is cut once 8 MiB is queued for it; reconnect with Last-Event-ID. Each open stream counts against --max-connections.
Session events
source: "session" events are the agent loop's own, in the shape of pi's JSON event stream (pi is the agent framework venom is built on). message_update carries only the delta and the latest usage, never a cumulative snapshot.
| Type | When |
|---|---|
agent_start, agent_end, agent_settled |
A run starts, ends, and has nothing left queued |
turn_start, turn_end |
One model call and its tool calls |
message_start, message_update, message_end |
A message streams; message_end holds the full message and its usage |
tool_execution_start, tool_execution_update, tool_execution_end |
A tool call; toolCallId links them, parentToolCallId names a calling tool |
queue_update |
Steering and follow-up queues changed |
compaction_start, compaction_end |
The context was compacted |
auto_retry_start, auto_retry_end |
A failed model request is retried |
summarization_retry_scheduled, summarization_retry_attempt_start, summarization_retry_finished |
A summary request is retried (its own source is sent as origin) |
entry_appended |
A session entry was saved (a turn checkpoint is entry.customType: "venom-checkpoint") |
session_info_changed |
The session's name changed |
thinking_level_changed |
The reasoning level changed |
bash_execution_update |
Output of a ! command the person typed |
An assistant message's usage.cost is the bundled list price of the model that served it (0 for local models). Summed over a session it equals the CLI's /cost. Skip types you don't know: new agent versions add events.
Harness events
source: "harness" events come from venom's harness; each has a schema in the API reference (HarnessEvent). A field the harness calls source is sent as origin.
| Type | What |
|---|---|
permission |
An audit record for every permission decision |
mode |
The permission mode changed |
todos |
The agent's todo list |
subagents |
Progress of task subagents |
compaction |
venom's own context mask and summarize step |
egress |
The sandbox egress proxy refused a connection |
lsp |
Language-server diagnostics after an edit, with dependents when files depending on it were checked |
format |
The project's formatter ran on an edited file |
edit-tool |
Which file-editing tools the model got |
test-edit |
An edit only changed a test's expected values (advisory) |
unseen-removal |
A write removed lines the model never read (advisory) |
checkpoint |
A file checkpoint was recorded, or files were undone, redone or restored |
guard |
A runaway guard fired |
injection |
A tool result looks like a prompt injection (advisory) |
hook, diagnostic |
A hook ran; a diagnostic message |
notice |
A slash command's output (/undo, /context, /cost, …) in a session without a UI |
agent, span |
Agent processes' state and their trace spans (Agents) |
memory |
The context memory layer acted |
call |
One model request: model asked for and served, upstream, tokens, costUsd, fallback reason |
cache-break |
A request lost most of its cached prompt prefix, with the likely cause |
workflow |
A /workflow run progress line |
escalation |
A fast-tier subagent's task was re-run on a stronger tier |
Server events
| Type | Fields | When |
|---|---|---|
approval_request |
approvalId, tool, toolCallId, input, summary, reason, mode, suggestions, rules, agent, parentToolCallId, expiresAt |
The policy asks (Approvals) |
approval_resolved |
approvalId, action, by (client, timeout, abort, close, or mode: the session's mode changed and now allows the call, settled as allow-once) |
An approval was answered or gave up |
question_request |
questionId, questions, expiresAt |
The model's ask_user tool asks something |
question_resolved |
questionId, answered, by |
A question was answered or gave up |
prompt_end |
promptId, text, error?, truncated? |
The run a prompt started has ended; text is the final answer. truncated: true means that reply was still cut off at the output-token limit after venom's retries, so text is incomplete |
events_dropped |
the gap | A replay gap older than the buffer |
session_closed |
The session closed; the stream ends |
Related pages
- Sessions
- Approvals and questions
- Clients: event parsing and reconnects in Python and TypeScript