> ## Documentation Index
> Fetch the complete documentation index at: https://internal.september.wtf/llms.txt
> Use this file to discover all available pages before exploring further.

# Streaming events

> Every Server-Sent Event the Engine can emit during /execute.

`POST /execute` returns Server-Sent Events. The events fall into four
families: lifecycle, content, tool calls, and human-in-the-loop. This page
catalogs them.

Each event has the shape:

```
event: <type>
data: <json>

```

A blank line terminates each event. The `data` payload's exact shape
depends on the event type.

## Lifecycle

### `thread_lifecycle`

Emitted at the start and end of every turn.

```json theme={null}
{
  "phase": "started" | "completed" | "errored",
  "task_id": "demo-001",
  "turn_id": "...",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

A turn always opens with a `started` event and closes with `completed` or
`errored`.

### `error`

Emitted when execution fails mid-stream. After this event, no more events
will arrive on the current call.

```json theme={null}
{
  "error": "LLM_PROVIDER_ERROR",
  "message": "Upstream model returned 500.",
  "details": { /* optional */ }
}
```

## Content

### `text_delta`

A chunk of model output text. Concatenate all `text_delta` events in order
to get the full response.

```json theme={null}
{
  "text": "Hello, "
}
```

### `thinking_delta`

A chunk of the model's internal reasoning when extended thinking is on.
Treat the same way as `text_delta` but render in a separate UI region (or
hide entirely if you don't surface thinking to users).

```json theme={null}
{
  "text": "Let me think about this..."
}
```

### `content_block_start` / `content_block_stop`

Emitted around content blocks (text, thinking, tool use). Useful when you
need to track block boundaries — for example, to emit a UI separator.

```json theme={null}
{
  "block_index": 0,
  "block_type": "text" | "thinking" | "tool_use"
}
```

## Tool execution

### `tool_call`

The model has decided to call a tool. The `input` field contains whatever
the model provided as arguments.

```json theme={null}
{
  "tool": "bash",
  "tool_call_id": "...",
  "input": {
    "command": "ls -la"
  }
}
```

### `tool_result`

The tool finished. `output` holds whatever the tool returned. May include
an `error` field if the call failed.

```json theme={null}
{
  "tool": "bash",
  "tool_call_id": "...",
  "output": "drwxr-xr-x  6 ...",
  "error": null
}
```

## Human-in-the-loop

### `hitl_request`

The agent has paused and needs your answer. Reply with
`POST /hitl/respond` using the `request_id`. Until you reply, the stream
will continue to emit other events (heartbeats) but will not proceed.

```json theme={null}
{
  "request_id": "hitl-...",
  "kind": "question" | "permission",
  "question": "Should I delete the file foo.txt?",
  "context": { /* the agent's view of why it's asking */ },
  "options": ["yes", "no"]
}
```

### `hitl_resolved`

Emitted after `POST /hitl/respond` to signal that the loop has resumed.

```json theme={null}
{
  "request_id": "hitl-...",
  "answer": "yes"
}
```

## Memory and context

### `working_memory_update`

Emitted when the agent writes to working memory.

```json theme={null}
{
  "entry_type": "note" | "observation" | "summary",
  "content": "..."
}
```

### `compaction_event`

Emitted when the compaction orchestrator collapses earlier turns.

```json theme={null}
{
  "before_tokens": 24000,
  "after_tokens": 8500,
  "strategy": "summary" | "structured_extraction"
}
```

## Diagnostic

### `heartbeat`

Periodic. Use to detect dead connections client-side.

```json theme={null}
{
  "now": "2026-04-27T12:34:56.000Z"
}
```

### `usage`

Token usage so far for the turn.

```json theme={null}
{
  "input_tokens": 1240,
  "output_tokens": 312,
  "cache_hit_tokens": 980
}
```

## Notes for client implementers

* **Missing `event:` lines.** Some clients omit the `event:` line and only
  send `data:`. The Engine always emits `event:`. Use it to route.
* **Reordering.** Events are emitted in execution order. Don't try to
  reorder them.
* **Multiple text streams.** A single turn can emit text from multiple
  tool calls and thinking blocks. Use `content_block_start` /
  `content_block_stop` to separate them.
* **Disconnections.** If your client disconnects mid-stream, use
  `GET /execute/replay?after=<ts>` to fetch missed events.

## See also

* [Endpoint reference: /execute](./endpoints/execute) for the request
  shape.
* [The agent loop](../agents-and-tools/agent-loop) for what the server is
  doing while you watch the stream.
* [Build with the Engine → Streaming](../capabilities/streaming) for
  client patterns.