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

# Session Events

> Definitions for asynchronous events emitted by a Session context.

Session Events are tracking payloads asynchronously generated by Session lifecycle updates rather than intense workflow executions. They primarily inform listeners when data states globally shift within the session memory parameters.

## Shared Event Format

All session events conform to the following base structure:

```json theme={null}
{
  "id": "uuid-event-id",
  "revision_id": "uuid-workflow-revision",
  "session_id": "uuid-active-session",   
  "created_at": "2026-05-28T12:00:00.000000Z",
  "type": "event_type_string",
  ... // Dynamic event-specific properties
}
```

## Event Types

### `session_object_modified`

Fired when a `upload_session_object` call is made against the Session, modifying semi-persistent object values securely within the active envelope. Extremely useful for reactive applications polling or streaming state updates directly.

```json theme={null}
{
  "id": "uuid-event-id",
  "revision_id": "uuid-workflow-revision",
  "session_id": "uuid-active-session",   
  "created_at": "2026-05-28T12:00:00.000000Z",
  "type": "session_object_modified",
  "session_object": {
    "alias": "my_stored_configuration_data"
  }
}
```

### `session_object_deleted`

Fired when a `delete_session_object` call removes a session object from the active session. For
thread-typed session objects this also cascades to remove all of the thread's items.

```json theme={null}
{
  "id": "uuid-event-id",
  "revision_id": "uuid-workflow-revision",
  "session_id": "uuid-active-session",
  "created_at": "2026-05-28T12:00:00.000000Z",
  "type": "session_object_deleted",
  "session_object": {
    "alias": "my_stored_configuration_data"
  }
}
```

### `session_thread_item_posted`

Fired when a `post_session_thread_item` call adds an item to a thread session object. Listeners can
re-fetch the thread tail via `list_session_thread_items` using the `item_id` to anchor
`created_since`.

```json theme={null}
{
  "id": "uuid-event-id",
  "revision_id": "uuid-workflow-revision",
  "session_id": "uuid-active-session",
  "created_at": "2026-05-28T12:00:00.000000Z",
  "type": "session_thread_item_posted",
  "session_object": {
    "alias": "onboarding_thread",
    "item_id": "uuid-of-the-new-item"
  }
}
```

### `session_graph_changed`

Fired once per `apply_session_graph_mutations` call, carrying the change delta for the affected graph
session object. Each entry in `changes` identifies one applied operation.

```json theme={null}
{
  "id": "uuid-event-id",
  "revision_id": "uuid-workflow-revision",
  "session_id": "uuid-active-session",
  "created_at": "2026-06-06T10:00:01.000000Z",
  "type": "session_graph_changed",
  "session_object": {
    "alias": "task_graph",
    "changes": [
      { "op": "upsert", "element_id": "t1", "type": "vertex", "rev": 4 },
      { "op": "delete", "element_id": "e7", "type": "edge" }
    ]
  }
}
```

Listeners apply the delta incrementally: remove elements whose `op` is `"delete"` from the local
cache, then call `get_session_graph_elements` with the `element_id` values from the remaining
`"upsert"` entries to fetch their updated state. This avoids refetching the entire graph on each
mutation.