agent-relay 1.0.8 → 1.0.11

package/scripts/games/hearts-setup.sh

@@ -0,0 +1,264 @@
+#!/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/postinstall.js

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+/**
+ * Postinstall Script for agent-relay
+ *
+ * This script runs after npm install to:
+ * 1. Rebuild native modules (better-sqlite3)
+ * 2. Install tmux binary if not available on the system
+ *
+ * The tmux binary is installed within the package itself (bin/tmux),
+ * making it portable and not requiring global installation.
+ */
+
+import { execSync } from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+import https from 'node:https';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/** Get package root directory (parent of scripts/) */
+function getPackageRoot() {
+  return path.resolve(__dirname, '..');
+}
+
+/** Installation directory (within the package) */
+function getInstallDir() {
+  return path.join(getPackageRoot(), 'bin');
+}
+
+// Colors for console output
+const colors = {
+  reset: '\x1b[0m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  red: '\x1b[31m',
+};
+
+function info(msg) {
+  console.log(`${colors.blue}[info]${colors.reset} ${msg}`);
+}
+
+function success(msg) {
+  console.log(`${colors.green}[success]${colors.reset} ${msg}`);
+}
+
+function warn(msg) {
+  console.log(`${colors.yellow}[warn]${colors.reset} ${msg}`);
+}
+
+function error(msg) {
+  console.log(`${colors.red}[error]${colors.reset} ${msg}`);
+}
+
+/**
+ * Check if tmux is available on the system
+ */
+function hasSystemTmux() {
+  try {
+    execSync('which tmux', { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get platform identifier for tmux-builds
+ */
+function getPlatformId() {
+  const platform = os.platform();
+  const arch = os.arch();
+
+  if (platform === 'darwin') {
+    return arch === 'arm64' ? 'macos-arm64' : 'macos-x86_64';
+  } else if (platform === 'linux') {
+    return arch === 'arm64' ? 'linux-arm64' : 'linux-x86_64';
+  }
+
+  return null;
+}
+
+/**
+ * Download file with redirect support
+ */
+function downloadFile(url, destPath) {
+  return new Promise((resolve, reject) => {
+    const file = fs.createWriteStream(destPath);
+
+    const request = (currentUrl, redirectCount = 0) => {
+      if (redirectCount > 5) {
+        reject(new Error('Too many redirects'));
+        return;
+      }
+
+      const urlObj = new URL(currentUrl);
+      const options = {
+        hostname: urlObj.hostname,
+        path: urlObj.pathname + urlObj.search,
+        headers: {
+          'User-Agent': 'agent-relay-installer',
+        },
+      };
+
+      https
+        .get(options, (response) => {
+          if (response.statusCode === 302 || response.statusCode === 301) {
+            const location = response.headers.location;
+            if (location) {
+              request(location, redirectCount + 1);
+              return;
+            }
+          }
+
+          if (response.statusCode !== 200) {
+            reject(new Error(`HTTP ${response.statusCode}`));
+            return;
+          }
+
+          response.pipe(file);
+          file.on('finish', () => {
+            file.close();
+            resolve();
+          });
+        })
+        .on('error', reject);
+    };
+
+    request(url);
+  });
+}
+
+/**
+ * Install tmux binary
+ */
+async function installTmux() {
+  const TMUX_VERSION = '3.6a';
+  const INSTALL_DIR = getInstallDir();
+  const tmuxPath = path.join(INSTALL_DIR, 'tmux');
+
+  // Check if already installed
+  if (fs.existsSync(tmuxPath)) {
+    info('Bundled tmux already installed');
+    return true;
+  }
+
+  const platformId = getPlatformId();
+  if (!platformId) {
+    const platform = os.platform();
+    warn(`Unsupported platform: ${platform} ${os.arch()}`);
+    if (platform === 'win32') {
+      warn('tmux requires WSL (Windows Subsystem for Linux)');
+      warn('Install WSL first, then run: sudo apt install tmux');
+    } else {
+      warn('Please install tmux manually: https://github.com/tmux/tmux/wiki/Installing');
+    }
+    return false;
+  }
+
+  info(`Installing tmux ${TMUX_VERSION} for ${platformId}...`);
+
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-relay-tmux-'));
+  const archiveName = `tmux-${TMUX_VERSION}-${platformId}.tar.gz`;
+  const archivePath = path.join(tmpDir, archiveName);
+  const downloadUrl = `https://github.com/tmux/tmux-builds/releases/download/v${TMUX_VERSION}/${archiveName}`;
+
+  try {
+    info('Downloading tmux binary...');
+    await downloadFile(downloadUrl, archivePath);
+
+    info('Extracting...');
+    execSync(`tar -xzf "${archivePath}" -C "${tmpDir}"`, { stdio: 'pipe' });
+
+    const extractedTmux = path.join(tmpDir, 'tmux');
+    if (!fs.existsSync(extractedTmux)) {
+      throw new Error('tmux binary not found in archive');
+    }
+
+    fs.mkdirSync(INSTALL_DIR, { recursive: true });
+    fs.copyFileSync(extractedTmux, tmuxPath);
+    fs.chmodSync(tmuxPath, 0o755);
+
+    success(`Installed tmux to ${tmuxPath}`);
+    return true;
+  } catch (err) {
+    error(`Failed to install tmux: ${err.message}`);
+    warn('Please install tmux manually, then reinstall: npm install agent-relay');
+    return false;
+  } finally {
+    try {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    } catch {
+      // Ignore
+    }
+  }
+}
+
+/**
+ * Main postinstall routine
+ */
+async function main() {
+  // Skip in CI environments where tmux isn't needed
+  if (process.env.CI === 'true') {
+    info('Skipping tmux install in CI environment');
+    return;
+  }
+
+  // Check if system tmux is available
+  if (hasSystemTmux()) {
+    info('System tmux found');
+    return;
+  }
+
+  // Try to install bundled tmux
+  await installTmux();
+}
+
+main().catch((err) => {
+  // Don't fail the install if tmux installation fails
+  // User can still install tmux manually
+  warn(`Postinstall warning: ${err.message}`);
+});

package/scripts/tictactoe-setup.sh

@@ -0,0 +1,181 @@
+#!/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 ""