graph TB
    Client([Client]) --> Regina

    subgraph Watt["Watt Runtime"]
        Regina["@platformatic/regina<br/>Agent Manager"]
        A1["Agent Instance<br/>@platformatic/regina-agent"]
        A2["Agent Instance<br/>@platformatic/regina-agent"]

        Regina -->|spawn / proxy| A1
        Regina -->|spawn / proxy| A2
    end

    A1 --- DB1[("SQLite VFS")]
    A2 --- DB2[("SQLite VFS")]

sequenceDiagram
    participant C as Client
    participant R as Regina
    participant A as Agent Instance

    C->>R: POST /instances/:id/chat
    R->>R: Lookup instance (local map)
    alt Instance suspended
        R->>R: Resume instance
    end
    R->>A: POST /chat (via thread interceptor)
    A->>A: Load conversation history
    A->>A: Run AI model (generateText)
    A-->>R: { text, usage }
    R-->>C: 200 { text, usage }

sequenceDiagram
    participant C as Client
    participant CO as Coordinator
    participant Redis as Redis
    participant P as Pod (Regina)
    participant A as Agent Instance

    C->>CO: POST /instances/:id/chat
    CO->>Redis: GET regina:instance:<id>
    Redis-->>CO: memberId
    CO->>Redis: GET regina:member:<memberId>
    Redis-->>CO: podAddress

    alt Pod is dead (orphan detected)
        CO->>CO: Pick new pod
        CO->>Redis: SET regina:instance:<id> newMemberId
    end

    CO->>P: POST /instances/:id/chat (HTTP proxy)

    alt Instance not found locally
        P->>P: Restore from shared storage
        P->>P: Spawn instance with existing ID
    end

    P->>A: POST /chat (via thread interceptor)
    A-->>P: { text, usage }
    P-->>CO: 200 { text, usage }
    CO-->>C: 200 { text, usage }

stateDiagram-v2
    [*] --> Started: POST /agents/:defId/instances
    Started --> Started: chat / heartbeat (reset idle timer)
    Started --> Suspended: Idle timeout / POST /instances/:id/suspend
    Suspended --> Started: POST /instances/:id/resume / chat (auto-resume)
    Started --> Removed: DELETE /instances/:id
    Suspended --> Removed: DELETE /instances/:id

    Suspended --> BackedUp: Storage configured
    BackedUp --> Restored: Cross-pod migration
    Restored --> Started: Spawn on new pod

    Removed --> [*]

    note right of BackedUp: State backed up to<br/>shared storage (fs/S3/Redis)

sequenceDiagram
    participant P as Pod (Regina)
    participant R as Redis

    Note over P: Startup
    P->>R: SADD regina:members <memberId>
    P->>R: SET regina:member:<memberId> <address> EX 30
    P->>R: SET regina:member:<memberId>:instances 0 EX 30

    loop Every 10 seconds
        P->>R: EXPIRE regina:member:<memberId> 30
        P->>R: EXPIRE regina:member:<memberId>:instances 30
    end

    Note over P: Instance spawned
    P->>R: SET regina:instance:<instanceId> <memberId>
    P->>R: INCR regina:member:<memberId>:instances

    Note over P: Shutdown
    P->>R: SREM regina:members <memberId>
    P->>R: DEL regina:member:<memberId>
    P->>R: DEL regina:member:<memberId>:instances

flowchart TD
    A[Client sends request<br/>for instanceId] --> B{Coordinator:<br/>lookup instance}
    B -->|Address found| C[Proxy to pod]
    B -->|Address null| D{Instance mapping<br/>exists in Redis?}
    D -->|No| E[404 Not Found]
    D -->|Yes: orphan detected| F[Pick a live pod]
    F --> G[Update Redis mapping]
    G --> H[Proxy to new pod]
    H --> I{Pod has instance<br/>locally?}
    I -->|Yes| J[Handle request]
    I -->|No| K[Restore SQLite<br/>from shared storage]
    K --> L[Spawn instance<br/>with existing ID]
    L --> J

flowchart LR
    A[Spawn Request] --> B{Strategy}
    B -->|round-robin| C["Cycle through pods<br/>(default)"]
    B -->|least-loaded| D["Pick pod with<br/>fewest instances"]
    B -->|random| E["Uniform random<br/>selection"]
    C --> F[Selected Pod]
    D --> F
    E --> F

flowchart TD
    IM[Instance Manager] --> SB[StateBackup]
    SB --> SA{Storage Adapter}
    SA -->|fs| FS["Filesystem<br/>(NFS / EFS)"]
    SA -->|s3| S3["S3-Compatible<br/>(AWS / MinIO / R2)"]
    SA -->|redis| RD["Redis / Valkey<br/>(HSET blob)"]

erDiagram
    MEMBERS ||--o{ MEMBER : contains
    MEMBER ||--o{ INSTANCE : hosts
    MEMBER ||--|| INSTANCE_COUNT : tracks

    MEMBERS {
        SET memberIds "regina_members"
    }
    MEMBER {
        STRING address "regina_member_(memberId)"
        int TTL "30 seconds"
    }
    INSTANCE_COUNT {
        STRING count "regina_member_(memberId)_instances"
        int TTL "30 seconds"
    }
    INSTANCE {
        STRING memberId "regina_instance_(instanceId)"
    }

sequenceDiagram
    participant C as Client
    participant A as Agent

    C->>A: POST /chat/stream { message }
    A-->>C: text-delta events
    A-->>C: tool-call event
    Note over A: Agent executes tool
    C->>A: POST /steer { message: "focus on X" }
    Note over A: onStepFinish drains queue
    A-->>C: tool-result event
    A-->>C: step-finish event
    Note over A: Model sees steering message
    A-->>C: text-delta events (adjusted)