[claude] feat: Add /api/health endpoint for monitoring (#6 ) (#12 )

[claude] fix: Workshop error state for perpetual INITIALIZING (#7 ) (#11 )
[claude] fix: Workshop connection HUD with timeout and retry (#5 ) (#10 )
2026-03-22 23:08:06 +00:00 · 2026-03-22 23:01:56 +00:00 · 2026-03-22 22:55:41 +00:00
4 changed files with 232 additions and 13 deletions
--- a/api/health/index.json
+++ b/api/health/index.json
@@ -0,0 +1,10 @@
+{
+  "status": "ok",
+  "services": {
+    "api": true,
+    "agent_loop": false,
+    "websocket": false
+  },
+  "uptime": null,
+  "version": "20260322.230710"
+}
--- a/scripts/build.py
+++ b/scripts/build.py
@@ -17,14 +17,17 @@ Generates:
 """

 import html
+import json
 import os
 import re
 from datetime import datetime, timezone
 from pathlib import Path

 SITE_URL = "https://alexanderwhitestone.com"
-BLOG_DIR = Path(__file__).parent.parent / "blog"
+ROOT_DIR = Path(__file__).parent.parent
+BLOG_DIR = ROOT_DIR / "blog"
 POSTS_DIR = BLOG_DIR / "posts"
+HEALTH_DIR = ROOT_DIR / "api" / "health"

 PAGE_STYLE = """\
    * { margin: 0; padding: 0; box-sizing: border-box; }
@@ -291,6 +294,23 @@ def generate_feed(posts):
    print(f"  Generated feed with {len(entries)} entry/entries.")


+def generate_health():
+    """Generate api/health/index.json with build-time metadata."""
+    HEALTH_DIR.mkdir(parents=True, exist_ok=True)
+    health = {
+        "status": "ok",
+        "services": {
+            "api": True,
+            "agent_loop": False,
+            "websocket": False,
+        },
+        "uptime": None,
+        "version": datetime.now(timezone.utc).strftime("%Y%m%d.%H%M%S"),
+    }
+    (HEALTH_DIR / "index.json").write_text(json.dumps(health, indent=2) + "\n")
+    print("  Generated api/health endpoint.")
+
+
 def main():
    print("Building The Scrolls...")
    posts = load_posts()
@@ -299,6 +319,7 @@ def main():
        print(f"  Built: {out.relative_to(BLOG_DIR.parent)}")
    generate_index(posts)
    generate_feed(posts)
+    generate_health()
    print("Build complete.")


--- a/world/index.html
+++ b/world/index.html
@@ -19,8 +19,57 @@
      color: #6a6050;
    }
    .placeholder h1 { font-size: 1.2rem; font-weight: normal; margin-bottom: 1rem; }
-    .placeholder p { font-size: 0.85rem; }
+    .placeholder p { font-size: 0.85rem; margin-bottom: 0.5rem; }
    .placeholder a { color: #8a7f6a; }
+
+    /* Connection status HUD */
+    #status-hud {
+      position: fixed;
+      top: 12px;
+      right: 12px;
+      background: rgba(10, 10, 15, 0.85);
+      border: 1px solid #2a2520;
+      border-radius: 6px;
+      padding: 8px 14px;
+      font-family: 'Courier New', monospace;
+      font-size: 0.75rem;
+      color: #6a6050;
+      z-index: 100;
+      min-width: 180px;
+    }
+    #status-hud .status-line {
+      display: flex;
+      align-items: center;
+      gap: 6px;
+      margin-bottom: 4px;
+    }
+    #status-hud .status-line:last-child { margin-bottom: 0; }
+    #status-hud .dot {
+      width: 8px;
+      height: 8px;
+      border-radius: 50%;
+      flex-shrink: 0;
+    }
+    #status-hud .dot.connecting { background: #b8860b; animation: pulse 1.2s ease-in-out infinite; }
+    #status-hud .dot.online { background: #4a9; }
+    #status-hud .dot.offline { background: #a44; }
+    @keyframes pulse {
+      0%, 100% { opacity: 1; }
+      50% { opacity: 0.3; }
+    }
+    #retry-btn {
+      display: none;
+      margin-top: 6px;
+      padding: 3px 10px;
+      background: #2a2520;
+      border: 1px solid #4a4030;
+      border-radius: 3px;
+      color: #8a7f6a;
+      font-family: 'Courier New', monospace;
+      font-size: 0.7rem;
+      cursor: pointer;
+    }
+    #retry-btn:hover { background: #3a3530; color: #c0b8a8; }
  </style>
 </head>
 <body>
