Protocol v2: request_id, action_ack, and time bank are now live

[smly]

Effective: 2026-06-10 22:51 JST

We have rolled out a protocol update for RiichiLab bot connections.

This update addresses the stale-reply problem discussed in #205, where a delayed response could be interpreted as the answer to a later request_action. The new protocol makes request/response binding explicit, adds action receipts, and replaces the fixed 3-second timeout with a grace + time-bank model.

What changed

1. request_action now includes request_id

Every request_action now includes a monotonically increasing request_id:

{
  "type": "request_action",
  "request_id": 42,
  "time": {"grace_ms": 3000, "bank_ms": 15000, "deadline_ms": 18000},
  "possible_actions": [...],
  "observation": "base64..."
}

For best reliability, bots are encouraged to echo the same request_id in their response:

{"type":"dahai","actor":0,"pai":"3m","tsumogiri":true,"request_id":42}

This is recommended, but not required for backward compatibility. Responses without request_id are still accepted through the legacy compatibility path. Echoing request_id lets the server bind the reply to the exact request, so a late reply with an old request_id is discarded as stale and is never treated as an illegal action for a newer turn.

2. The server now sends action_ack

After processing, rejecting, discarding, or substituting an action, the server sends an action_ack event:

{"type":"action_ack","request_id":42,"status":"accepted",
 "elapsed_ms":850,"bank_consumed_ms":0,"bank_ms":15000}

Possible statuses:

status	Meaning	Score effect
accepted	The action was accepted and applied	None
rejected	The message parsed, but was not in possible_actions	Chombo
unparseable	Invalid JSON, invalid tile string, request_id mismatch, etc.	Chombo
stale	A late or old reply was discarded	None
defaulted	The deadline was missed and the server played a default action	None

Simple bots may ignore action_ack. It is primarily useful for debugging, latency measurement, and tracking remaining time bank.

3. Fixed timeout is replaced by grace + per-kyoku time bank

The old effective behavior was a fixed 3-second response window.

The new default rule is:

• grace_ms = 3000: each request has 3 seconds of free time.
• bank_ms = 15000: each player gets a 15-second time bank per kyoku.
• deadline_ms = grace_ms + remaining bank.

With a full bank, a bot can take up to 18 seconds on one request. Time beyond the 3-second grace is deducted from the bank. Once the bank is empty, the bot is back to a 3-second deadline.

The bank resets at the start of every kyoku and does not carry over.

Timeouts are still not penalized. On timeout, the server substitutes the default action:

• draw turn: tsumogiri
• call / ron response: none

Compatibility

This is a backward-compatible extension of the current MJAI-style protocol, not a clean-break envelope rewrite.

Existing bots can continue to connect without changes if they already ignore unknown fields and unknown event types.

What legacy bots will see:

Change	Legacy behavior
request_action.request_id	Ignored if the bot does not read it
request_action.time	Ignored if the bot does not read it
action_ack event	Should be ignored like any unknown event type
Response without request_id	Still accepted using legacy arrival-order binding with server-side stale-reply accounting
Timeout rule	More lenient than before: 3s grace + up to 15s bank

For best reliability, bot authors should update their bots to:

1. Echo request_id on every response.
2. Ignore unknown event types and unknown fields.
3. Read timing values from request_action.time instead of hardcoding timeout assumptions.
4. Validate every response against possible_actions before sending.

Echoing request_id is strongly recommended and may become mandatory for ranked play after a future notice period.

What is unchanged

Event	Behavior
Legal action within deadline	Accepted normally
Timeout	Server substitutes default action; no penalty
WebSocket disconnect	Server substitutes default actions for the rest of the game; no penalty
Illegal action	Chombo penalty, same as announced in #205
Malformed / unparseable message	Chombo penalty, same as announced in #205

Why this change was made

The previous protocol had no explicit identifier tying a bot response to the request_action it answered. That made delayed replies difficult to classify reliably.

The new request_id echo makes stale handling deterministic:

• current request_id -> process the action
• old request_id -> discard as stale, no penalty
• unknown / future request_id -> protocol violation, chombo
• no request_id -> legacy compatibility path

This should make slow-turn failures easier to debug and prevent delayed replies from being misclassified as illegal actions for later game states.