# Conversation State Management Specification

## Overview

Conversation state management for multi-turn VTM conversations.

## State Schema

```json
{
  "session_id": "uuid",
  "user_id": "uuid",
  "context": {
    "current_workflow": "bridge_action",
    "workflow_state": {...},
    "entities": {
      "amount": "100",
      "source_chain": "138",
      "destination_chain": "1"
    }
  },
  "conversation_history": [
    {
      "turn": 1,
      "user": "I want to bridge tokens",
      "assistant": "Which chains would you like to bridge between?",
      "timestamp": "2024-01-01T00:00:00Z"
    }
  ],
  "intents": ["bridge_initiation"],
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:05:00Z"
}
```

## Context Preservation

### Context Types

**Workflow Context**: Current workflow state
**Entity Context**: Extracted entities (amounts, addresses, etc.)
**User Context**: User preferences, history
**Session Context**: Session metadata

### Context Updates

**Triggers**:
- User input
- Workflow progression
- Entity extraction
- External events

## Multi-Turn Conversation Handling

### Turn Management

**Track**:
- Turn number
- User input
- Assistant response
- Extracted entities
- Intent changes

### Entity Extraction

**Entities**:
- Amounts
- Addresses
- Chain names/IDs
- Token symbols
- Dates/times

### Disambiguation

**Handling Ambiguity**:
- Ask clarifying questions
- Suggest options
- Use context to infer

## Session Timeout and Recovery

### Timeout

**Duration**: 30 minutes of inactivity
**Action**: Save state, end session
**Recovery**: Resume from saved state if user returns

### Recovery

**Process**:
1. User returns within timeout window
2. Restore conversation state
3. Continue from last turn
4. Prompt user to continue

## References

- Teller Orchestrator: See `teller-orchestrator.md`
- Workflows: See `teller-workflows.md`