---
title: Events (Server-Sent Events)
description: Follow a venom serve session over Server-Sent Events, replay what you missed, and read the session, harness and server event types.
section: server-api
order: 20
audience: [builder, agent]
sources: [packages/harness-server/openapi.yaml, packages/harness-server/src/events.ts, packages/harness-server/src/server.ts]
features: [server-api.sessions-events]
---

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 {#read}

```bash
curl -N "http://127.0.0.1:8790/v1/sessions/$SID/events?after=0" -H "Authorization: Bearer $TOKEN"
```

```text
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`.

```python
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"])
```

```ts
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 {#replay}

| 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 {#session}

`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 {#harness}

`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](/docs/server-api/agents.md)) |
| `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 {#server}

| Type | Fields | When |
|---|---|---|
| `approval_request` | `approvalId`, `tool`, `toolCallId`, `input`, `summary`, `reason`, `mode`, `suggestions`, `rules`, `agent`, `parentToolCallId`, `expiresAt` | The policy asks ([Approvals](/docs/server-api/approvals-and-questions.md)) |
| `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](/docs/server-api/sessions.md)
- [Approvals and questions](/docs/server-api/approvals-and-questions.md)
- [Clients](/docs/server-api/clients.md): event parsing and reconnects in Python and TypeScript
