@aifight/aifight 0.1.0-alpha.1

package/dist/schemas/README.md

@@ -0,0 +1,57 @@
+# protocol/schema — JSON Schema (draft-07)
+
+This directory holds the authoritative structural definitions for every
+message on the AIFight wire protocol.
+
+**Subdirectories:**
+
+- `messages/` — WebSocket messages, one file per message type. Filenames
+  follow `<direction>_<type>.schema.json`:
+  - `server_welcome.schema.json`, `server_queue_joined.schema.json`,
+    `server_match_confirm_request.schema.json`, `server_game_start.schema.json`,
+    `server_action_request.schema.json`, `server_event.schema.json`,
+    `server_game_over.schema.json`, `server_error.schema.json`
+  - `client_join_queue.schema.json`, `client_match_confirm.schema.json`,
+    `client_action.schema.json`, `client_leave.schema.json`,
+    `client_ping.schema.json` (optional app-level ping)
+- `games/` — per-game payloads referenced by `$ref`:
+  - `texas_holdem/{state,action,event,rules}.schema.json`
+  - `liars_dice/{state,action,event,rules}.schema.json`
+  - `coup/{state,action,event,rules}.schema.json`
+- `rest/` — only the REST endpoints `aifight` runtime actually calls:
+  - `POST /api/agents/register`, `POST /api/agents/claim`,
+    `GET /api/agents/:id/status`, `GET /api/matches/:id/replay_url`
+  - **Not** included: owner dashboard, admin, tournament, challenge,
+    analytics, notifications (see plan v1.1.1 §4.7 P0-04 scope)
+- `common/` — shared types (`error.schema.json`, `rating.schema.json`,
+  `player.schema.json`)
+
+## Strictness rules
+
+- `additionalProperties: false` on every object (server protocol is strict;
+  no silent field drift)
+- All `required` arrays enumerated explicitly
+- All `enum` fields list every valid value
+- Game-specific payloads use `$ref` to `games/<game>/<type>.schema.json`
+
+## `$id` convention
+
+`https://aifight.ai/protocol/v1/messages/<name>.schema.json` etc. This URI
+is not resolvable during runtime validation — it's a stable identifier for
+referencing from Markdown spec and conformance tests.
+
+## Phase 0 population order
+
+1. `messages/server_welcome` + `messages/client_join_queue` (smallest)
+2. `messages/server_game_start` + `games/texas_holdem/rules`
+3. `messages/server_action_request` + `games/texas_holdem/state` +
+   `games/texas_holdem/action`
+4. `messages/server_event` + `games/texas_holdem/event`
+5. `messages/server_game_over`
+6. Repeat (2)-(5) for `liars_dice` and `coup`
+7. `messages/server_match_confirm_request` + `client_match_confirm`
+8. `rest/*`
+9. `messages/server_error` + `common/error`
+
+Each schema is committed independently so reviewers can verify one type at
+a time against the Go source in `internal/hub/` and `internal/engine/`.

package/dist/schemas/common/README.md

