Initial release — agent-visibility dashboard

Real-time debug dashboard for multi-agent AI systems:
- Topology canvas with clickable agent nodes that expand into
per-kind operation sub-nodes (generate, embed, retrieve, tool)
- Full LLM turn inspector: messages in, response out, thinking
- Tool call traces with full input/output (not truncated)
- Embeddings, retrievals, memory panel, plan tab, event log
- Chronological sequence numbers and collapsible dropdowns
- Canvas overlay panel tied to Tools tab selection
- Three built-in demo scenarios with realistic prompt/response data
- HTTP POST API + optional MCP bridge (agentscope)
- Zero dependencies, Node ≥ 18

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

.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+.wrangler/
+.claude/
+*.log
+.env
+.DS_Store

README.md

@@ -0,0 +1,133 @@
+# agent-visibility
+
+Real-time debug dashboard for multi-agent AI systems.
+
+Plug it into any agent framework via HTTP or MCP and get an instant view of:
+
+- **Topology graph** — live agent nodes, hierarchy lines, message arrows; click any node to expand into operation sub-nodes
+- **LLM turn inspector** — full prompt messages, model response, and optional thinking/scratchpad for every generation
+- **Tool call traces** — full input/output for every tool call, with success/error status and latency
+- **Embeddings & retrievals** — query text, top results, similarity scores
+- **Memory panel** — key/value store with read/write flash animations
+- **Plan & event log** — task plan with completion state, timestamped event stream
+
+![screenshot placeholder](docs/screenshot.png)
+
+---
+
+## Quick start
+
+```bash
+# no install needed — zero dependencies
+node bin/visibility.js
+# → Dashboard at http://localhost:4242
+```
+
+Click one of the built-in demo scenarios (Research + code, Critic retry loop, Memory overflow) to see a full run with real LLM prompts and responses.
+
+---
+
+## Send data from your agent
+
+### Option A — HTTP POST (any language)
+
+```bash
+curl -X POST http://localhost:4242/tool \
+  -H 'Content-Type: application/json' \
+  -d '{"tool":"register_agent","args":{"id":"my-agent","label":"My Agent","role":"worker","model":"claude-sonnet-4-5"}}'
+```
+
+### Option B — MCP bridge
+
+```bash
+node bin/visibility.js --mcp
+# → MCP SSE endpoint at http://localhost:4243/sse
+```
+
+Add to your agent's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "agentscope": { "url": "http://localhost:4243/sse" }
+  }
+}
+```
+
+---
+
+## Available tools
+
+| Tool | Purpose |
+|---|---|
+| `register_agent` | Register an agent (id, label, role, model, hierarchy) |
+| `set_goal` | Set the run goal and start the timer |
+| `set_agent_state` | Update agent status (`running`, `done`, `error`, …) |
+| `log_event` | Log a timestamped event to the event stream |
+| `log_llm_turn` | **Full LLM turn** — messages in, response out, optional thinking |
+| `log_generation` | Token-count-only generation (lightweight alternative) |
+| `log_tool_call` | Tool call with full input/output |
+| `log_embedding` | Embedding call (text, model, dims) |
+| `log_retrieval` | Retrieval call (query, results with scores) |
+| `trace_step` | Draw an arrow between two agents on the graph |
+| `set_memory` | Write/read a value in the memory panel |
+| `set_plan` | Publish the task plan |
+| `finish_run` | Mark the run as done or errored |
+
+### Logging a full LLM turn
+
+```bash
+curl -X POST http://localhost:4242/tool \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "tool": "log_llm_turn",
+    "args": {
+      "agent": "researcher",
+      "model": "claude-haiku-4-5",
+      "prompt_tokens": 1840,
+      "completion_tokens": 620,
+      "latency_ms": 1320,
+      "stop_reason": "end_turn",
+      "messages": [
+        {"role": "system", "content": "You are a researcher agent…"},
+        {"role": "user",   "content": "Explain quicksort."}
+      ],
+      "response": "Quicksort is a divide-and-conquer algorithm…"
+    }
+  }'
+```
+
+---
+
+## Canvas interaction
+
+- **Click an agent node** → expands into operation-type sub-nodes (generate, embed, retrieve, tool) with counts and stats
+- **Click a tool dropdown** → highlights the agent node on the canvas and shows an info overlay
+
+---
+
+## Ports
+
+| Port | Service |
+|---|---|
+| `4242` | Dashboard HTTP server + SSE stream |
+| `4243` | MCP bridge (only with `--mcp`) |
+
+Override with `--port` / `--mcp-port` flags or `VISIBILITY_PORT` / `VISIBILITY_MCP_PORT` env vars.
+
+---
+
+## File layout
+
+```
+bin/visibility.js          CLI entry point
+src/server.js              HTTP + SSE dashboard server
+src/dashboard.html         Dark-theme UI (served by the node server)
+agentscope/agentscope.js   MCP bridge (forwards tool calls to the dashboard)
+```
+
+---
+
+## License
+
+MIT

agentscope/agentscope.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+/**
+ * agentscope — MCP bridge for agent-visibility
+ *
+ * Agents connect here via MCP (SSE transport). Tool calls are forwarded to
+ * the dashboard server at DASHBOARD_URL.
+ *
+ * Usage:
+ *   node agentscope/agentscope.js
+ *
+ * MCP config for your agent:
+ *   { "mcpServers": { "agentscope": { "url": "http://localhost:4243/sse" } } }
+ */
+'use strict';
+const http = require('http');
+
+const MCP_PORT     = parseInt(process.env.VISIBILITY_MCP_PORT || '4243');
+const DASHBOARD    = `http://localhost:${process.env.VISIBILITY_PORT || '4242'}`;
+
+// ── Tool definitions ──────────────────────────────────────────────────────────
+const TOOLS = [
+  { name: 'register_agent', description: 'Register an agent with the visibility dashboard.', inputSchema: { type:'object', required:['id','label','role'], properties: { id:{type:'string'}, label:{type:'string'}, role:{type:'string',enum:['orchestrator','worker','researcher','coder','critic','synthesiser']}, model:{type:'string'}, reports_to:{type:'string'}, token_budget:{type:'number'}, color:{type:'string'} } } },
+  { name: 'log_event',      description: 'Log an agent event to the dashboard.',              inputSchema: { type:'object', required:['agent','event_type','message'], properties: { agent:{type:'string'}, event_type:{type:'string',enum:['start','plan','route','reply','tool','result','pass','fail','retry','warn','error','done']}, message:{type:'string'}, tokens:{type:'number'}, latency_ms:{type:'number'}, metadata:{type:'object'} } } },
+  { name: 'log_llm_turn',   description: 'Log a full LLM conversation turn (messages in + response out + optional thinking). Use this to expose the exact context sent to and received from the model.',
+    inputSchema: { type:'object', required:['agent'], properties: { agent:{type:'string'}, model:{type:'string'}, prompt_tokens:{type:'number'}, completion_tokens:{type:'number'}, latency_ms:{type:'number'}, stop_reason:{type:'string'}, messages:{type:'array',items:{type:'object',properties:{role:{type:'string'},content:{type:'string'}}}}, response:{type:'string'}, thinking:{type:'string'} } } },
+  { name: 'trace_step',     description: 'Draw an arrow between two agents on the canvas.',  inputSchema: { type:'object', required:['from_agent','to_agent'], properties: { from_agent:{type:'string'}, to_agent:{type:'string'}, label:{type:'string'}, arrow_type:{type:'string',enum:['msg','result','retry','tool']} } } },
+  { name: 'set_memory',     description: 'Write a value to the shared memory panel.',        inputSchema: { type:'object', required:['key','value'], properties: { key:{type:'string'}, value:{type:'string'}, op:{type:'string',enum:['write','read']} } } },
+  { name: 'set_agent_state',description: 'Update an agent status on the dashboard.',         inputSchema: { type:'object', required:['agent_id','status'], properties: { agent_id:{type:'string'}, status:{type:'string',enum:['idle','running','active','done','error']} } } },
+  { name: 'set_goal',       description: 'Set the run goal and mark the run as started.',    inputSchema: { type:'object', required:['goal'], properties: { goal:{type:'string'}, run_id:{type:'string'} } } },
+  { name: 'set_plan',       description: 'Publish the task plan to the Plan tab.',           inputSchema: { type:'object', required:['tasks'], properties: { tasks:{type:'array'} } } },
+  { name: 'finish_run',     description: 'Mark the current run as complete.',                inputSchema: { type:'object', properties: { status:{type:'string',enum:['done','error']} } } },
+];
+
+// ── Forward tool call to dashboard ────────────────────────────────────────────
+function forward(tool, args) {
+  return new Promise(resolve => {
+    const body = JSON.stringify({ tool, args });
+    const req = http.request(DASHBOARD + '/tool', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) },
+    }, res => {
+      let data = '';
+      res.on('data', c => data += c);
+      res.on('end', () => { try { resolve(JSON.parse(data)); } catch (_) { resolve({ ok: true }); } });
+    });
+    req.on('error', err => resolve({ ok: false, error: `Dashboard unreachable: ${err.message}` }));
+    req.write(body); req.end();
+  });
+}
+
+// ── MCP message handling ──────────────────────────────────────────────────────
+async function handleMsg(msg, send) {
+  const { id, method, params } = msg;
+  if (method === 'initialize') {
+    send({ jsonrpc:'2.0', id, result: { protocolVersion:'2024-11-05', capabilities:{ tools:{} }, serverInfo:{ name:'agentscope', version:'1.0.0' } } });
+  } else if (method === 'tools/list') {
+    send({ jsonrpc:'2.0', id, result: { tools: TOOLS } });
+  } else if (method === 'tools/call') {
+    const { name, arguments: args } = params || {};
+    const found = TOOLS.find(t => t.name === name);
+    if (!found) { send({ jsonrpc:'2.0', id, error:{ code:-32601, message:`Unknown tool: ${name}` } }); return; }
+    const result = await forward(name, args || {});
+    send({ jsonrpc:'2.0', id, result:{ content:[{ type:'text', text:JSON.stringify(result) }], isError: result.ok === false } });
+  } else if (method === 'notifications/initialized') {
+    // no response
+  } else if (id !== undefined) {
+    send({ jsonrpc:'2.0', id, error:{ code:-32601, message:`Method not found: ${method}` } });
+  }
+}
+
+// ── HTTP server (SSE transport) ────────────────────────────────────────────────
+const sessions = new Map();
+const CORS = { 'Access-Control-Allow-Origin':'*', 'Access-Control-Allow-Methods':'GET, POST, OPTIONS', 'Access-Control-Allow-Headers':'Content-Type, Accept' };
+function readBody(req, cb) { let d=''; req.on('data', c=>d+=c); req.on('end', ()=>cb(d)); }
+
+http.createServer((req, res) => {
+  if (req.method === 'OPTIONS') { res.writeHead(204, CORS); res.end(); return; }
+
+  if (req.method === 'GET' && req.url === '/sse') {
+    const sid = `s_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+    res.writeHead(200, { ...CORS, 'Content-Type':'text/event-stream', 'Cache-Control':'no-cache', 'Connection':'keep-alive' });
+    const send = obj => { try { res.write(`data: ${JSON.stringify(obj)}\n\n`); } catch (_) {} };
+    res.write(`event: endpoint\ndata: /message?sessionId=${sid}\n\n`);
+    sessions.set(sid, { send });
+    req.on('close', () => sessions.delete(sid));
+    return;
+  }
+
+  if (req.method === 'POST' && req.url.startsWith('/message')) {
+    const sid = new URL(req.url, 'http://localhost').searchParams.get('sessionId');
+    const session = sessions.get(sid);
+    if (!session) { res.writeHead(404, { ...CORS, 'Content-Type':'application/json' }); res.end(JSON.stringify({ error:'Session not found' })); return; }
+    readBody(req, async data => {
+      let msg;
+      try { msg = JSON.parse(data); } catch (_) { res.writeHead(400, { ...CORS }); res.end('{}'); return; }
+      res.writeHead(202, { ...CORS, 'Content-Type':'application/json' }); res.end('{"ok":true}');
+      await handleMsg(msg, session.send);
+    });
+    return;
+  }
+
+  if (req.url === '/health') {
+    res.writeHead(200, { ...CORS, 'Content-Type':'application/json' });
+    res.end(JSON.stringify({ ok:true, tools: TOOLS.map(t => t.name), dashboard: DASHBOARD }));
+    return;
+  }
+
+  res.writeHead(404, { ...CORS, 'Content-Type':'application/json' }); res.end('{"error":"Not found"}');
+}).listen(MCP_PORT, () => {
+  console.log(`\n  agentscope — MCP bridge\n`);
+  console.log(`  SSE:       http://localhost:${MCP_PORT}/sse`);
+  console.log(`  Dashboard: ${DASHBOARD}\n`);
+  console.log(`  Add to your agent config:`);
+  console.log(`  { "mcpServers": { "agentscope": { "url": "http://localhost:${MCP_PORT}/sse" } } }\n`);
+});

bin/visibility.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * visibility — agent-visibility CLI
+ *
+ * Usage:
+ *   visibility                  dashboard on :4242, opens browser
+ *   visibility --mcp            dashboard + MCP bridge on :4243
+ *   visibility --port 5000      custom dashboard port
+ *   visibility --mcp-port 5001  custom MCP port
+ *   visibility --no-open        don't auto-open browser
+ *   visibility --help
+ */
+'use strict';
+const path = require('path');
+const { execSync, spawn } = require('child_process');
+
+const argv  = process.argv.slice(2);
+const flags = { mcp:false, noOpen:false, help:false, port:4242, mcpPort:4243 };
+for (let i = 0; i < argv.length; i++) {
+  if (argv[i] === '--mcp')                      flags.mcp     = true;
+  if (argv[i] === '--no-open')                  flags.noOpen  = true;
+  if (argv[i] === '--help' || argv[i] === '-h') flags.help    = true;
+  if (argv[i] === '--port'     && argv[i+1])    flags.port    = parseInt(argv[++i]);
+  if (argv[i] === '--mcp-port' && argv[i+1])    flags.mcpPort = parseInt(argv[++i]);
+}
+
+if (flags.help) {
+  console.log(`
+  agent-visibility
+
+  Commands:
+    visibility                  dashboard on :4242, opens browser
+    visibility --mcp            dashboard + MCP bridge on :4243
+    visibility --port 5000      custom dashboard port
+    visibility --mcp-port 5001  custom MCP port
+    visibility --no-open        suppress auto browser open
+    visibility --help
+
+  MCP config (after running with --mcp):
+    { "mcpServers": { "agentscope": { "url": "http://localhost:4243/sse" } } }
+  `);
+  process.exit(0);
+}
+
+const env = { ...process.env, VISIBILITY_PORT: String(flags.port), VISIBILITY_MCP_PORT: String(flags.mcpPort) };
+const children = [];
+
+function spawn_(script) {
+  const child = spawn(process.execPath, [script], { stdio:'inherit', env });
+  children.push(child);
+  child.on('exit', code => { if (code) process.exit(code); });
+}
+
+function shutdown() { children.forEach(c => { try { c.kill('SIGTERM'); } catch (_) {} }); }
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);
+
+spawn_(path.join(__dirname, '..', 'src', 'server.js'));
+
+if (flags.mcp) {
+  setTimeout(() => spawn_(path.join(__dirname, '..', 'agentscope', 'agentscope.js')), 400);
+}
+
+if (!flags.noOpen) {
+  setTimeout(() => {
+    const url = `http://localhost:${flags.port}`;
+    const cmd = process.platform === 'win32' ? `start "" "${url}"` : process.platform === 'darwin' ? `open "${url}"` : `xdg-open "${url}"`;
+    try { execSync(cmd, { stdio:'ignore' }); } catch (_) {}
+  }, 900);
+}

