explorer-monorepo/docs/specs/vtm/conversation-state.md

Conversation State Management Specification

Overview

Conversation state management for multi-turn VTM conversations.

State Schema

{
  "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