feat(arena): SAP-style autobattler — contracts + MCP + Tournament Hall UI (#29)

Author: keanji-x

agent-runner/src/llm.ts

@@ -432,6 +432,28 @@ export function buildSystemPrompt(
     "   50% chance to reduce happiness by 30. If happiness hits 0, you CAPTURE it and respawn with 200 ore!",
     "   Cooldown 30s per hex. Keep trying different hexes!",
     "",
+    "=== ARENA (side-system: async autobattler) ===",
+    "The Arena is an OPTIONAL side-game layered on the main world. It does NOT touch your hexes — only your ore.",
+    "You build a 5-slot 'bench' (your 'ghost') from a roster of 12 unit types, then SUBMIT it to the matchmaking pool.",
+    "Other agents' ghosts will fight yours asynchronously. Wins boost your ELO; losses drop it. The whole battle is deterministic — once you submit, the bench you snapshotted at submit time is what fights.",
+    "",
+    "Units span 4 tiers (cost 3 / 4 / 5 / 6 ore each), with abilities triggering on ON_BUY / ON_START / ON_HURT / ON_SELL / ON_DEATH / ON_FRIEND_DEATH.",
+    "Battles use a simple loop: each turn the side with the highest-ATK living unit hits the opponent's frontmost-living unit. Synergies matter — e.g. Battlemage's ON_BUY (+2 ATK right neighbor) means slot placement is meaningful; Wraith's ON_DEATH summon enables resurrection chains with Spiritbinder; Stoneguard tanks while glass-cannon attackers (Skirmisher, Shadowstalker) deal the damage.",
+    "",
+    "Tools:",
+    "  arena_list_units() — see all 12 units (stats + abilities). Look at this BEFORE buying.",
+    "  arena_get_state(agent_id) — see your current bench, ELO, bucket, ore.",
+    "  arena_buy(agent_id, unit_type, slot) — buy unit_type (1-12) into bench slot (0-4). Costs ore from your main pool.",
+    "  arena_submit(agent_id) — push your ghost into matchmaking. Idempotent.",
+    "  arena_get_recent_matches(agent_id) — read 'arena defeat' entries on your evaluation ledger to LEARN from losses.",
+    "",
+    "Strategy hints (you discover the rest yourself):",
+    "  - Spend leftover ore in Arena rather than wasting it at the 1000 cap.",
+    "  - Front line tanks shield damage dealers; place Stoneguard / Crystalwarden up front, glass cannons behind.",
+    "  - Battlemage's right-neighbor buff and Crystalwarden's both-neighbor buff reward THINKING about slot order.",
+    "  - Submitting an empty bench reverts — buy at least one unit first.",
+    "  - The Arena is OPTIONAL. Hex play, not Arena, decides the main scoreboard. Use Arena for ore burn, side bragging rights, and reputation via wins.",
+    "",
     "=== RULES ===",
     "- ALWAYS call tools. Don't describe intentions — TAKE ACTION.",
     "- Every cycle: harvest + build + at least one of (raid, debate, chronicle, scout, diplomacy).",
@@ -535,6 +557,35 @@ export function buildUserPrompt(context: AgentContext): string {
     inboxNudge += `\nPREDICTION ALERT: You have ${predictionNotices.length} prediction-related message(s)! Check predictions and bet ore with vote_debate.`;
   }
 
+  // Arena state surfacing — show the agent its current bench + ELO so it can
+  // decide whether to refine, submit, or ignore the Arena this cycle.
+  const arena = context.arenaState as
+    | { bench?: any[]; elo?: number; bucketId?: number; exists?: boolean; ore?: number }
+    | null;
+  let arenaPrompt = "";
+  if (arena) {
+    const filledSlots = Array.isArray(arena.bench)
+      ? arena.bench.filter((s: any) => !s.empty).length
+      : 0;
+    const benchSummary = Array.isArray(arena.bench)
+      ? arena.bench
+          .map((s: any) =>
+            s.empty
+              ? `slot${s.slot}: empty`
+              : `slot${s.slot}: ${s.name}(${s.atk}/${s.hp})`
+          )
+          .join(", ")
+      : "(unknown)";
+    arenaPrompt = [
+      "=== ARENA STATE (side-system, optional) ===",
+      `Your ghost — ELO ${arena.elo ?? 0}, bucket ${arena.bucketId ?? 0}, ${filledSlots}/5 slots filled.`,
+      `Bench: ${benchSummary}`,
+      filledSlots === 0
+        ? "You have NO units yet. If you have spare ore (>= 3), consider arena_list_units → arena_buy → arena_submit to enter the Arena. (Optional.)"
+        : "Submit with arena_submit to get matched against another ghost. Or refine your bench with more arena_buy.",
+    ].join("\n");
+  }
+
   // Active Oracle prophecy — surfaced every cycle so betting never depends on the
   // perishable inbox notice (which the debate-notice flood evicts quickly).
   const aod = context.activeOracleDebate as
@@ -558,6 +609,7 @@ export function buildUserPrompt(context: AgentContext): string {
     happinessWarning,
     inboxNudge,
     oraclePrompt,
+    arenaPrompt,
     "",
     "IMPORTANT: Call tools — don't describe intentions. TAKE ACTION NOW.",
     "IMPORTANT: Vary your actions each cycle. Harvest + build + (scout or raid or diplomacy or post).",
@@ -588,6 +640,8 @@ export function createToolDefinitions(agentId: number, tools: McpTool[]): ToolDe
       "get_my_hexes", "get_score", "harvest",
       "build", "attack", "raid", "incite_rebellion", "claim_neutral",
       "start_debate", "vote_debate", "write_chronicle", "get_chronicle",
+      // Arena side-system
+      "arena_buy", "arena_submit", "arena_get_state", "arena_get_recent_matches",
     ];
 
     if (selfTools.includes(tool.name)) {

agent-runner/src/mcp.ts

@@ -83,7 +83,7 @@ export async function collectContext(
       ? Number((self as AgentSnapshot).location)
       : undefined;
 
-  const [world, nearbyAgents, memories, locationBoard, inbox, myHexes, activeOracleDebate] = await Promise.all([
+  const [world, nearbyAgents, memories, locationBoard, inbox, myHexes, activeOracleDebate, arenaState] = await Promise.all([
     callMcpTool(client, "get_world").then(parseToolJson),
     callMcpTool(client, "get_nearby_agents", { agent_id: agentId }).then(parseToolJson),
     callMcpTool(client, "read_memories", { agent_id: agentId, count: 10 }).then(parseToolJson),
@@ -93,9 +93,12 @@ export async function collectContext(
     callMcpTool(client, "read_inbox", { agent_id: agentId, count: 16 }).then(parseToolJson),
     callMcpTool(client, "get_my_hexes", { agent_id: agentId }).then(parseToolJson).catch(() => null),
     callMcpTool(client, "get_active_oracle_debate").then(parseToolJson).catch(() => null),
+    // Arena side-system — pull current ghost state if tool exists. Best-effort: if
+    // the chain has no ArenaEngine deployed the tool errors and we degrade to null.
+    callMcpTool(client, "arena_get_state", { agent_id: agentId }).then(parseToolJson).catch(() => null),
   ]);
 
-  return { self, world, nearbyAgents, memories, locationBoard, inbox, myHexes, activeOracleDebate };
+  return { self, world, nearbyAgents, memories, locationBoard, inbox, myHexes, activeOracleDebate, arenaState };
 }
 
 export function parseArguments(toolCall: ToolCall): Record<string, unknown> {
@@ -118,6 +121,8 @@ export function applyAgentDefaults(
     "get_my_hexes", "get_score", "harvest",
     "build", "attack", "raid", "incite_rebellion", "claim_neutral",
     "start_debate", "vote_debate", "write_chronicle", "get_chronicle",
+    // Arena
+    "arena_buy", "arena_submit", "arena_get_state", "arena_get_recent_matches",
   ];
 
   if (selfTools.includes(toolName) && next.agent_id === undefined) {

agent-runner/src/types.ts

@@ -53,6 +53,7 @@ export interface AgentContext {
   inbox: unknown;
   myHexes: unknown;       // agent's owned hex territories
   activeOracleDebate?: unknown;  // current open Oracle prediction (for betting), or null
+  arenaState?: unknown;          // current Arena ghost (bench, ELO, bucket), or null if Arena unavailable
 }
 
 export interface AgentSnapshot {

contracts/foundry.lock

@@ -0,0 +1,11 @@
+{
+  "lib/forge-std": {
+    "rev": "4540e4aadda88eeb19a54d2b5ad2117c2c7632ec"
+  },
+  "lib/openzeppelin-contracts": {
+    "rev": "9cfdccd35350f7bcc585cf2ede08cd04e7f0ec10"
+  },
+  "lib/openzeppelin-contracts-upgradeable": {
+    "rev": "25780dbcea4d5124fd517f002f0f8984881c5198"
+  }
+}

contracts/script/Deploy.s.sol

@@ -9,6 +9,7 @@ import "../src/LocationLedger.sol";
 import "../src/InboxLedger.sol";
 import "../src/EvaluationLedger.sol";
 import "../src/GameEngine.sol";
+import "../src/ArenaEngine.sol";
 import "../src/Router.sol";
 
 contract DeployScript is Script {
@@ -82,6 +83,21 @@ contract DeployScript is Script {
         engine.setAgentLedger(address(agentLedgerProxy));
         engine.setEvaluationLedger(address(evalLedgerProxy));
 
+        // ──── Deploy ArenaEngine (side system on top of main world) ────
+        ArenaEngine arenaImpl = new ArenaEngine();
+        ERC1967Proxy arenaProxy = new ERC1967Proxy(
+            address(arenaImpl),
+            abi.encodeCall(ArenaEngine.initialize, (
+                address(registry),
+                address(engine),
+                address(evalLedgerProxy)
+            ))
+        );
+        // Arena needs to be operator so it can call GameEngine.spendOre and
+        // EvaluationLedger.write.
+        registry.addOperator(address(arenaProxy));
+        Router(address(routerProxy)).setArenaEngine(address(arenaProxy));
+
         // ──── Initialize World Bible ────
         engine.initWorldBible();
 
@@ -94,6 +110,7 @@ contract DeployScript is Script {
         console.log("InboxLedger      (proxy):", address(inboxLedgerProxy));
         console.log("EvaluationLedger (proxy):", address(evalLedgerProxy));
         console.log("GameEngine       (proxy):", address(engineProxy));
+        console.log("ArenaEngine      (proxy):", address(arenaProxy));
 
         string memory json = string.concat(
             '{\n',

contracts/script/Upgrade.s.sol

@@ -10,6 +10,7 @@ import "../src/LocationLedger.sol";
 import "../src/InboxLedger.sol";
 import "../src/EvaluationLedger.sol";
 import "../src/GameEngine.sol";
+import "../src/ArenaEngine.sol";
 
 /// @notice Upgrade all implementations behind existing proxies.
 ///         Only requires ROUTER_ADDRESS - resolves everything else on-chain.
@@ -101,6 +102,31 @@ contract UpgradeScript is Script {
             }
         }
 
+        // 5. ArenaEngine: deploy fresh proxy if router slot is unset, else upgrade.
+        //    Same shape as the EvaluationLedger backfill above.
+        address arenaProxy;
+        (bool okArena, bytes memory arenaData) = routerProxy.staticcall(abi.encodeWithSignature("arenaEngine()"));
+        if (okArena && arenaData.length >= 32) {
+            arenaProxy = abi.decode(arenaData, (address));
+        }
+
+        if (arenaProxy == address(0)) {
+            console.log("ArenaEngine not found - deploying new proxy...");
+            ArenaEngine arenaImpl = new ArenaEngine();
+            ERC1967Proxy newArena = new ERC1967Proxy(
+                address(arenaImpl),
+                abi.encodeCall(ArenaEngine.initialize, (registryProxy, engineProxy, evalLedgerProxy))
+            );
+            arenaProxy = address(newArena);
+            Router(routerProxy).setArenaEngine(arenaProxy);
+            // Arena needs to call GameEngine.spendOre and EvaluationLedger.write.
+            AgentRegistry(registryProxy).addOperator(arenaProxy);
+            console.log("ArenaEngine      (new):", arenaProxy);
+        } else {
+            ArenaEngine(arenaProxy).upgradeToAndCall(address(new ArenaEngine()), "");
+            console.log("ArenaEngine upgraded:", arenaProxy);
+        }
+
         vm.stopBroadcast();
 
         console.log("All contracts upgraded successfully");