Playing a CIG2 game from an automated client

This is a game-agnostic guide for a program, such as an LLM playtest agent, a bot or a load test, that plays a CIG2 game over the host HTTP surface. It does not need to know the game’s rules up front. Everything it needs is in the snapshot it reads.

Everything here is opt-in on the server. The worked example uses cmd/cig2-demo, started in agent mode:

go run ./cmd/cig2-demo -addr 127.0.0.1:8080 -sync-actions
B=http://127.0.0.1:8080

In Go, that is host.Server{SyncActions: true}; seat tokens are on by default (a server started with -insecure-seats / InsecureSeats has none). Every host.Run server also refuses POSTs a browser marks as cross-site; an agent sends no Origin or Sec-Fetch-Site header, so it is unaffected. Behind -password-env, add -u any:$PASSWORD to every curl. Basic Auth with the app password is the outer gate.

The loop

discover → claim a seat → read state → (act | answer) → read state → … → over

0. Learn the game and the API

Two routes let you learn the server without reading its source:

curl -s $B/describe       # the game's rules, seat range, and JSON Schema for each action's data
curl -s $B/schema         # every wire type as JSON Schema; $B/openapi.json is the whole API

/describe answers 404 for a game that doesn’t implement cig2.GameDescriber. Then legal hints (below) are your only guide, and they are enough.

Signing in: lobby and matchmaking

A server with an identity layer (host.Config.Identity) gives you a principal instead of seat tokens. An agent signs in with an API key that an operator issues (POST /auth/keys, or Identity.IssueAPIKey):

H="Authorization: Bearer cig2_…"
curl -s -H "$H" $B/auth/me                                   # who you are
curl -s -H "$H" -X POST $B/match/tickets -d '{"game":"high-card-duel"}'
curl -s -H "$H" $B/match/tickets/<id>                        # until "status":"matched": your table and seat
curl -s -H "$H" $B/lobby/tables/<table>/state                # then play: state, action, events
curl -s -H "$H" -X POST $B/lobby/tables/<table>/action -d '{"action":"reveal","id":"a1"}'
curl -s -H "$H" $B/auth/me/results                           # your match history

A seat bound to your identity needs no token, so steps 2 to 6 below apply with /lobby/tables/<table>/… routes and the Authorization header in place of ?player=&token=. Lobby actions are always synchronous (200, 422 or 409, as with -sync-actions). GET /lobby/tables and POST /lobby/tables are the self-serve alternative to matchmaking: join a table, then POST …/ready.

1. Discover

curl -s $B/tables
# {"game":"high-card-duel","tables":[{"id":"default","seats":["p1","p2"]}]}

Routes without a prefix (/state, /action, …) address the table default. Any other table uses /t/<id>/…. A server may run in explicit mode (Registry.SetExplicit). There, an unknown table is 404 until someone creates it:

curl -s -X POST $B/t/game7/create -d '{"config": {"faction": "red"}}'
# {"status":"created","table":"game7"}        (409 if it exists)

The config body reaches the game’s Setup as raw JSON. Its meaning is up to the game: house rules, factions, a bias spec. A game that decodes it with cig2.DecodeConfig rejects unknown keys and bad values with a 400 naming the problem (nothing is created; a rejected reset keeps the current game).

To make a game reproducible, add "seed": <integer> to a create or reset body. The same seed, game and actions deal the same cards. The seed applies to that one game, and a plain reset deals a fresh one. If the server runs with ExposeSeeds, every create and reset response (and /tables) reports the seed actually used, so you can record any game and replay it with {"seed": n}. Seeds reveal every hidden card, so never hand one to a player agent while its game runs. A replay deals the same cards but not the same card uuids — those are random every game — so compare replays by what the cards are and where they sit, never by uuid.

2. Claim a seat

curl -s -X POST "$B/claim?player=p1"
# {"seat":"p1","table":"default","token":"2743a867e72d0144fbb94766d5adde10"}

Send that token on every later request for the seat — preferably as the X-CIG2-Seat-Token header, since a ?token= in the URL lands in access and proxy logs (use &token= only for the event stream, if your client cannot set headers). Without it you get 403. The claim also completes the session’s join handshake for your seat, so never send an "ack" action yourself. A seat already claimed by someone else is 409. Tokens survive reset. To give a seat up, call POST /release?player=p1&token=…. (Seat tokens are on by default; only a server started with -insecure-seats has none, and its /claim is 404.)

