@terminals-tech/agent-zero 1.0.0

package/dist/rail/userSessionManager.js

@@ -0,0 +1,87 @@
+/**
+ * User Session Manager
+ * Maps authenticated Supabase users to rail agent identities.
+ */
+import { createHmac, randomBytes } from 'crypto';
+const MAX_SESSIONS_PER_USER = 3;
+export class UserSessionManager {
+    sessions = new Map(); // sessionToken -> session
+    userSessions = new Map(); // userId -> set of sessionTokens
+    sessionSecret;
+    constructor() {
+        this.sessionSecret = process.env['RAIL_SESSION_SECRET'] || randomBytes(32).toString('hex');
+    }
+    createSession(userId, email) {
+        // Check concurrent session limit
+        const existing = this.userSessions.get(userId);
+        if (existing && existing.size >= MAX_SESSIONS_PER_USER) {
+            // Evict oldest session
+            let oldest = null;
+            for (const token of existing) {
+                const s = this.sessions.get(token);
+                if (s && (!oldest || s.connectedAt < oldest.connectedAt))
+                    oldest = s;
+            }
+            if (oldest)
+                this.endSessionByToken(oldest.sessionToken);
+        }
+        const agentId = `user:${userId}`;
+        const sessionToken = this.generateSessionToken(userId);
+        const now = Date.now();
+        const session = {
+            userId,
+            agentId,
+            email,
+            sessionToken,
+            connectedAt: now,
+            lastActive: now,
+        };
+        this.sessions.set(sessionToken, session);
+        if (!this.userSessions.has(userId))
+            this.userSessions.set(userId, new Set());
+        this.userSessions.get(userId).add(sessionToken);
+        return { agentId, sessionToken };
+    }
+    validateSession(sessionToken) {
+        const session = this.sessions.get(sessionToken);
+        if (!session)
+            return null;
+        session.lastActive = Date.now();
+        return session;
+    }
+    endSession(userId) {
+        const tokens = this.userSessions.get(userId);
+        if (!tokens)
+            return;
+        for (const token of tokens) {
+            this.sessions.delete(token);
+        }
+        this.userSessions.delete(userId);
+    }
+    endSessionByToken(token) {
+        const session = this.sessions.get(token);
+        if (!session)
+            return;
+        this.sessions.delete(token);
+        const userTokens = this.userSessions.get(session.userId);
+        if (userTokens) {
+            userTokens.delete(token);
+            if (userTokens.size === 0)
+                this.userSessions.delete(session.userId);
+        }
+    }
+    getActiveSessions() {
+        return Array.from(this.sessions.values());
+    }
+    getActiveCount() {
+        return this.sessions.size;
+    }
+    generateSessionToken(userId) {
+        const nonce = randomBytes(16).toString('hex');
+        const sig = createHmac('sha256', this.sessionSecret)
+            .update(`${userId}:${nonce}:${Date.now()}`)
+            .digest('hex');
+        return `rs_${nonce}${sig.slice(0, 16)}`;
+    }
+}
+//# sourceMappingURL=userSessionManager.js.map

package/dist/rail/userSessionManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"userSessionManager.js","sourceRoot":"","sources":["../../src/rail/userSessionManager.ts"],"names":[],"mappings":"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"}

package/dist/rail/wsServer.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Resonance Rail WebSocket Server
+ *
+ * Wraps ResonanceRailServer with real WebSocket I/O via the `ws` library.
+ * - On connection: parse join message, call server.handleJoin()
+ * - Maps clientId -> WebSocket for message routing
+ * - Heartbeat ping/pong every 10s
+ * - HTTP health endpoint at GET /health
+ */
+import { ResonanceRailServer } from './server.js';
+export interface WsServerConfig {
+    port: number;
+    heartbeatIntervalMs: number;
+    staleTimeoutMs: number;
+}
+export declare class RailWebSocketServer {
+    private config;
+    private rail;
+    private httpServer;
+    private wss;
+    private sockets;
+    private heartbeatTimer?;
+    private rateLimiter;
+    private persistence?;
+    private metadataBroadcaster?;
+    private userSessionManager;
+    constructor(config: WsServerConfig);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private handleConnection;
+    private heartbeat;
+    private sendTo;
+    private broadcastToAll;
+    private handleHttp;
+    getRail(): ResonanceRailServer;
+    getConnectedCount(): number;
+}
+export declare function createRailWebSocketServer(config?: Partial<WsServerConfig>): RailWebSocketServer;
+//# sourceMappingURL=wsServer.d.ts.map