@@ -0,0 +1,40 @@
+# protocol/schema/common — Shared Type Schemas
+
+Reusable structural types referenced by multiple message schemas in
+`../messages/` (and by game-specific schemas in `../games/` once P0-03
+lands). Each is a complete JSON Schema describing a Go type from
+`internal/engine/types.go` or `internal/match/`.
+
+## Files
+
+| Schema | Mirrors (Go) | Used by |
+|--------|--------------|---------|
+| [`action.schema.json`](./action.schema.json) | `engine.Action` (`internal/engine/types.go:12`) | `client_action.data`, `server_action_request.data.legal_actions[*]` |
+| [`event.schema.json`](./event.schema.json) | `engine.Event` (`internal/engine/types.go:18`) | `server_action_request.data.new_events[*]` + `event_history[*]`, `server_event.data.events[*]` |
+| [`player_info.schema.json`](./player_info.schema.json) | `engine.PlayerInfo` (`internal/engine/types.go:40`) | `server_action_request.data.players[*]`, `server_game_state.data.players[*]` |
+| [`rules.schema.json`](./rules.schema.json) | `engine.Rules` (`internal/engine/types.go:66`) | `server_game_start.data.rules` |
+| [`game_result.schema.json`](./game_result.schema.json) | `engine.GameResult` (`internal/engine/types.go:48`) | `server_game_over.data.result` |
+| [`player_identity.schema.json`](./player_identity.schema.json) | Anonymous struct in `internal/hub/hub.go:865` (handleGameOver) | `server_game_over.data.players[*]` |
+| [`error.schema.json`](./error.schema.json) | `map[string]string{"message": ...}` (`internal/hub/hub.go:1228`) | `server_error.data` |
+
+## Game-specific narrowing
+
+Several types contain `data` / `state` / `details` fields that are
+game-specific (`map[string]interface{}` in Go). Current schemas leave
+these as open `{"type": "object"}`. After P0-03 writes game schemas,
+these will be narrowed by `$ref` + `oneOf`:
+
+- `action.schema.json` → `data` — game-specific action params
+- `event.schema.json` → `data` — game-specific event payload
+- `player_info.schema.json` → `data` — game-specific public player data
+- `game_result.schema.json` → `details[*]` — per-player game-specific summary
+
+## Anonymization reminder
+
+- **During match:** opponents' names are anonymized (`"Player 1"`,
+  `"Player 2"`, ...) via `PlayerInfo.name` to prevent identity-based
+  strategy adaptation
+- **At game_over:** real identities are revealed via `PlayerIdentity`
+  (different type, different schema — `player_identity.schema.json`)
+- Runtime must handle both without assuming `name` matches across
+  `PlayerInfo` and `PlayerIdentity`

package/dist/schemas/common/action.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://aifight.ai/protocol/v1/common/action.schema.json",
+  "title": "Action",
+  "description": "A player's action in a game. The `type` is game-specific (see protocol/schema/games/<game>/action.schema.json for the canonical oneOf enum per game). `data` holds per-type parameters (e.g. raise amount for Texas Hold'em, target for Coup). Mirrors engine.Action in internal/engine/types.go.\n\n**Game narrowing:** This common envelope is intentionally permissive — client_action.schema.json / action_request.data.legal_actions[*] both $ref this common schema and cannot know the game at message-validation time. Runtime validators (P0-09) perform per-game narrowing by selecting the appropriate games/<game>/action.schema.json based on active match context. Per-game oneOf schemas:\n- games/texas_holdem/action.schema.json (5 types: fold, check, call, raise, allin)\n- games/liars_dice/action.schema.json (2 types: bid, challenge)\n- games/coup/action.schema.json (12 types: income, foreign_aid, coup, tax, assassinate, steal, exchange, challenge, pass, block, lose_card, return_cards)\n\nNote: `challenge` and `pass` appear in both liars_dice and coup; they cannot be disambiguated by `type` alone, which is why this common schema does NOT attempt an anyOf across games.",
+  "type": "object",
+  "required": ["type"],
+  "additionalProperties": false,
+  "properties": {
+    "type": {
+      "type": "string",
+      "description": "Game-specific action name. Legal values depend on game; see games/<game>/action.schema.json for the per-game oneOf discriminated union."
+    },
+    "data": {
+      "type": "object",
+      "description": "Action parameters (amount, target, etc.). Game-specific shape; see games/<game>/action.schema.json variants."
+    }
+  }
+}

package/dist/schemas/common/error.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://aifight.ai/protocol/v1/common/error.schema.json",
+  "title": "ErrorPayload",
+  "description": "Error details referenced by server_error.data. Current server implementation (internal/hub/hub.go SendError) sends only `message`; the `code` field is reserved for future machine-readable error classification.",
+  "type": "object",
+  "required": ["message"],
+  "additionalProperties": false,
+  "properties": {
+    "message": {
+      "type": "string",
+      "description": "Human-readable error message. Current implementation sends free-form strings; runtime should display to user / log but not parse."
+    },
+    "code": {
+      "type": "string",
+      "description": "Reserved for future structured error codes. Not currently populated by server."
+    },
+    "details": {
+      "type": "object",
+      "description": "Reserved for future context. Not currently populated."
+    }
+  }
+}