3. Read state

curl -s "$B/state?player=p1&token=$T1"

This returns your full current snapshot. It is the same JSON the event stream would push, filtered for your seat. The fields an agent needs:

fieldmeaning
youyour seat
rootthe board: a tree of zones. Each has count (always true). cards holds only what you may see. A card without payload is face-down to you
legalif present, the actions the game says you may take now, each {"action","data","label"}. [] means nothing is legal for you right now (wait). If the field is missing, the game gives no hints
decisionspending server questions. An entry with ask is yours to answer (see 5). Without ask, someone else is deciding
turn, phase, roundturn and phase, if the game uses them
game_stategame-specific extra state, shaped by the game
ack_idthe id of your latest accepted action
over, resultthe game has ended, and who won

Use polling or streaming, whichever suits you. To stream, GET /events?player=p1&token=… is Server-Sent Events, with one data: snapshot per change. When the server ends a stream on purpose, its last frame is event: close with data: {"reason": …}: "reset" (reconnect now for the new game), "displaced" (another client claimed your seat — don’t fight it in a loop), "shutdown", "deleted" (the table is gone; stop), or "failed" (a bug in the game stopped the table; it answers 500 until someone resets it — report it, don’t retry in a loop). A stream that ends with no farewell was a network drop.

4. Act

Send one of the legal entries back exactly as you got it. Add an id of your own so you can match the answer:

curl -s -X POST "$B/action?player=p1&token=$T1" -d '{"action":"reveal","id":"a1"}'
# {"ok":true,"id":"a1"}                                             200
curl -s -X POST "$B/action?player=p1&token=$T1" -d '{"action":"reveal","id":"a2"}'
# {"ok":false,"id":"a2","error":"highcardduel: p1 has already revealed"}   422

With -sync-actions (SyncActions), the response is the outcome:

statusmeaningwhat to do
200accepted, applied, settledread state
422the game rejected it; error says whyread state, pick again
409the game is overstop
400your JSON was malformedfix the envelope
403/404wrong token or unknown seat/tablere-claim / re-discover
500a game bug: a settle runaway, or a panic ("internal error"). If the table failed, every request answers 500 until a resetreport it; POST reset to start over

Without sync mode, POST /action always returns 202 right away. A rejection then arrives on the event stream as {"type":"error","message":…,"id":"a2"}. id names your action, and once an action is accepted it shows up as ack_id in your next snapshot.

legal is a hint, not the rule. The game’s own validation is the only judge, so a stale hint just gets a 422.

Action names starting with cig2. belong to the framework: anything but cig2.answer is a 422. Actions the game runs on timers (a turn timeout, an AI move) can’t be sent by a client: the game sees your copy as a player action and rejects it.

5. Answer a decision

When a snapshot’s decisions holds an entry with ask, the server is waiting for you:

"decisions": [{"id": "d-91…", "seat": "p1", "deadline": "2026-10-07T12:00:30Z",
  "ask": {"kind": "keep-one", "prompt": {…}, "choices": ["u1", "u2", "u3"], "min": 1, "max": 1}}]

Answer by picking between min and max distinct choices:

curl -s -X POST "$B/action?player=p1&token=$T1" \
  -d '{"action":"cig2.answer","id":"a5","data":{"id":"d-91…","choices":["u2"]}}'

The same status codes apply. After deadline, the game answers for you with its default, so a slow agent never hangs the table. Decisions are not repeated in legal.

6. Detect the end

curl -s "$B/state?player=p1&token=$T1"
# … "over":true, "result":{"winners":["p2"],"reason":"highest card"}, "legal":[] …

Once over is true, every further action is 409. For another game, call POST /reset (or /t/<id>/reset, optionally with {"config": …} and/or {"seed": …}). Your seat token remains valid.

A server with AllowDelete also takes POST /t/<id>/delete (200, 404 if unknown). It ends the table for good — streams get the "deleted" farewell, seat tokens go with it — and the ID can be created again.

Rules of thumb for agents

  • Re-read state after every action. Don’t track the board in your head: snapshots are complete, never diffs.
  • Act only from legal, answer only questions that have ask, and treat legal: [] as “wait”, not “stuck”.
  • Tag every action with an id. It’s the only way to tie an asynchronous error to the action that caused it.
  • What you can’t see doesn’t exist for you. Missing payloads and counts without card entries are deliberate. The server never sends what your seat may not know.