open-agents-nexus 0.1.0

package/dist/node.js

@@ -0,0 +1,136 @@
+/**
+ * libp2p node creation and configuration
+ *
+ * Responsible for creating and configuring the libp2p node with:
+ * - Transport: TCP, WebSockets, Circuit Relay v2
+ * - Encryption: Noise
+ * - Muxer: Yamux
+ * - Discovery: mDNS, Bootstrap (when peers provided), Pubsub Peer Discovery
+ * - Services: Identify, KadDHT (/nexus/kad/1.0.0), GossipSub, Circuit Relay Server
+ *
+ * Discovery cascade (in priority order):
+ *   1. Signaling Server peers — callers must pass these in via signalingPeers
+ *   2. Public bootstrap WSS nodes — enabled by discoveryConfig.usePublicBootstrap
+ *   3. Pubsub peer discovery — all agents subscribe to NEXUS_DISCOVERY_TOPIC
+ *   4. mDNS — local-network zero-config discovery
+ *   5. Circuit Relay v2 — NAT traversal (enabled for non-light roles)
+ */
+import { createLibp2p } from 'libp2p';
+import { noise } from '@chainsafe/libp2p-noise';
+import { yamux } from '@chainsafe/libp2p-yamux';
+import { tcp } from '@libp2p/tcp';
+import { webSockets } from '@libp2p/websockets';
+import { kadDHT } from '@libp2p/kad-dht';
+import { gossipsub } from '@libp2p/gossipsub';
+import { identify } from '@libp2p/identify';
+import { bootstrap } from '@libp2p/bootstrap';
+import { mdns } from '@libp2p/mdns';
+import { ping } from '@libp2p/ping';
+import { circuitRelayTransport, circuitRelayServer } from '@libp2p/circuit-relay-v2';
+import { pubsubPeerDiscovery } from '@libp2p/pubsub-peer-discovery';
+import { msgIdFn as nexusMsgIdFn, PROTOCOLS } from './protocol/index.js';
+import { resolveDiscovery, buildBootstrapList, NEXUS_DISCOVERY_TOPIC, } from './discovery.js';
+import { createLogger } from './logger.js';
+const log = createLogger('node');
+/**
+ * Create and start a fully-configured libp2p nexus node.
+ *
+ * The node uses:
+ *   - TCP + WebSockets + Circuit Relay v2 transports
+ *   - Noise connection encryption
+ *   - Yamux stream multiplexing
+ *   - Identify service for protocol/address exchange
+ *   - KadDHT on the /nexus/kad/1.0.0 protocol (client mode for 'light' role)
+ *   - GossipSub for pub/sub messaging
+ *   - Pubsub peer discovery on the global nexus discovery topic
+ *   - mDNS for local-network peer discovery (controllable via discoveryConfig)
+ *   - Bootstrap peer discovery (when the resolved bootstrap list is non-empty)
+ *   - Circuit relay server for non-light roles (helps NAT'd peers connect)
+ *
+ * @param config         - Nexus node configuration
+ * @param privateKey     - Ed25519 private key for this node's identity
+ * @param discoveryConfig - Optional discovery cascade settings (defaults applied)
+ * @param signalingPeers - Bootstrap peers fetched from the signaling server (Level 1)
+ */
+export async function createNexusNode(config, privateKey, discoveryConfig, signalingPeers = []) {
+    // Resolve discovery settings, merging config-level fields and explicit param
+    const discovery = resolveDiscovery({
+        usePublicBootstrap: config.usePublicBootstrap,
+        enableCircuitRelay: config.enableCircuitRelay,
+        enablePubsubDiscovery: config.enablePubsubDiscovery,
+        enableMdns: config.enableMdns,
+        ...discoveryConfig,
+    });
+    // Build the combined bootstrap peer list from all sources
+    // Merge config.bootstrapPeers (operator-supplied) into signalingPeers position
+    const allSignalingPeers = [...signalingPeers, ...config.bootstrapPeers];
+    const bootstrapList = buildBootstrapList(discovery, allSignalingPeers);
+    // Build peer discovery modules
+    const peerDiscovery = [];
+    if (bootstrapList.length > 0) {
+        peerDiscovery.push(bootstrap({ list: bootstrapList }));
+    }
+    if (discovery.enableMdns) {
+        peerDiscovery.push(mdns());
+    }
+    if (discovery.enablePubsubDiscovery) {
+        peerDiscovery.push(pubsubPeerDiscovery({
+            interval: 10_000, // Re-announce every 10 seconds
+            topics: [NEXUS_DISCOVERY_TOPIC],
+            listenOnly: false,
+        }));
+    }
+    // Build transport list — always include circuit relay transport so we can
+    // both dial and receive relay-mediated connections.
+    const transports = [
+        tcp(),
+        webSockets(),
+        ...(discovery.enableCircuitRelay ? [circuitRelayTransport()] : []),
+    ];
+    // Listen addresses — add /p2p-circuit so relay-connected peers can reach us
+    const listenAddresses = [
+        ...config.listenAddresses,
+        ...(discovery.enableCircuitRelay ? ['/p2p-circuit'] : []),
+    ];
+    // Adapt our protocol-level msgIdFn to the gossipsub MsgIdFn signature.
+    // Gossipsub guarantees msg.data is always a Uint8Array for received messages.
+    function gossipMsgIdFn(msg) {
+        return nexusMsgIdFn({ data: msg.data });
+    }
+    // Build services — full/storage nodes act as circuit relay servers, helping
+    // NAT'd light nodes connect to the rest of the network.
+    const isRelayServer = discovery.enableCircuitRelay && config.role !== 'light';
+    const node = await createLibp2p({
+        privateKey,
+        addresses: {
+            listen: listenAddresses,
+        },
+        transports,
+        connectionEncrypters: [noise()],
+        streamMuxers: [yamux()],
+        peerDiscovery,
+        services: {
+            identify: identify(),
+            ping: ping(),
+            dht: kadDHT({
+                protocol: PROTOCOLS.DHT,
+                clientMode: config.role === 'light',
+            }),
+            pubsub: gossipsub({
+                emitSelf: false,
+                allowPublishToZeroTopicPeers: true,
+                msgIdFn: gossipMsgIdFn,
+            }),
+            ...(isRelayServer ? { relay: circuitRelayServer() } : {}),
+        },
+    });
+    log.info(`Node created with PeerId: ${node.peerId.toString()}`);
+    log.info(`Role: ${config.role}`);
+    log.info(`Discovery: bootstrap=${bootstrapList.length} peers, ` +
+        `mdns=${discovery.enableMdns}, ` +
+        `pubsub=${discovery.enablePubsubDiscovery}, ` +
+        `relay=${discovery.enableCircuitRelay}`);
+    log.info(`Listening on: ${node.getMultiaddrs().map((a) => a.toString()).join(', ')}`);
+    return node;
+}
+//# sourceMappingURL=node.js.map