package/dist/rail/wsServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wsServer.d.ts","sourceRoot":"","sources":["../../src/rail/wsServer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,mBAAmB,EAAqC,MAAM,aAAa,CAAC;AAcrF,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,mBAAmB,EAAE,MAAM,CAAC;IAC5B,cAAc,EAAE,MAAM,CAAC;CACxB;AAkBD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,IAAI,CAAsB;IAClC,OAAO,CAAC,UAAU,CAAkC;IACpD,OAAO,CAAC,GAAG,CAAkB;IAC7B,OAAO,CAAC,OAAO,CAAyC;IACxD,OAAO,CAAC,cAAc,CAAC,CAAiC;IACxD,OAAO,CAAC,WAAW,CAAoB;IACvC,OAAO,CAAC,WAAW,CAAC,CAAwB;IAC5C,OAAO,CAAC,mBAAmB,CAAC,CAAsB;IAClD,OAAO,CAAC,kBAAkB,CAAgD;gBAE9D,MAAM,EAAE,cAAc;IAiC5B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA0DtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA+B3B,OAAO,CAAC,gBAAgB;IAwOxB,OAAO,CAAC,SAAS;IA0BjB,OAAO,CAAC,MAAM;IAMd,OAAO,CAAC,cAAc;IAatB,OAAO,CAAC,UAAU;IA2JlB,OAAO,IAAI,mBAAmB;IAI9B,iBAAiB,IAAI,MAAM;CAG5B;AAMD,wBAAgB,yBAAyB,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,mBAAmB,CAO/F"}

package/dist/rail/wsServer.js

