🤖 Wumpus Agents & Episodes Guide

Quick Start (Browser)

1. Open the home page and choose Enhanced mode.
2. Click Start Adventure to create a human-playable game if desired.
3. On the right panel, under Agent Runner, pick an agent, grid size, and max steps.
4. Click Run One to run a single episode, or Run Batch for many.
5. Scroll down to Replays, select an episode, and use Play/Step controls to view it.

Key Concepts

• Agent: Implements a policy via act(...) returning an action.
• Episode: A full game from start until win/death/timeout. Episodes are reproducible.
• Replays: View any stored episode, step-by-step, independent of current engine code.

Running From Terminal (CLI)

Start the dev server in another terminal:

npm run dev

Then, list agents, run single or batches:

npm run agents:list
npm run agents:stats -- --agent random
npm run agents:run -- --agent greedy --grid-size 4 --max-steps 200 --seed 123
npm run agents:run -- --agent random --grid-size 4 --runs 50 --max-steps 200

CLI talks to the running server via tRPC fetch endpoints.

Server API (tRPC)

Endpoints (namespaced under /api/trpc):

• agents.list → list available agents
• episodes.runOne → run one episode
• episodes.runBatch → run multiple episodes
• episodes.list → list episodes
• episodes.get → fetch an episode by id
• episodes.stats → aggregate statistics

Raw fetch uses ?input= with JSON-encoded input; responses are tRPC-wrapped JSON.

Replays & Persistence

• Replays store initialGrid, seed, engineVersion, and the full history.
• Persist episodes to disk by starting the server with EPISODES_DIR:

  EPISODES_DIR=./data/episodes npm run dev

Add Your Own Agent

1. Create a new file at src/agents/MyAgent.ts:

   import type { Agent } from "@/agents";
   
   export const myAgent: Agent = {
     id: "my-agent",
     meta: { name: "My Agent", version: "1.0.0", description: "Example." },
     async act({ percepts, state, actionsAvailable }) {
       // Simple policy: grab if glitter, else move forward.
       if (percepts.glitter) return "Grab";
       return actionsAvailable.includes("Forward") ? "Forward" : actionsAvailable[0];
     },
   };

2. Register it in src/agents/index.ts by adding it to the agents map.
3. Reload the app; the agent will appear in the runner.

Agent API reference:

interface Agent {
  id: string;
  meta: { name: string; version: string; description?: string };
  reset?: (ctx: { gridSize: number }) => void | Promise<void>;
  act: (input: {
    step: number;             // 0-based step index (excludes initial Start)
    percepts: Percepts;       // current percepts at agent position
    state: AgentState;        // current agent state (x, y, dir, hasGold, arrow, alive)
    actionsAvailable: Action[]; // ["TurnLeft","TurnRight","Forward","Grab","Shoot"]
  }) => Action | Promise<Action>;
}

Technical Reference

• State: see src/game/types.ts. A GameState includes seed and engineVersion.
• Runner: src/sim/runner.ts provides simulateEpisode and simulateBatch.
• TRPC: procedures in src/server/trpc.ts under agents and episodes.
• UI: AgentControls and ReplayPlayer integrated in Enhanced mode.

Tips

• Use seeds to reproduce environments when comparing agents.
• Batch runs are great for aggregate performance statistics.
• Replays let you visually inspect policy behavior and errors.