Add simulation speed controls: pause/resume and speed adjustment

- Add pause/resume and speed control (0.25x to 5x) to API server
- New endpoints: GET/POST /api/controls, /controls/pause, /controls/resume, /controls/speed
- Web UI header now has play/pause button, fast/normal/slow speed buttons
- Speed label shows current state (PAUSED, 4x, 2x, 1x, 0.3x)
- Controls state persisted across page refreshes via API

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

src/soci/api/routes.py

@@ -300,6 +300,37 @@ async def get_events(limit: int = 50):
     return {"events": events}
 
 
+@router.get("/controls")
+async def get_controls():
+    """Get current simulation control state."""
+    from soci.api.server import _sim_paused, _sim_speed
+    return {"paused": _sim_paused, "speed": _sim_speed}
+
+
+@router.post("/controls/pause")
+async def pause_simulation():
+    """Pause the simulation."""
+    import soci.api.server as srv
+    srv._sim_paused = True
+    return {"paused": True}
+
+
+@router.post("/controls/resume")
+async def resume_simulation():
+    """Resume the simulation."""
+    import soci.api.server as srv
+    srv._sim_paused = False
+    return {"paused": False}
+
+
+@router.post("/controls/speed")
+async def set_speed(multiplier: float = 1.0):
+    """Set simulation speed. 0.25=fast, 1.0=normal, 3.0=slow."""
+    import soci.api.server as srv
+    srv._sim_speed = max(0.1, min(5.0, multiplier))
+    return {"speed": srv._sim_speed}
+
+
 @router.post("/save")
 async def save_state(name: str = "manual_save"):
     """Manually save the simulation state."""

src/soci/api/server.py

@@ -28,6 +28,8 @@ logger = logging.getLogger(__name__)
 _simulation: Optional[Simulation] = None
 _database: Optional[Database] = None
 _sim_task: Optional[asyncio.Task] = None
+_sim_paused: bool = False
+_sim_speed: float = 1.0  # 1.0 = normal, 0.5 = fast, 2.0 = slow
 
 
 def get_simulation() -> Simulation:
@@ -42,13 +44,17 @@ def get_database() -> Database:
 
 async def simulation_loop(sim: Simulation, db: Database, tick_delay: float = 2.0) -> None:
     """Background task that runs the simulation continuously."""
+    global _sim_paused, _sim_speed
     while True:
         try:
+            if _sim_paused:
+                await asyncio.sleep(0.5)
+                continue
             await sim.tick()
             # Auto-save every 24 ticks
             if sim.clock.total_ticks % 24 == 0:
                 await save_simulation(sim, db, "autosave")
-            await asyncio.sleep(tick_delay)
+            await asyncio.sleep(tick_delay * _sim_speed)
         except asyncio.CancelledError:
             logger.info("Simulation loop cancelled")
             await save_simulation(sim, db, "autosave")

web/index.html

@@ -131,6 +131,18 @@
   .rel-mini-bar { flex: 1; height: 4px; background: #0f3460; border-radius: 2px; overflow: hidden; }
   .rel-mini-fill { height: 100%; border-radius: 2px; }
 
+  /* CONTROLS */
+  .controls { display: flex; align-items: center; gap: 4px; }
+  .ctrl-btn {
+    background: #0f3460; border: 1px solid #1a3a6e; color: #a0a0c0;
+    padding: 3px 8px; border-radius: 3px; cursor: pointer; font-size: 11px;
+    transition: all 0.15s;
+  }
+  .ctrl-btn:hover { background: #1a4a80; color: #fff; }
+  .ctrl-btn.active { background: #4ecca3; color: #1a1a2e; border-color: #4ecca3; }
+  .ctrl-btn.paused { background: #e94560; color: #fff; border-color: #e94560; }
+  .speed-label { font-size: 10px; color: #666; margin-left: 2px; }
+
   ::-webkit-scrollbar { width: 6px; }
   ::-webkit-scrollbar-track { background: #1a1a2e; }
   ::-webkit-scrollbar-thumb { background: #0f3460; border-radius: 3px; }
@@ -144,6 +156,13 @@
     <span><span id="weather-icon"></span> <span id="weather">Sunny</span></span>
     <span id="agent-count"><span class="dot green"></span> 0 agents</span>
     <span id="conv-count">0 convos</span>
+    <span class="controls">
+      <button class="ctrl-btn" id="btn-pause" onclick="togglePause()" title="Pause/Resume">&#x23EF;</button>
+      <button class="ctrl-btn" id="btn-fast" onclick="setSpeed(0.25)" title="Fast">&#x23E9;</button>
+      <button class="ctrl-btn active" id="btn-normal" onclick="setSpeed(1.0)" title="Normal">1x</button>
+      <button class="ctrl-btn" id="btn-slow" onclick="setSpeed(3.0)" title="Slow">&#x1F422;</button>
+      <span class="speed-label" id="speed-label">1x</span>
+    </span>
     <span id="api-calls">API: 0</span>
     <span id="cost">$0.00</span>
     <span id="status"><span class="dot yellow"></span> Connecting...</span>
@@ -1108,12 +1127,67 @@ async function fetchState() {
   }
 }
 
+// ============================================================
+// CONTROLS
+// ============================================================
+let simPaused = false;
+let simSpeed = 1.0;
+
+async function togglePause() {
+  try {
+    const endpoint = simPaused ? 'resume' : 'pause';
+    const res = await fetch(`${API_BASE}/controls/${endpoint}`, { method: 'POST' });
+    if (res.ok) {
+      const data = await res.json();
+      simPaused = data.paused;
+      updateControlsUI();
+    }
+  } catch(e) {}
+}
+
+async function setSpeed(mult) {
+  try {
+    const res = await fetch(`${API_BASE}/controls/speed?multiplier=${mult}`, { method: 'POST' });
+    if (res.ok) {
+      const data = await res.json();
+      simSpeed = data.speed;
+      updateControlsUI();
+    }
+  } catch(e) {}
+}
+
+function updateControlsUI() {
+  const pauseBtn = document.getElementById('btn-pause');
+  pauseBtn.className = 'ctrl-btn' + (simPaused ? ' paused' : '');
+  pauseBtn.title = simPaused ? 'Resume' : 'Pause';
+
+  document.getElementById('btn-fast').className = 'ctrl-btn' + (simSpeed <= 0.3 ? ' active' : '');
+  document.getElementById('btn-normal').className = 'ctrl-btn' + (simSpeed > 0.3 && simSpeed <= 1.5 ? ' active' : '');
+  document.getElementById('btn-slow').className = 'ctrl-btn' + (simSpeed > 1.5 ? ' active' : '');
+
+  const label = simPaused ? 'PAUSED' : (simSpeed <= 0.3 ? '4x' : (simSpeed <= 0.6 ? '2x' : (simSpeed <= 1.5 ? '1x' : '0.3x')));
+  document.getElementById('speed-label').textContent = label;
+}
+
+async function fetchControls() {
+  try {
+    const res = await fetch(`${API_BASE}/controls`);
+    if (res.ok) {
+      const data = await res.json();
+      simPaused = data.paused;
+      simSpeed = data.speed;
+      updateControlsUI();
+    }
+  } catch(e) {}
+}
+
 // ============================================================
 // INIT
 // ============================================================
 initCanvas();
 showDefaultDetail();
 fetchState();
+fetchControls();
 setInterval(fetchState, POLL_INTERVAL);
 </script>
 </body>