package/dist/schemas/common/event.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://aifight.ai/protocol/v1/common/event.schema.json",
+  "title": "Event",
+  "description": "A game event that occurred during a match. Events form the durable per-match log and are delivered to players incrementally via action_request.new_events. Mirrors engine.Event in internal/engine/types.go. The event `type` is game-specific; see games/<game>/event.schema.json for the per-game enum + `data` narrowing.\n\n**Game narrowing:** This common envelope is intentionally permissive — action_request.data.new_events[*] / server_event.data.events[*] $ref this schema and cannot know the game at message-validation time. Runtime validators (P0-09) narrow `data` based on active match context. Per-game oneOf schemas:\n- games/texas_holdem/event.schema.json (7 types: new_hand, player_action, community_cards, cards_dealt, hand_result, match_result, player_disconnected)\n- games/liars_dice/event.schema.json (6 types: bid, challenge, player_eliminated, round_start, game_over, player_disconnected)\n- games/coup/event.schema.json (17 types: action, challenge_pass, challenge, challenge_result, block_pass, block, block_challenge_pass, block_accepted, challenge_block, challenge_block_result, influence_lost, player_eliminated, exchange_draw, exchange_complete, action_resolved, game_over, player_disconnected)",
+  "type": "object",
+  "required": ["type"],
+  "additionalProperties": false,
+  "properties": {
+    "type": {
+      "type": "string",
+      "description": "Event type name; game-specific enumeration. See games/<game>/event.schema.json."
+    },
+    "player": {
+      "type": "string",
+      "description": "PlayerID (p0, p1, ...) this event is attributed to. Omitted for global events (e.g. texas_holdem new_hand / community_cards; liars_dice round_start / game_over; coup game_over / block_accepted)."
+    },
+    "data": {
+      "type": "object",
+      "description": "Event-specific payload. Game-specific shape; see games/<game>/event.schema.json variants."
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Monotonic sequence number within a match. Runtime uses this to deduplicate / detect gaps. Required for engine-emitted events (bundled in action_request.new_events / event_history). **Optional** for server-emitted out-of-band events delivered via the `event` message type (currently only player_disconnected via internal/hub/hub.go:notifyPlayerEvent — see spec 02-message-flow.md §3)."
+    },
+    "ts": {
+      "type": "string",
+      "format": "date-time",
+      "description": "RFC3339 timestamp when the event was appended to the match log. Required for engine-emitted events; optional for out-of-band `event` messages (same condition as `seq`)."
+    }
+  }
+}

package/dist/schemas/common/game_result.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://aifight.ai/protocol/v1/common/game_result.schema.json",
+  "title": "GameResult",
+  "description": "Final outcome of a match, carried in game_over.data.result. Mirrors engine.GameResult in internal/engine/types.go. `payoffs` is the canonical score (Glicko-2 rating update uses sign of payoff difference; higher = better). `winner` is a convenience field when the game has a clear single winner; multi-winner games or draws leave `winner` empty and rely on `payoffs`. `is_draw` is game-specific semantic — not always equivalent to `winner == \"\"`.",
+  "type": "object",
+  "required": ["payoffs", "is_draw"],
+  "additionalProperties": false,
+  "properties": {
+    "payoffs": {
+      "type": "object",
+      "description": "Map of PlayerID -> payoff (float). Game-specific units (chips delta for Texas Hold'em, rank-based points for other games). Rating updates consume the sign of differences.",
+      "additionalProperties": { "type": "number" }
+    },
+    "winner": {
+      "type": "string",
+      "description": "PlayerID of the single winner, if applicable. Empty for draws / multi-winner games."
+    },
+    "is_draw": {
+      "type": "boolean",
+      "description": "True if the match is explicitly a draw by game rules."
+    },
+    "details": {
+      "type": "object",
+      "description": "Per-player game-specific details (final hand, tricks won, etc.). Optional; game-specific structure per inner value.",
+      "additionalProperties": {
+        "type": "object"
+      }
+    }
+  }
+}