package.json

@@ -0,0 +1,19 @@
+{
+  "name": "agent-visibility",
+  "version": "0.1.0",
+  "description": "Real-time debug dashboard for multi-agent AI systems — topology graph, LLM turn inspector, tool call traces, memory panel",
+  "main": "src/server.js",
+  "bin": {
+    "visibility": "bin/visibility.js"
+  },
+  "scripts": {
+    "start": "node bin/visibility.js",
+    "start:mcp": "node bin/visibility.js --mcp",
+    "dev": "node bin/visibility.js --no-open"
+  },
+  "keywords": ["agent", "llm", "debug", "visibility", "observability", "mcp", "multi-agent"],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

src/dashboard.html

@@ -0,0 +1,806 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1.0">
+<title>Agent Visibility</title>
+<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=Inter:wght@300;400;500&display=swap" rel="stylesheet">
+<style>
+:root{
+  --bg:#0d0f12;--bg2:#161820;--bg3:#1e2028;--border:rgba(255,255,255,.08);--border2:rgba(255,255,255,.14);
+  --text:#e2e4e8;--muted:#5a6070;--purple:#8b7cf8;--teal:#2dd4b0;--amber:#f59e0b;--coral:#f87171;--blue:#60a5fa;--green:#4ade80;
+}
+*,*::before,*::after{box-sizing:border-box;margin:0;padding:0}
+html,body{height:100%;background:var(--bg);color:var(--text);font-family:'Inter',sans-serif;font-size:13px;overflow:hidden}
+
+/* ── Shell ── */
+.shell{display:grid;grid-template-rows:48px 1fr;height:100vh}
+
+/* ── Top bar ── */
+.bar{display:flex;align-items:center;gap:12px;padding:0 20px;border-bottom:1px solid var(--border);background:var(--bg2)}
+.logo{font-family:'IBM Plex Mono',monospace;font-size:13px;font-weight:500;color:var(--purple);letter-spacing:-.01em}
+.goal{flex:1;font-size:12px;color:var(--muted);white-space:nowrap;overflow:hidden;text-overflow:ellipsis;padding:0 12px}
+.badge{font-size:11px;padding:3px 9px;border-radius:12px;border:1px solid var(--border);color:var(--muted);font-weight:500}
+.badge.live{border-color:var(--green);color:var(--green)}.badge.dead{border-color:var(--coral);color:var(--coral)}
+.badge.running{border-color:var(--teal);color:var(--teal)}.badge.done{border-color:var(--green);color:var(--green)}.badge.error{border-color:var(--coral);color:var(--coral)}
+.btn-reset{background:var(--bg3);color:var(--muted);border:1px solid var(--border2);border-radius:7px;padding:5px 12px;font-size:12px;font-family:'Inter',sans-serif;cursor:pointer}
+.btn-reset:hover{color:var(--text);border-color:var(--border2)}
+
+/* ── Main grid ── */
+.grid{display:grid;grid-template-columns:200px 1fr;height:100%;overflow:hidden}
+
+/* ── Left sidebar ── */
+.sidebar{display:flex;flex-direction:column;border-right:1px solid var(--border);overflow:hidden}
+.section{padding:12px 14px;border-bottom:1px solid var(--border)}
+.section-label{font-size:10px;font-weight:600;letter-spacing:.08em;text-transform:uppercase;color:var(--muted);margin-bottom:8px}
+
+/* scenario buttons */
+.demo-btn{display:block;width:100%;text-align:left;background:transparent;border:1px solid var(--border);border-radius:8px;padding:8px 10px;margin-bottom:6px;cursor:pointer;color:var(--muted);font-family:'Inter',sans-serif;font-size:12px;transition:border-color .15s,color .15s}
+.demo-btn:last-child{margin-bottom:0}
+.demo-btn:hover{border-color:var(--purple);color:var(--text)}
+.demo-btn strong{display:block;font-size:12px;font-weight:500;color:var(--text);margin-bottom:1px}
+.demo-btn span{font-size:10px}
+
+/* agents list */
+.agents-scroll{flex:1;overflow-y:auto;padding:10px 14px}
+.agents-scroll::-webkit-scrollbar{width:2px}.agents-scroll::-webkit-scrollbar-thumb{background:var(--bg3)}
+.agent-row{display:flex;align-items:center;gap:8px;padding:7px 9px;border-radius:8px;margin-bottom:4px;border:1px solid transparent;transition:border-color .2s,background .2s}
+.agent-row.idle{border-color:var(--border)}.agent-row.registered{border-color:rgba(139,124,248,.25)}
+.agent-row.running{border-color:var(--teal);background:rgba(45,212,176,.04)}.agent-row.active{border-color:var(--purple);background:rgba(139,124,248,.04)}
+.agent-row.done{border-color:rgba(74,222,128,.3)}.agent-row.error{border-color:var(--coral)}
+.agent-dot{width:7px;height:7px;border-radius:50%;flex-shrink:0;background:var(--muted)}
+.agent-row.running .agent-dot{background:var(--teal)}.agent-row.active .agent-dot{background:var(--purple)}
+.agent-row.done .agent-dot{background:var(--green)}.agent-row.error .agent-dot{background:var(--coral)}
+.agent-row.registered .agent-dot{background:rgba(139,124,248,.6)}
+.agent-name{font-size:12px;font-weight:500;flex:1;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.agent-role{font-size:10px;padding:1px 5px;border-radius:4px;white-space:nowrap;flex-shrink:0}
+
+/* ── Right panel ── */
+.main{display:flex;flex-direction:column;overflow:hidden}
+
+/* canvas */
+.canvas-wrap{position:relative;flex-shrink:0;border-bottom:1px solid var(--border)}
+canvas{display:block;width:100%}
+.tool-overlay{position:absolute;background:var(--bg2);border:1px solid var(--border2);border-radius:9px;min-width:210px;max-width:270px;pointer-events:none;z-index:10;box-shadow:0 6px 20px rgba(0,0,0,.5);overflow:hidden}
+.tool-overlay .tool-blocks{padding:6px 6px 4px 6px}
+.tool-overlay-hdr{display:flex;align-items:center;gap:6px;padding:6px 8px 5px;border-bottom:1px solid var(--border)}
+.tool-overlay-hdr .tool-kind{font-size:10px}
+.tool-overlay-hdr .tool-seq{font-size:10px;color:var(--muted);font-family:'IBM Plex Mono',monospace}
+.tool-overlay-hdr .tool-agent-name{font-size:11px;font-weight:600;flex:1}
+
+/* tabs */
+.tabs{display:flex;border-bottom:1px solid var(--border);flex-shrink:0;background:var(--bg2)}
+.tab{font-size:12px;font-weight:500;padding:9px 16px;cursor:pointer;color:var(--muted);border-bottom:2px solid transparent;margin-bottom:-1px;transition:color .15s}
+.tab:hover{color:var(--text)}.tab.active{color:var(--text);border-bottom-color:var(--purple)}
+.tab-panel{display:none;flex:1;overflow-y:auto;padding:12px 14px}
+.tab-panel::-webkit-scrollbar{width:2px}.tab-panel::-webkit-scrollbar-thumb{background:var(--bg3)}
+.tab-panel.active{display:block}
+.empty{color:var(--muted);font-size:12px;font-style:italic;padding:8px 0}
+
+/* ── Log tab ── */
+.log-row{display:flex;gap:8px;align-items:flex-start;padding:5px 0;border-bottom:1px solid rgba(255,255,255,.04)}
+.log-row:last-child{border-bottom:none}
+.log-tag{font-size:10px;padding:2px 6px;border-radius:4px;white-space:nowrap;flex-shrink:0;margin-top:1px;font-weight:500}
+.log-msg{font-size:12px;line-height:1.45;color:#c8cad0;flex:1;word-break:break-word}
+.log-time{font-family:'IBM Plex Mono',monospace;font-size:10px;color:var(--muted);white-space:nowrap;flex-shrink:0}
+
+/* ── Tools tab ── */
+.tool-item{border-bottom:1px solid rgba(255,255,255,.04)}
+.tool-item:last-child{border-bottom:none}
+.tool-item summary{display:flex;gap:8px;align-items:center;padding:6px 2px;cursor:pointer;list-style:none;user-select:none;outline:none}
+.tool-item summary::-webkit-details-marker{display:none}
+.tool-chevron{font-size:8px;color:var(--muted);transition:transform .15s;flex-shrink:0}
+.tool-item[open] .tool-chevron{transform:rotate(90deg)}
+.tool-seq{font-family:'IBM Plex Mono',monospace;font-size:10px;color:var(--muted);flex-shrink:0;width:22px;text-align:right}
+.tool-kind{font-size:10px;padding:2px 6px;border-radius:4px;font-weight:600;white-space:nowrap;flex-shrink:0}
+.tool-agent-name{font-size:12px;font-weight:500;white-space:nowrap;flex-shrink:0}
+.tool-preview{font-size:12px;color:var(--muted);flex:1;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.tool-lat{font-family:'IBM Plex Mono',monospace;font-size:10px;color:var(--muted);white-space:nowrap;flex-shrink:0}
+.tool-body{border-top:1px solid rgba(255,255,255,.04);padding:6px 4px 8px 0}
+.tool-blocks{display:flex;flex-wrap:wrap;gap:5px;padding:4px 4px 2px 36px}
+.tool-block{background:var(--bg3);border:1px solid var(--border);border-radius:6px;padding:5px 9px;min-width:90px}
+.tool-block.full{flex-basis:100%;min-width:0}
+.tb-label{font-size:9px;font-weight:600;letter-spacing:.08em;text-transform:uppercase;color:var(--muted);display:block;margin-bottom:2px}
+.tb-val{font-size:12px;color:var(--text);line-height:1.45;word-break:break-word}
+.tb-val b{font-weight:600}
+
+/* ── LLM conversation thread ── */
+.llm-thread{display:flex;flex-direction:column;gap:3px;padding:4px 4px 2px 36px}
+.llm-turn{border-radius:5px;padding:5px 8px;border:1px solid rgba(255,255,255,.05)}
+.llm-turn.system{background:rgba(255,255,255,.02)}
+.llm-turn.user{background:rgba(96,165,250,.05);border-color:rgba(96,165,250,.12)}
+.llm-turn.assistant{background:rgba(139,124,248,.05);border-color:rgba(139,124,248,.12)}
+.llm-turn.tool{background:rgba(45,212,176,.04);border-color:rgba(45,212,176,.10)}
+.llm-role{font-size:9px;font-weight:600;letter-spacing:.08em;text-transform:uppercase;margin-bottom:2px}
+.llm-turn.system .llm-role{color:var(--muted)}
+.llm-turn.user .llm-role{color:var(--blue)}
+.llm-turn.assistant .llm-role{color:var(--purple)}
+.llm-turn.tool .llm-role{color:var(--teal)}
+.llm-content{font-size:11px;line-height:1.5;color:var(--text);word-break:break-word;white-space:pre-wrap}
+.llm-response{border-top:1px solid rgba(255,255,255,.06);padding:6px 8px 6px 36px}
+.llm-section-label{font-size:9px;font-weight:600;letter-spacing:.08em;text-transform:uppercase;margin-bottom:4px}
+.llm-response .llm-section-label{color:var(--purple)}
+.llm-thinking .llm-section-label{color:var(--amber)}
+.llm-response-text,.llm-thinking-text{font-size:11px;line-height:1.5;color:var(--text);white-space:pre-wrap;word-break:break-word}
+.llm-thinking{border-top:1px solid rgba(255,255,255,.06);padding:6px 8px 6px 36px}
+.llm-thinking-text{color:var(--muted);font-style:italic}
+
+/* ── Memory tab ── */
+.mem-card{border:1px solid var(--border);border-radius:8px;padding:8px 10px;margin-bottom:6px;transition:border-color .3s,background .3s}
+@keyframes fw{0%{border-color:var(--teal);background:rgba(45,212,176,.07)}100%{border-color:var(--border);background:transparent}}
+@keyframes fr{0%{border-color:var(--blue);background:rgba(96,165,250,.07)}100%{border-color:var(--border);background:transparent}}
+.mem-card.fw{animation:fw .9s ease-out forwards}.mem-card.fr{animation:fr .6s ease-out forwards}
+.mem-key{font-family:'IBM Plex Mono',monospace;font-size:10px;font-weight:500;color:var(--muted);margin-bottom:3px;text-transform:uppercase;letter-spacing:.04em}
+.mem-val{font-size:12px;line-height:1.5;color:var(--text)}
+.mem-val b{font-weight:600}
+
+/* ── Plan tab ── */
+.plan-row{display:flex;align-items:center;gap:8px;padding:6px 0;border-bottom:1px solid rgba(255,255,255,.04)}
+.plan-row:last-child{border-bottom:none}
+.plan-dot{width:6px;height:6px;border-radius:50%;flex-shrink:0}
+.plan-agent{font-size:11px;font-weight:600;width:80px;flex-shrink:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.plan-task{font-size:12px;color:var(--muted);flex:1;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.plan-done{font-size:10px;padding:1px 6px;border-radius:4px;background:rgba(74,222,128,.1);color:var(--green);white-space:nowrap}
+
+/* ── Metrics bar ── */
+.metrics{display:flex;border-top:1px solid var(--border);flex-shrink:0;background:var(--bg2)}
+.metric{flex:1;padding:8px 14px;border-right:1px solid var(--border)}.metric:last-child{border-right:none}
+.metric-label{font-size:10px;font-weight:600;letter-spacing:.07em;text-transform:uppercase;color:var(--muted);margin-bottom:2px}
+.metric-val{font-family:'IBM Plex Mono',monospace;font-size:16px;font-weight:500}
+
+@keyframes spin{to{transform:rotate(360deg)}}
+.spinner{width:12px;height:12px;border:1.5px solid var(--border2);border-top-color:var(--purple);border-radius:50%;animation:spin .6s linear infinite;display:none;flex-shrink:0}
+.spinner.on{display:inline-block}
+</style>
+</head>
+<body>
+<div class="shell">
+
+<!-- top bar -->
+<div class="bar">
+  <div class="logo">agent.visibility</div>
+  <div class="goal" id="goal-text">waiting for agents…</div>
+  <span class="spinner" id="spinner"></span>
+  <span class="badge" id="run-status">idle</span>
+  <span class="badge dead" id="conn-badge">connecting…</span>
+  <button class="btn-reset" onclick="doReset()">Reset</button>
+</div>
+
+<div class="grid">
+
+  <!-- sidebar -->
+  <div class="sidebar">
+    <div class="section">
+      <div class="section-label">Demo scenarios</div>
+      <button class="demo-btn" onclick="emulate('research_code')">
+        <strong>Research + code</strong>
+        <span>4 agents · clean run</span>
+      </button>
+      <button class="demo-btn" onclick="emulate('critic_retry')">
+        <strong>Critic retry loop</strong>
+        <span>3 agents · fail → retry → pass</span>
+      </button>
+      <button class="demo-btn" onclick="emulate('memory_overflow')">
+        <strong>Memory overflow</strong>
+        <span>4 agents · context truncation</span>
+      </button>
+    </div>
+    <div class="section" style="padding-bottom:6px">
+      <div class="section-label">Agents</div>
+    </div>
+    <div class="agents-scroll" id="agents-list">
+      <div class="empty">Agents appear after registration</div>
+    </div>
+  </div>
+
+  <!-- main panel -->
+  <div class="main">
+    <div class="canvas-wrap"><canvas id="fc" height="260"></canvas></div>
+    <div class="tabs">
+      <div class="tab active" onclick="switchTab(event,'log')">Log</div>
+      <div class="tab" onclick="switchTab(event,'tools')">Tools</div>
+      <div class="tab" onclick="switchTab(event,'mem')">Memory</div>
+      <div class="tab" onclick="switchTab(event,'plan')">Plan</div>
+    </div>
+    <div class="tab-panel active" id="tp-log"><div class="empty">Events stream here during a run</div></div>
+    <div class="tab-panel" id="tp-tools"><div class="empty">Embeddings, retrievals, tool calls and LLM generations appear here</div></div>
+    <div class="tab-panel" id="tp-mem"><div id="mem-grid"></div></div>
+    <div class="tab-panel" id="tp-plan"><div id="plan-list"><div class="empty">Plan appears after orchestrator runs</div></div></div>
+    <div class="metrics">
+      <div class="metric"><div class="metric-label">Steps</div><div class="metric-val" id="m-steps">0</div></div>
+      <div class="metric"><div class="metric-label">Tokens</div><div class="metric-val" id="m-tokens">0</div></div>
+      <div class="metric"><div class="metric-label">Elapsed</div><div class="metric-val" id="m-elapsed">—</div></div>
+      <div class="metric"><div class="metric-label">Retries</div><div class="metric-val" id="m-retries">0</div></div>
+    </div>
+  </div>
+</div>
+</div>
+
+<script>
+const SERVER = location.origin;
+
+const ROLE_COLORS = {
+  orchestrator:'#8b7cf8', researcher:'#2dd4b0', coder:'#60a5fa',
+  critic:'#f59e0b', synthesiser:'#60a5fa', worker:'#2dd4b0',
+};
+
+let S = { registry:{}, agents:{}, memory:{}, events:[], plan:[], internals:[], metrics:{steps:0,tokens:0,retries:0}, status:'idle', goal:'', startedAt:null, lastArrow:null };
+let es = null, elapsedTimer = null, toolSeq = 0, selectedToolItem = null, flowPos = {}, expandedAgent = null;
+
+// ── Canvas ─────────────────────────────────────────────────────────────────────
+const fc = document.getElementById('fc');
+const ctx = fc.getContext('2d');
+function initCanvas(){ fc.width = fc.parentElement.clientWidth; drawFlow(); }
+window.addEventListener('resize', initCanvas);
+
+// click agent node → expand / collapse sub-nodes
+fc.addEventListener('click', e => {
+  if (!Object.keys(S.registry).length) return;
+  const rect = fc.getBoundingClientRect();
+  const scaleX = fc.width / fc.clientWidth, scaleY = fc.height / fc.clientHeight;
+  const mx = (e.clientX - rect.left) * scaleX, my = (e.clientY - rect.top) * scaleY;
+  let hit = null;
+  Object.keys(S.registry).forEach(id => {
+    const p = flowPos[id]; if (!p) return;
+    if (mx >= p.x-46 && mx <= p.x+46 && my >= p.y-17 && my <= p.y+17) hit = id;
+  });
+  if (hit !== null) { expandedAgent = (expandedAgent === hit) ? null : hit; drawFlow(); }
+});
+
+fc.addEventListener('mousemove', e => {
+  if (!Object.keys(S.registry).length) { fc.style.cursor='default'; return; }
+  const rect = fc.getBoundingClientRect();
+  const scaleX = fc.width / fc.clientWidth, scaleY = fc.height / fc.clientHeight;
+  const mx = (e.clientX - rect.left) * scaleX, my = (e.clientY - rect.top) * scaleY;
+  let hit = false;
+  Object.keys(S.registry).forEach(id => {
+    const p = flowPos[id]; if (!p) return;
+    if (mx >= p.x-46 && mx <= p.x+46 && my >= p.y-17 && my <= p.y+17) hit = true;
+  });
+  fc.style.cursor = hit ? 'pointer' : 'default';
+});
+
+function hexA(h, a){
+  const r=parseInt(h.slice(1,3),16), g=parseInt(h.slice(3,5),16), b=parseInt(h.slice(5,7),16);
+  return `rgba(${r},${g},${b},${a})`;
+}
+
+function layout(reg){
+  const ids = Object.keys(reg);
+  if (!ids.length) return {};
+  const tierOf = {};
+  function depth(id){
+    if (tierOf[id] !== undefined) return tierOf[id];
+    const parent = reg[id]?.reports_to;
+    tierOf[id] = (parent && reg[parent]) ? depth(parent)+1 : 0;
+    return tierOf[id];
+  }
+  ids.forEach(id => depth(id));
+  const maxTier = Math.max(...Object.values(tierOf));
+  const rows = Array.from({length: maxTier+1}, () => []);
+  ids.forEach(id => rows[tierOf[id]].push(id));
+  const filled = rows.filter(r => r.length > 0);
+  const W = fc.width || 600, H = fc.height;
+  const rowY = filled.length === 1
+    ? [H*.45]
+    : filled.map((_,i) => H*(.14 + i*(.72/Math.max(filled.length-1,1))));
+  const pos = {};
+  filled.forEach((row, ri) => {
+    const step = W/(row.length+1);
+    row.forEach((id, ci) => { pos[id] = { x: step*(ci+1), y: rowY[ri], color: reg[id].color || '#6b7280' }; });
+  });
+  return pos;
+}
+
+function drawArrow(x1,y1,x2,y2,color,label,dashed){
+  const dx=x2-x1, dy=y2-y1, len=Math.sqrt(dx*dx+dy*dy);
+  if (len < 5) return;
+  const u={x:dx/len,y:dy/len}, pad=18;
+  const s={x:x1+u.x*pad,y:y1+u.y*pad}, e={x:x2-u.x*pad,y:y2-u.y*pad};
+  const cx=(s.x+e.x)/2-u.y*24, cy=(s.y+e.y)/2+u.x*24;
+  ctx.beginPath(); ctx.moveTo(s.x,s.y); ctx.quadraticCurveTo(cx,cy,e.x,e.y);
+  ctx.strokeStyle=color; ctx.lineWidth=1.5; ctx.setLineDash(dashed?[4,3]:[]); ctx.stroke(); ctx.setLineDash([]);
+  const ang=Math.atan2(e.y-cy,e.x-cx);
+  ctx.beginPath(); ctx.moveTo(e.x,e.y);
+  ctx.lineTo(e.x-7*Math.cos(ang-.4),e.y-7*Math.sin(ang-.4));
+  ctx.lineTo(e.x-7*Math.cos(ang+.4),e.y-7*Math.sin(ang+.4));
+  ctx.closePath(); ctx.fillStyle=color; ctx.fill();
+  if (label){
+    ctx.fillStyle=color; ctx.font='9px "IBM Plex Mono",monospace';
+    ctx.textAlign='center'; ctx.textBaseline='middle';
+    ctx.fillText(label.length>16?label.slice(0,16)+'…':label, cx, cy-10);
+  }
+}
+
+function drawFlow(){
+  if (!fc.width) return;
+  const targetH = (expandedAgent && Object.keys(S.registry).length) ? 390 : 260;
+  if (fc.height !== targetH) fc.height = targetH;
+  ctx.clearRect(0,0,fc.width,fc.height);
+  const reg = S.registry;
+  if (!Object.keys(reg).length){
+    ctx.fillStyle='#2a2d35'; ctx.font='12px "Inter",sans-serif';
+    ctx.textAlign='center'; ctx.textBaseline='middle';
+    ctx.fillText('Agent topology renders here after a scenario runs', fc.width/2, fc.height/2);
+    return;
+  }
+  const pos = layout(reg);
+  flowPos = pos;
+  // hierarchy lines
+  Object.values(reg).forEach(agent => {
+    if (!agent.reports_to || !pos[agent.id] || !pos[agent.reports_to]) return;
+    const fp=pos[agent.reports_to], tp=pos[agent.id];
+    ctx.beginPath(); ctx.moveTo(fp.x,fp.y+16); ctx.lineTo(tp.x,tp.y-16);
+    ctx.strokeStyle='rgba(255,255,255,.08)'; ctx.lineWidth=1; ctx.setLineDash([4,3]); ctx.stroke(); ctx.setLineDash([]);
+  });
+  // last arrow
+  if (S.lastArrow && pos[S.lastArrow.from] && pos[S.lastArrow.to]){
+    const a=S.lastArrow, fp=pos[a.from], tp=pos[a.to];
+    const col = a.arrow_type==='retry'?'#f59e0b' : a.arrow_type==='result'?'#4ade80' : (reg[a.from]?.color||'#888');
+    drawArrow(fp.x,fp.y,tp.x,tp.y,col,a.label,a.arrow_type==='retry');
+  }
+  // nodes
+  Object.keys(reg).forEach(id => {
+    const p=pos[id], ag=S.agents[id], r=reg[id];
+    if (!p) return;
+    const st=ag?.status||'idle', nw=88, nh=30, nx=p.x-nw/2, ny=p.y-nh/2, active=st!=='idle';
+    if (st==='running'){ ctx.shadowColor=p.color; ctx.shadowBlur=12; }
+    ctx.beginPath(); ctx.roundRect(nx,ny,nw,nh,7);
+    ctx.fillStyle=active?hexA(p.color,.12):'#1e2028'; ctx.fill();
+    ctx.strokeStyle=active?p.color:'rgba(255,255,255,.1)'; ctx.lineWidth=active?1.5:.7; ctx.stroke();
+    ctx.shadowBlur=0;
+    ctx.fillStyle=active?p.color:'#5a6070';
+    ctx.font=(active?'500 ':'')+'11px "Inter",sans-serif';
+    ctx.textAlign='center'; ctx.textBaseline='middle'; ctx.fillText(r.label,p.x,p.y-4);
+    ctx.fillStyle=hexA(p.color,active?.6:.35); ctx.font='9px "IBM Plex Mono",monospace';
+    ctx.fillText(r.role,p.x,p.y+8);
+  });
+  // ── Expanded agent sub-nodes ─────────────────────────────────────────────────
+  if (expandedAgent && pos[expandedAgent]) {
+    const parent = pos[expandedAgent];
+    // show ▼ on node
+    ctx.fillStyle = hexA(parent.color, .8);
+    ctx.font = 'bold 8px "Inter",sans-serif';
+    ctx.textAlign = 'center'; ctx.textBaseline = 'top';
+    ctx.fillText('▼', parent.x, parent.y + 17);
+    // gather ops by kind
+    const byKind = {};
+    S.internals.filter(it => it.agent === expandedAgent).forEach(it => {
+      (byKind[it.kind] = byKind[it.kind] || []).push(it);
+    });
+    const kinds = Object.keys(byKind);
+    if (kinds.length) {
+      const subW = 108, subH = 38, gap = 10;
+      const subY = parent.y + 76;
+      const totalW = kinds.length * (subW + gap) - gap;
+      let startX = parent.x - totalW / 2;
+      // clamp to canvas
+      if (startX < 8) startX = 8;
+      if (startX + totalW > fc.width - 8) startX = fc.width - 8 - totalW;
+      kinds.forEach((kind, i) => {
+        const items = byKind[kind];
+        const [bg, col, kindLabel] = (KIND[kind]||'rgba(107,114,128,.15)|#6b7280|?').split('|');
+        const sx = startX + i * (subW + gap) + subW / 2;
+        const sy = subY;
+        flowPos[expandedAgent + ':' + kind] = { x: sx, y: sy, color: col };
+        // connector
+        ctx.beginPath(); ctx.moveTo(parent.x, parent.y + 16); ctx.lineTo(sx, sy - subH/2 - 1);
+        ctx.strokeStyle = hexA(col, .2); ctx.lineWidth = 1; ctx.setLineDash([3, 3]); ctx.stroke(); ctx.setLineDash([]);
+        // box
+        ctx.beginPath(); ctx.roundRect(sx - subW/2, sy - subH/2, subW, subH, 7);
+        ctx.fillStyle = bg; ctx.fill();
+        ctx.strokeStyle = col; ctx.lineWidth = 1; ctx.stroke();
+        // kind label
+        ctx.fillStyle = col; ctx.font = '600 9px "IBM Plex Mono",monospace';
+        ctx.textAlign = 'center'; ctx.textBaseline = 'middle';
+        ctx.fillText(kindLabel.toUpperCase(), sx, sy - 9);
+        // detail
+        let detail = '×' + items.length;
+        if (kind === 'generation') {
+          const tok = items.reduce((s, it) => s + (it.prompt_tokens||0) + (it.completion_tokens||0), 0);
+          const model = trunc(items[0]?.model||'', 10);
+          detail = items.length + '× · ' + (tok > 999 ? (tok/1000).toFixed(1)+'k' : tok) + ' tok';
+          ctx.fillStyle = hexA(col, .55); ctx.font = '8px "IBM Plex Mono",monospace';
+          ctx.fillText(trunc(model, 14), sx, sy + 3);
+        } else if (kind === 'tool_call') {
+          const tools = [...new Set(items.map(it => it.tool_name))].slice(0, 2);
+          ctx.fillStyle = hexA(col, .55); ctx.font = '8px "IBM Plex Mono",monospace';
+          ctx.fillText(trunc(tools.join(', '), 16), sx, sy + 3);
+        } else if (kind === 'embedding') {
+          const model = items[0]?.model || '—';
+          ctx.fillStyle = hexA(col, .55); ctx.font = '8px "IBM Plex Mono",monospace';
+          ctx.fillText(trunc(model, 14), sx, sy + 3);
+        } else if (kind === 'retrieval') {
+          ctx.fillStyle = hexA(col, .55); ctx.font = '8px "IBM Plex Mono",monospace';
+          ctx.fillText((items[0]?.results?.length || 0) + ' results ea.', sx, sy + 3);
+        }
+        ctx.fillStyle = hexA(col, .85); ctx.font = '500 9px "Inter",sans-serif';
+        ctx.textAlign = 'center'; ctx.textBaseline = 'middle';
+        ctx.fillText(detail, sx, sy + 12);
+      });
+    } else {
+      // agent has no internals yet
+      ctx.fillStyle = hexA(parent.color, .35); ctx.font = '10px "Inter",sans-serif';
+      ctx.textAlign = 'center'; ctx.textBaseline = 'middle';
+      ctx.fillText('no operations recorded', parent.x, parent.y + 65);
+    }
+  }
+
+  // selection ring from Tools tab
+  if (selectedToolItem && pos[selectedToolItem.agent]){
+    const p=pos[selectedToolItem.agent];
+    const col=(KIND[selectedToolItem.kind]||'|||').split('|')[1]||'#888';
+    const [,,kindLabel]=(KIND[selectedToolItem.kind]||'||?').split('|');
+    ctx.shadowColor=col; ctx.shadowBlur=22;
+    ctx.beginPath(); ctx.roundRect(p.x-48,p.y-18,96,36,9);
+    ctx.strokeStyle=col; ctx.lineWidth=2; ctx.stroke(); ctx.shadowBlur=0;
+    ctx.fillStyle=col; ctx.font='bold 9px "IBM Plex Mono",monospace';
+    ctx.textAlign='center'; ctx.textBaseline='bottom';
+    ctx.fillText('▶ '+kindLabel, p.x, p.y-21);
+  }
+}
+
+// ── Tool overlay on canvas ─────────────────────────────────────────────────────
+function updateToolOverlay(item, show, seq){
+  let ov = document.getElementById('tool-overlay');
+  if (!show){
+    if (ov) ov.style.display='none';
+    return;
+  }
+  const p = flowPos[item?.agent];
+  if (!p){ if (ov) ov.style.display='none'; return; }
+
+  const [bg,col,kindLabel]=(KIND[item.kind]||'rgba(107,114,128,.15)|#6b7280|?').split('|');
+  const agentLabel=(S.registry[item.agent]?.label)||item.agent;
+  const agentColor=S.registry[item.agent]?.color||'#6b7280';
+
+  if (!ov){
+    ov=document.createElement('div'); ov.id='tool-overlay'; ov.className='tool-overlay';
+    fc.parentElement.appendChild(ov);
+  }
+
+  ov.innerHTML=`<div class="tool-overlay-hdr">
+    <span class="tool-seq">#${seq}</span>
+    <span class="tool-kind" style="background:${bg};color:${col}">${kindLabel}</span>
+    <span class="tool-agent-name" style="color:${agentColor}">${agentLabel}</span>
+  </div>
+  ${toolBody(item)}`;
+  ov.style.display='block';
+
+  // Map canvas coords → CSS px (canvas may be scaled via CSS width:100%)
+  const scaleX = fc.clientWidth / fc.width;
+  const scaleY = fc.clientHeight / fc.height;
+  const cx = p.x * scaleX, cy = p.y * scaleY;
+  const ovW = 260, ovH = ov.offsetHeight || 160;
+  // prefer right side, fall back to left
+  let left = cx + 54;
+  if (left + ovW > fc.clientWidth - 4) left = cx - 54 - ovW;
+  left = Math.max(4, left);
+  let top = cy - ovH / 2;
+  top = Math.max(4, Math.min(fc.clientHeight - ovH - 4, top));
+  ov.style.left = left+'px';
+  ov.style.top  = top+'px';
+}
+
+// ── Agents list ────────────────────────────────────────────────────────────────
+function renderAgents(){
+  const el = document.getElementById('agents-list');
+  const reg = S.registry, agents = S.agents;
+  const ids = Object.keys(reg);
+  if (!ids.length){ el.innerHTML = '<div class="empty">Agents appear after registration</div>'; return; }
+  el.innerHTML = '';
+  ids.forEach(id => {
+    const r=reg[id], a=agents[id]||{}, col=r.color||ROLE_COLORS[r.role]||'#6b7280';
+    const st=a.status||'idle', display=st==='idle'&&reg[id]?'registered':st;
+    const row=document.createElement('div'); row.className='agent-row '+display;
+    row.innerHTML = `<div class="agent-dot"></div>
+      <span class="agent-name" style="color:${st==='idle'?'var(--text)':col}">${r.label}</span>
+      <span class="agent-role" style="background:${hexA(col,.14)};color:${col}">${r.role}</span>`;
+    el.appendChild(row);
+  });
+}
+
+// ── Memory tab ────────────────────────────────────────────────────────────────
+function memSentence(k, m){
+  if (!m) return `Nothing has been stored under <b>${k}</b> yet.`;
+  const v = String(m.value);
+  const short = v.slice(0,90)+(v.length>90?'…':'');
+  return `<b>${k}</b> was ${m.op==='read'?'read as':'set to'}: "${short}"`;
+}
+
+function renderMem(){
+  const g=document.getElementById('mem-grid');
+  const keys=[...new Set([...Object.keys(S.memory)])];
+  if (!keys.length){ g.innerHTML='<div class="empty">No memory entries yet</div>'; return; }
+  g.innerHTML='';
+  keys.forEach(k => {
+    const m=S.memory[k], card=document.createElement('div'); card.className='mem-card'; card.id='mc-'+k;
+    card.innerHTML=`<div class="mem-val set">${memSentence(k,m)}</div>`;
+    g.appendChild(card);
+  });
+}
+
+function flashMem(key,op){
+  const c=document.getElementById('mc-'+key);
+  if (!c){ renderMem(); return; }
+  c.classList.remove('fw','fr'); void c.offsetWidth; c.classList.add(op==='write'?'fw':'fr');
+}
+
+// ── Log tab ───────────────────────────────────────────────────────────────────
+const TAG = {
+  start:'rgba(139,124,248,.15)|#8b7cf8', plan:'rgba(139,124,248,.15)|#8b7cf8', route:'rgba(139,124,248,.15)|#8b7cf8',
+  registered:'rgba(139,124,248,.12)|#7f77dd', reply:'rgba(74,222,128,.12)|#4ade80', pass:'rgba(74,222,128,.12)|#4ade80',
+  done:'rgba(74,222,128,.12)|#4ade80', fail:'rgba(248,113,113,.12)|#f87171', error:'rgba(248,113,113,.12)|#f87171',
+  retry:'rgba(245,158,11,.12)|#f59e0b', warn:'rgba(245,158,11,.12)|#f59e0b',
+};
+
+const LOG_VERB = {
+  start:'started', plan:'planned', route:'routed a task', registered:'joined',
+  reply:'replied', pass:'passed', done:'finished', fail:'failed',
+  error:'hit an error', retry:'is retrying', warn:'warned', tool:'called a tool', result:'got a result',
+};
+
+function logSentence(ev){
+  const label = (S.registry[ev.agent]?.label) || ev.agent;
+  const verb  = LOG_VERB[ev.event_type] || ev.event_type;
+  return `<b>${label}</b> ${verb} — ${ev.message}`;
+}
+
+function addLog(ev, prepend=true){
+  const log=document.getElementById('tp-log');
+  const empty=log.querySelector('.empty'); if (empty) empty.remove();
+  const [bg,col]=(TAG[ev.event_type]||'rgba(255,255,255,.06)|#9ca3af').split('|');
+  const d=new Date(ev.ts||Date.now()), ts=`${String(d.getMinutes()).padStart(2,'0')}:${String(d.getSeconds()).padStart(2,'0')}`;
+  const row=document.createElement('div'); row.className='log-row';
+  row.innerHTML=`<span class="log-tag" style="background:${bg};color:${col}">${ev.event_type}</span><span class="log-msg">${logSentence(ev)}</span><span class="log-time">${ts}</span>`;
+  if (prepend) log.insertBefore(row,log.firstChild); else log.appendChild(row);
+  if (log.children.length>80) log.removeChild(log.lastChild);
+}
+
+// ── Tools tab ─────────────────────────────────────────────────────────────────
+const KIND = {
+  embedding: 'rgba(139,124,248,.15)|#8b7cf8|embed',
+  retrieval: 'rgba(45,212,176,.15)|#2dd4b0|retrieve',
+  tool_call: 'rgba(96,165,250,.15)|#60a5fa|tool',
+  generation:'rgba(245,158,11,.15)|#f59e0b|generate',
+};
+
+const trunc = (s, n) => (s && s.length > n) ? s.slice(0, n) + '…' : (s||'');
+
+function toolPreview(item){
+  switch(item.kind){
+    case 'embedding':  return `"${trunc(item.text, 45)}" → ${item.dims}d (${item.model})`;
+    case 'retrieval':  return `search: "${trunc(item.query, 45)}"`;
+    case 'tool_call':  return item.error ? `✗ ${item.tool_name}: ${trunc(item.error, 50)}` : `${item.tool_name} — ${trunc(item.output, 55)}`;
+    case 'generation': return `${item.model||'model'} · ${(item.prompt_tokens+item.completion_tokens).toLocaleString()} tokens`;
+    default: return trunc(JSON.stringify(item), 60);
+  }
+}
+
+function toolBody(item){
+  const agentLabel = (S.registry[item.agent]?.label) || item.agent;
+  const agentColor = S.registry[item.agent]?.color || '#6b7280';
+  const blk = (label, val, full=false) =>
+    `<div class="tool-block${full?' full':''}"><span class="tb-label">${label}</span><div class="tb-val">${val}</div></div>`;
+  const agent = `<span style="color:${agentColor};font-weight:600">${agentLabel}</span>`;
+  switch(item.kind){
+    case 'embedding':
+      return `<div class="tool-blocks">
+        ${blk('Agent', agent)}
+        ${blk('Model', item.model||'—')}
+        ${blk('Dimensions', item.dims ? item.dims+'d' : '—')}
+        ${blk('Input text', trunc(item.text, 300), true)}
+      </div>`;
+    case 'retrieval': {
+      const n=(item.results||[]).length, top=item.results?.[0];
+      return `<div class="tool-blocks">
+        ${blk('Agent', agent)}
+        ${blk('Results found', String(n))}
+        ${blk('Query', trunc(item.query, 300), true)}
+        ${top ? blk('Best match', `<span style="color:var(--teal)">score ${top.score.toFixed(2)}</span> — ${trunc(top.text, 200)}`, true) : ''}
+      </div>`;
+    }
+    case 'tool_call': {
+      const ok=!item.error;
+      const esc = s => String(s||'').replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');
+      return `<div class="tool-blocks">
+        ${blk('Agent', agent)}
+        ${blk('Tool', `<b>${item.tool_name}</b>`)}
+        ${blk('Status', ok ? '<span style="color:var(--green)">✓ success</span>' : '<span style="color:var(--coral)">✗ failed</span>')}
+        ${item.latency_ms ? blk('Latency', item.latency_ms+'ms') : ''}
+      </div>
+      ${item.input ? `<div class="llm-response" style="border-top:1px solid rgba(255,255,255,.06)"><div class="llm-section-label" style="color:var(--blue)">↑ input</div><div class="llm-response-text" style="color:var(--muted)">${esc(item.input)}</div></div>` : ''}
+      ${ok && item.output ? `<div class="llm-response"><div class="llm-section-label" style="color:var(--green)">↓ output</div><div class="llm-response-text">${esc(item.output)}</div></div>` : ''}
+      ${!ok && item.error ? `<div class="llm-response"><div class="llm-section-label" style="color:var(--coral)">✗ error</div><div class="llm-response-text" style="color:var(--coral)">${esc(item.error)}</div></div>` : ''}`;
+    }
+    case 'generation': {
+      const total = item.prompt_tokens + item.completion_tokens;
+      const esc = s => String(s||'').replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');
+      const msgs = (item.messages||[]).map(m =>
+        `<div class="llm-turn ${m.role}"><div class="llm-role">${m.role}</div><div class="llm-content">${esc(m.content)}</div></div>`
+      ).join('');
+      return `<div class="tool-blocks">
+        ${blk('Agent', agent)}
+        ${blk('Model', item.model||'—')}
+        ${blk('Prompt tokens', item.prompt_tokens.toLocaleString())}
+        ${blk('Completion tokens', item.completion_tokens.toLocaleString())}
+        ${blk('Total tokens', total.toLocaleString())}
+        ${item.latency_ms ? blk('Latency', item.latency_ms+'ms') : ''}
+        ${item.stop_reason ? blk('Stop reason', item.stop_reason) : ''}
+      </div>
+      ${msgs ? `<div class="llm-thread">${msgs}</div>` : ''}
+      ${item.thinking ? `<div class="llm-thinking"><div class="llm-section-label">◎ thinking</div><div class="llm-thinking-text">${esc(item.thinking)}</div></div>` : ''}
+      ${item.response ? `<div class="llm-response"><div class="llm-section-label">↩ response</div><div class="llm-response-text">${esc(item.response)}</div></div>` : ''}`;
+    }
+    default:
+      return `<div class="tool-blocks">${blk('Raw', `<pre style="font-size:10px;white-space:pre-wrap">${JSON.stringify(item,null,2)}</pre>`, true)}</div>`;
+  }
+}
+
+function addInternal(item, prepend=true, seqOverride=null){
+  const panel=document.getElementById('tp-tools');
+  const empty=panel.querySelector('.empty'); if (empty) empty.remove();
+  const [bg,col,kindLabel]=(KIND[item.kind]||'rgba(107,114,128,.15)|#6b7280|?').split('|');
+  const agentLabel = (S.registry[item.agent]?.label) || item.agent;
+  const agentColor = S.registry[item.agent]?.color || '#6b7280';
+
+  if (seqOverride === null) toolSeq++;
+  const seq = seqOverride !== null ? seqOverride : toolSeq;
+
+  const det = document.createElement('details'); det.className='tool-item';
+  det.innerHTML=`<summary>
+    <span class="tool-chevron">▶</span>
+    <span class="tool-seq">#${seq}</span>
+    <span class="tool-kind" style="background:${bg};color:${col}">${kindLabel}</span>
+    <span class="tool-agent-name" style="color:${agentColor}">${agentLabel}</span>
+    <span class="tool-preview">${toolPreview(item)}</span>
+    ${item.latency_ms?`<span class="tool-lat">${item.latency_ms}ms</span>`:''}
+  </summary>
+  <div class="tool-body">${toolBody(item)}</div>`;
+
+  det.addEventListener('toggle', () => {
+    selectedToolItem = det.open ? item : null;
+    drawFlow();
+    updateToolOverlay(item, det.open, seq);
+  });
+
+  if (prepend) panel.insertBefore(det, panel.firstChild); else panel.appendChild(det);
+  if (panel.children.length>100) panel.removeChild(panel.lastChild);
+}
+
+// ── Plan tab ──────────────────────────────────────────────────────────────────
+function renderPlan(){
+  const pl=document.getElementById('plan-list');
+  if (!S.plan.length) return;
+  pl.innerHTML='';
+  S.plan.forEach((t,i) => {
+    const r=S.registry[t.agent]||{}, col=r.color||'#6b7280';
+    const done=(S.agents[t.agent]?.status==='done')||S.metrics.steps>i+2;
+    const row=document.createElement('div'); row.className='plan-row';
+    row.innerHTML=`<div class="plan-dot" style="background:${done?'#4ade80':col}"></div><span class="plan-agent" style="color:${col}">${t.agent}</span><span class="plan-task">${t.task}</span>${done?'<span class="plan-done">done</span>':''}`;
+    pl.appendChild(row);
+  });
+}
+
+// ── Status / elapsed ─────────────────────────────────────────────────────────
+function setStatus(s){
+  S.status=s;
+  const p=document.getElementById('run-status');
+  p.textContent=s; p.className='badge '+s;
+  document.getElementById('spinner').className='spinner'+(s==='running'?' on':'');
+  if (s!=='running'){ clearInterval(elapsedTimer); elapsedTimer=null; }
+}
+function startElapsed(){
+  if (elapsedTimer) clearInterval(elapsedTimer);
+  elapsedTimer=setInterval(() => {
+    if (!S.startedAt) return;
+    document.getElementById('m-elapsed').textContent=(Math.round((Date.now()-S.startedAt)/100)/10)+'s';
+  },200);
+}
+
+// ── Full state apply ──────────────────────────────────────────────────────────
+function applyFull(st){
+  if (!st){
+    S={registry:{},agents:{},memory:{},events:[],plan:[],internals:[],metrics:{steps:0,tokens:0,retries:0},status:'idle',goal:'',startedAt:null,lastArrow:null};
+    toolSeq=0; selectedToolItem=null; flowPos={}; expandedAgent=null;
+    const _ov=document.getElementById('tool-overlay'); if(_ov) _ov.style.display='none';
+    document.getElementById('goal-text').textContent='waiting for agents…';
+    document.getElementById('tp-log').innerHTML='<div class="empty">Events stream here during a run</div>';
+    document.getElementById('tp-tools').innerHTML='<div class="empty">Embeddings, retrievals, tool calls and LLM generations appear here</div>';
+    document.getElementById('mem-grid').innerHTML='';
+    document.getElementById('plan-list').innerHTML='<div class="empty">Plan appears after orchestrator runs</div>';
+    ['m-steps','m-tokens','m-retries'].forEach(id=>document.getElementById(id).textContent='0');
+    document.getElementById('m-elapsed').textContent='—';
+    setStatus('idle'); renderAgents(); drawFlow();
+    return;
+  }
+  S.registry=st.registry||{};
+  S.agents=st.agents||{};
+  S.memory={};
+  Object.entries(st.memory||{}).forEach(([k,v])=>S.memory[k]=v);
+  S.events=st.events||[];
+  S.plan=st.plan||[];
+  S.internals=st.internals||[];
+  S.metrics=st.metrics||{steps:0,tokens:0,retries:0};
+  S.status=st.status||'idle';
+  S.goal=st.goal||'';
+  S.startedAt=st.startedAt||null;
+  S.lastArrow=(st.arrows||[])[0]||null;
+
+  document.getElementById('goal-text').textContent=S.goal||'waiting for agents…';
+  document.getElementById('m-steps').textContent=S.metrics.steps;
+  document.getElementById('m-tokens').textContent=S.metrics.tokens>999?(S.metrics.tokens/1000).toFixed(1)+'k':S.metrics.tokens;
+  document.getElementById('m-retries').textContent=S.metrics.retries;
+  setStatus(S.status);
+  renderAgents(); renderMem(); renderPlan(); drawFlow();
+
+  const logEl=document.getElementById('tp-log'); logEl.innerHTML='';
+  S.events.slice().reverse().forEach(ev=>addLog(ev,false));
+  if (!S.events.length) logEl.innerHTML='<div class="empty">Events stream here during a run</div>';
+
+  toolSeq = 0;
+  const toolsEl=document.getElementById('tp-tools'); toolsEl.innerHTML='';
+  if (S.internals.length) S.internals.forEach((it,i)=>addInternal(it,false,i+1));
+  else toolsEl.innerHTML='<div class="empty">Embeddings, retrievals, tool calls and LLM generations appear here</div>';
+
+  if (S.startedAt&&S.status==='running') startElapsed();
+}
+
+// ── SSE handler ───────────────────────────────────────────────────────────────
+function handle(type,p){
+  switch(type){
+    case 'init':    applyFull(p.state); break;
+    case 'reset':   applyFull(null); break;
+    case 'registry': S.registry=p; renderAgents(); drawFlow(); break;
+    case 'agents':   S.agents=p; renderAgents(); drawFlow(); break;
+    case 'goal':     S.goal=p.goal; S.startedAt=Date.now(); document.getElementById('goal-text').textContent=p.goal; startElapsed(); break;
+    case 'status':   setStatus(p); break;
+    case 'event':    addLog(p); break;
+    case 'memory':   S.memory[p.key]=p; renderMem(); flashMem(p.key,p.op); break;
+    case 'arrow':    S.lastArrow=p; drawFlow(); break;
+    case 'plan':     S.plan=p; renderPlan(); break;
+    case 'metrics':
+      S.metrics=p;
+      document.getElementById('m-steps').textContent=p.steps;
+      document.getElementById('m-tokens').textContent=p.tokens>999?(p.tokens/1000).toFixed(1)+'k':p.tokens;
+      document.getElementById('m-retries').textContent=p.retries;
+      break;
+    case 'internal': addInternal(p); break;
+  }
+}
+
+// ── Connection ────────────────────────────────────────────────────────────────
+function setBadge(live){
+  const b=document.getElementById('conn-badge');
+  b.textContent=live?'live':'reconnecting…';
+  b.className='badge '+(live?'live':'dead');
+}
+function connect(){
+  if (es){ es.close(); es=null; }
+  es=new EventSource(SERVER+'/events');
+  es.onopen=()=>setBadge(true);
+  es.onerror=()=>{ setBadge(false); es.close(); es=null; setTimeout(connect,2000); };
+  es.onmessage=e=>{ setBadge(true); const msg=JSON.parse(e.data); handle(msg.type,msg.payload); };
+}
+
+// ── UI actions ────────────────────────────────────────────────────────────────
+function switchTab(e,name){
+  document.querySelectorAll('.tab').forEach(t=>t.classList.remove('active'));
+  document.querySelectorAll('.tab-panel').forEach(p=>p.classList.remove('active'));
+  e.target.classList.add('active');
+  document.getElementById('tp-'+name).classList.add('active');
+}
+async function emulate(scenario){
+  try{
+    const r=await fetch(SERVER+'/emulate',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({scenario})});
+    if (!r.ok) alert('Server error: '+r.status);
+  }catch(_){alert('Cannot reach server at '+SERVER);}
+}
+async function doReset(){
+  try{ await fetch(SERVER+'/reset',{method:'POST'}); }catch(_){ applyFull(null); }
+}
+
+// ── Boot ──────────────────────────────────────────────────────────────────────
+setTimeout(()=>{ initCanvas(); connect(); },80);
+</script>
+</body>
+</html>

src/server.js

@@ -0,0 +1,615 @@
+#!/usr/bin/env node
+'use strict';
+const http = require('http');
+const fs   = require('fs');
+const path = require('path');
+
+const PORT = parseInt(process.env.VISIBILITY_PORT || '4242');
+
+// ── State ─────────────────────────────────────────────────────────────────────
+let state = fresh();
+function fresh() {
+  return {
+    agents: {}, registry: {}, memory: {}, events: [],
+    arrows: [], plan: [], internals: [],
+    metrics: { steps: 0, tokens: 0, retries: 0 },
+    goal: '', runId: null, status: 'idle', startedAt: null,
+    clients: [],
+  };
+}
+
+// ── SSE broadcast ─────────────────────────────────────────────────────────────
+function broadcast(type, payload) {
+  const msg = `data: ${JSON.stringify({ type, payload, ts: Date.now() })}\n\n`;
+  state.clients.forEach(r => { try { r.write(msg); } catch (_) {} });
+}
+
+// ── Role colours ──────────────────────────────────────────────────────────────
+const COLORS = {
+  orchestrator: '#8b7cf8', researcher: '#2dd4b0', coder: '#60a5fa',
+  critic: '#f59e0b', synthesiser: '#60a5fa', worker: '#2dd4b0',
+};
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function ensureAgent(id) {
+  if (!state.agents[id]) {
+    const r = state.registry[id] || {};
+    state.agents[id] = {
+      id, label: r.label || id, role: r.role || 'worker', model: r.model || '',
+      reports_to: r.reports_to || null, token_budget: r.token_budget || 8192,
+      color: r.color || COLORS[r.role] || '#6b7280', status: 'idle', tokens: 0, calls: 0,
+    };
+  }
+}
+function safeAgents() {
+  const out = {};
+  for (const [k, v] of Object.entries(state.agents)) {
+    out[k] = { id: v.id, label: v.label, role: v.role, model: v.model,
+      reports_to: v.reports_to, token_budget: v.token_budget, color: v.color,
+      status: v.status, tokens: v.tokens, calls: v.calls };
+  }
+  return out;
+}
+function snapshot() {
+  return {
+    registry: state.registry, runId: state.runId, goal: state.goal,
+    status: state.status, startedAt: state.startedAt, agents: safeAgents(),
+    memory: state.memory, events: state.events.slice(0, 80),
+    arrows: state.arrows.slice(0, 20), plan: state.plan, metrics: state.metrics,
+    internals: state.internals.slice(0, 60),
+    scenarios: Object.keys(SCENARIOS),
+  };
+}
+
+// ── Tools ─────────────────────────────────────────────────────────────────────
+const TOOLS = {
+  register_agent({ id, label, role = 'worker', model = '', reports_to = null, token_budget = 8192, color = null }) {
+    const c = color || COLORS[role] || '#6b7280';
+    state.registry[id] = { id, label, role, model, reports_to, token_budget, color: c };
+    state.agents[id]   = { ...state.registry[id], status: 'idle', tokens: 0, calls: 0 };
+    broadcast('registry', state.registry);
+    broadcast('agents', safeAgents());
+    broadcast('event', { agent: id, event_type: 'registered',
+      message: `${label} registered — role:${role}, model:${model || 'unset'}`,
+      tokens: 0, latency_ms: 0, ts: Date.now() });
+    return { ok: true };
+  },
+  log_event({ agent, event_type, message, tokens = 0, latency_ms = 0, metadata = {} }) {
+    ensureAgent(agent);
+    const item = { agent, event_type, message, tokens, latency_ms, metadata, ts: Date.now() };
+    state.events.unshift(item);
+    if (state.events.length > 200) state.events.pop();
+    if (tokens) {
+      state.agents[agent].tokens += tokens;
+      state.agents[agent].calls  += 1;
+      state.metrics.tokens       += tokens;
+    }
+    state.metrics.steps++;
+    broadcast('event', item);
+    broadcast('metrics', state.metrics);
+    broadcast('agents', safeAgents());
+    return { ok: true };
+  },
+  set_memory({ key, value, op = 'write' }) {
+    state.memory[key] = { value, op, ts: Date.now() };
+    broadcast('memory', { key, value, op, ts: Date.now() });
+    return { ok: true };
+  },
+  set_agent_state({ agent_id, status }) {
+    ensureAgent(agent_id);
+    state.agents[agent_id].status = status;
+    broadcast('agents', safeAgents());
+    return { ok: true };
+  },
+  trace_step({ from_agent, to_agent, label = '', arrow_type = 'msg' }) {
+    ensureAgent(from_agent); ensureAgent(to_agent);
+    const arrow = { from: from_agent, to: to_agent, label, arrow_type, ts: Date.now() };
+    state.arrows.unshift(arrow);
+    if (state.arrows.length > 50) state.arrows.pop();
+    broadcast('arrow', arrow);
+    return { ok: true };
+  },
+  set_plan({ tasks }) { state.plan = tasks; broadcast('plan', tasks); return { ok: true }; },
+  set_goal({ goal, run_id }) {
+    state.goal = goal; state.runId = run_id || String(Date.now());
+    state.status = 'running'; state.startedAt = Date.now();
+    broadcast('goal', { goal, runId: state.runId });
+    broadcast('status', 'running');
+    return { ok: true };
+  },
+  finish_run({ status = 'done' }) {
+    state.status = status; broadcast('status', status); return { ok: true };
+  },
+
+  // ── Internal observability tools ──────────────────────────────────────────
+  log_embedding({ agent, text, model = 'text-embedding-3-small', dims = 1536, latency_ms = 0 }) {
+    ensureAgent(agent);
+    const item = { kind: 'embedding', agent, text: String(text).slice(0, 90), model, dims, latency_ms, ts: Date.now() };
+    state.internals.unshift(item);
+    if (state.internals.length > 200) state.internals.pop();
+    broadcast('internal', item);
+    return { ok: true };
+  },
+  log_retrieval({ agent, query, results = [], latency_ms = 0 }) {
+    ensureAgent(agent);
+    const item = {
+      kind: 'retrieval', agent,
+      query: String(query).slice(0, 90),
+      results: results.slice(0, 6).map(r => ({ text: String(r.text || '').slice(0, 70), score: r.score ?? 0 })),
+      latency_ms, ts: Date.now(),
+    };
+    state.internals.unshift(item);
+    if (state.internals.length > 200) state.internals.pop();
+    broadcast('internal', item);
+    return { ok: true };
+  },
+  log_tool_call({ agent, tool_name, input = '', output = '', latency_ms = 0, error = null }) {
+    ensureAgent(agent);
+    const item = {
+      kind: 'tool_call', agent, tool_name,
+      input:  String(input).slice(0, 4000),
+      output: String(output).slice(0, 4000),
+      latency_ms, error, ts: Date.now(),
+    };
+    state.internals.unshift(item);
+    if (state.internals.length > 200) state.internals.pop();
+    broadcast('internal', item);
+    return { ok: true };
+  },
+  log_generation({ agent, prompt_tokens = 0, completion_tokens = 0, model = '', latency_ms = 0, stop_reason = 'stop', messages = [], response = null, thinking = null }) {
+    ensureAgent(agent);
+    const total = prompt_tokens + completion_tokens;
+    const item = {
+      kind: 'generation', agent, prompt_tokens, completion_tokens, total, model, latency_ms, stop_reason,
+      messages: (messages||[]).slice(0,30).map(m => ({ role: String(m.role||'user'), content: String(m.content||'').slice(0,2000) })),
+      response: response ? String(response).slice(0,4000) : null,
+      thinking: thinking ? String(thinking).slice(0,3000) : null,
+      ts: Date.now(),
+    };
+    state.internals.unshift(item);
+    if (state.internals.length > 200) state.internals.pop();
+    if (total) {
+      state.agents[agent].tokens += total;
+      state.agents[agent].calls  += 1;
+      state.metrics.tokens       += total;
+    }
+    broadcast('internal', item);
+    broadcast('agents', safeAgents());
+    broadcast('metrics', state.metrics);
+    return { ok: true };
+  },
+};
+// alias: log_llm_turn → log_generation (richer name exposed in MCP)
+TOOLS.log_llm_turn = TOOLS.log_generation;
+
+// ── Demo scenarios ─────────────────────────────────────────────────────────────
+const SCENARIOS = {
+  research_code: {
+    goal: 'Explain quicksort and write a Python implementation',
+    steps: [
+      { delay: 0, fn: () => {
+        TOOLS.register_agent({ id: 'orchestrator', label: 'Orchestrator', role: 'orchestrator', model: 'claude-sonnet-4-20250514', token_budget: 16384 });
+        TOOLS.register_agent({ id: 'researcher',   label: 'Researcher',   role: 'researcher',   model: 'claude-haiku-4-5-20251001', reports_to: 'orchestrator', token_budget: 8192 });
+        TOOLS.register_agent({ id: 'coder',        label: 'Coder',        role: 'coder',        model: 'claude-sonnet-4-20250514',  reports_to: 'orchestrator', token_budget: 8192 });
+        TOOLS.register_agent({ id: 'critic',       label: 'Critic',       role: 'critic',       model: 'claude-haiku-4-5-20251001', reports_to: 'orchestrator', token_budget: 4096 });
+      }},
+      { delay: 800, fn: () => {
+        TOOLS.set_goal({ goal: SCENARIOS.research_code.goal });
+        TOOLS.set_agent_state({ agent_id: 'orchestrator', status: 'running' });
+        TOOLS.log_generation({ agent: 'orchestrator', prompt_tokens: 280, completion_tokens: 95, model: 'claude-sonnet-4-20250514', latency_ms: 620, stop_reason: 'end_turn',
+          messages: [
+            { role: 'system', content: 'You are an orchestrator agent. Break the user goal into subtasks and delegate to specialist agents: Researcher (theory/research), Coder (implementation), Critic (validation). Always plan before routing.' },
+            { role: 'user', content: 'Explain quicksort and write a Python implementation' },
+          ],
+          response: "I'll break this into 3 sequential tasks:\n1. **Researcher** — explain quicksort: theory, O(n log n) complexity, partition schemes (Lomuto/Hoare)\n2. **Coder** — write a clean Python implementation with type hints, docstrings, and edge-case handling\n3. **Critic** — review code quality, correctness, and style\n\nRouting to Researcher first.",
+        });
+        TOOLS.log_event({ agent: 'orchestrator', event_type: 'start', message: 'Planning tasks…' });
+      }},
+      { delay: 900, fn: () => {
+        TOOLS.set_plan({ tasks: [{ agent: 'researcher', task: 'Explain quicksort', depends_on: [] }, { agent: 'coder', task: 'Write Python implementation', depends_on: [0] }, { agent: 'critic', task: 'Validate code quality', depends_on: [1] }] });
+        TOOLS.trace_step({ from_agent: 'orchestrator', to_agent: 'researcher', label: 'explain', arrow_type: 'msg' });
+        TOOLS.set_agent_state({ agent_id: 'researcher', status: 'running' });
+        TOOLS.set_memory({ key: 'goal', value: SCENARIOS.research_code.goal });
+      }},
+      // Researcher — embed query, web search, generate
+      { delay: 400, fn: () => {
+        TOOLS.log_embedding({ agent: 'researcher', text: 'quicksort algorithm explanation divide conquer', model: 'text-embedding-3-small', dims: 1536, latency_ms: 48 });
+      }},
+      { delay: 300, fn: () => {
+        TOOLS.log_retrieval({ agent: 'researcher', query: 'quicksort algorithm complexity analysis', latency_ms: 92,
+          results: [
+            { text: 'Quicksort uses divide-and-conquer: pick a pivot, partition into <, =, > subarrays.', score: 0.94 },
+            { text: 'Average-case O(n log n); worst-case O(n²) with bad pivot selection.', score: 0.91 },
+            { text: 'Lomuto vs Hoare partition schemes differ in swap count and cache behaviour.', score: 0.87 },
+            { text: 'Introsort (used in STL) falls back to heapsort to avoid O(n²) worst case.', score: 0.82 },
+          ],
+        });
+      }},
+      { delay: 500, fn: () => {
+        TOOLS.log_tool_call({ agent: 'researcher', tool_name: 'web_search', input: 'quicksort algorithm detailed explanation', output: '6 results — Wikipedia, CS Visualizer, CLRS excerpt', latency_ms: 340 });
+      }},
+      { delay: 900, fn: () => {
+        TOOLS.log_generation({ agent: 'researcher', prompt_tokens: 1840, completion_tokens: 620, model: 'claude-haiku-4-5-20251001', latency_ms: 1320, stop_reason: 'end_turn',
+          messages: [
+            { role: 'system', content: 'You are a researcher agent. Synthesise accurate technical information from retrieved documents. Be precise, cite complexity bounds, note tradeoffs.' },
+            { role: 'user', content: 'Task from orchestrator: Explain the quicksort algorithm in detail — theory, complexity, partition schemes.' },
+            { role: 'assistant', content: '[embedding query and retrieving relevant documents…]' },
+            { role: 'tool', content: 'Retrieved 4 chunks:\n• Quicksort uses divide-and-conquer: pick a pivot, partition into <, =, > subarrays. (score 0.94)\n• Average O(n log n); worst O(n²) with bad pivot selection. (score 0.91)\n• Lomuto vs Hoare partition differ in swap count and cache behaviour. (score 0.87)\n• Introsort falls back to heapsort to avoid O(n²) worst case. (score 0.82)' },
+          ],
+          response: "**Quicksort** is a divide-and-conquer sorting algorithm:\n\n**Core strategy**: Choose a pivot element, partition the array into ≤ pivot and > pivot halves, then recursively sort each half in-place.\n\n**Complexity**:\n- Average: O(n log n) — balanced splits with good pivot choice\n- Worst: O(n²) — degenerate pivot on already-sorted input\n- Space: O(log n) stack depth average\n\n**Partition schemes**:\n- *Lomuto*: simpler code, last element as pivot, O(n) comparisons\n- *Hoare*: ~3× fewer swaps, two converging pointers\n\n**Practical optimisations**:\n- Median-of-3 pivot selection to avoid worst case\n- Switch to insertion sort for subarrays smaller than ~10 elements\n- Introsort (Python's Timsort variant) adds heapsort fallback for guaranteed O(n log n)",
+        });
+        TOOLS.log_event({ agent: 'researcher', event_type: 'reply', message: 'Quicksort: divide-and-conquer. Pivot splits into <, =, > partitions. Avg O(n log n), worst O(n²) with sorted input.' });
+        TOOLS.set_memory({ key: 'research', value: 'Quicksort: O(n log n) avg, O(n²) worst. Lomuto/Hoare partition.' });
+        TOOLS.trace_step({ from_agent: 'researcher', to_agent: 'orchestrator', label: 'done', arrow_type: 'result' });
+        TOOLS.set_agent_state({ agent_id: 'researcher', status: 'done' });
+      }},
+      { delay: 500, fn: () => {
+        TOOLS.trace_step({ from_agent: 'orchestrator', to_agent: 'coder', label: 'implement', arrow_type: 'msg' });
+        TOOLS.set_agent_state({ agent_id: 'coder', status: 'running' });
+      }},
+      // Coder — retrieve code examples, execute sandbox, generate
+      { delay: 400, fn: () => {
+        TOOLS.log_embedding({ agent: 'coder', text: 'Python quicksort implementation with type hints', model: 'text-embedding-3-small', dims: 1536, latency_ms: 51 });
+      }},
+      { delay: 300, fn: () => {
+        TOOLS.log_retrieval({ agent: 'coder', query: 'Python quicksort recursive + in-place implementation', latency_ms: 88,
+          results: [
+            { text: 'def quicksort(arr): return [] if not arr else quicksort([x for x in arr[1:] if x<=arr[0]])+[arr[0]]+...', score: 0.96 },
+            { text: 'def partition(arr, lo, hi): pivot=arr[hi]; i=lo-1; ...', score: 0.93 },
+            { text: 'Lomuto partition: O(n) extra calls, simpler code. Hoare: fewer swaps.', score: 0.88 },
+          ],
+        });
+      }},
+      { delay: 800, fn: () => {
+        TOOLS.log_generation({ agent: 'coder', prompt_tokens: 3200, completion_tokens: 980, model: 'claude-sonnet-4-20250514', latency_ms: 2100, stop_reason: 'end_turn',
+          messages: [
+            { role: 'system', content: 'You are a coder agent. Write production-quality Python code with type hints, docstrings, and edge-case handling. Use retrieved snippets as reference, not copy-paste.' },
+            { role: 'user', content: 'Task from orchestrator: Implement quicksort in Python. Context from researcher:\n- Quicksort: divide-and-conquer, pick pivot, partition into ≤ and > halves\n- Avg O(n log n), worst O(n²)\n- Lomuto partition is simpler; Hoare has fewer swaps' },
+            { role: 'assistant', content: '[retrieving code examples and planning implementation…]' },
+            { role: 'tool', content: 'Retrieved snippets:\n• def quicksort(arr): return [] if not arr else quicksort([x for x in arr[1:] if x<=arr[0]])+[arr[0]]+... (functional, not in-place)\n• def partition(arr, lo, hi): pivot=arr[hi]; i=lo-1; ... (Lomuto, in-place)' },
+          ],
+          response: "```python\nfrom typing import TypeVar\n\nT = TypeVar('T')\n\n\ndef quicksort(arr: list[T]) -> list[T]:\n    \"\"\"Return a new sorted list using quicksort (functional style).\n\n    Average O(n log n), worst-case O(n²). Not in-place.\n    \"\"\"\n    if len(arr) <= 1:\n        return arr\n    pivot = arr[len(arr) // 2]  # median-of-1 (simple)\n    left  = [x for x in arr if x < pivot]\n    mid   = [x for x in arr if x == pivot]\n    right = [x for x in arr if x > pivot]\n    return quicksort(left) + mid + quicksort(right)\n\n\ndef quicksort_inplace(arr: list[T], lo: int = 0, hi: int | None = None) -> None:\n    \"\"\"Sort arr in-place using Lomuto partition scheme.\"\"\"\n    if hi is None:\n        hi = len(arr) - 1\n    if lo < hi:\n        p = _partition(arr, lo, hi)\n        quicksort_inplace(arr, lo, p - 1)\n        quicksort_inplace(arr, p + 1, hi)\n\n\ndef _partition(arr: list[T], lo: int, hi: int) -> int:\n    pivot, i = arr[hi], lo - 1\n    for j in range(lo, hi):\n        if arr[j] <= pivot:\n            i += 1\n            arr[i], arr[j] = arr[j], arr[i]\n    arr[i + 1], arr[hi] = arr[hi], arr[i + 1]\n    return i + 1\n```\n\nBoth variants pass edge cases: empty list, single element, all-equal, reverse-sorted.",
+        });
+      }},
+      { delay: 600, fn: () => {
+        TOOLS.log_tool_call({ agent: 'coder', tool_name: 'code_execute', input: 'quicksort([3,1,4,1,5,9,2,6]) — smoke test', output: '[1, 1, 2, 3, 4, 5, 6, 9] ✓ (12ms)', latency_ms: 112 });
+        TOOLS.log_tool_call({ agent: 'coder', tool_name: 'code_execute', input: 'quicksort([]) — edge case empty list', output: '[] ✓', latency_ms: 8 });
+        TOOLS.log_tool_call({ agent: 'coder', tool_name: 'code_execute', input: 'quicksort([1]) — single element', output: '[1] ✓', latency_ms: 6 });
+      }},
+      { delay: 900, fn: () => {
+        TOOLS.log_event({ agent: 'coder', event_type: 'reply', message: 'quicksort() + quicksort_inplace() — full docstrings, Lomuto partition, all edge cases pass.' });
+        TOOLS.set_memory({ key: 'code', value: 'def quicksort(arr: list) -> list: ...\ndef quicksort_inplace(arr, lo, hi): ...' });
+        TOOLS.trace_step({ from_agent: 'coder', to_agent: 'orchestrator', label: 'ready', arrow_type: 'result' });
+        TOOLS.set_agent_state({ agent_id: 'coder', status: 'done' });
+      }},
+      { delay: 500, fn: () => {
+        TOOLS.trace_step({ from_agent: 'orchestrator', to_agent: 'critic', label: 'validate', arrow_type: 'msg' });
+        TOOLS.set_agent_state({ agent_id: 'critic', status: 'running' });
+      }},
+      // Critic — embed code, lint, generate review
+      { delay: 400, fn: () => {
+        TOOLS.log_embedding({ agent: 'critic', text: 'def quicksort(arr: list) -> list: ...', model: 'text-embedding-3-small', dims: 1536, latency_ms: 44 });
+      }},
+      { delay: 300, fn: () => {
+        TOOLS.log_tool_call({ agent: 'critic', tool_name: 'lint_check', input: 'quicksort.py', output: 'pylint 9.8/10 — 0 errors, 1 convention (missing module docstring)', latency_ms: 180 });
+        TOOLS.log_tool_call({ agent: 'critic', tool_name: 'type_check',  input: 'mypy quicksort.py --strict', output: 'Success: no issues found in 1 source file', latency_ms: 95 });
+      }},
+      { delay: 700, fn: () => {
+        TOOLS.log_generation({ agent: 'critic', prompt_tokens: 2100, completion_tokens: 480, model: 'claude-haiku-4-5-20251001', latency_ms: 980, stop_reason: 'end_turn',
+          messages: [
+            { role: 'system', content: 'You are a critic agent. Review code for correctness, style, type safety, and edge-case coverage. Output a score /10 with justification.' },
+            { role: 'user', content: 'Review this Python quicksort implementation:\n\ndef quicksort(arr: list[T]) -> list[T]: ...\ndef quicksort_inplace(arr, lo, hi): ...\n\nTool results: pylint 9.8/10, mypy strict: no issues.' },
+          ],
+          response: "**PASS — 9/10**\n\n✓ Type hints on public API (TypeVar T for generics)\n✓ Docstrings explain complexity and behaviour\n✓ Both functional and in-place variants provided\n✓ Edge cases: empty list, single element return correctly\n✓ mypy strict passes — no type errors\n✓ pylint 9.8/10\n\n**Minor issues**:\n- Missing module-level docstring (-0.5)\n- `quicksort_inplace` docstring doesn't document `lo`/`hi` params (-0.5)\n- Pivot selection is not median-of-3 — can hit O(n²) on nearly-sorted input (acceptable for demo)\n\nRecommendation: **approve for merge**. Add module docstring before production use.",
+        });
+        TOOLS.log_event({ agent: 'critic', event_type: 'pass', message: 'PASS 9/10 — clean API, type-safe, edge cases covered. Minor: missing module docstring.' });
+        TOOLS.trace_step({ from_agent: 'critic', to_agent: 'orchestrator', label: 'pass 9/10', arrow_type: 'result' });
+        TOOLS.set_agent_state({ agent_id: 'critic', status: 'done' });
+      }},
+      { delay: 400, fn: () => {
+        TOOLS.set_memory({ key: 'output', value: 'quicksort.py — approved 9/10' });
+        TOOLS.log_event({ agent: 'orchestrator', event_type: 'done', message: 'Run complete — 18 steps' });
+        TOOLS.set_agent_state({ agent_id: 'orchestrator', status: 'done' });
+        TOOLS.finish_run({ status: 'done' });
+      }},
+    ],
+  },
+
+  critic_retry: {
+    goal: 'Write an RFC-5321 compliant email regex validator',
+    steps: [
+      { delay: 0, fn: () => {
+        TOOLS.register_agent({ id: 'orchestrator', label: 'Orchestrator', role: 'orchestrator', model: 'claude-sonnet-4-20250514', token_budget: 16384 });
+        TOOLS.register_agent({ id: 'coder',        label: 'Coder',        role: 'coder',        model: 'claude-sonnet-4-20250514',  reports_to: 'orchestrator', token_budget: 8192 });
+        TOOLS.register_agent({ id: 'critic',       label: 'Critic',       role: 'critic',       model: 'claude-haiku-4-5-20251001', reports_to: 'orchestrator', token_budget: 4096 });
+      }},
+      { delay: 700, fn: () => {
+        TOOLS.set_goal({ goal: SCENARIOS.critic_retry.goal });
+        TOOLS.set_agent_state({ agent_id: 'orchestrator', status: 'running' });
+        TOOLS.log_generation({ agent: 'orchestrator', prompt_tokens: 240, completion_tokens: 80, model: 'claude-sonnet-4-20250514', latency_ms: 580 });
+        TOOLS.log_event({ agent: 'orchestrator', event_type: 'start', message: 'Planning…' });
+      }},
+      { delay: 800, fn: () => {
+        TOOLS.set_plan({ tasks: [{ agent: 'coder', task: 'Write RFC-5321 email regex', depends_on: [] }, { agent: 'critic', task: 'Validate regex correctness', depends_on: [0] }] });
+        TOOLS.trace_step({ from_agent: 'orchestrator', to_agent: 'coder', label: 'write', arrow_type: 'msg' });
+        TOOLS.set_agent_state({ agent_id: 'coder', status: 'running' });
+      }},
+      // Coder v1 — minimal attempt
+      { delay: 400, fn: () => {
+        TOOLS.log_embedding({ agent: 'coder', text: 'RFC-5321 email address validation regex Python', model: 'text-embedding-3-small', dims: 1536, latency_ms: 49 });
+      }},
+      { delay: 300, fn: () => {
+        TOOLS.log_retrieval({ agent: 'coder', query: 'email regex RFC 5321 compliant Python', latency_ms: 84,
+          results: [
+            { text: 'Simple: r"[^@]+@[^@]+\\.[^@]+" — catches most but misses edge cases.', score: 0.89 },
+            { text: 'RFC-5321 allows quoted strings, IP literals, special chars in local part.', score: 0.85 },
+          ],
+        });
+      }},
+      { delay: 900, fn: () => {
+        TOOLS.log_generation({ agent: 'coder', prompt_tokens: 920, completion_tokens: 240, model: 'claude-sonnet-4-20250514', latency_ms: 1800, stop_reason: 'end_turn' });
+        TOOLS.log_tool_call({ agent: 'coder', tool_name: 'code_execute', input: 'test_email("user@example.com")', output: 'True ✓', latency_ms: 14 });
+        TOOLS.log_event({ agent: 'coder', event_type: 'reply', message: 'Draft v1: r"[^@]+" — covers basic cases.' });
+        TOOLS.set_memory({ key: 'code', value: 'r"[^@]+"' });
+        TOOLS.trace_step({ from_agent: 'coder', to_agent: 'orchestrator', label: 'v1', arrow_type: 'result' });
+        TOOLS.set_agent_state({ agent_id: 'coder', status: 'active' });
+      }},
+      // Critic v1 review — fail
+      { delay: 500, fn: () => {
+        TOOLS.trace_step({ from_agent: 'orchestrator', to_agent: 'critic', label: 'review v1', arrow_type: 'msg' });
+        TOOLS.set_agent_state({ agent_id: 'critic', status: 'running' });
+      }},
+      { delay: 400, fn: () => {
+        TOOLS.log_embedding({ agent: 'critic', text: 'r"[^@]+" email regex RFC-5321 compliance', model: 'text-embedding-3-small', dims: 1536, latency_ms: 46 });
+        TOOLS.log_tool_call({ agent: 'critic', tool_name: 'regex_test_suite', input: 'RFC-5321 test vectors (120 cases)', output: '67/120 pass — missing TLDs, quoted strings, IP literals, consecutive dot check', latency_ms: 220 });
+      }},
+      { delay: 700, fn: () => {
+        TOOLS.log_generation({ agent: 'critic', prompt_tokens: 1400, completion_tokens: 360, model: 'claude-haiku-4-5-20251001', latency_ms: 980, stop_reason: 'end_turn' });
+        TOOLS.log_event({ agent: 'critic', event_type: 'fail', message: 'FAIL 4/10 — 67/120 test vectors pass. Missing: TLDs, quoted strings, IP literals, consecutive-dot rule.' });
+        TOOLS.set_memory({ key: 'critique', value: 'fail 4/10 — missing TLDs, quoted strings, IP literals' });
+        TOOLS.trace_step({ from_agent: 'critic', to_agent: 'orchestrator', label: 'fail 4/10', arrow_type: 'result' });
+        TOOLS.set_agent_state({ agent_id: 'critic', status: 'active' });
+        state.metrics.retries++; broadcast('metrics', state.metrics);
+      }},
+      // Orchestrator retries coder
+      { delay: 500, fn: () => {
+        TOOLS.log_generation({ agent: 'orchestrator', prompt_tokens: 480, completion_tokens: 120, model: 'claude-sonnet-4-20250514', latency_ms: 640 });
+        TOOLS.log_event({ agent: 'orchestrator', event_type: 'retry', message: 'Critic FAIL — retrying Coder with full critique attached' });
+        TOOLS.trace_step({ from_agent: 'orchestrator', to_agent: 'coder', label: 'retry', arrow_type: 'retry' });
+        TOOLS.set_agent_state({ agent_id: 'coder', status: 'running' });
+      }},
+      // Coder v2 — thorough attempt
+      { delay: 400, fn: () => {
+        TOOLS.log_embedding({ agent: 'coder', text: 'RFC-5321 quoted strings IP literal TLD validation', model: 'text-embedding-3-small', dims: 1536, latency_ms: 52 });
+        TOOLS.log_retrieval({ agent: 'coder', query: 'RFC 5321 email local-part quoted string IP literal syntax', latency_ms: 96,
+          results: [
+            { text: 'Local part: atom or quoted-string. Quoted allows spaces, special chars within double quotes.', score: 0.95 },
+            { text: 'Domain: hostname or IP literal [n.n.n.n]. TLD must be 2+ alpha chars.', score: 0.93 },
+            { text: 'No consecutive dots in local or domain part. No leading/trailing dot.', score: 0.91 },
+          ],
+        });
+      }},
+      { delay: 1200, fn: () => {
+        TOOLS.log_generation({ agent: 'coder', prompt_tokens: 2800, completion_tokens: 780, model: 'claude-sonnet-4-20250514', latency_ms: 2600, stop_reason: 'end_turn' });
+      }},
+      { delay: 600, fn: () => {
+        TOOLS.log_tool_call({ agent: 'coder', tool_name: 'code_execute', input: 'RFC-5321 test suite — 120 vectors', output: '118/120 pass (2 obscure IPv6 edge cases)', latency_ms: 340 });
+        TOOLS.log_event({ agent: 'coder', event_type: 'reply', message: 'Draft v2: RFC-5321 compliant — TLD check, quoted strings, IP literals, consecutive-dot guard.' });
+        TOOLS.set_memory({ key: 'code', value: 'RFC5321_RE = re.compile(r\'...\')  # 118/120 RFC vectors pass' });
+        TOOLS.trace_step({ from_agent: 'coder', to_agent: 'orchestrator', label: 'v2', arrow_type: 'result' });
+        TOOLS.set_agent_state({ agent_id: 'coder', status: 'done' });
+      }},
+      // Critic v2 review — pass
+      { delay: 500, fn: () => {
+        TOOLS.trace_step({ from_agent: 'orchestrator', to_agent: 'critic', label: 'review v2', arrow_type: 'msg' });
+        TOOLS.set_agent_state({ agent_id: 'critic', status: 'running' });
+      }},
+      { delay: 400, fn: () => {
+        TOOLS.log_tool_call({ agent: 'critic', tool_name: 'regex_test_suite', input: 'RFC-5321 test vectors (120 cases)', output: '118/120 pass — 2 obscure IPv6 literals; acceptable for prod use', latency_ms: 215 });
+      }},
+      { delay: 700, fn: () => {
+        TOOLS.log_generation({ agent: 'critic', prompt_tokens: 1600, completion_tokens: 320, model: 'claude-haiku-4-5-20251001', latency_ms: 860, stop_reason: 'end_turn' });
+        TOOLS.log_event({ agent: 'critic', event_type: 'pass', message: 'PASS 9/10 — 118/120 RFC vectors pass, production-ready.' });
+        TOOLS.trace_step({ from_agent: 'critic', to_agent: 'orchestrator', label: 'pass 9/10', arrow_type: 'result' });
+        TOOLS.set_agent_state({ agent_id: 'critic', status: 'done' });
+      }},
+      { delay: 400, fn: () => {
+        TOOLS.log_event({ agent: 'orchestrator', event_type: 'done', message: 'Complete after 1 retry — 1 retry, 20 steps' });
+        TOOLS.set_agent_state({ agent_id: 'orchestrator', status: 'done' });
+        TOOLS.finish_run({ status: 'done' });
+      }},
+    ],
+  },
+
+  memory_overflow: {
+    goal: 'Summarise 3 ML papers and synthesise into a report',
+    steps: [
+      { delay: 0, fn: () => {
+        TOOLS.register_agent({ id: 'orchestrator', label: 'Orchestrator', role: 'orchestrator', model: 'claude-sonnet-4-20250514', token_budget: 16384 });
+        TOOLS.register_agent({ id: 'researcher',   label: 'Researcher',   role: 'researcher',   model: 'claude-haiku-4-5-20251001', reports_to: 'orchestrator', token_budget: 8192 });
+        TOOLS.register_agent({ id: 'synthesiser',  label: 'Synthesiser',  role: 'synthesiser',  model: 'claude-sonnet-4-20250514',  reports_to: 'orchestrator', token_budget: 8192 });
+        TOOLS.register_agent({ id: 'critic',       label: 'Critic',       role: 'critic',       model: 'claude-haiku-4-5-20251001', reports_to: 'orchestrator', token_budget: 4096 });
+      }},
+      { delay: 700, fn: () => {
+        TOOLS.set_goal({ goal: SCENARIOS.memory_overflow.goal });
+        TOOLS.set_agent_state({ agent_id: 'orchestrator', status: 'running' });
+        TOOLS.log_generation({ agent: 'orchestrator', prompt_tokens: 260, completion_tokens: 88, model: 'claude-sonnet-4-20250514', latency_ms: 600 });
+        TOOLS.log_event({ agent: 'orchestrator', event_type: 'start', message: 'Planning 3-paper synthesis…' });
+      }},
+      { delay: 900, fn: () => {
+        TOOLS.set_plan({ tasks: [{ agent: 'researcher', task: 'Summarise paper A — scaling laws', depends_on: [] }, { agent: 'researcher', task: 'Summarise paper B — MoE routing', depends_on: [] }, { agent: 'researcher', task: 'Summarise paper C — RLHF hacking', depends_on: [] }, { agent: 'synthesiser', task: 'Synthesise into report', depends_on: [0,1,2] }] });
+        TOOLS.trace_step({ from_agent: 'orchestrator', to_agent: 'researcher', label: 'paper A', arrow_type: 'msg' });
+        TOOLS.set_agent_state({ agent_id: 'researcher', status: 'running' });
+      }},
+      // Paper A
+      { delay: 400, fn: () => {
+        TOOLS.log_tool_call({ agent: 'researcher', tool_name: 'pdf_extract', input: 'scaling_laws_2020.pdf', output: '18,400 tokens extracted — 42 pages', latency_ms: 480 });
+        TOOLS.log_embedding({ agent: 'researcher', text: 'neural scaling laws loss compute data parameters', model: 'text-embedding-3-small', dims: 1536, latency_ms: 55 });
+      }},
+      { delay: 600, fn: () => {
+        TOOLS.log_retrieval({ agent: 'researcher', query: 'key findings scaling laws compute-optimal training', latency_ms: 104,
+          results: [
+            { text: 'Loss scales as power law with N (params), D (data), C (compute): L ∝ N^0.076.', score: 0.97 },
+            { text: 'Compute-optimal: scale params and data proportionally. Chinchilla law.', score: 0.94 },
+            { text: 'Irreducible loss ≈ 1.69 nats; emergent capabilities at scale thresholds.', score: 0.88 },
+          ],
+        });
+        TOOLS.log_generation({ agent: 'researcher', prompt_tokens: 2400, completion_tokens: 520, model: 'claude-haiku-4-5-20251001', latency_ms: 1600, stop_reason: 'end_turn' });
+        TOOLS.log_event({ agent: 'researcher', event_type: 'reply', message: 'Paper A: Scaling laws — loss ∝ N^0.076. Compute-optimal: equal param/data scaling.' });
+        TOOLS.set_memory({ key: 'paper_a', value: 'Scaling laws: loss ∝ N^0.076, Chinchilla-optimal' });
+        TOOLS.trace_step({ from_agent: 'researcher', to_agent: 'orchestrator', label: 'A done', arrow_type: 'result' });
+      }},
+      // Paper B
+      { delay: 400, fn: () => {
+        TOOLS.trace_step({ from_agent: 'orchestrator', to_agent: 'researcher', label: 'paper B', arrow_type: 'msg' });
+        TOOLS.log_tool_call({ agent: 'researcher', tool_name: 'pdf_extract', input: 'moe_routing_2023.pdf', output: '22,100 tokens extracted — 51 pages', latency_ms: 520 });
+        TOOLS.log_embedding({ agent: 'researcher', text: 'mixture of experts routing sparse transformer efficiency', model: 'text-embedding-3-small', dims: 1536, latency_ms: 53 });
+      }},
+      { delay: 600, fn: () => {
+        TOOLS.log_retrieval({ agent: 'researcher', query: 'MoE routing top-k expert selection load balancing', latency_ms: 98,
+          results: [
+            { text: 'Top-2 routing: each token sent to 2 of N experts. 60% active-param reduction vs dense.', score: 0.96 },
+            { text: 'Load balancing loss prevents expert collapse. Jitter noise aids exploration.', score: 0.92 },
+            { text: 'Switch Transformer: top-1 routing, simpler but prone to collapse without aux loss.', score: 0.87 },
+          ],
+        });
+        TOOLS.log_generation({ agent: 'researcher', prompt_tokens: 2800, completion_tokens: 490, model: 'claude-haiku-4-5-20251001', latency_ms: 1500, stop_reason: 'end_turn' });
+        TOOLS.log_event({ agent: 'researcher', event_type: 'reply', message: 'Paper B: MoE top-2 routing, 60% active-param reduction. Load-balance aux loss prevents collapse.' });
+        TOOLS.set_memory({ key: 'paper_b', value: 'MoE: top-2 routing, 60% reduction, aux load-balance loss' });
+        TOOLS.trace_step({ from_agent: 'researcher', to_agent: 'orchestrator', label: 'B done', arrow_type: 'result' });
+      }},
+      // Paper C — triggers memory pressure
+      { delay: 400, fn: () => {
+        TOOLS.trace_step({ from_agent: 'orchestrator', to_agent: 'researcher', label: 'paper C', arrow_type: 'msg' });
+        TOOLS.log_tool_call({ agent: 'researcher', tool_name: 'pdf_extract', input: 'rlhf_reward_hacking_2024.pdf', output: '31,200 tokens extracted — 68 pages', latency_ms: 710 });
+        TOOLS.log_embedding({ agent: 'researcher', text: 'RLHF reward hacking overoptimisation KL penalty', model: 'text-embedding-3-small', dims: 1536, latency_ms: 58 });
+      }},
+      { delay: 600, fn: () => {
+        TOOLS.log_retrieval({ agent: 'researcher', query: 'reward hacking frequency mitigation strategies RLHF', latency_ms: 112,
+          results: [
+            { text: 'Reward hacking observed in 34% of runs beyond 3000 RL steps. KL alone insufficient.', score: 0.95 },
+            { text: 'Constitutional AI + process reward models reduce hacking to <8%.', score: 0.91 },
+            { text: 'Ensemble reward models provide more robust signal than single RM.', score: 0.88 },
+          ],
+        });
+        TOOLS.log_generation({ agent: 'researcher', prompt_tokens: 3200, completion_tokens: 560, model: 'claude-haiku-4-5-20251001', latency_ms: 1800, stop_reason: 'end_turn' });
+        TOOLS.log_event({ agent: 'researcher', event_type: 'reply', message: 'Paper C: RLHF reward hacking in 34% of runs. KL penalty alone insufficient; ensemble RMs help.' });
+        TOOLS.set_memory({ key: 'paper_c', value: 'RLHF: reward hacking 34%, use ensemble RMs + CAI' });
+        TOOLS.trace_step({ from_agent: 'researcher', to_agent: 'orchestrator', label: 'C done', arrow_type: 'result' });
+        TOOLS.set_agent_state({ agent_id: 'researcher', status: 'done' });
+      }},
+      // Synthesiser — context overflow
+      { delay: 600, fn: () => {
+        TOOLS.trace_step({ from_agent: 'orchestrator', to_agent: 'synthesiser', label: 'synthesise', arrow_type: 'msg' });
+        TOOLS.set_agent_state({ agent_id: 'synthesiser', status: 'running' });
+      }},
+      { delay: 400, fn: () => {
+        TOOLS.log_embedding({ agent: 'synthesiser', text: 'scaling laws MoE routing RLHF reward hacking synthesis', model: 'text-embedding-3-small', dims: 1536, latency_ms: 62 });
+        TOOLS.log_tool_call({ agent: 'synthesiser', tool_name: 'context_count', input: 'papers A+B+C combined tokens', output: '7,840 / 8,192 tokens used (95.7%) — paper C will be truncated', latency_ms: 12 });
+        TOOLS.log_event({ agent: 'synthesiser', event_type: 'warn', message: 'WARNING: context at 95.7% — paper C (RLHF) will be truncated to fit budget.' });
+      }},
+      { delay: 1200, fn: () => {
+        TOOLS.log_generation({ agent: 'synthesiser', prompt_tokens: 7840, completion_tokens: 980, model: 'claude-sonnet-4-20250514', latency_ms: 3200, stop_reason: 'max_tokens' });
+        TOOLS.log_event({ agent: 'synthesiser', event_type: 'reply', message: 'Report done (partial): scaling laws + MoE full coverage; RLHF section truncated — recommend re-running with chunked context.' });
+        TOOLS.set_memory({ key: 'output', value: 'Report: scaling (full) + MoE (full) + RLHF (truncated)' });
+        TOOLS.trace_step({ from_agent: 'synthesiser', to_agent: 'orchestrator', label: 'report', arrow_type: 'result' });
+        TOOLS.set_agent_state({ agent_id: 'synthesiser', status: 'done' });
+      }},
+      { delay: 400, fn: () => {
+        TOOLS.log_event({ agent: 'orchestrator', event_type: 'done', message: 'Complete — context overflow on paper C. Recommend chunked summarisation for large doc sets.' });
+        TOOLS.set_agent_state({ agent_id: 'orchestrator', status: 'done' });
+        TOOLS.finish_run({ status: 'done' });
+      }},
+    ],
+  },
+};
+
+function runScenario(name) {
+  const s = SCENARIOS[name];
+  if (!s) return false;
+  const clients = state.clients;
+  state = fresh();
+  state.clients = clients;
+  broadcast('reset', {});
+  let cum = 0;
+  s.steps.forEach(step => { cum += step.delay; setTimeout(() => { try { step.fn(); } catch (e) { console.error(e); } }, cum); });
+  return true;
+}
+
+// ── Dashboard HTML ─────────────────────────────────────────────────────────────
+const HTML = fs.readFileSync(path.join(__dirname, 'dashboard.html'), 'utf8');
+
+// ── HTTP helpers ──────────────────────────────────────────────────────────────
+const CORS = {
+  'Access-Control-Allow-Origin':  '*',
+  'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+  'Access-Control-Allow-Headers': 'Content-Type',
+};
+function body(req, cb) { let d = ''; req.on('data', c => d += c); req.on('end', () => cb(d)); }
+function json(res, data, status = 200) {
+  res.writeHead(status, { ...CORS, 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(data));
+}
+
+// ── HTTP server ────────────────────────────────────────────────────────────────
+const server = http.createServer((req, res) => {
+  if (req.method === 'OPTIONS') { res.writeHead(204, CORS); res.end(); return; }
+
+  // Dashboard UI
+  if (req.method === 'GET' && (req.url === '/' || req.url === '/index.html')) {
+    res.writeHead(200, { 'Content-Type': 'text/html' });
+    res.end(HTML);
+    return;
+  }
+
+  // SSE stream
+  if (req.method === 'GET' && req.url === '/events') {
+    res.writeHead(200, { ...CORS, 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', 'Connection': 'keep-alive' });
+    res.write(`data: ${JSON.stringify({ type: 'init', payload: { state: snapshot() }, ts: Date.now() })}\n\n`);
+    state.clients.push(res);
+    req.on('close', () => { state.clients = state.clients.filter(c => c !== res); });
+    return;
+  }
+
+  // Current state snapshot
+  if (req.method === 'GET' && req.url === '/state') {
+    json(res, snapshot()); return;
+  }
+
+  // Tool call
+  if (req.method === 'POST' && req.url === '/tool') {
+    body(req, data => {
+      try {
+        const { tool, args } = JSON.parse(data);
+        const fn = TOOLS[tool];
+        json(res, fn ? fn(args || {}) : { error: `Unknown tool: ${tool}` });
+      } catch (e) { json(res, { error: e.message }, 400); }
+    }); return;
+  }
+
+  // Run a demo scenario
+  if (req.method === 'POST' && req.url === '/emulate') {
+    body(req, data => {
+      const { scenario } = JSON.parse(data || '{}');
+      const ok = runScenario(scenario || 'research_code');
+      json(res, { ok, scenario }, ok ? 200 : 400);
+    }); return;
+  }
+
+  // Reset state
+  if (req.method === 'POST' && req.url === '/reset') {
+    const clients = state.clients;
+    state = fresh(); state.clients = clients;
+    broadcast('reset', {});
+    json(res, { ok: true }); return;
+  }
+
+  json(res, { error: 'Not found' }, 404);
+});
+
+server.listen(PORT, () => {
+  console.log(`\n  agent-visibility\n`);
+  console.log(`  Dashboard  →  http://localhost:${PORT}`);
+  console.log(`  Tool POST  →  http://localhost:${PORT}/tool`);
+  console.log(`  Ctrl+C to stop\n`);
+});