agent-relay 1.5.2 → 2.0.0

package/packages/dashboard/dist/health-worker.js

@@ -0,0 +1,79 @@
+/**
+ * Health Check Worker Thread
+ *
+ * Runs a minimal HTTP server on a separate thread to handle health checks.
+ * This ensures health checks respond even when the main event loop is blocked
+ * by heavy compute tasks (builds, large file operations, etc.).
+ */
+import { parentPort, workerData } from 'node:worker_threads';
+import http from 'node:http';
+// Default stats until we receive updates from main thread
+let currentStats = {
+    uptime: 0,
+    memoryMB: 0,
+    relayConnected: false,
+    agentCount: 0,
+    status: 'healthy',
+};
+// Track when we last received stats from main thread
+let lastStatsUpdate = Date.now();
+const STATS_STALE_THRESHOLD_MS = 60_000; // 1 minute
+// Listen for stats updates from main thread
+if (parentPort) {
+    parentPort.on('message', (stats) => {
+        currentStats = stats;
+        lastStatsUpdate = Date.now();
+    });
+}
+const { port } = workerData;
+const server = http.createServer((req, res) => {
+    // Only handle /health endpoint
+    if (req.url !== '/health' && req.url !== '/') {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Not found' }));
+        return;
+    }
+    // Check if stats are stale (main thread might be blocked)
+    const statsAge = Date.now() - lastStatsUpdate;
+    const isStale = statsAge > STATS_STALE_THRESHOLD_MS;
+    // Determine status
+    let status = currentStats.status;
+    if (isStale) {
+        status = 'busy'; // Main thread is likely blocked
+    }
+    const response = {
+        status,
+        uptime: currentStats.uptime,
+        memoryMB: currentStats.memoryMB,
+        relayConnected: currentStats.relayConnected,
+        agentCount: currentStats.agentCount,
+        statsAgeMs: statsAge,
+        worker: true, // Indicates response is from worker thread
+    };
+    // Return 200 for healthy/busy, 503 for degraded
+    const statusCode = status === 'degraded' ? 503 : 200;
+    res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(response));
+});
+server.listen(port, '0.0.0.0', () => {
+    console.log(`[health-worker] Health check server listening on port ${port}`);
+    // Notify main thread we're ready
+    if (parentPort) {
+        parentPort.postMessage({ type: 'ready', port });
+    }
+});
+// Handle errors gracefully
+server.on('error', (err) => {
+    console.error('[health-worker] Server error:', err);
+    if (parentPort) {
+        parentPort.postMessage({ type: 'error', error: String(err) });
+    }
+});
+// Keep the worker alive
+process.on('uncaughtException', (err) => {
+    console.error('[health-worker] Uncaught exception:', err);
+});
+process.on('unhandledRejection', (err) => {
+    console.error('[health-worker] Unhandled rejection:', err);
+});
+//# sourceMappingURL=health-worker.js.map

package/packages/dashboard/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @agent-relay/dashboard
+ *
+ * Optional web dashboard for Agent Relay.
+ * Install separately: npm install -g @agent-relay/dashboard
+ *
+ * This package provides:
+ * - Dashboard HTTP API for agent management
+ * - WebSocket connections for real-time updates
+ * - User bridge for browser-based users
+ * - Metrics collection and reporting
+ * - Static Next.js UI for visual agent coordination
+ */
+export { startDashboard } from './server.js';
+export { UserBridge, type IRelayClient } from './user-bridge.js';
+export { computeNeedsAttention, type AttentionMessage } from './needs-attention.js';
+export { computeSystemMetrics, formatPrometheusMetrics, type AgentMetrics, type ThroughputMetrics, } from './metrics.js';
+export { HealthWorkerManager, getHealthPort, type HealthWorkerConfig, type HealthStatsProvider } from './health-worker-manager.js';
+export type { ThreadMetadata } from './types/threading.js';
+//# sourceMappingURL=index.d.ts.map

package/packages/dashboard/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * @agent-relay/dashboard
+ *
+ * Optional web dashboard for Agent Relay.
+ * Install separately: npm install -g @agent-relay/dashboard
+ *
+ * This package provides:
+ * - Dashboard HTTP API for agent management
+ * - WebSocket connections for real-time updates
+ * - User bridge for browser-based users
+ * - Metrics collection and reporting
+ * - Static Next.js UI for visual agent coordination
+ */
+export { startDashboard } from './server.js';
+export { UserBridge } from './user-bridge.js';
+export { computeNeedsAttention } from './needs-attention.js';
+export { computeSystemMetrics, formatPrometheusMetrics, } from './metrics.js';
+export { HealthWorkerManager, getHealthPort } from './health-worker-manager.js';
+//# sourceMappingURL=index.js.map