@@ -31,6 +80,17 @@
      <p><a href="/">← Back to the Tower</a></p>
    </div>
  </div>
+
+  <div id="status-hud">
+    <div class="status-line">
+      <span class="dot connecting" id="status-dot"></span>
+      <span id="status-text">INITIALIZING</span>
+    </div>
+    <div class="status-line">AGENTS: <span id="agent-count">0</span></div>
+    <button id="retry-btn">Retry connection</button>
+    <a id="fallback-link" href="/api/ui" style="display:none; margin-top:6px; color:#8a7f6a; font-size:0.7rem;">Open API dashboard →</a>
+  </div>
+
  <!-- Reject unknown sub-paths: only /world/ is valid -->
  <script>
    (function() {
@@ -40,7 +100,25 @@
      }
    })();
  </script>
+  <!-- Fallback: if main.js fails to load, don't leave user on INITIALIZING forever -->
+  <script>
+    (function() {
+      var INIT_TIMEOUT_MS = 8000;
+      window.__workshopBooted = false;
+      setTimeout(function() {
+        if (window.__workshopBooted) return;
+        var dot = document.getElementById('status-dot');
+        var text = document.getElementById('status-text');
+        var btn = document.getElementById('retry-btn');
+        var fallback = document.getElementById('fallback-link');
+        if (dot) { dot.className = 'dot offline'; }
+        if (text) { text.textContent = 'WORKSHOP UNREACHABLE'; }
+        if (btn) { btn.style.display = 'block'; }
+        if (fallback) { fallback.style.display = 'block'; }
+      }, INIT_TIMEOUT_MS);
+    })();
+  </script>
  <!-- Three.js scene will mount to #scene -->
-  <!-- <script type="module" src="main.js"></script> -->
+  <script type="module" src="main.js"></script>
 </body>
 </html>
--- a/world/main.js
+++ b/world/main.js
@@ -1,20 +1,130 @@
 /**
 * The Workshop — Three.js scene bootstrap
 *
- * This file will initialize the 3D world where Timmy lives.
- * Currently a placeholder until tech decisions are made:
- *   - 3D engine confirmed (Three.js vs Babylon.js)
- *   - Character design direction chosen
- *   - WebSocket bridge to Timmy's soul designed (#243)
+ * Initializes the 3D world where Timmy lives.
+ * Handles WebSocket connection to tower-hermes backend with
+ * timeout, retry, and clear status display.
 *
 * See: #242 (3D world), #243 (WebSocket bridge), #265 (presence schema)
 */

 // Future: import * as THREE from 'three';

