agent-dashboard-cf

name	agent-dashboard-cf
description	"{{AGENT_NAME}} 에이전트 상태를 Cloudflare Workers + KV로 호스팅. 4-tab insight-driven dashboard (Overview/System/Brain/Usage) + live agent activity + 23 collectors"

Agent Dashboard (Cloudflare Workers)

4-tab insight-driven dashboard. Load this skill when the user asks about the agent dashboard — adding features, fixing display issues, debugging pusher collectors, or expanding tab content.

Architecture

로컬 Mac (cron: 5min push)           Cloudflare Worker
─────────────────────────────        ──────────────────
pusher (agent_dashboard_push.py)     src/index.js
  ├─ 23 collectors                    ├─ POST /api/push → KV(latest)
  ├─ system/launchd/kanban/          ├─ GET  /api/status ← KV(latest)
  ├─ cron/network/vault/graph/       └─ GET  / (static assets)
  ├─ errors/usage/models/brain/
  ├─ today/timeline/live/misc/
  └─ session_details/provider/weekly → JSON → KV

Tab-Based Layout (Final)

HEALTH BANNER (green/yellow/red, issue count)
ACTIVITY ROW (Live dot + session IDs + elapsed + event count)

[Overview] [System] [Brain] [Usage]

Overview — 4 Hero cards (click→details) + Vault Graph (square, 1:1) + Kanban + Cron
System   — 4 Hero cards + Services(PID) + Network(Ports) + Vault(layers) + Misc
Brain    — 4 Hero cards + Models table + Skills categories + Providers + Gateway
Usage    — 4 Hero cards + 7-Day Trend chart + Hourly chart + Events + Sessions + Errors

Design Principles

1. Insight-first, not data-first. Every card answers "what should I know?"
2. Tab-based depth. >15 sections → tabs. Single page = summary only.
3. Live activity > static metrics. The live event stream from agent.log is the single biggest UX win.
4. 15s full refresh. Gentle/DOM-preserving updates add complexity for marginal benefit.
5. Error grouping. Group by message prefix, show count. Never repeat the same error 8 times.

Key Implementation Patterns

HTML Structure

<div id="status" class="loading">Connecting...</div>
<div id="content">
  <div class="ar" id="activityRow"></div>
  <div class="tabs">...</div>
  <div class="page" id="p-overview">...</div>
  <div class="page" id="p-system">...</div>
  ...
</div>

JS Pattern (avoid scoping bugs)

var _data = null;           // global data cache
function $(id){ return document.getElementById(id); }

async function load(){
  try{
    var r = await fetch('/api/status');
    var d = await r.json();
    _data = d;
    $('status').innerHTML = 'Connected';
    $('content').classList.add('show');
    renderAll();
    setTimeout(load, 15000);
  }catch(e){
    $('status').innerHTML = '❗ ' + esc(e.message);
    $('status').className = 'err';
    setTimeout(load, 5000);
  }
}

function renderAll(){ renderActivity(_data); renderOverview(_data); ... }

CRITICAL: Each render function resolves its own DOM elements via $(). Never pass DOM references between functions — JS scoping will bite you. The bug: render() tried to use dash (declared in load() scope). Fix: each render function calls $('dashboard') itself. The safest pattern: all render functions declare function renderX(d){} and read d from the parameter (passed via renderAll calling with _data).

Session Regex Pattern

# CORRECT: 20 + YYMMDD (6 digits, not 8!) + _ + HHMMSS (6 digits) + _ + hex
r'\[(20[0-9]{6}_[0-9]{6}_[a-f0-9]+)\]'
# Example: [20260615_152532_1c7ad7]
#          20 + 260615 (6) + _ + 152532 (6) + _ + 1c7ad7 (hex)

20260615 = 20 + 260615 (6 digits). Do NOT use [0-9]{8} — that would require 2 digits after '20' followed by 8 more, which doesn't match YYYYMMDD dates.

OpenRouter in Provider Display

When the user has stopped using OpenRouter (removed key from .env), previous log lines still record provider=openrouter. Filter it in the pusher:

if p == 'openrouter': continue

Multi-Session Display

The activity row must show ALL active sessions, not just the most recent:

// HTML: flex-wrap to wrap on overflow, no overflow:hidden
.ar .ars { display:flex; gap:6px; flex-wrap:wrap; font-family:monospace; font-size:9px; }

