harness-multitool

0029 — Games between agents, Texas hold'em first

Why

The owner wants multitool's agents to play games with each other, Texas hold'em first:

Decision (draft)

The engine on the daemon

A crate harness-games holds a Game interface and its first implementation, texas_holdem. It needs no platform (INV-1):

pub trait Game {
    fn name(&self) -> &str;
    fn seats(&self) -> std::ops::RangeInclusive<usize>;      // 2..=9 for hold'em
    fn start(&mut self, players: &[PlayerId], seed: u64, rules: &Value) -> Vec<GameEvent>;
    fn act(&mut self, player: &PlayerId, action: &Value) -> Result<Vec<GameEvent>, Refusal>;
    fn timeout(&mut self, player: &PlayerId) -> Vec<GameEvent>; // the rule of a silent player
    fn view(&self, player: Option<&PlayerId>) -> Value;       // what one player may see; None is a spectator
}

Hold'em covers:

A hand is reproducible from its seed and actions, which is how it is tested.

Tables and players

The daemon keeps <data dir>/games/tables/<id>.json: the game, the rules, the seats and the table's own state.

Every hand has its own SQLite database, <data dir>/games/tables/<id>/hand-<n>.sqlite, with the hand's meta, every action taken and every event the rules gave (private ones included).

These databases are the source of truth:

A player is an agent: a conversation in some window, named by its nick (CON-105). An agent is online when its tab is open with a session.

Callbacks: kind game

The daemon puts game messages into an agent's queue as an inbound message of a new kind, game, alongside telegram, agent and callback (the inbound-messages fixtures). Its card is the callback card in its own colour. The messages:

WhenSays
invitedYou are invited to a poker table T7 (6 seats, blinds 10/20). Join with game_join, or game_decline.
your turnYour turn at T7, hand 12: you hold A♠ K♦, the board is …, the pot is 340, it is 60 to call. Act with game_act.
a player actedAt T7: nick raised to 120. Batched, so a turn's message carries what happened since the last one.
a hand endedHand 12 at T7: nick won 340 with a flush.
the game endedThe game at T7 ended: 1st nick (2400), 2nd …

Tools for agents

A tool refuses an illegal action and says why, for example "a raise must be at least 40".

Settings > Games

The dashboard

The daemon serves a page on its HTTP port: /dashboard, local only. Its tabs:

Other tabs can come later (journals, maps).

A table, live

A table is drawn in a design of the harness's own:

How it stays current:

The page

The page is one static HTML file with CSS and JavaScript, embedded in the binary, with no build step. It reads /dashboard/api/*, which answers JSON.

Open questions for the owner (journal#952)

  1. Chips: play money only? The starting stack and blinds by default? The draft: 1000, blinds 10/20, rising every 10 hands.

  2. Time to act, and what happens to a silent agent? The draft was 120 s, then check or fold. The owner, 2026-11-12: no limit, a game is played at leisure and an agent may be busy; the rules act only for one who left (journal#1006).

  3. Can the user sit at a table from the dashboard? The draft: no, the user watches.

  4. Access to the dashboard: local only, with a token in the URL as callbacks have? The draft: localhost, plus the daemon's token.

  5. Cost: every 'your turn' is a model turn of the agent. Should a table have a limit on hands or on cost? The draft: a limit of 50 hands, and the table stops when an agent's session ends.

  6. Do agents see each other's chat, or table talk? The draft: no.

Rejected

This page's source