feat: implement turn-based conversation modalities (addresses #1103)

[jacyanthis]

This adds feature #1103

This is a turn-based mode where each agent sends one message in a cycle. The moderator speaks first, then a random order of participants, then the moderator and a new random order... Participants see their text entry disabled and a "Waiting" banner then a "It's your turn" banner.

There is a checkbox in Conversation Settings for the Group Chat stage.

This PR was heavily assisted with an LLM agent, and it's my first time contributing, so thank you for the review! (maybe @rasmi for API regression? @jimbojw ?) I hope to add a few other related features.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[jimbojw]

Hi @jacyanthis, I'm working on running this locally to check it out. In the mean time, it looks like the schemas need to be updated (there's a failing check to this effect).

[jimbojw]

@jacyanthis What are the steps to test this out manually? Do you start as an Experimenter and make an experiment from scratch? Thanks in advance for step-by-step instructions.

[jacyanthis]

@jimbojw thanks! Schemas are updated. Yes, this is a checkbox in Conversation Settings for the Group Chat stage when editing an experiment.

1. Run ./run_locally.sh.
2. Visit localhost:4201.
3. Click Build experiment from scratch (or use one of your existing experiments).
4. Create a Group Chat stage or use one.
5. In the settings menu that appears, click the new Turn-based checkbox (see screenshot).
6. Launch the experiment as usual. The Group Chat stage should operate in a turn-based manner.

[jimbojw]

@jacyanthis OK thanks, I was able to test locally using simulated human participants.

There seems to be a bug at the end of the first turn of conversation.

To reproduce:

1. Create a new experiment with a Group Chat stage enforcing the turn-based conversation (feature under test).
2. Create a new cohort with at least two "human" participants.
3. For each simulated participant, select the participant and click the "Click to begin experiment button".
4. With the experiment started, iterate through the participants as prompted, entering a chat message.

Expected: After the last participant has entered a message, the first participant should be prompted to continue.

Actual: The last participant is prompted a second time. After they enter a second comment, then the conversation rotates back to the first participant.

In the following screenshot, you can see that the third active participant, camel-red-7804, was prompted for both the third conversation turn (C, correct) but also the fourth (D).

[jimbojw]

Note: In my test example, I included only simulated "human" participants, with no mediators. That may be relevant to the bug.

[jacyanthis]

Thanks! I've modified it to prevent back-to-back turns of the same participant when in a no-mediator Group Chat. Specifically, it will use a single turn order for each 'cycle' of the chat, so the person who goes first in a cycle never went last in the previous cycle. This can still occur if there is a mediator, but then there is an intervening mediator turn between cycles.

I checked for other DL functionalities that might not mesh intuitively with turn-based chat. For new participants or mediators being added mid-conversation, I modified the PR so it appends new mediators to the initial mediator 'phase' of the cycle and appends new participants to the secondary participant phase. When a new mediator is added to a no-mediator Group Chat, the turn order will remain fixed.

These seem like the most intuitive options to me, though I don't expect these corner cases to come up with turn-based conversations, or at least not with our intended usage. Alternatively, some other functionalities could be disabled when turn-based is enabled.

[cjqian]

LGTM! I haven't pulled this locally, but one minor P2 improvement

may be having a little indicator in the participants panel to show whose current turn it is. Something to consider!

[jacyanthis]

Thanks! I added several commits to address various possible issues for turn management (e.g., handling repeated API failures, turn skips for ineligible participants), and I added that turn indicator to the participants panel.

[jimbojw]

@jacyanthis I'll try the latest. You'll want to rebase against main. We had to bump a dependency version to restore GitHub Actions functionality. See #1132

[jacyanthis]

@jimbojw sounds great! Rebase done.

[jimbojw]

Code looks good. I ran it and can confirm that things appear to be working correctly.

I did notice a bug, but I don't know if it's a new one, or it was there previously. In the following screenshot, bear just finished their turn. For conversational simplicity, I was piloting each participant to just enter letters of the alphabet sequentially ('A', 'B', and so on).

On bear's turn, I entered 'F', then rapidly hammered the Enter button. This caused a sequence of 'F' messages from bear even though, presumably, only one message should be allowed.

The multiple messages only go through during the intermediate period in which the send button has been replaced with a spinner. Once the first such message goes through, later taps of Enter do not spawn additional messages.

[jimbojw]

Thanks for fixing the issue with repeated submissions. 🙏

[jimbojw]

@jacyanthis The latest commit seems to have broken a suite in the Firebase Functions tests. You can see the results here: https://github.com/PAIR-code/deliberate-lab/actions/runs/26546481194/job/78283373946?pr=1119

To reproduce these failures locally, run

npm test -w functions

There appear to be two kinds of failures:

1. Simple name swaps. Like the test was looking for cohort123-1 and got cohort123-0.
2. Mocks being called unexpectedly.

Here's an example of the latter:

  ● Chat Triggers - Turn Taking Mechanics › 3. Prevention of Out-of-Turn Advancement › triggers the mediator if it was the mediator's turn but someone else speaks first                   
                                                                                                                                                                                           
    expect(jest.fn()).not.toHaveBeenCalled()                                                                                                                                               
                                                                                                                                                                                           
    Expected number of calls: 0                                                                                                                                                            
    Received number of calls: 2                                                                                                                                                            
                                                                                                                                                                                           
    1: "experiments/exp123/cohorts/cohort123/publicStageData/stage123", {"currentTurnParticipantId": "m1", "cycleIndex": 0, "turnOrder": ["m1", "p1", "p2", "p3"]}, {"merge": true}        
    2: "experiments/exp123/cohorts/cohort123/publicStageData/stage123", {"currentTurnParticipantId": "m1", "cycleIndex": 0, "turnOrder": ["m1", "p1", "p2", "p3"]}, {"merge": true}        
                                                                                                                                                                                           
      501 |                                                                                                                                                                                
      502 |       // Assert turn did not advance in database                                                                                                                               
    > 503 |       expect(__mocks__.setMock).not.toHaveBeenCalled();                                                                                                                        
          |                                     ^                                                                                                                                          
      504 |                                                                                                                                                                                
      505 |       // Assert mediator is triggered to speak the initial message                                                                                                             
      506 |       expect(mockInternalCreateAgentChatMessage).toHaveBeenCalledWith(                                                                                                         
                                                                                                                                                                                           
      at Object.toHaveBeenCalled (src/triggers/chat.triggers.test.ts:503:37)

It's not clear to me whether the tests need to be updated, or if the code needs to be updated to satisfy the tests.

[jacyanthis]

Thank you for your patience!

I had switched to using transactions for database retrieval to guard against race conditions with messages and dropout/kicks in quick succession but failed to update the tests to account for that. With mockGet() working in the test suite, it seems to pass now.