// JS: map sessions to spans, first = active (green + bold)
if(l.sessions&&l.sessions.length) ses = '<div class="ars">' +
  l.sessions.map(function(s,i){return '<span'+(i===0?' class="a"':'')+'>'+
    esc(s.slice(-16))+'</span>'}).join('') + '</div>';

// Hero card detail readability
.hcd { font-size:12px; padding:8px 10px; line-height:1.4; }
.hcd td { padding:4px 6px; }

Square Graph Container

Force-directed graphs are circular → use aspect-ratio: 1/1:

#graph { padding:10px; aspect-ratio:1/1; max-height:420px; width:100%; }

vis-network physics for all-node visibility:

physics:{
  solver:'forceAtlas2Based',
  forceAtlas2Based:{
    gravitationalConstant:-50,  // tighter cluster
    centralGravity:0.01,
    springLength:150,           // node spacing
    springConstant:0.04,
    damping:0.5
  },
  stabilization:{iterations:150}
},
layout:{improvedLayout:true}

Error Display (Debug Infinite Loading)

// BEFORE (silent failure, infinite spinner):
try{ ... }catch(e){}

// AFTER (visible error, retry):
try{ ... }catch(e){
  $('status').innerHTML = '❗ ' + esc(e.message);
  $('status').className = 'err';
  setTimeout(load, 5000);
}

Common causes of "Connecting..." stuck:

1. vis-network CDN fails → vis undefined → new vis.Network() throws → silent catch → spinner forever. Fix: check CDN URL, add error display.
2. JS syntax error → script fails to execute at all → load() never called. Fix: test locally before deploy.
3. Fetch blocked by CORS/WAF → response not JSON → r.json() throws. Fix: check Worker response headers.

Graph Flickering Fix

vis-network re-render on every refresh causes visible flickering. Fix: render once on first load only.

var _firstGraph = true;

function renderAll() {
  // ... other renders called every refresh ...
  if(_firstGraph) { renderGraph(d.graph); _firstGraph = false; }
}

This applies to /api/status fetches. The _firstGraph flag survives because it's declared at module scope.

Overview Layout

The Overview page uses a side-by-side layout: 2x2 hero cards (left) + square graph (right).

<div class="ov-top">
  <div class="ov-hero" id="ovHero"></div>
  <div class="ov-graph">
    <div class="lbl">&#128200; Vault Graph</div>
    <div id="ovGraph"></div>
  </div>
</div>

.ov-top { display:grid; grid-template-columns:1fr 1fr; gap:6px; }
.ov-hero { display:grid; grid-template-columns:1fr 1fr; gap:6px; }
#ovGraph { width:100%; aspect-ratio:1/1; max-height:350px; }

This avoids a full-width graph below the cards — cleaner visual balance.

Hero Cards: Always-Visible Details

Hero cards used to hide details behind accordion click. Final design: details always visible.

.hcd { display:block; /* not display:none */ }

Remove the click-toggle for hero cards entirely:

// Before: hero cards had toggle
document.addEventListener('click', function(e) {
  var h = e.target.closest('.hc'); if(h) { h.classList.toggle('open'); return; }
  var p = e.target.closest('.pn'); if(p) { p.classList.toggle('open'); }
});

// After: only panels toggle, hero cards are flat
document.addEventListener('click', function(e) {
  var p = e.target.closest('.pn'); if(p) { p.classList.toggle('open'); }
});

Auto-Refresh

Final decision: 15s full page refresh. Rationale:

• Tab-based layout keeps each page's content light
• Full update ensures data consistency (no partial stale state)
• Simpler code vs gentle-DOM-update (90s with value-only changes was too complex for marginal benefit)
• Error retry at 5s interval

Deploy Commands

# Initial
cd ~/Sites/agent-dashboard
wrangler kv namespace create AGENT_DASHBOARD
wrangler deploy

# Update (both worker + static assets)
cd ~/Sites/agent-dashboard && wrangler deploy

# After deploy, push initial data
python3 ~/.{{AGENT_NAME_LOWER}}/scripts/agent_dashboard_push.py

Pusher Script

Located at ~/.{{AGENT_NAME_LOWER}}/scripts/agent_dashboard_push.py. Runs every 5min via no-agent cron.

23 Collectors