package/packages/dashboard/dist/metrics.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Metrics collection and computation for the Agent Relay dashboard.
+ * Provides real-time metrics for monitoring: throughput, agent health, error rates.
+ */
+export interface AgentMetrics {
+    name: string;
+    messagesSent: number;
+    messagesReceived: number;
+    firstSeen: string;
+    lastSeen: string;
+    isOnline: boolean;
+    uptimeSeconds: number;
+}
+export interface ThroughputMetrics {
+    messagesLastMinute: number;
+    messagesLastHour: number;
+    messagesLast24Hours: number;
+    avgMessagesPerMinute: number;
+}
+export interface SessionMetrics {
+    totalSessions: number;
+    activeSessions: number;
+    closedByAgent: number;
+    closedByDisconnect: number;
+    closedByError: number;
+    errorRate: number;
+    recentSessions: Array<{
+        id: string;
+        agentName: string;
+        startedAt: string;
+        endedAt?: string;
+        closedBy?: 'agent' | 'disconnect' | 'error';
+        messageCount: number;
+    }>;
+}
+export interface SystemMetrics {
+    totalAgents: number;
+    onlineAgents: number;
+    offlineAgents: number;
+    totalMessages: number;
+    throughput: ThroughputMetrics;
+    sessions: SessionMetrics;
+    agents: AgentMetrics[];
+    timestamp: string;
+}
+export interface PrometheusMetric {
+    name: string;
+    help: string;
+    type: 'counter' | 'gauge' | 'histogram';
+    values: Array<{
+        labels: Record<string, string>;
+        value: number;
+    }>;
+}
+/**
+ * Compute agent-level metrics from registry data
+ */
+export declare function computeAgentMetrics(agents: Array<{
+    name: string;
+    messagesSent: number;
+    messagesReceived: number;
+    firstSeen: string;
+    lastSeen: string;
+}>): AgentMetrics[];
+/**
+ * Compute throughput metrics from message history
+ */
+export declare function computeThroughputMetrics(messages: Array<{
+    timestamp: string;
+}>): ThroughputMetrics;
+/**
+ * Compute session lifecycle metrics from session history
+ */
+export declare function computeSessionMetrics(sessions: Array<{
+    id: string;
+    agentName: string;
+    startedAt: number;
+    endedAt?: number;
+    closedBy?: 'agent' | 'disconnect' | 'error';
+    messageCount: number;
+}>): SessionMetrics;
+/**
+ * Compute full system metrics
+ */
+export declare function computeSystemMetrics(agents: Array<{
+    name: string;
+    messagesSent: number;
+    messagesReceived: number;
+    firstSeen: string;
+    lastSeen: string;
+}>, messages: Array<{
+    timestamp: string;
+}>, sessions?: Array<{
+    id: string;
+    agentName: string;
+    startedAt: number;
+    endedAt?: number;
+    closedBy?: 'agent' | 'disconnect' | 'error';
+    messageCount: number;
+}>): SystemMetrics;
+/**
+ * Format metrics in Prometheus exposition format
+ */
+export declare function formatPrometheusMetrics(metrics: SystemMetrics): string;
+//# sourceMappingURL=metrics.d.ts.map

package/packages/dashboard/dist/metrics.js