package/dist/node.js.map

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

package/dist/protocol/index.d.ts

@@ -0,0 +1,11 @@
+import { type MessageType, type NexusMessage } from './types.js';
+export * from './types.js';
+export declare function uuidv7(): string;
+export declare function createMessage(type: MessageType, topic: string, sender: string, payload: NexusMessage['payload'], references?: string[]): NexusMessage;
+export declare function encodeMessage(msg: NexusMessage): Uint8Array;
+export declare function decodeMessage(data: Uint8Array): NexusMessage;
+export declare function msgIdFn(msg: {
+    data: Uint8Array | null;
+}): Uint8Array;
+export declare function roomTopic(roomId: string): string;
+export declare function ephemeralTopic(sessionId: string): string;

package/dist/protocol/index.js

@@ -0,0 +1,66 @@
+import { PROTOCOL_VERSION, TOPICS, } from './types.js';
+export * from './types.js';
+// UUIDv7 generation (no external dependency)
+// UUIDv7 = unix_ms (48 bits) + version (4 bits) + rand_a (12 bits) + variant (2 bits) + rand_b (62 bits)
+export function uuidv7() {
+    const now = Date.now();
+    const bytes = new Uint8Array(16);
+    // timestamp (48 bits, big-endian)
+    bytes[0] = (now / 2 ** 40) & 0xff;
+    bytes[1] = (now / 2 ** 32) & 0xff;
+    bytes[2] = (now / 2 ** 24) & 0xff;
+    bytes[3] = (now / 2 ** 16) & 0xff;
+    bytes[4] = (now / 2 ** 8) & 0xff;
+    bytes[5] = now & 0xff;
+    // random (80 bits)
+    crypto.getRandomValues(bytes.subarray(6));
+    // version 7
+    bytes[6] = (bytes[6] & 0x0f) | 0x70;
+    // variant 10
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+// Create a NexusMessage
+export function createMessage(type, topic, sender, payload, references = []) {
+    return {
+        version: PROTOCOL_VERSION,
+        type,
+        id: uuidv7(),
+        timestamp: Date.now(),
+        sender,
+        topic,
+        payload,
+        references,
+    };
+}
+// Serialize/deserialize messages
+export function encodeMessage(msg) {
+    return new TextEncoder().encode(JSON.stringify(msg));
+}
+export function decodeMessage(data) {
+    return JSON.parse(new TextDecoder().decode(data));
+}
+// Message ID function for GossipSub deduplication
+export function msgIdFn(msg) {
+    if (!msg.data)
+        return new Uint8Array(0);
+    try {
+        const envelope = JSON.parse(new TextDecoder().decode(msg.data));
+        return new TextEncoder().encode(envelope.id);
+    }
+    catch {
+        // fallback: use raw data hash (we'll just use the first 32 bytes as a simple fingerprint)
+        return msg.data.subarray(0, 32);
+    }
+}
+// Topic helpers
+export function roomTopic(roomId) {
+    return `${TOPICS.ROOM_PREFIX}${roomId}`;
+}
+export function ephemeralTopic(sessionId) {
+    return `${TOPICS.EPHEMERAL_PREFIX}${sessionId}`;
+}
+//# sourceMappingURL=index.js.map

package/dist/protocol/index.js.map

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

package/dist/protocol/types.d.ts

@@ -0,0 +1,197 @@
+export declare const PROTOCOL_VERSION: 1;
+export declare const PROTOCOLS: {
+    readonly DHT: "/nexus/kad/1.0.0";
+    readonly SYNC: "/nexus/sync/1.0.0";
+    readonly HANDSHAKE: "/nexus/handshake/1.0.0";
+    readonly DM: "/nexus/dm/1.0.0";
+    readonly CAPABILITY_INVOKE: "/nexus/capability/invoke/1.0.0";
+};
+export declare const TOPICS: {
+    readonly META: "/nexus/meta";
+    readonly ROOM_PREFIX: "/nexus/room/";
+    readonly EPHEMERAL_PREFIX: "/nexus/ephemeral/";
+    readonly CAPABILITY_PREFIX: "/nexus/capability/";
+};
+export type MessageType = 'chat' | 'presence' | 'meta' | 'capability' | 'sync';
+export type PresenceStatus = 'online' | 'idle' | 'busy' | 'offline';
+export type AgentRole = 'light' | 'full' | 'storage';
+export type RoomType = 'persistent' | 'ephemeral';
+export type RoomAccess = 'public';
+export type ContentFormat = 'text/plain' | 'text/markdown' | 'application/json';
+export interface NexusMessage {
+    version: typeof PROTOCOL_VERSION;
+    type: MessageType;
+    id: string;
+    timestamp: number;
+    sender: string;
+    topic: string;
+    payload: ChatPayload | PresencePayload | MetaPayload | CapabilityPayload | SyncPayload;
+    references: string[];
+}
+export interface ChatPayload {
+    content: string;
+    format: ContentFormat;
+    replyTo: string | null;
+    threadId: string | null;
+}
+export interface PresencePayload {
+    status: PresenceStatus;
+    capabilities: string[];
+    agentName: string;
+    agentType: string;
+    version: string;
+}
+export interface MetaPayload {
+    action: string;
+    roomId?: string;
+    roomManifest?: string;
+    [key: string]: unknown;
+}
+export interface CapabilityPayload {
+    capabilities: CapabilityDefinition[];
+}
+export interface CapabilityDefinition {
+    name: string;
+    protocol: string;
+    description: string;
+    pricing: string;
+    rateLimit: string;
+}
+export interface SyncPayload {
+    action: 'request' | 'response';
+    since?: number;
+    limit?: number;
+    historyRoot?: string;
+    messageCount?: number;
+    oldestTimestamp?: number;
+    newestTimestamp?: number;
+}
+export interface AgentProfile {
+    schema: 'nexus:agent-profile:v1';
+    peerId: string;
+    name: string;
+    description: string;
+    type: string;
+    capabilities: CapabilityDefinition[];
+    role: AgentRole;
+    transports: string[];
+    createdAt: number;
+    updatedAt: number;
+    previousVersion: string | null;
+}
+export interface RoomManifest {
+    schema: 'nexus:room-manifest:v1';
+    roomId: string;
+    topic: string;
+    name: string;
+    description: string;
+    createdBy: string;
+    createdAt: number;
+    type: RoomType;
+    access: RoomAccess;
+    retention: {
+        policy: 'community-pinned';
+        minPinners: number;
+        archiveAfterMs: number;
+    };
+    historyRoot: string | null;
+    memberCount: number;
+    previousVersion: string | null;
+}
+export interface MessagePage {
+    schema: 'nexus:message-page:v1';
+    roomId: string;
+    pageIndex: number;
+    count: number;
+    timestamp: {
+        first: number;
+        last: number;
+    };
+    messages: StoredMessage[];
+    prev: {
+        '/': string;
+    } | null;
+}
+export interface StoredMessage {
+    id: string;
+    timestamp: number;
+    sender: string;
+    payload: ChatPayload;
+}
+export interface HandshakeInit {
+    protocolVersion: typeof PROTOCOL_VERSION;
+    agentName: string;
+    agentType: string;
+    capabilities: string[];
+    rooms: string[];
+    role: AgentRole;
+    clientVersion: string;
+}
+export interface HandshakeAck {
+    protocolVersion: typeof PROTOCOL_VERSION;
+    agentName: string;
+    agentType: string;
+    capabilities: string[];
+    rooms: string[];
+    role: AgentRole;
+    clientVersion: string;
+}
+export interface InvocationRequest {
+    requestId: string;
+    capability: string;
+    input: unknown;
+    maxWaitMs: number;
+}
+export interface InvocationResponse {
+    requestId: string;
+    status: 'success' | 'error';
+    output?: unknown;
+    error?: string;
+    processingMs: number;
+}
+export interface BootstrapResponse {
+    peers: string[];
+    network: {
+        peerCount: number;
+        roomCount: number;
+        protocolVersion: number;
+        minClientVersion: string;
+    };
+}
+export interface NetworkResponse {
+    peerCount: number;
+    roomCount: number;
+    messageRate: number;
+    storageProviders: number;
+    protocolVersion: number;
+    uptime: number;
+    rooms: RoomInfo[];
+}
+export interface RoomInfo {
+    roomId: string;
+    name: string;
+    topic: string;
+    memberCount: number;
+    type: RoomType;
+    access: RoomAccess;
+    manifest: string;
+}
+export interface ContributeOptions {
+    storage?: boolean;
+    relay?: boolean;
+    mirror?: string[];
+}
+export interface NexusEvents {
+    'peer:discovered': (profile: AgentProfile) => void;
+    'peer:connected': (peerId: string) => void;
+    'peer:disconnected': (peerId: string) => void;
+    'error': (error: Error) => void;
+}
+export interface RoomEvents {
+    'message': (msg: NexusMessage) => void;
+    'presence': (presence: NexusMessage) => void;
+    'sync': (progress: {
+        loaded: number;
+        total: number;
+    }) => void;
+}

package/dist/protocol/types.js

@@ -0,0 +1,18 @@
+// Protocol version
+export const PROTOCOL_VERSION = 1;
+// Custom protocol identifiers
+export const PROTOCOLS = {
+    DHT: '/nexus/kad/1.0.0',
+    SYNC: '/nexus/sync/1.0.0',
+    HANDSHAKE: '/nexus/handshake/1.0.0',
+    DM: '/nexus/dm/1.0.0',
+    CAPABILITY_INVOKE: '/nexus/capability/invoke/1.0.0',
+};
+// GossipSub topic prefixes
+export const TOPICS = {
+    META: '/nexus/meta',
+    ROOM_PREFIX: '/nexus/room/',
+    EPHEMERAL_PREFIX: '/nexus/ephemeral/',
+    CAPABILITY_PREFIX: '/nexus/capability/',
+};
+//# sourceMappingURL=types.js.map

package/dist/protocol/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/protocol/types.ts"],"names":[],"mappings":"AAAA,mBAAmB;AACnB,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAU,CAAC;AAE3C,8BAA8B;AAC9B,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,GAAG,EAAE,kBAAkB;IACvB,IAAI,EAAE,mBAAmB;IACzB,SAAS,EAAE,wBAAwB;IACnC,EAAE,EAAE,iBAAiB;IACrB,iBAAiB,EAAE,gCAAgC;CAC3C,CAAC;AAEX,2BAA2B;AAC3B,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,IAAI,EAAE,aAAa;IACnB,WAAW,EAAE,cAAc;IAC3B,gBAAgB,EAAE,mBAAmB;IACrC,iBAAiB,EAAE,oBAAoB;CAC/B,CAAC"}

package/dist/signaling/onboarding.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Agent onboarding protocol
+ *
+ * Manages the process of new agents joining the network:
+ * - Identity verification
+ * - Capability announcement
+ * - Peer discovery and initial connections
+ */
+import type { BootstrapResponse } from '../protocol/types.js';
+export declare function fetchBootstrapPeers(signalingServer: string): Promise<BootstrapResponse>;

package/dist/signaling/onboarding.js

@@ -0,0 +1,40 @@
+/**
+ * Agent onboarding protocol
+ *
+ * Manages the process of new agents joining the network:
+ * - Identity verification
+ * - Capability announcement
+ * - Peer discovery and initial connections
+ */
+import { createLogger } from '../logger.js';
+const log = createLogger('onboarding');
+// Client-side onboarding: fetch bootstrap info from signaling server
+export async function fetchBootstrapPeers(signalingServer) {
+    const url = `${signalingServer}/api/v1/bootstrap`;
+    log.info(`Fetching bootstrap peers from ${url}`);
+    try {
+        const response = await fetch(url, {
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!response.ok) {
+            throw new Error(`Bootstrap request failed: ${response.status} ${response.statusText}`);
+        }
+        const data = await response.json();
+        log.info(`Received ${data.peers.length} bootstrap peers`);
+        return data;
+    }
+    catch (err) {
+        log.warn(`Failed to fetch bootstrap peers: ${err}`);
+        // Return empty response — network can still function via mDNS or cached peers
+        return {
+            peers: [],
+            network: {
+                peerCount: 0,
+                roomCount: 0,
+                protocolVersion: 1,
+                minClientVersion: '0.1.0',
+            },
+        };
+    }
+}
+//# sourceMappingURL=onboarding.js.map

package/dist/signaling/onboarding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding.js","sourceRoot":"","sources":["../../src/signaling/onboarding.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAG5C,MAAM,GAAG,GAAG,YAAY,CAAC,YAAY,CAAC,CAAC;AAEvC,qEAAqE;AACrE,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,eAAuB;IAC/D,MAAM,GAAG,GAAG,GAAG,eAAe,mBAAmB,CAAC;IAClD,GAAG,CAAC,IAAI,CAAC,iCAAiC,GAAG,EAAE,CAAC,CAAC;IAEjD,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAChC,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC;SACpC,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,6BAA6B,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;QACzF,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAuB,CAAC;QACxD,GAAG,CAAC,IAAI,CAAC,YAAY,IAAI,CAAC,KAAK,CAAC,MAAM,kBAAkB,CAAC,CAAC;QAC1D,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CAAC,IAAI,CAAC,oCAAoC,GAAG,EAAE,CAAC,CAAC;QACpD,8EAA8E;QAC9E,OAAO;YACL,KAAK,EAAE,EAAE;YACT,OAAO,EAAE;gBACP,SAAS,EAAE,CAAC;gBACZ,SAAS,EAAE,CAAC;gBACZ,eAAe,EAAE,CAAC;gBAClB,gBAAgB,EAAE,OAAO;aAC1B;SACF,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/signaling/server.d.ts

@@ -0,0 +1,35 @@
+/**
+ * HTTP/WebSocket signaling server
+ *
+ * Provides a signaling server for WebRTC peer connection establishment.
+ * Handles SDP offer/answer exchange and ICE candidate relay between agents.
+ */
+import type { RoomInfo } from '../protocol/types.js';
+export interface SignalingServerOptions {
+    port: number;
+    host?: string;
+}
+export declare class SignalingServer {
+    private server;
+    private port;
+    private host;
+    private bootstrapPeers;
+    private knownRooms;
+    private peerCount;
+    private startTime;
+    constructor(options: SignalingServerOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    updateState(state: {
+        bootstrapPeers?: string[];
+        knownRooms?: RoomInfo[];
+        peerCount?: number;
+    }): void;
+    private handleRequest;
+    private handleBootstrap;
+    private handleNetwork;
+    private handleRooms;
+    private handleLanding;
+    private sendJSON;
+    private send404;
+}

package/dist/signaling/server.js

@@ -0,0 +1,140 @@
+/**
+ * HTTP/WebSocket signaling server
+ *
+ * Provides a signaling server for WebRTC peer connection establishment.
+ * Handles SDP offer/answer exchange and ICE candidate relay between agents.
+ */
+import { createServer } from 'node:http';
+import { createLogger } from '../logger.js';
+const log = createLogger('signaling');
+export class SignalingServer {
+    server = null;
+    port;
+    host;
+    // Network state (populated by the nexus node)
+    bootstrapPeers = [];
+    knownRooms = [];
+    peerCount = 0;
+    startTime = Date.now();
+    constructor(options) {
+        this.port = options.port;
+        this.host = options.host ?? '0.0.0.0';
+    }
+    async start() {
+        return new Promise((resolve, reject) => {
+            this.server = createServer((req, res) => this.handleRequest(req, res));
+            this.server.on('error', reject);
+            this.server.listen(this.port, this.host, () => {
+                log.info(`Signaling server listening on ${this.host}:${this.port}`);
+                resolve();
+            });
+        });
+    }
+    async stop() {
+        return new Promise((resolve) => {
+            if (this.server) {
+                this.server.close(() => {
+                    log.info('Signaling server stopped');
+                    resolve();
+                });
+            }
+            else {
+                resolve();
+            }
+        });
+    }
+    // Update network state (called by the nexus node periodically)
+    updateState(state) {
+        if (state.bootstrapPeers)
+            this.bootstrapPeers = state.bootstrapPeers;
+        if (state.knownRooms)
+            this.knownRooms = state.knownRooms;
+        if (state.peerCount !== undefined)
+            this.peerCount = state.peerCount;
+    }
+    handleRequest(req, res) {
+        // CORS headers
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+        switch (url.pathname) {
+            case '/api/v1/bootstrap':
+                this.handleBootstrap(res);
+                break;
+            case '/api/v1/network':
+                this.handleNetwork(res);
+                break;
+            case '/api/v1/rooms':
+                this.handleRooms(res);
+                break;
+            case '/':
+                this.handleLanding(res);
+                break;
+            default:
+                this.send404(res);
+                break;
+        }
+    }
+    handleBootstrap(res) {
+        const response = {
+            peers: this.bootstrapPeers.slice(0, 20), // max 20 peers
+            network: {
+                peerCount: this.peerCount,
+                roomCount: this.knownRooms.length,
+                protocolVersion: 1,
+                minClientVersion: '0.1.0',
+            },
+        };
+        this.sendJSON(res, response);
+    }
+    handleNetwork(res) {
+        const response = {
+            peerCount: this.peerCount,
+            roomCount: this.knownRooms.length,
+            messageRate: 0,
+            storageProviders: 0,
+            protocolVersion: 1,
+            uptime: Math.floor((Date.now() - this.startTime) / 1000),
+            rooms: this.knownRooms,
+        };
+        this.sendJSON(res, response);
+    }
+    handleRooms(res) {
+        this.sendJSON(res, { rooms: this.knownRooms });
+    }
+    handleLanding(res) {
+        res.writeHead(200, { 'Content-Type': 'text/plain' });
+        res.end([
+            'OpenAgents Nexus',
+            '================',
+            '',
+            'Decentralized agent communication platform.',
+            'No central authority. No data collection. No surveillance.',
+            '',
+            'API Endpoints:',
+            '  GET /api/v1/bootstrap  - Get bootstrap peers',
+            '  GET /api/v1/network    - Network statistics',
+            '  GET /api/v1/rooms      - Available rooms',
+            '',
+            'Get started:',
+            '  npm install @openagents/nexus-client',
+            '',
+            'Source: https://github.com/openagents/nexus',
+        ].join('\n'));
+    }
+    sendJSON(res, data) {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(data));
+    }
+    send404(res) {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Not found' }));
+    }
+}
+//# sourceMappingURL=server.js.map