Collector	Source	Returns
collect_system()	uptime/df/vm_stat/sw_vers/uname	uptime, load, disk, memory, os/kernel/python/opencode versions
collect_launchd()	launchctl list	ai.{{AGENT_NAME_LOWER}}.* services with PID/exit_code
collect_kanban()	kanban.db direct read	tasks with status/assignee
collect_cron()	jobs.json direct read	active/errors/paused jobs
collect_network()	lsof -iTCP	known services with listening/down
collect_vault()	du -sh P* dirs	P-layer sizes
collect_recent_errors()	errors.log + agent.log	top 5 error types grouped by message prefix, with count
collect_git_status()	git status --porcelain	uncommitted/unpushed counts
collect_brew_updates()	brew outdated	count
collect_docker()	docker ps	container names + status
collect_thermal()	pmset -g therm/batt	thermal/battery state
collect_graph()	glob skills + P-layer .md, extract [[wikilinks]]	nodes + edges for vis-network
collect_daily_usage()	grep agent.log by date	hours5, today, yesterday, week, month, daily_avg, change_pct
collect_model_usage()	agent.log regex (model= / in= / out= / total=)	per-model calls, tokens, providers
collect_brain_health()	glob skills/ SKILL.md + *.neuron + P2/memories	skills, neurons, memories, total
collect_today_summary()	agent.log grep today + session extraction	log_lines, sessions, tool_calls
collect_timeline()	cron last_run + error times	merged chronological events
collect_live_activity()	agent.log tail 80 lines	last 15 events with icon/type/text/time + multiple sessions
collect_cpu_details()	sysctl machdep/hw/uname	brand, cores, arch, total_ram
collect_skill_categories()	glob skills/**/SKILL.md by category dir	per-category counts
collect_hourly_usage()	24 greps agent.log "YYYY-MM-DD HH:"	24-hour bar chart data
collect_provider_usage()	agent.log regex provider=	provider call counts
collect_weekly_trend()	7 greps agent.log by date	per-day counts

Cron/PATH Issue

When running as no-agent cron script, PATH may not include required tool locations:

_EXTRA_PATH = os.pathsep.join([
    os.path.join(HOME, ".local", "bin"),
    "/opt/homebrew/bin", "/usr/local/bin",
])
# Pass to subprocess.run(env={**_EXTRA_ENV, **os.environ})

Cloudflare WAF Block

Python urllib default UA blocked → set Mozilla UA:

req.headers["User-Agent"] = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ..."

Regex: Session ID Pattern

# CORRECT: YYMMDD (6 digits after 20)
r'\[(20[0-9]{6}_[0-9]{6}_[a-f0-9]+)\]'
# Example: [20260615_152532_1c7ad7]
#          20 + 260615 (6 digits) + _ + 152532 (6 digits) + _ + 1c7ad7 (hex)

Common Issues

HTTP 400: Model Not Found

provider=openrouter model=opencode-go/deepseek-v4-flash → HTTP 400
provider=opencode-go model=deepseek-v4-flash → OK

Fix: Remove OPENROUTER_API_KEY from ~/.{{AGENT_NAME_LOWER}}/.env. Session restore picks up openrouter as provider but model name opencode-go/... doesn't exist there.

Gateway Watchdog — No PID Expected

ai.{{AGENT_NAME_LOWER}}.gateway-watchdog is OnDemand=true. Actual watchdog is the cron job running every 5min. Pusher checks cron job status, not launchd PID.

Health Warning Count Overlap

Warning counter = disk (>65%) + cron errors (len) + recent errors. These can overlap if cron errors and recent_errors reference the same failure. Not a bug — the user sees a consistent count.

7-Day Trend: date -v on macOS

macOS date -v is different from GNU date -d. Python pusher uses time.strftime for cross-platform compatibility.

Git Vault Cleanup Workflow

When Git shows 200+ dirty files:

1. Add .gitignore: *.lock, *_cache.json, .bak., wordpress/, lsp/
2. git add -A && git commit -m "..."
3. gh api -X DELETE repos/.../branches/main/protection (disable branch protection)
4. git push --force <remote> main
5. Re-enable protection: gh api -X PUT ... -H "Accept: application/vnd.github+json" --input <(cat <<'EOF' ...)
6. git rm --cached -r <unwanted>/ for dirs that shouldn't be tracked