ACP Session Lifecycle - iGent Concert

This page describes ACP compatibility behavior. The current internal model is Fabric conversation and stream state mediated by Diminuendo.

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

Table	Contents
`turns`	Turn metadata (id, started_at, completed_at, token_usage)
`elements`	Content elements (text, tool calls, file changes)
`messages`	User and agent messages
`approvals`	Approval requests and responses
`diffs`	File diffs produced during turns
`plans`	Agent plans

memory.db tables

Table	Contents
`memories`	Agent memory entries (key-value with metadata)
`summaries`	Conversation 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