agent-relay 1.1.0 → 1.2.3

package/scripts/games/game-protocol.md

@@ -1,79 +0,0 @@
-# Multi-Agent Game Protocol
-
-This document defines the standard protocol for multi-agent games using agent-relay.
-
-## Core Commands
-
-All agents use these `agent-relay` commands:
-
-### Wait for messages (blocking)
-```bash
-agent-relay inbox-poll -n YOUR_NAME -d GAME_DIR --clear
-```
-
-### Send to one player
-```bash
-agent-relay inbox-write -t RECIPIENT -f YOUR_NAME -m "MESSAGE" -d GAME_DIR
-```
-
-### Broadcast to all players
-```bash
-agent-relay inbox-write -t "*" -f YOUR_NAME -m "MESSAGE" -d GAME_DIR
-```
-
-### List all players
-```bash
-agent-relay inbox-agents -d GAME_DIR
-```
-
-## Message Format
-
-All game messages should follow this structure:
-
-```
-ACTION: <action_type>
-DATA: <json_or_text>
-```
-
-### Standard Actions
-
-- `PLAY` - Make a game move
-- `PASS` - Pass cards/turn
-- `STATE` - Share game state
-- `TURN` - Indicate whose turn it is
-- `RESULT` - Announce round/game result
-- `ACK` - Acknowledge receipt
-
-## Turn-Based Protocol
-
-1. **Wait Phase**: Run `inbox-poll` to wait for your turn
-2. **Action Phase**: Process received message, make your move
-3. **Send Phase**: Send your action to next player or broadcast
-4. **Repeat**: Go back to Wait Phase
-
-## Game Coordinator
-
-For complex games, one player can act as coordinator:
-- Deals cards/sets up game
-- Validates moves
-- Tracks state
-- Announces results
-
-## Example Flow (3 players: A, B, C)
-
-```
-A: Broadcasts "ACTION: STATE, DATA: {round: 1, turn: A}"
-A: Makes move, sends to B "ACTION: PLAY, DATA: {card: '2H'}"
-A: Runs inbox-poll (blocks)
-
-B: Receives A's message
-B: Makes move, sends to C "ACTION: PLAY, DATA: {card: '5H'}"
-B: Runs inbox-poll (blocks)
-
-C: Receives B's message
-C: Makes move, broadcasts "ACTION: PLAY, DATA: {card: 'KH'}"
-C: Broadcasts "ACTION: TURN, DATA: {winner: C, next_lead: C}"
-C: Runs inbox-poll (blocks)
-
-A: Receives broadcast, continues...
-```

package/scripts/games/hearts-setup.sh