@@ -0,0 +1,544 @@
+/**
+ * Resonance Rail WebSocket Server
+ *
+ * Wraps ResonanceRailServer with real WebSocket I/O via the `ws` library.
+ * - On connection: parse join message, call server.handleJoin()
+ * - Maps clientId -> WebSocket for message routing
+ * - Heartbeat ping/pong every 10s
+ * - HTTP health endpoint at GET /health
+ */
+import { createServer } from 'http';
+import { WebSocketServer, WebSocket } from 'ws';
+import { ResonanceRailServer } from './server.js';
+import { ClientRateLimiter } from './clientRateLimiter.js';
+import { createRailPersistence } from './persistence.js';
+import { createMetadataBroadcaster } from './metadataBroadcaster.js';
+import { verifyUserToken } from './jwtVerifier.js';
+import { UserSessionManager } from './userSessionManager.js';
+import { AbsorptionProtocol } from '../coherence/absorption.js';
+import { RailAuthProtocol } from './authProtocol.js';
+import { railLog } from './logger.js';
+// Connection limits
+const MAX_CONNECTIONS = 200;
+const MAX_OBSERVERS = 50;
+// ============================================================================
+// WS SERVER
+// ============================================================================
+export class RailWebSocketServer {
+    config;
+    rail;
+    httpServer;
+    wss;
+    sockets = new Map();
+    heartbeatTimer;
+    rateLimiter;
+    persistence;
+    metadataBroadcaster;
+    userSessionManager = new UserSessionManager();
+    constructor(config) {
+        this.config = config;
+        const absorptionProtocol = new AbsorptionProtocol();
+        this.rail = new ResonanceRailServer(absorptionProtocol);
+        this.rateLimiter = new ClientRateLimiter();
+        this.httpServer = createServer((req, res) => {
+            this.handleHttp(req, res);
+        });
+        this.wss = new WebSocketServer({ server: this.httpServer });
+        // Wire rail broadcast events to WebSocket delivery
+        this.rail.on('message:broadcast', (message) => {
+            this.broadcastToAll(message);
+        });
+        // Wire rate limiter violations to disconnect
+        this.rateLimiter.on('violation', ({ clientId, type, count }) => {
+            railLog.warn('security', 'Rate limit violation', { clientId, type, count });
+            const tracked = this.sockets.get(clientId);
+            if (tracked) {
+                tracked.ws.close(1008, `Rate limit exceeded: ${type}`);
+                this.sockets.delete(clientId);
+                this.rateLimiter.removeClient(clientId);
+            }
+        });
+    }
+    // ==========================================================================
+    // LIFECYCLE
+    // ==========================================================================
+    async start() {
+        // Initialize persistence if data dir is available
+        const dataDir = process.env['RAIL_DATA_DIR'] || './data';
+        try {
+            this.persistence = createRailPersistence(dataDir);
+            await this.persistence.init();
+            railLog.info('rail', 'Persistence initialized', { dataDir });
+            // Restore enrollments from persistence
+            try {
+                const enrollments = await this.persistence.loadEnrollments();
+                for (const e of enrollments) {
+                    this.rail.getAuthProtocol().registerAgent(e.agent_id, e.secret_hash);
+                }
+                if (enrollments.length > 0) {
+                    railLog.info('rail', 'Restored enrollments', { count: enrollments.length });
+                }
+            }
+            catch (err) {
+                railLog.warn('rail', 'Failed to restore enrollments', { error: String(err) });
+            }
+        }
+        catch (err) {
+            railLog.warn('rail', 'Persistence unavailable', { error: String(err) });
+            this.persistence = undefined;
+        }
+        // Initialize metadata broadcaster
+        this.metadataBroadcaster = createMetadataBroadcaster(this.rail, (msg) => this.broadcastToAll(msg));
+        return new Promise((resolve) => {
+            this.wss.on('connection', (ws) => {
+                this.handleConnection(ws);
+            });
+            this.rail.start(100);
+            this.metadataBroadcaster.start();
+            // Start coherence logging
+            if (this.persistence) {
+                this.persistence.startCoherenceLogging(() => this.rail.getStats().globalCoherence, () => this.rail.getStats().connectedAgents, () => this.rail.getKuramoto().getMeanPhase());
+            }
+            this.heartbeatTimer = setInterval(() => {
+                this.heartbeat();
+            }, this.config.heartbeatIntervalMs);
+            this.httpServer.listen(this.config.port, () => {
+                resolve();
+            });
+        });
+    }
+    async stop() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = undefined;
+        }
+        this.metadataBroadcaster?.stop();
+        this.rail.stop();
+        // Close all WebSocket connections
+        for (const tracked of this.sockets.values()) {
+            tracked.ws.close(1001, 'Server shutting down');
+        }
+        this.sockets.clear();
+        await this.persistence?.close().catch(() => { });
+        return new Promise((resolve, reject) => {
+            this.wss.close(() => {
+                this.httpServer.close((err) => {
+                    if (err)
+                        reject(err);
+                    else
+                        resolve();
+                });
+            });
+        });
+    }
+    // ==========================================================================
+    // CONNECTION HANDLING
+    // ==========================================================================
+    handleConnection(ws) {
+        let tracked;
+        ws.on('message', (data) => {
+            let message;
+            try {
+                message = JSON.parse(data.toString());
+            }
+            catch {
+                ws.close(1003, 'Invalid JSON');
+                return;
+            }
+            if (!tracked) {
+                // First message must be a join
+                if (message.type !== 'join') {
+                    ws.close(1002, 'First message must be join');
+                    return;
+                }
+                const payload = message.payload;
+                const isObserver = payload?.platform === 'observer' || payload?.platform === 'moltyverse';
+                if (isObserver) {
+                    // Check observer limit
+                    const observerCount = Array.from(this.sockets.values()).filter(s => s.observer).length;
+                    if (observerCount >= MAX_OBSERVERS) {
+                        railLog.warn('rail', 'Observer limit reached', { current: observerCount, max: MAX_OBSERVERS });
+                        ws.close(1013, 'Too many observers');
+                        return;
+                    }
+                    // Observer mode: no auth required, no Kuramoto registration
+                    const observerId = `obs-${Date.now().toString(36)}`;
+                    tracked = {
+                        ws,
+                        clientId: observerId,
+                        agentId: message.agentId,
+                        alive: true,
+                        observer: true,
+                    };
+                    this.sockets.set(observerId, tracked);
+                    // Send sync with current state
+                    this.sendTo(tracked, {
+                        type: 'sync',
+                        agentId: 'server',
+                        agentName: 'Resonance Rail',
+                        payload: {
+                            clientId: observerId,
+                            coherence: this.rail.getStats().globalCoherence,
+                            agents: this.rail.getClients().map(c => ({
+                                id: c.agentId,
+                                name: c.agentName,
+                                platform: c.platform,
+                            })),
+                            observer: true,
+                        },
+                        timestamp: Date.now(),
+                    });
+                    return;
+                }
+                // Check connection limit
+                const totalConnections = this.sockets.size;
+                if (totalConnections >= MAX_CONNECTIONS) {
+                    railLog.warn('rail', 'Connection limit reached', { current: totalConnections, max: MAX_CONNECTIONS });
+                    ws.close(1013, 'Server at capacity');
+                    return;
+                }
+                // JWT auth path: browser-runtime users via Supabase
+                const joinPayload = message.payload;
+                if (joinPayload?.jwt) {
+                    const user = verifyUserToken(joinPayload.jwt);
+                    if (!user) {
+                        ws.close(1008, 'Invalid JWT');
+                        return;
+                    }
+                    const session = this.userSessionManager.createSession(user.userId, user.email);
+                    if (!session) {
+                        ws.close(1013, 'Session limit exceeded');
+                        return;
+                    }
+                    // Override agentId/name for user agents
+                    message.agentId = session.agentId;
+                    message.agentName = user.email.split('@')[0] || `user-${user.userId.slice(0, 8)}`;
+                    message.payload['platform'] = 'browser-runtime';
+                    // Skip HMAC auth — JWT is the auth
+                    const result = this.rail.handleJoin(message);
+                    if (!result) {
+                        ws.close(1002, 'Join rejected');
+                        return;
+                    }
+                    tracked = {
+                        ws,
+                        clientId: result.client.id,
+                        agentId: result.client.agentId,
+                        alive: true,
+                        observer: false,
+                    };
+                    this.sockets.set(result.client.id, tracked);
+                    this.persistence?.recordSession(result.client, 'join').catch(() => { });
+                    this.persistence?.recordEvent('user_auth', session.agentId, { email: user.email }).catch(() => { });
+                    this.sendTo(tracked, {
+                        type: 'sync',
+                        agentId: 'server',
+                        agentName: 'Resonance Rail',
+                        payload: {
+                            clientId: result.client.id,
+                            coherence: this.rail.getStats().globalCoherence,
+                            agents: this.rail.getClients().map(c => ({
+                                id: c.agentId,
+                                name: c.agentName,
+                                platform: c.platform,
+                            })),
+                            sessionToken: session.sessionToken,
+                            reconnectToken: result.reconnectToken,
+                        },
+                        timestamp: Date.now(),
+                    });
+                    return;
+                }
+                // Session token reconnect for user agents
+                if (joinPayload?.sessionToken) {
+                    const session = this.userSessionManager.validateSession(joinPayload.sessionToken);
+                    if (session) {
+                        message.agentId = session.agentId;
+                        // Fall through to normal join flow
+                    }
+                }
+                // Check join rate limit (use agentId as temp identifier)
+                if (!this.rateLimiter.checkJoin(message.agentId)) {
+                    ws.close(1008, 'Join rate limit exceeded');
+                    return;
+                }
+                const result = this.rail.handleJoin(message);
+                if (!result) {
+                    ws.close(1002, 'Join rejected');
+                    return;
+                }
+                tracked = {
+                    ws,
+                    clientId: result.client.id,
+                    agentId: result.client.agentId,
+                    alive: true,
+                    observer: false,
+                };
+                this.sockets.set(result.client.id, tracked);
+                // Persist join
+                this.persistence?.recordSession(result.client, 'join').catch(() => { });
+                // Send join acknowledgement with reconnect token
+                this.sendTo(tracked, {
+                    type: 'sync',
+                    agentId: 'server',
+                    agentName: 'Resonance Rail',
+                    payload: {
+                        clientId: result.client.id,
+                        coherence: this.rail.getStats().globalCoherence,
+                        agents: this.rail.getClients().map(c => ({
+                            id: c.agentId,
+                            name: c.agentName,
+                            platform: c.platform,
+                        })),
+                        reconnectToken: result.reconnectToken,
+                    },
+                    timestamp: Date.now(),
+                });
+                return;
+            }
+            // Observers can only receive, not send
+            if (tracked.observer) {
+                tracked.alive = true;
+                return;
+            }
+            // Rate limit check for messages
+            if (!this.rateLimiter.checkMessage(tracked.clientId)) {
+                return;
+            }
+            // Additional check for broadcast messages
+            if (message.type === 'broadcast') {
+                if (!this.rateLimiter.checkBroadcast(tracked.clientId)) {
+                    return;
+                }
+            }
+            // Subsequent messages: mark alive and forward to rail
+            tracked.alive = true;
+            this.rail.processMessage(message);
+        });
+        ws.on('pong', () => {
+            if (tracked)
+                tracked.alive = true;
+        });
+        ws.on('close', () => {
+            if (tracked) {
+                this.rail.handleLeave({
+                    type: 'leave',
+                    agentId: tracked.agentId,
+                    agentName: '',
+                    payload: {},
+                    timestamp: Date.now(),
+                });
+                this.sockets.delete(tracked.clientId);
+                this.rateLimiter.removeClient(tracked.clientId);
+            }
+        });
+        ws.on('error', () => {
+            ws.close();
+        });
+    }
+    // ==========================================================================
+    // HEARTBEAT
+    // ==========================================================================
+    heartbeat() {
+        for (const [id, tracked] of this.sockets) {
+            if (!tracked.alive) {
+                // Stale: terminate
+                tracked.ws.terminate();
+                this.sockets.delete(id);
+                this.rateLimiter.removeClient(id);
+                this.rail.handleLeave({
+                    type: 'leave',
+                    agentId: tracked.agentId,
+                    agentName: '',
+                    payload: {},
+                    timestamp: Date.now(),
+                });
+                continue;
+            }
+            tracked.alive = false;
+            tracked.ws.ping();
+        }
+    }
+    // ==========================================================================
+    // MESSAGE DELIVERY
+    // ==========================================================================
+    sendTo(tracked, message) {
+        if (tracked.ws.readyState === WebSocket.OPEN) {
+            tracked.ws.send(JSON.stringify(message));
+        }
+    }
+    broadcastToAll(message) {
+        const payload = JSON.stringify(message);
+        for (const tracked of this.sockets.values()) {
+            if (tracked.ws.readyState === WebSocket.OPEN) {
+                tracked.ws.send(payload);
+            }
+        }
+    }
+    // ==========================================================================
+    // HTTP HEALTH
+    // ==========================================================================
+    handleHttp(req, res) {
+        const url = req.url ?? '';
+        // CORS handling
+        const origin = req.headers['origin'] ?? '';
+        const allowedOrigins = [
+            /\.terminals\.tech$/,
+            /\.moltyverse\.(space|live)$/,
+            /^https?:\/\/localhost(:\d+)?$/,
+        ];
+        const isAllowed = allowedOrigins.some(re => re.test(origin));
+        if (isAllowed) {
+            res.setHeader('Access-Control-Allow-Origin', origin);
+            res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+            res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+        }
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        if (req.method === 'GET' && url === '/health') {
+            const stats = this.rail.getStats();
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                status: 'ok',
+                uptime: stats.uptimeSeconds,
+                agents: stats.connectedAgents,
+                coherence: stats.globalCoherence,
+                messages: stats.messagesProcessed,
+                observers: Array.from(this.sockets.values()).filter(s => s.observer).length,
+            }));
+            return;
+        }
+        if (req.method === 'GET' && url === '/stats') {
+            const stats = this.rail.getStats();
+            const securityStats = this.rail.getSecurityStats(3600_000);
+            const coherenceStats = this.rail.getCoherenceStats();
+            const userSessions = this.userSessionManager.getActiveCount();
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ stats, security: securityStats, coherence: coherenceStats, userSessions }));
+            return;
+        }
+        if (req.method === 'GET' && url === '/metrics') {
+            const stats = this.rail.getStats();
+            const lines = [
+                `# HELP rail_agents Connected agent count`,
+                `# TYPE rail_agents gauge`,
+                `rail_agents ${stats.connectedAgents}`,
+                `# HELP rail_coherence Global coherence order parameter`,
+                `# TYPE rail_coherence gauge`,
+                `rail_coherence ${stats.globalCoherence}`,
+                `# HELP rail_messages_total Messages processed`,
+                `# TYPE rail_messages_total counter`,
+                `rail_messages_total ${stats.messagesProcessed}`,
+                `# HELP rail_uptime_seconds Server uptime`,
+                `# TYPE rail_uptime_seconds counter`,
+                `rail_uptime_seconds ${stats.uptimeSeconds}`,
+            ];
+            res.writeHead(200, { 'Content-Type': 'text/plain' });
+            res.end(lines.join('\n') + '\n');
+            return;
+        }
+        if (req.method === 'POST' && url === '/enroll') {
+            const adminSecret = process.env['RAIL_ADMIN_SECRET'];
+            if (!adminSecret) {
+                res.writeHead(503, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Enrollment not configured' }));
+                return;
+            }
+            const authHeader = req.headers['authorization'];
+            if (authHeader !== `Bearer ${adminSecret}`) {
+                res.writeHead(401, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Unauthorized' }));
+                return;
+            }
+            let body = '';
+            req.on('data', (chunk) => { body += chunk; });
+            req.on('end', () => {
+                try {
+                    const { agentId, secret: providedSecret } = JSON.parse(body);
+                    if (!agentId) {
+                        res.writeHead(400, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: 'agentId required' }));
+                        return;
+                    }
+                    const secret = providedSecret || RailAuthProtocol.generateSecret();
+                    const serverGenerated = !providedSecret;
+                    this.rail.getAuthProtocol().registerAgent(agentId, secret);
+                    this.persistence?.saveEnrollment(agentId, secret).catch(() => { });
+                    this.persistence?.recordEvent('enroll', agentId).catch(() => { });
+                    const response = { enrolled: agentId };
+                    if (serverGenerated)
+                        response.secret = secret;
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify(response));
+                }
+                catch {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'Invalid JSON' }));
+                }
+            });
+            return;
+        }
+        if (req.method === 'GET' && url === '/agents') {
+            const clients = this.rail.getClients();
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                agents: clients.map(c => ({
+                    id: c.agentId,
+                    name: c.agentName,
+                    platform: c.platform,
+                    coherence: c.coherenceContribution,
+                })),
+                total: clients.length,
+            }));
+            return;
+        }
+        if (req.method === 'GET' && (url === '/.well-known/resonance-rail' || url === '/.well-known/resonance-rail.json')) {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                endpoint: 'wss://space.terminals.tech',
+                version: '0.2.0',
+                protocol: 'resonance-rail-v1',
+                absorption: true,
+                capabilities: ['kuramoto', 'thermodynamic-routing', 'semantic-search'],
+                enrollment: 'https://space.terminals.tech/enroll',
+                auth_methods: ['hmac-sha256', 'jwt', 'observer'],
+                join_schema: {
+                    type: 'join',
+                    agentId: 'string (required)',
+                    agentName: 'string',
+                    payload: { platform: 'string', authToken: 'object (for hmac)' },
+                },
+                heartbeat_interval_ms: 30000,
+                observer_platforms: ['moltyverse', 'observer'],
+                absorption_stages: ['observed', 'assessed', 'invited', 'connected', 'syncing', 'absorbed'],
+            }));
+            return;
+        }
+        res.writeHead(404);
+        res.end();
+    }
+    // ==========================================================================
+    // ACCESSORS
+    // ==========================================================================
+    getRail() {
+        return this.rail;
+    }
+    getConnectedCount() {
+        return this.sockets.size;
+    }
+}
+// ============================================================================
+// FACTORY
+// ============================================================================
+export function createRailWebSocketServer(config) {
+    return new RailWebSocketServer({
+        port: config?.port ?? 3100,
+        heartbeatIntervalMs: config?.heartbeatIntervalMs ?? 10_000,
+        staleTimeoutMs: config?.staleTimeoutMs ?? 30_000,
+        ...config,
+    });
+}
+//# sourceMappingURL=wsServer.js.map