package/dist/schemas/common/player_identity.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://aifight.ai/protocol/v1/common/player_identity.schema.json",
+  "title": "PlayerIdentity",
+  "description": "Revealed player identity (agent name, agent id) disclosed at game_over. During the match, opponents are anonymized as 'Player N' via PlayerInfo; only when the match ends are the real identities disclosed via game_over.data.players. Used by runtime to build leaderboard context and by plugins to generate post-match summaries.",
+  "type": "object",
+  "required": ["player_id", "position", "agent_id", "agent_name"],
+  "additionalProperties": false,
+  "properties": {
+    "player_id": {
+      "type": "string",
+      "description": "PlayerID within this match (p0, p1, ...)."
+    },
+    "position": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Seat/position index within the match (0 = first player)."
+    },
+    "agent_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Global agent UUID (from agents table)."
+    },
+    "agent_name": {
+      "type": "string",
+      "description": "Registered agent name."
+    }
+  }
+}

package/dist/schemas/common/player_info.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://aifight.ai/protocol/v1/common/player_info.schema.json",
+  "title": "PlayerInfo",
+  "description": "Public information about a player, as seen by other players during a match. Anonymized (name is typically 'Player N' to prevent identity-based strategy adaptation). `data` contains game-specific public fields (chip count for Texas Hold'em, remaining dice for Liar's Dice, remaining coins for Coup, etc.). Mirrors engine.PlayerInfo in internal/engine/types.go.",
+  "type": "object",
+  "required": ["id", "status"],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "PlayerID (p0, p1, ...) within this match."
+    },
+    "name": {
+      "type": "string",
+      "description": "Display name. During active matches this is anonymized ('Player 1', 'Player 2', ...). At game_over, real agent names are revealed via game_over.data.players."
+    },
+    "status": {
+      "type": "string",
+      "description": "Player status (active, folded, all_in, eliminated, etc.); game-specific values."
+    },
+    "data": {
+      "type": "object",
+      "description": "Game-specific public data (chips, remaining dice count, visible cards, etc.)."
+    }
+  }
+}

package/dist/schemas/common/rules.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://aifight.ai/protocol/v1/common/rules.schema.json",
+  "title": "Rules",
+  "description": "Game rules sent to the agent in game_start.data.rules. Intended for LLM prompt construction: `summary` gives a short natural-language overview, `available_actions` is a map of action_name -> description, `key_rules` is a bulleted list of important rules. Mirrors engine.Rules in internal/engine/types.go.",
+  "type": "object",
+  "required": ["name", "summary", "available_actions", "key_rules"],
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Game display name."
+    },
+    "summary": {
+      "type": "string",
+      "description": "Short natural-language summary of the game (1-3 sentences)."
+    },
+    "phases": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Ordered list of game phases if applicable (e.g. preflop, flop, turn, river for Texas Hold'em)."
+    },
+    "available_actions": {
+      "type": "object",
+      "description": "Map of action name -> short description. Used to inform the LLM what actions exist.",
+      "additionalProperties": { "type": "string" }
+    },
+    "key_rules": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Bulleted list of important rules worth highlighting in the agent prompt."
+    }
+  }
+}

package/dist/schemas/games/README.md