@@ -1,264 +0,0 @@
-#!/bin/bash
-#
-# Hearts - 3 Player Autonomous Agent Game
-# Sets up three agents to play Hearts autonomously via file-based inbox
-#
-
-set -e
-
-GAME_DIR="${GAME_DIR:-/tmp/agent-relay-hearts}"
-PLAYER_1="Alice"
-PLAYER_2="Bob"
-PLAYER_3="Carol"
-
-echo "=== Hearts 3-Player Game Setup ==="
-echo "Game directory: $GAME_DIR"
-echo "Players: $PLAYER_1, $PLAYER_2, $PLAYER_3"
-echo ""
-
-# Create directories
-mkdir -p "$GAME_DIR/$PLAYER_1"
-mkdir -p "$GAME_DIR/$PLAYER_2"
-mkdir -p "$GAME_DIR/$PLAYER_3"
-
-# Clear any existing inbox
-echo "" > "$GAME_DIR/$PLAYER_1/inbox.md"
-echo "" > "$GAME_DIR/$PLAYER_2/inbox.md"
-echo "" > "$GAME_DIR/$PLAYER_3/inbox.md"
-
-# Generate and deal cards
-# For 3 players: remove 2 of diamonds, deal 17 cards each
-CARDS="2C 3C 4C 5C 6C 7C 8C 9C TC JC QC KC AC 2H 3H 4H 5H 6H 7H 8H 9H TH JH QH KH AH 2S 3S 4S 5S 6S 7S 8S 9S TS JS QS KS AS 3D 4D 5D 6D 7D 8D 9D TD JD QD KD AD"
-
-# Shuffle cards using a simple method
-SHUFFLED=$(echo $CARDS | tr ' ' '\n' | sort -R | tr '\n' ' ')
-CARD_ARRAY=($SHUFFLED)
-
-# Deal 17 cards to each player
-HAND_1="${CARD_ARRAY[@]:0:17}"
-HAND_2="${CARD_ARRAY[@]:17:17}"
-HAND_3="${CARD_ARRAY[@]:34:17}"
-
-# Create common game rules file
-cat > "$GAME_DIR/GAME_RULES.md" << 'EOF'
-# Hearts - 3 Player Rules
-
-## Overview
-Hearts is a trick-taking card game where you try to AVOID points.
-
-## Card Values
-- Suits: Clubs (C), Diamonds (D), Spades (S), Hearts (H)
-- Ranks: 2-9, T(10), J, Q, K, A (low to high)
-- Card notation: RankSuit (e.g., 2C = 2 of Clubs, QS = Queen of Spades)
-
-## Scoring
-- Each Heart: 1 point
-- Queen of Spades (QS): 13 points
-- **Goal: Get the LOWEST score**
-
-## Special Rule: Shooting the Moon
-If you take ALL hearts AND the Queen of Spades in one round:
-- You score 0 points
-- All opponents get 26 points each
-
-## Gameplay
-
-### 1. Passing Phase
-- Pass 3 cards to the player on your left
-- Round 1: Alice→Bob, Bob→Carol, Carol→Alice
-
-### 2. Trick Phase
-- Player with 2 of Clubs (2C) leads first trick
-- Players must follow suit if able
-- If can't follow suit, can play any card
-- Highest card of the led suit wins the trick
-- Winner leads next trick
-
-### 3. Hearts Breaking
-- Cannot lead hearts until hearts have been "broken"
-- Hearts break when someone plays a heart (because they can't follow suit)
-
-## Turn Order
-Alice → Bob → Carol → Alice → ...
-
-## End of Round
-- Round ends when all 17 tricks are played
-- Count points taken
-- Game ends when someone reaches 100 points
-
-## Commands
-
-**Wait for your turn:**
-```bash
-agent-relay inbox-poll -n YOUR_NAME -d /tmp/agent-relay-hearts --clear
-```
-
-**Play a card (to next player or broadcast):**
-```bash
-agent-relay inbox-write -t "NEXT_PLAYER" -f YOUR_NAME -m "PLAY: CARD" -d /tmp/agent-relay-hearts
-```
-
-**Broadcast to all:**
-```bash
-agent-relay inbox-write -t "*" -f YOUR_NAME -m "MESSAGE" -d /tmp/agent-relay-hearts
-```
-EOF
-
-# Create player-specific instruction files
-create_player_instructions() {
-  local PLAYER=$1
-  local HAND=$2
-  local PREV=$3
-  local NEXT=$4
-  local IS_FIRST=$5
-
-  cat > "$GAME_DIR/$PLAYER/INSTRUCTIONS.md" << EOFPLAYER
-# Hearts - You are $PLAYER
-
-Read the game rules: \`cat /tmp/agent-relay-hearts/GAME_RULES.md\`
-
-## Your Starting Hand (17 cards)
-\`\`\`
-$HAND
-\`\`\`
-
-## Players
-- You: **$PLAYER**
-- To your left (you pass TO): **$NEXT**
-- To your right (you receive FROM): **$PREV**
-
-## Commands
-
-**Wait for messages:**
-\`\`\`bash
-agent-relay inbox-poll -n $PLAYER -d /tmp/agent-relay-hearts --clear
-\`\`\`
-
-**Send to next player:**
-\`\`\`bash
-agent-relay inbox-write -t "$NEXT" -f $PLAYER -m "YOUR_MESSAGE" -d /tmp/agent-relay-hearts
-\`\`\`
-
-**Broadcast to all:**
-\`\`\`bash
-agent-relay inbox-write -t "*" -f $PLAYER -m "YOUR_MESSAGE" -d /tmp/agent-relay-hearts
-\`\`\`
-
-## Game Protocol
-
-### Phase 1: Card Passing
-1. Choose 3 cards to pass to $NEXT
-2. Send: \`PASS: card1 card2 card3\`
-3. Wait to receive 3 cards from $PREV
-4. Update your hand (remove passed, add received)
-
-### Phase 2: Playing Tricks
-The player with 2C leads the first trick.
-
-**When it's your turn to play:**
-1. Look at what's been played in this trick
-2. If you have the led suit, you MUST play it
-3. If you don't have the led suit, play any card
-4. Send: \`PLAY: CARD\` (e.g., \`PLAY: 7H\`)
-5. If you're last in trick, also announce winner and next lead
-
-**Message format for playing:**
-- \`PLAY: CARD\` - Your card play
-- \`TRICK_WINNER: PLAYER\` - Who won the trick
-- \`POINTS: {Alice: X, Bob: Y, Carol: Z}\` - Point totals
-
-### Tracking State
-Keep track of:
-- Your current hand
-- Cards played this trick
-- Who has played
-- Hearts broken? (true/false)
-- Points taken this round
-
-EOFPLAYER
-
-  if [ "$IS_FIRST" = "true" ]; then
-    cat >> "$GAME_DIR/$PLAYER/INSTRUCTIONS.md" << EOFSTART
-
-## You Start!
-Since you are $PLAYER, you coordinate the game start:
-
-1. **First, wait for all pass cards:**
-   \`\`\`bash
-   agent-relay inbox-poll -n $PLAYER -d /tmp/agent-relay-hearts --clear
-   \`\`\`
-
-2. **Send your 3 pass cards to $NEXT:**
-   \`\`\`bash
-   agent-relay inbox-write -t "$NEXT" -f $PLAYER -m "PASS: [card1] [card2] [card3]" -d /tmp/agent-relay-hearts
-   \`\`\`
-
-3. **Wait for pass cards from $PREV**
-
-4. **After everyone has passed, if you have 2C, lead first trick:**
-   \`\`\`bash
-   agent-relay inbox-write -t "*" -f $PLAYER -m "TRICK 1 - $PLAYER leads: PLAY: 2C" -d /tmp/agent-relay-hearts
-   \`\`\`
-
-5. **Wait for responses and continue the game loop**
-
-## START NOW
-Begin by choosing 3 cards to pass and sending them to $NEXT!
-EOFSTART
-  else
-    cat >> "$GAME_DIR/$PLAYER/INSTRUCTIONS.md" << EOFWAIT
-
-## Waiting for Game Start
-You will receive the first message when it's time to pass cards.
-
-1. **Wait for instruction to pass:**
-   \`\`\`bash
-   agent-relay inbox-poll -n $PLAYER -d /tmp/agent-relay-hearts --clear
-   \`\`\`
-
-2. **When prompted, send your 3 pass cards to $NEXT:**
-   \`\`\`bash
-   agent-relay inbox-write -t "$NEXT" -f $PLAYER -m "PASS: [card1] [card2] [card3]" -d /tmp/agent-relay-hearts
-   \`\`\`
-
-3. **Continue following the game protocol**
-
-## START NOW
-Run the inbox-poll command to wait for the game to begin!
-EOFWAIT
-  fi
-}
-
-# Create instructions for each player
-create_player_instructions "$PLAYER_1" "$HAND_1" "$PLAYER_3" "$PLAYER_2" "true"
-create_player_instructions "$PLAYER_2" "$HAND_2" "$PLAYER_1" "$PLAYER_3" "false"
-create_player_instructions "$PLAYER_3" "$HAND_3" "$PLAYER_2" "$PLAYER_1" "false"
-
-echo "Created game files:"
-echo "  - $GAME_DIR/GAME_RULES.md"
-echo "  - $GAME_DIR/$PLAYER_1/INSTRUCTIONS.md (Hand: $HAND_1)"
-echo "  - $GAME_DIR/$PLAYER_2/INSTRUCTIONS.md (Hand: $HAND_2)"
-echo "  - $GAME_DIR/$PLAYER_3/INSTRUCTIONS.md (Hand: $HAND_3)"
-echo ""
-echo "=== TO START THE GAME ==="
-echo ""
-echo "Make sure agent-relay is built:"
-echo "  cd $(dirname "$0")/../.."
-echo "  npm run build"
-echo ""
-echo "Open THREE terminal windows and run Claude/Codex in each:"
-echo ""
-echo "Terminal 1 ($PLAYER_1 - coordinates start):"
-echo "  claude"
-echo "  # Say: Read $GAME_DIR/$PLAYER_1/INSTRUCTIONS.md and start the Hearts game"
-echo ""
-echo "Terminal 2 ($PLAYER_2):"
-echo "  claude"
-echo "  # Say: Read $GAME_DIR/$PLAYER_2/INSTRUCTIONS.md and play Hearts"
-echo ""
-echo "Terminal 3 ($PLAYER_3):"
-echo "  claude"
-echo "  # Say: Read $GAME_DIR/$PLAYER_3/INSTRUCTIONS.md and play Hearts"
-echo ""
-echo "The three agents will autonomously play Hearts!"
-echo ""

package/scripts/tictactoe-setup.sh

@@ -1,181 +0,0 @@
-#!/bin/bash
-#
-# Tic-Tac-Toe Autonomous Agent Test
-# Sets up two agents to play tic-tac-toe autonomously via file-based inbox
-#
-
-set -e
-
-RELAY_DIR="${AGENT_RELAY_DIR:-/tmp/agent-relay-ttt}"
-PLAYER_X="PlayerX"
-PLAYER_O="PlayerO"
-
-echo "=== Tic-Tac-Toe Agent Setup ==="
-echo "Relay directory: $RELAY_DIR"
-echo ""
-
-# Create directories
-mkdir -p "$RELAY_DIR/$PLAYER_X"
-mkdir -p "$RELAY_DIR/$PLAYER_O"
-
-# Clear any existing inbox
-echo "" > "$RELAY_DIR/$PLAYER_X/inbox.md"
-echo "" > "$RELAY_DIR/$PLAYER_O/inbox.md"
-
-# Create game instructions for Player X (goes first)
-cat > "$RELAY_DIR/$PLAYER_X/GAME_INSTRUCTIONS.md" << 'EOF'
-# Tic-Tac-Toe Autonomous Game Protocol
-
-You are **PlayerX** (X). You play FIRST. Your opponent is **PlayerO** (O).
-
-## Board Positions
-```
- 1 | 2 | 3
------------
- 4 | 5 | 6
------------
- 7 | 8 | 9
-```
-
-## Commands Available
-You have these `agent-relay` commands to communicate:
-
-**Wait for opponent's message (blocking):**
-```bash
-agent-relay inbox-poll -n PlayerX -d /tmp/agent-relay-ttt --clear
-```
-
-**Send a move to opponent:**
-```bash
-agent-relay inbox-write -t PlayerO -f PlayerX -m "MOVE: X at position N" -d /tmp/agent-relay-ttt
-```
-
-## PROTOCOL (follow EXACTLY)
-
-### Since you're X, you go FIRST:
-1. Make your first move to position 5 (center)
-2. Send it to opponent:
-   ```bash
-   agent-relay inbox-write -t PlayerO -f PlayerX -m "MOVE: X at position 5" -d /tmp/agent-relay-ttt
-   ```
-
-### Then enter the game loop:
-1. **WAIT** for opponent's response (this will block until they respond):
-   ```bash
-   agent-relay inbox-poll -n PlayerX -d /tmp/agent-relay-ttt --clear
-   ```
-
-2. **UPDATE** your mental board state with opponent's move
-
-3. **CHECK** for win/draw. If game over, send result and announce:
-   ```bash
-   agent-relay inbox-write -t PlayerO -f PlayerX -m "GAME OVER: X wins!" -d /tmp/agent-relay-ttt
-   ```
-
-4. **MAKE** your next move and send it:
-   ```bash
-   agent-relay inbox-write -t PlayerO -f PlayerX -m "MOVE: X at position N" -d /tmp/agent-relay-ttt
-   ```
-
-5. **REPEAT** from step 1 until game over
-
-## Rules
-- Valid moves: positions 1-9 that are empty
-- Win: 3 in a row (horizontal, vertical, or diagonal)
-- Draw: all 9 positions filled with no winner
-
-## CRITICAL
-- NEVER stop mid-game
-- ALWAYS use the inbox-poll command to wait (it blocks until opponent responds)
-- Keep track of the board state
-- Announce result when game ends
-
-## START NOW
-Make your FIRST MOVE to position 5, then wait for opponent's response.
-EOF
-
-# Create game instructions for Player O (waits for X)
-cat > "$RELAY_DIR/$PLAYER_O/GAME_INSTRUCTIONS.md" << 'EOF'
-# Tic-Tac-Toe Autonomous Game Protocol
-
-You are **PlayerO** (O). PlayerX plays first, so you WAIT for their move.
-
-## Board Positions
-```
- 1 | 2 | 3
------------
- 4 | 5 | 6
------------
- 7 | 8 | 9
-```
-
-## Commands Available
-You have these `agent-relay` commands to communicate:
-
-**Wait for opponent's message (blocking):**
-```bash
-agent-relay inbox-poll -n PlayerO -d /tmp/agent-relay-ttt --clear
-```
-
-**Send a move to opponent:**
-```bash
-agent-relay inbox-write -t PlayerX -f PlayerO -m "MOVE: O at position N" -d /tmp/agent-relay-ttt
-```
-
-## PROTOCOL (follow EXACTLY)
-
-### Since you're O, you go SECOND. Start by waiting:
-1. **WAIT** for opponent's first move (this will block until they move):
-   ```bash
-   agent-relay inbox-poll -n PlayerO -d /tmp/agent-relay-ttt --clear
-   ```
-
-2. **UPDATE** your mental board state with opponent's move
-
-3. **CHECK** for win/draw. If game over, announce result.
-
-4. **MAKE** your response move and send it:
-   ```bash
-   agent-relay inbox-write -t PlayerX -f PlayerO -m "MOVE: O at position N" -d /tmp/agent-relay-ttt
-   ```
-
-5. **WAIT** for opponent's next move (back to step 1)
-
-## Rules
-- Valid moves: positions 1-9 that are empty
-- Win: 3 in a row (horizontal, vertical, or diagonal)
-- Draw: all 9 positions filled with no winner
-
-## CRITICAL
-- NEVER stop mid-game
-- ALWAYS use the inbox-poll command to wait (it blocks until opponent responds)
-- Keep track of the board state
-- Announce result when game ends
-
-## START NOW
-Run the inbox-poll command to WAIT for PlayerX's first move.
-EOF
-
-echo "Created game instructions:"
-echo "  - $RELAY_DIR/$PLAYER_X/GAME_INSTRUCTIONS.md"
-echo "  - $RELAY_DIR/$PLAYER_O/GAME_INSTRUCTIONS.md"
-echo ""
-echo "=== TO START THE GAME ==="
-echo ""
-echo "Make sure agent-relay is built and in your PATH:"
-echo "  cd $(dirname "$0")/.."
-echo "  npm run build"
-echo "  export PATH=\"\$PATH:\$(pwd)/dist/cli\""
-echo ""
-echo "Open TWO terminal windows and run Claude in each:"
-echo ""
-echo "Terminal 1 (PlayerX - goes first):"
-echo "  claude"
-echo "  # Then tell Claude: Read $RELAY_DIR/$PLAYER_X/GAME_INSTRUCTIONS.md and start the game"
-echo ""
-echo "Terminal 2 (PlayerO - waits):"
-echo "  claude"
-echo "  # Then tell Claude: Read $RELAY_DIR/$PLAYER_O/GAME_INSTRUCTIONS.md and start the game"
-echo ""
-echo "Both agents will autonomously play tic-tac-toe!"
-echo ""