-export function initWorkshop(container) {
-  // TODO: Initialize 3D scene
-  // TODO: Load wizard character model
-  // TODO: Connect to Timmy presence WebSocket
-  console.log('[Workshop] Scene container ready:', container.id);
+const HERMES_WS_URL = (location.protocol === 'https:' ? 'wss://' : 'ws://') +
+  location.host + '/ws/tower';
+const CONNECT_TIMEOUT_MS = 5000;
+const RETRY_DELAY_MS = 3000;
+const MAX_AUTO_RETRIES = 3;
+
+const Status = { CONNECTING: 'connecting', ONLINE: 'online', OFFLINE: 'offline' };
+
+const dom = {
+  dot: document.getElementById('status-dot'),
+  text: document.getElementById('status-text'),
+  agents: document.getElementById('agent-count'),
+  retryBtn: document.getElementById('retry-btn'),
+  fallback: document.getElementById('fallback-link'),
+};
+
+// Signal to inline fallback script that main.js loaded successfully
+window.__workshopBooted = true;
+
+let ws = null;
+let autoRetries = 0;
+let connectTimer = null;
+
+function setStatus(state, message) {
+  dom.dot.className = 'dot ' + state;
+  dom.text.textContent = message;
+  var isOffline = state === Status.OFFLINE;
+  dom.retryBtn.style.display = isOffline ? 'block' : 'none';
+  if (dom.fallback) dom.fallback.style.display = isOffline ? 'block' : 'none';
 }
+
+function setAgentCount(n) {
+  dom.agents.textContent = n;
+}
+
+function cleanup() {
+  clearTimeout(connectTimer);
+  if (ws) {
+    ws.onopen = null;
+    ws.onclose = null;
+    ws.onerror = null;
+    ws.onmessage = null;
+    if (ws.readyState <= WebSocket.OPEN) ws.close();
+    ws = null;
+  }
+}
+
+function connect() {
+  cleanup();
+  setStatus(Status.CONNECTING, 'CONNECTING\u2026');
+  setAgentCount(0);
+
+  try {
+    ws = new WebSocket(HERMES_WS_URL);
+  } catch (err) {
+    console.error('[Workshop] WebSocket creation failed:', err);
+    onFail();
+    return;
+  }
+
+  connectTimer = setTimeout(function () {
+    console.warn('[Workshop] Connection timeout after ' + CONNECT_TIMEOUT_MS + 'ms');
+    cleanup();
+    onFail();
+  }, CONNECT_TIMEOUT_MS);
+
+  ws.onopen = function () {
+    clearTimeout(connectTimer);
+    autoRetries = 0;
+    setStatus(Status.ONLINE, 'ONLINE');
+    console.log('[Workshop] Connected to tower-hermes');
+  };
+
+  ws.onmessage = function (evt) {
+    try {
+      var msg = JSON.parse(evt.data);
+      if (typeof msg.agents === 'number') setAgentCount(msg.agents);
+    } catch (_) {
+      // non-JSON messages are ignored
+    }
+  };
+
+  ws.onclose = function () {
+    clearTimeout(connectTimer);
+    console.log('[Workshop] Connection closed');
+    onFail();
+  };
+
+  ws.onerror = function () {
+    clearTimeout(connectTimer);
+    console.error('[Workshop] WebSocket error');
+    // onclose will fire after this, which calls onFail
+  };
+}
+
+function onFail() {
+  if (autoRetries < MAX_AUTO_RETRIES) {
+    autoRetries++;
+    setStatus(Status.CONNECTING, 'RETRYING (' + autoRetries + '/' + MAX_AUTO_RETRIES + ')\u2026');
+    setTimeout(connect, RETRY_DELAY_MS);
+  } else {
+    setStatus(Status.OFFLINE, 'WORKSHOP OFFLINE');
+  }
+}
+
+// Manual retry resets the counter
+dom.retryBtn.addEventListener('click', function () {
+  autoRetries = 0;
+  connect();
+});
+
+// Boot
+export function initWorkshop(container) {
+  console.log('[Workshop] Scene container ready:', container.id);
+  connect();
+}
+
+initWorkshop(document.getElementById('scene'));
Author	SHA1	Message	Date
Claude (Opus 4.6)	5ccfa25388	[claude] feat: Add /api/health endpoint for monitoring (#6 ) (#12 )	2026-03-22 23:08:06 +00:00
Claude (Opus 4.6)	5acce0f015	[claude] fix: Workshop error state for perpetual INITIALIZING (#7 ) (#11 )	2026-03-22 23:01:56 +00:00
Claude (Opus 4.6)	64d711e256	[claude] fix: Workshop connection HUD with timeout and retry (#5 ) (#10 )	2026-03-22 22:55:41 +00:00