Skip to content
Docs menu

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.

View .md

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"}}

: ping

Each 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