Bot turns

GET /_rystic/settle tells your driver when your bot has finished reacting. After your driver acts, your bot’s turn is several events, acks and Web API calls, and only the simulator sees when it ends. Settle, post a message that mentions the bot as a person, settle again and read the call log:

curl -s -X POST "$RYSTIC_URL/_rystic/scenario" -d '{"name":"design_studio"}' -o /dev/null
curl -s "$RYSTIC_URL/_rystic/settle?quiet_ms=100" | jq -c '{settled, last_call_seq}'
# -> {"settled":true,"last_call_seq":0}
curl -s -X POST "$RYSTIC_URL/api/chat.postMessage" -H 'Authorization: Bearer xoxp-anything' -H 'X-Rystic-Actor: UWDC0000020' -H 'X-Rystic-Surface: client' -d channel=CWDC0000004 --data-urlencode 'text=<@UWDCBOT0001> draft a reply' | jq -c '{ok, ts}'
# -> {"ok":true,"ts":"1772323200.000001"}
curl -s "$RYSTIC_URL/_rystic/settle?quiet_ms=100" | jq -c '{settled, last_call_seq}'
# -> {"settled":true,"last_call_seq":1}
curl -s "$RYSTIC_URL/_rystic/calls?tail=1" | jq -c '.calls[] | {seq, principal, path, surface}'
# -> {"seq":1,"principal":"UWDC0000020","path":"/api/chat.postMessage","surface":"client"}

No bot is connected here, so the log holds only the driver’s post. With your bot connected over the Events API, the bot’s calls follow that post. The second settle waits for them as long as no pause inside the turn outlasts quiet_ms.

When a turn is over

GET /_rystic/settle returns "settled":true once both hold:

• no event or interaction awaits your bot’s ack (in request URL mode, its 2xx);
• no Web API call has landed for quiet_ms of wall time (default 500).

At timeout_ms (default 30000) it returns "settled":false with pending, what is still open. Both are at most 60000.

Calls made with X-Rystic-Surface: client or X-Rystic-Source: ui, or by a timeline event, never count, so your driver’s own post does not. The workspace UI sends neither header, so its calls count. principal=UWDCBOT0001 watches only calls made as that user. A redelivery due later never holds it and is listed in scheduled.

Read what the turn did

Read your bot’s turn from /_rystic/calls: between the two settles’ last_call_seq, keep the calls whose principal is your bot’s user and that carry no surface or source. Settle once before your driver acts and once after; each settle’s last_call_seq is the last seq in the log at that moment. Your bot’s user is UWDCBOT0001 in design_studio. Settle does not count calls with surface or source either.

Any unbound token acts as the bot, so give your driver and every other agent its own bound token or X-Rystic-Actor. Identities describes each call log entry.

Quiet is wall time, not the simulator’s clock, because your bot runs in real time. Set quiet_ms above the longest pause inside one turn, such as a model call. rystic settle <instance> and the MCP server’s settle tool ask the same route.