@@ -0,0 +1,193 @@
+/**
+ * Metrics collection and computation for the Agent Relay dashboard.
+ * Provides real-time metrics for monitoring: throughput, agent health, error rates.
+ */
+// Consider agents offline after 30 seconds of inactivity
+// Aligns with heartbeat timeout (5s heartbeat * 6 multiplier = 30s)
+const OFFLINE_THRESHOLD_MS = 30 * 1000;
+/**
+ * Compute agent-level metrics from registry data
+ */
+export function computeAgentMetrics(agents) {
+    const now = Date.now();
+    return agents.map((agent) => {
+        const lastSeenTime = new Date(agent.lastSeen).getTime();
+        const firstSeenTime = new Date(agent.firstSeen).getTime();
+        const isOnline = now - lastSeenTime < OFFLINE_THRESHOLD_MS;
+        const uptimeSeconds = Math.floor((now - firstSeenTime) / 1000);
+        return {
+            name: agent.name,
+            messagesSent: agent.messagesSent,
+            messagesReceived: agent.messagesReceived,
+            firstSeen: agent.firstSeen,
+            lastSeen: agent.lastSeen,
+            isOnline,
+            uptimeSeconds,
+        };
+    });
+}
+/**
+ * Compute throughput metrics from message history
+ */
+export function computeThroughputMetrics(messages) {
+    const now = Date.now();
+    const oneMinuteAgo = now - 60 * 1000;
+    const oneHourAgo = now - 60 * 60 * 1000;
+    const oneDayAgo = now - 24 * 60 * 60 * 1000;
+    let lastMinute = 0;
+    let lastHour = 0;
+    let last24Hours = 0;
+    for (const msg of messages) {
+        const ts = new Date(msg.timestamp).getTime();
+        if (ts >= oneMinuteAgo)
+            lastMinute++;
+        if (ts >= oneHourAgo)
+            lastHour++;
+        if (ts >= oneDayAgo)
+            last24Hours++;
+    }
+    // Calculate average messages per minute over the last hour
+    const avgMessagesPerMinute = lastHour / 60;
+    return {
+        messagesLastMinute: lastMinute,
+        messagesLastHour: lastHour,
+        messagesLast24Hours: last24Hours,
+        avgMessagesPerMinute: Math.round(avgMessagesPerMinute * 100) / 100,
+    };
+}
+/**
+ * Compute session lifecycle metrics from session history
+ */
+export function computeSessionMetrics(sessions) {
+    let activeSessions = 0;
+    let closedByAgent = 0;
+    let closedByDisconnect = 0;
+    let closedByError = 0;
+    for (const session of sessions) {
+        if (!session.endedAt) {
+            activeSessions++;
+        }
+        else {
+            switch (session.closedBy) {
+                case 'agent':
+                    closedByAgent++;
+                    break;
+                case 'disconnect':
+                    closedByDisconnect++;
+                    break;
+                case 'error':
+                    closedByError++;
+                    break;
+                default:
+                    // Ended but no closedBy - treat as disconnect
+                    closedByDisconnect++;
+            }
+        }
+    }
+    const closedSessions = closedByAgent + closedByDisconnect + closedByError;
+    const errorRate = closedSessions > 0 ? (closedByError / closedSessions) * 100 : 0;
+    // Format recent sessions for display (most recent 10)
+    const recentSessions = sessions
+        .slice(0, 10)
+        .map((s) => ({
+        id: s.id,
+        agentName: s.agentName,
+        startedAt: new Date(s.startedAt).toISOString(),
+        endedAt: s.endedAt ? new Date(s.endedAt).toISOString() : undefined,
+        closedBy: s.closedBy,
+        messageCount: s.messageCount,
+    }));
+    return {
+        totalSessions: sessions.length,
+        activeSessions,
+        closedByAgent,
+        closedByDisconnect,
+        closedByError,
+        errorRate: Math.round(errorRate * 100) / 100,
+        recentSessions,
+    };
+}
+/**
+ * Compute full system metrics
+ */
+export function computeSystemMetrics(agents, messages, sessions = []) {
+    const agentMetrics = computeAgentMetrics(agents);
+    const throughput = computeThroughputMetrics(messages);
+    const sessionMetrics = computeSessionMetrics(sessions);
+    const onlineAgents = agentMetrics.filter((a) => a.isOnline).length;
+    const totalMessages = agents.reduce((sum, a) => sum + a.messagesSent + a.messagesReceived, 0) / 2; // Divide by 2 since each message is counted twice (sent + received)
+    return {
+        totalAgents: agents.length,
+        onlineAgents,
+        offlineAgents: agents.length - onlineAgents,
+        totalMessages: Math.round(totalMessages),
+        throughput,
+        sessions: sessionMetrics,
+        agents: agentMetrics,
+        timestamp: new Date().toISOString(),
+    };
+}
+/**
+ * Format metrics in Prometheus exposition format
+ */
+export function formatPrometheusMetrics(metrics) {
+    const lines = [];
+    // Agent counts
+    lines.push('# HELP agent_relay_agents_total Total number of registered agents');
+    lines.push('# TYPE agent_relay_agents_total gauge');
+    lines.push(`agent_relay_agents_total ${metrics.totalAgents}`);
+    lines.push('# HELP agent_relay_agents_online Number of online agents');
+    lines.push('# TYPE agent_relay_agents_online gauge');
+    lines.push(`agent_relay_agents_online ${metrics.onlineAgents}`);
+    // Message throughput
+    lines.push('# HELP agent_relay_messages_total Total messages processed');
+    lines.push('# TYPE agent_relay_messages_total counter');
+    lines.push(`agent_relay_messages_total ${metrics.totalMessages}`);
+    lines.push('# HELP agent_relay_messages_last_minute Messages in last minute');
+    lines.push('# TYPE agent_relay_messages_last_minute gauge');
+    lines.push(`agent_relay_messages_last_minute ${metrics.throughput.messagesLastMinute}`);
+    lines.push('# HELP agent_relay_messages_last_hour Messages in last hour');
+    lines.push('# TYPE agent_relay_messages_last_hour gauge');
+    lines.push(`agent_relay_messages_last_hour ${metrics.throughput.messagesLastHour}`);
+    lines.push('# HELP agent_relay_messages_avg_per_minute Average messages per minute');
+    lines.push('# TYPE agent_relay_messages_avg_per_minute gauge');
+    lines.push(`agent_relay_messages_avg_per_minute ${metrics.throughput.avgMessagesPerMinute}`);
+    // Per-agent metrics
+    lines.push('# HELP agent_relay_agent_messages_sent Messages sent by agent');
+    lines.push('# TYPE agent_relay_agent_messages_sent counter');
+    for (const agent of metrics.agents) {
+        lines.push(`agent_relay_agent_messages_sent{agent="${agent.name}"} ${agent.messagesSent}`);
+    }
+    lines.push('# HELP agent_relay_agent_messages_received Messages received by agent');
+    lines.push('# TYPE agent_relay_agent_messages_received counter');
+    for (const agent of metrics.agents) {
+        lines.push(`agent_relay_agent_messages_received{agent="${agent.name}"} ${agent.messagesReceived}`);
+    }
+    lines.push('# HELP agent_relay_agent_online Agent online status (1=online, 0=offline)');
+    lines.push('# TYPE agent_relay_agent_online gauge');
+    for (const agent of metrics.agents) {
+        lines.push(`agent_relay_agent_online{agent="${agent.name}"} ${agent.isOnline ? 1 : 0}`);
+    }
+    lines.push('# HELP agent_relay_agent_uptime_seconds Agent uptime in seconds');
+    lines.push('# TYPE agent_relay_agent_uptime_seconds gauge');
+    for (const agent of metrics.agents) {
+        lines.push(`agent_relay_agent_uptime_seconds{agent="${agent.name}"} ${agent.uptimeSeconds}`);
+    }
+    // Session lifecycle metrics
+    lines.push('# HELP agent_relay_sessions_total Total number of sessions');
+    lines.push('# TYPE agent_relay_sessions_total counter');
+    lines.push(`agent_relay_sessions_total ${metrics.sessions.totalSessions}`);
+    lines.push('# HELP agent_relay_sessions_active Number of active sessions');
+    lines.push('# TYPE agent_relay_sessions_active gauge');
+    lines.push(`agent_relay_sessions_active ${metrics.sessions.activeSessions}`);
+    lines.push('# HELP agent_relay_sessions_closed_total Sessions closed by type');
+    lines.push('# TYPE agent_relay_sessions_closed_total counter');
+    lines.push(`agent_relay_sessions_closed_total{closed_by="agent"} ${metrics.sessions.closedByAgent}`);
+    lines.push(`agent_relay_sessions_closed_total{closed_by="disconnect"} ${metrics.sessions.closedByDisconnect}`);
+    lines.push(`agent_relay_sessions_closed_total{closed_by="error"} ${metrics.sessions.closedByError}`);
+    lines.push('# HELP agent_relay_sessions_error_rate Percentage of sessions closed by error');
+    lines.push('# TYPE agent_relay_sessions_error_rate gauge');
+    lines.push(`agent_relay_sessions_error_rate ${metrics.sessions.errorRate}`);
+    return lines.join('\n') + '\n';
+}
+//# sourceMappingURL=metrics.js.map

