​
Creating a Session

Client                          Gateway                         Podium
  │                                │                               │
  │── thread/start {agentType} ──>│                               │
  │                                │── POST /api/v1/instances ──>│
  │                                │   {deployment_id, config}     │
  │                                │<── {instance_id} ─────────────│
  │                                │                               │
  │                                │── WS /agent/{instanceId} ───>│
  │                                │   (native protocol connection) │
  │<── thread/started ─────────────│                               │
The gateway:
  1. Resolves agentType to a deployment_id (latest version)
  2. Creates instance on Podium (via gateway → coordinator)
  3. Establishes native protocol WebSocket to the coordinator at /agent/{instanceId}
  4. Creates session database (data/sessions/{id}/session.db)
  5. Notifies client with thread/started

​
Resuming a Session

Client                          Gateway
  │                                │
  │── thread/resume {threadId} ──>│
  │                                │── Checks if agent is still running
  │                                │   (Podium instance info)
  │                                │
  │                                │── If not running: re-spawn agent
  │                                │── If running: reconnect WS
  │                                │
  │<── thread history ─────────────│  (replays persisted messages)
  │<── thread/started ─────────────│

​
Turn Processing

State: ready
  │
  │── turn/start {text}
  │
State: running
  │
  ├── item/agentMessage/delta (streaming tokens)
  ├── item/toolCall/started (tool calls)
  ├── item/commandExecution/requestApproval (if needs approval)
  │
  ├── State: waiting (if approval requested)
  │   │
  │   │── item/approve {approved: true}
  │   │
  │   State: running (resume)
  │
  ├── item/completed
  └── turn/completed
      │
State: ready (waiting for next turn)

​
Data Persistence

Every session event is persisted to the session’s SQLite database:

​
session.db tables

TableContents
turnsTurn metadata (id, started_at, completed_at, token_usage)
elementsContent elements (text, tool calls, file changes)
messagesUser and agent messages
approvalsApproval requests and responses
diffsFile diffs produced during turns
plansAgent plans

​
memory.db tables

TableContents
memoriesAgent memory entries (key-value with metadata)
summariesConversation summaries

​
Session Cleanup

When a thread is deleted or archived:
  1. Agent instance is stopped on Podium
  2. Native protocol WebSocket to Podium is closed
  3. Session databases are preserved (for archived) or deleted
  4. Litestream replicas persist in S3 for recovery