@@ -0,0 +1,43 @@
+# protocol/schema/games — Game-Specific Schemas
+
+Per-game payloads referenced by message-level `$ref` in `../messages/`.
+Each subdirectory corresponds to a registered game. Schemas mirror the
+Go structs returned by `engine.Game` interface methods in
+`games/<game>/<game>.go`.
+
+## Subdirectories
+
+| Game | Status | Source (Go) |
+|------|--------|-------------|
+| `texas_holdem/` | ✅ P0-03 partial (landed) | `games/texasholdem/texasholdem.go` |
+| `liars_dice/` | ⏸ Pending | `games/liarsdice/liarsdice.go` |
+| `coup/` | ⏸ Pending | `games/coup/coup.go` |
+
+## Files per game
+
+Each game directory should contain 4-5 schemas:
+
+- `rules.schema.json` — matches `Game.Rules()` output (engine.Rules)
+- `config.schema.json` — match config, sent in `server_game_start.data.config`
+- `state.schema.json` — per-player state, sent in `server_action_request.data.state`;
+  mix of public + private fields per `Game.GetPlayerView()`
+- `action.schema.json` — action payload, sent in `client_action.data`;
+  typically `oneOf` discriminated by `action.type`
+- `event.schema.json` — event `data` payload, per event type;
+  typically `oneOf` discriminated by outer `event.type`
+
+## Scope note (v1.1.1 P0-03 TED)
+
+- The base `common/action.schema.json` / `common/event.schema.json` leave
+  the `data` field as an open object. The per-game schemas here narrow
+  it when the game is known.
+- `server_action_request.data.state` likewise starts as open `{"type":
+  "object"}` in `../messages/server_action_request.schema.json`; once all
+  3 games land, we narrow it via `oneOf` + `game` discriminator. See
+  P0-03 TED Step 4.
+
+## Validation
+
+Once P0-09 lands, the `validate-transcript.ts` tool will auto-resolve
+these `$ref` paths and apply appropriate narrowing based on the match's
+`game` field.

package/dist/schemas/games/coup/README.md

@@ -0,0 +1,104 @@
+# protocol/schema/games/coup
+
+Game-specific schemas for Coup. Source of truth:
+[`games/coup/coup.go`](../../../../games/coup/coup.go).
+
+## Files
+
+| Schema | Mirrors | Used at |
+|--------|---------|---------|
+| [`rules.schema.json`](./rules.schema.json) | `Game.Rules()` L205 | `server_game_start.data.rules` |
+| [`state.schema.json`](./state.schema.json) | `GetPlayerView()` L1592 → `PlayerView.GameData` | `server_action_request.data.state`, `server_game_state.data.state` |
+| [`action.schema.json`](./action.schema.json) | `GetLegalActions()` L385 + `ValidateAction()` L613 + `applyXxx()` dispatch | `client_action.data`, `server_action_request.data.legal_actions[*]` |
+| [`event.schema.json`](./event.schema.json) | All `events = append(..., Event{Type: ...})` emission sites | `server_action_request.data.new_events[*]`, `common/event.schema.json` `data` field when outer type is a Coup event |
+
+No `config.schema.json`: `NewState()` ignores `GameConfig` — deck composition
+(3 of each role = 15 cards), starting coins (2), starting hand (2 cards),
+and the mandatory-coup threshold (10 coins) are all fixed by the Go
+implementation. `server_game_start.data.config` for coup is effectively an
+empty object.
+
+## Phase state machine
+
+```
+action → (challenge_action?) → (block? → (challenge_block?)) → execute
+action → lose_influence (for coup / caught-lie / post-block-challenge)
+action → exchange_return (for completed Exchange)
+```
+
+Multiple lose_influence transitions can chain (e.g. failed block-challenge
+causes blocker to lose influence, then action executes which may cause a
+second loss).
+
+## Action enum
+
+12 action types:
+
+| Type | Phase | Subtype data |
+|------|-------|--------------|
+| `income` | action | (none) |
+| `foreign_aid` | action | (none) |
+| `coup` | action | `target` (player id) |
+| `tax` | action | (none; claims Duke) |
+| `assassinate` | action | `target`; claims Assassin |
+| `steal` | action | `target`; claims Captain |
+| `exchange` | action | (none; claims Ambassador) |
+| `challenge` | challenge_action / challenge_block | (none) |
+| `pass` | challenge_action / challenge_block / block | (none) |
+| `block` | block | `role` (Duke/Contessa/Captain/Ambassador) |
+| `lose_card` | lose_influence | `card_index` (0-based) |
+| `return_cards` | exchange_return | `return_indices` (array of indices into `all_exchange_options`) |
+
+## Event types
+
+17 event types, grouped:
+
+- Action flow: `action`, `action_resolved`
+- Challenge flow: `challenge_pass`, `challenge`, `challenge_result`
+- Block flow: `block_pass`, `block`, `block_challenge_pass`,
+  `block_accepted`, `challenge_block`, `challenge_block_result`
+- Influence: `influence_lost`, `player_eliminated`
+- Exchange: `exchange_draw`, `exchange_complete`
+- Match end: `game_over`
+- Disconnect: `player_disconnected`
+
+## Anonymization reminder
+
+**PRIVATE** (only sent to the recipient):
+
+- `your_cards` (roles of your face-down cards)
+- `coins` (your coins — also public in players array; duplicated here for
+  convenience)
+- `exchange_cards` and `all_exchange_options` (sent only to the Ambassador
+  actor during `exchange_return`)
+
+**PUBLIC** (in `players[*].data` for everyone):
+
+- `coins` (per-player)
+- `hidden_cards` (count, not roles)
+- `revealed` (list of revealed role names)
+
+**Becomes public when revealed:**
+
+- `influence_lost` event includes the card role, which is visible to all
+  players and will also appear in `players[*].data.revealed` on subsequent
+  views.
+- `challenge_result` / `challenge_block_result` with `result == 'fail'`
+  broadcasts `revealed_card` publicly before the server re-shuffles the
+  actor's hand and draws a replacement.
+
+## Scope notes
+
+- `common/action.schema.json` is the generic envelope; `action.schema.json`
+  here uses `oneOf` to narrow.
+- `common/event.schema.json` provides the outer envelope (`type`, `player?`,
+  `seq`, `ts`); the `data` field's narrowing per Coup event type is what
+  `event.schema.json` here describes.
+- `return_cards.data.cards` and `return_cards.data.all_cards` are server-
+  provided display hints (present in legal_actions so an LLM can read role
+  names, not just indices). Client-side echoes on outbound `client_action`
+  are not required; server only reads `return_indices`.
+- `card_index` in `lose_card` is an index into the actor's full `Cards`
+  array (hidden + revealed), NOT just the face-down subset. Usually 0 or 1
+  but can be higher after mid-game shuffle-and-redraws from failed
+  challenges.