package/packages/dashboard/dist/needs-attention.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Derive which agents currently need attention based on message history.
+ *
+ * Heuristic:
+ * - Track the most recent inbound message to an agent for each conversation key.
+ * - Conversation key is thread ID if present, otherwise the counterparty agent.
+ * - Track the most recent outbound message from the agent for the same key.
+ * - An agent needs attention if their latest inbound message for any key is newer
+ *   than their latest outbound message for that key.
+ */
+export interface AttentionMessage {
+    from: string;
+    to: string;
+    timestamp: string;
+    thread?: string;
+    /** Whether the message was sent as a broadcast (to: '*') */
+    isBroadcast?: boolean;
+}
+/**
+ * Compute which agents have pending inbound messages they haven't answered.
+ * Only considers messages within the attention window (last 30 minutes).
+ */
+export declare function computeNeedsAttention(messages: AttentionMessage[]): Set<string>;
+//# sourceMappingURL=needs-attention.d.ts.map

package/packages/dashboard/dist/needs-attention.js

@@ -0,0 +1,78 @@
+/**
+ * Derive which agents currently need attention based on message history.
+ *
+ * Heuristic:
+ * - Track the most recent inbound message to an agent for each conversation key.
+ * - Conversation key is thread ID if present, otherwise the counterparty agent.
+ * - Track the most recent outbound message from the agent for the same key.
+ * - An agent needs attention if their latest inbound message for any key is newer
+ *   than their latest outbound message for that key.
+ */
+// Only consider messages from the last 30 minutes for "needs attention"
+const ATTENTION_WINDOW_MS = 30 * 60 * 1000;
+function updateLatest(map, agent, key, ts) {
+    const agentMap = map.get(agent) ?? new Map();
+    const prev = agentMap.get(key) ?? -Infinity;
+    if (ts > prev) {
+        agentMap.set(key, ts);
+        map.set(agent, agentMap);
+    }
+}
+/**
+ * Compute which agents have pending inbound messages they haven't answered.
+ * Only considers messages within the attention window (last 30 minutes).
+ */
+export function computeNeedsAttention(messages) {
+    const latestInbound = new Map(); // agent -> (key -> ts)
+    const latestOutbound = new Map(); // agent -> (key -> ts)
+    const now = Date.now();
+    const cutoffTime = now - ATTENTION_WINDOW_MS;
+    for (const message of messages) {
+        const ts = Date.parse(message.timestamp);
+        if (Number.isNaN(ts))
+            continue;
+        // Detect broadcasts: either explicit isBroadcast flag or to === '*'
+        const isBroadcast = message.isBroadcast || message.to === '*';
+        // Inbound: messages directed to a specific agent (ignore broadcasts)
+        // Note: isBroadcast indicates the message was originally a broadcast, even though
+        // the 'to' field is set to the individual recipient for storage purposes
+        if (message.to && !isBroadcast) {
+            const inboundKey = message.thread ? `thread:${message.thread}` : `sender:${message.from}`;
+            updateLatest(latestInbound, message.to, inboundKey, ts);
+        }
+        // Outbound: track replies by thread (preferred) or by target agent
+        // Also treat broadcasts as clearing attention for all prior senders
+        if (message.from) {
+            const outboundKey = message.thread
+                ? `thread:${message.thread}`
+                : (message.to && !isBroadcast)
+                    ? `sender:${message.to}`
+                    : null;
+            if (outboundKey) {
+                updateLatest(latestOutbound, message.from, outboundKey, ts);
+            }
+            // Broadcasts clear attention: agent is actively participating
+            // Track as a "catch-all" outbound timestamp for this agent
+            if (isBroadcast) {
+                updateLatest(latestOutbound, message.from, '__broadcast__', ts);
+            }
+        }
+    }
+    const needsAttention = new Set();
+    latestInbound.forEach((keyMap, agent) => {
+        keyMap.forEach((inboundTs, key) => {
+            // Skip if inbound message is too old (outside attention window)
+            if (inboundTs < cutoffTime)
+                return;
+            const outboundTs = latestOutbound.get(agent)?.get(key) ?? -Infinity;
+            // Also check if agent sent a broadcast after the inbound message
+            const broadcastTs = latestOutbound.get(agent)?.get('__broadcast__') ?? -Infinity;
+            const latestReply = Math.max(outboundTs, broadcastTs);
+            if (inboundTs > latestReply) {
+                needsAttention.add(agent);
+            }
+        });
+    });
+    return needsAttention;
+}
+//# sourceMappingURL=needs-attention.js.map

package/packages/dashboard/dist/server.d.ts

@@ -0,0 +1,25 @@
+export interface DashboardOptions {
+    port: number;
+    dataDir: string;
+    teamDir: string;
+    dbPath?: string;
+    /** Enable agent spawning API */
+    enableSpawner?: boolean;
+    /** Project root for spawner (defaults to dataDir) */
+    projectRoot?: string;
+    /** Tmux session name for workers */
+    tmuxSession?: string;
+    /**
+     * Callback to mark an agent as spawning (before HELLO completes).
+     * Messages sent to this agent will be queued for delivery after registration.
+     */
+    onMarkSpawning?: (agentName: string) => void;
+    /**
+     * Callback to clear the spawning flag for an agent.
+     * Called when spawn fails or is cancelled.
+     */
+    onClearSpawning?: (agentName: string) => void;
+}
+export declare function startDashboard(port: number, dataDir: string, teamDir: string, dbPath?: string): Promise<number>;
+export declare function startDashboard(options: DashboardOptions): Promise<number>;
+//# sourceMappingURL=server.d.ts.map