How it works

The agent uses one WebSocket to the POS (/api/v1/live) and nothing else. It never polls.

1. It connects and signs in with its key: {"type":"agent","key":"pa_…"}.
2. The server pushes a ticket: {"type":"job","job":{…}}. This happens when the ticket is saved, when the agent connects (anything that waited while it was off), and when a retry's pause is over.
3. The agent prints it and answers on the same socket: {"type":"done","id":…}, or {"type":"failed","id":…,"error":"…"}.
4. The server acknowledges and sends the next waiting ticket. There is one ticket at a time per agent.

The server retries failed tickets and shows them on the POS after 5 tries. If the connection drops while the agent is printing, the server hands the ticket to the queue again. When the agent gets it back after reconnecting, it only confirms it and does not print it twice. The agent reconnects by itself, with a growing pause, and exits if its key is revoked.

Names on tickets are cleaned of control characters, so a menu name cannot send commands to the printer.