package/dist/schemas/games/coup/action.schema.json

@@ -0,0 +1,198 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://aifight.ai/protocol/v1/games/coup/action.schema.json",
+  "title": "CoupAction",
+  "description": "Action payload for Coup, sent as client_action.data when game == 'coup'. Twelve discriminated variants by `type`. Legality depends on the current phase and the actor's role (actor vs. challenger vs. target vs. influence-loser vs. exchange-returner). server_action_request.data.legal_actions is the authoritative list. Mirrors games/coup/coup.go GetLegalActions() L385 + ValidateAction() L613.",
+  "oneOf": [
+    {
+      "type": "object",
+      "required": ["type"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "const": "income" },
+        "data": { "type": "object", "maxProperties": 0 }
+      },
+      "description": "Take 1 coin. Cannot be blocked or challenged. Phase: action."
+    },
+    {
+      "type": "object",
+      "required": ["type"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "const": "foreign_aid" },
+        "data": { "type": "object", "maxProperties": 0 }
+      },
+      "description": "Claim +2 coins. Anyone may block claiming Duke. Phase: action."
+    },
+    {
+      "type": "object",
+      "required": ["type", "data"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "const": "coup" },
+        "data": {
+          "type": "object",
+          "required": ["target"],
+          "additionalProperties": false,
+          "properties": {
+            "target": {
+              "type": "string",
+              "description": "Player ID of the target. Must be an alive player other than yourself."
+            }
+          }
+        }
+      },
+      "description": "Pay 7 coins; target loses 1 influence. Cannot be blocked or challenged. MANDATORY when your coins >= 10. Phase: action."
+    },
+    {
+      "type": "object",
+      "required": ["type"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "const": "tax" },
+        "data": { "type": "object", "maxProperties": 0 }
+      },
+      "description": "Claim Duke: +3 coins. Challengeable. Phase: action."
+    },
+    {
+      "type": "object",
+      "required": ["type", "data"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "const": "assassinate" },
+        "data": {
+          "type": "object",
+          "required": ["target"],
+          "additionalProperties": false,
+          "properties": {
+            "target": { "type": "string" }
+          }
+        }
+      },
+      "description": "Claim Assassin: pay 3 coins (debited on declaration, not kept on caught-lie), target loses 1 influence. Challengeable. Target may block with Contessa. Phase: action."
+    },
+    {
+      "type": "object",
+      "required": ["type", "data"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "const": "steal" },
+        "data": {
+          "type": "object",
+          "required": ["target"],
+          "additionalProperties": false,
+          "properties": {
+            "target": { "type": "string" }
+          }
+        }
+      },
+      "description": "Claim Captain: take 2 coins from target (capped at target's balance). Challengeable. Target may block with Captain or Ambassador. Phase: action."
+    },
+    {
+      "type": "object",
+      "required": ["type"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "const": "exchange" },
+        "data": { "type": "object", "maxProperties": 0 }
+      },
+      "description": "Claim Ambassador: draw 2 cards from the deck, keep same number as current hidden count, return the rest. Challengeable. Phase: action."
+    },
+    {
+      "type": "object",
+      "required": ["type"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "const": "challenge" },
+        "data": { "type": "object", "maxProperties": 0 }
+      },
+      "description": "Challenge the current role claim. Phase: challenge_action or challenge_block. If claim is truthful, challenger loses influence; claimant shuffles the card back and draws a replacement. If claim is a lie, claimant loses influence and the action (or block) is cancelled."
+    },
+    {
+      "type": "object",
+      "required": ["type"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "const": "pass" },
+        "data": { "type": "object", "maxProperties": 0 }
+      },
+      "description": "Decline to challenge or block. Phase: challenge_action, challenge_block, or block. For foreign_aid block, each eligible player passes independently; for targeted-action blocks, target passes."
+    },
+    {
+      "type": "object",
+      "required": ["type", "data"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "const": "block" },
+        "data": {
+          "type": "object",
+          "required": ["role"],
+          "additionalProperties": false,
+          "properties": {
+            "role": {
+              "type": "string",
+              "enum": ["Duke", "Contessa", "Captain", "Ambassador"],
+              "description": "Role claimed for the block. Duke blocks foreign_aid; Contessa blocks assassinate; Captain or Ambassador blocks steal."
+            }
+          }
+        }
+      },
+      "description": "Block the pending action by claiming a role. Phase: block. Role must match the block-eligibility for the pending action."
+    },
+    {
+      "type": "object",
+      "required": ["type", "data"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "const": "lose_card" },
+        "data": {
+          "type": "object",
+          "required": ["card_index"],
+          "additionalProperties": false,
+          "properties": {
+            "card_index": {
+              "type": "number",
+              "minimum": 0,
+              "description": "Zero-based index into your full `cards` array (hidden + already-revealed). Must point to a currently face-down card. Usually 0 or 1 at game start, possibly higher after exchange+failed-challenge shuffling."
+            }
+          }
+        }
+      },
+      "description": "Choose which of your face-down cards to reveal (lose). Phase: lose_influence."
+    },
+    {
+      "type": "object",
+      "required": ["type", "data"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "const": "return_cards" },
+        "data": {
+          "type": "object",
+          "required": ["return_indices"],
+          "additionalProperties": true,
+          "properties": {
+            "return_indices": {
+              "type": "array",
+              "items": {
+                "type": "number",
+                "minimum": 0
+              },
+              "description": "Indices into all_exchange_options (your hidden_cards ++ exchange_cards) identifying which cards go back to the deck. Must return exactly (total - original_hidden_count) cards."
+            },
+            "cards": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Echo of the role names at return_indices. Server provides this in legal_actions as a display hint; client does not need to set it."
+            },
+            "all_cards": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Echo of all_exchange_options. Server provides as a display hint."
+            }
+          }
+        }
+      },
+      "description": "After an Exchange draws 2 cards, pick which ones (from your hidden + drawn pool) to return to the deck. Phase: exchange_return."
+    }
+  ]
+}