@vdoninja/ninja-p2p 0.1.0

package/dist/protocol.js

@@ -0,0 +1,67 @@
+/**
+ * P2P Message Protocol
+ *
+ * Defines the wire format for all messages exchanged over VDO.Ninja
+ * WebRTC data channels. This module has zero dependencies on stevesbot
+ * internals — it can be extracted and reused by any bot.
+ */
+import { randomBytes, randomUUID } from "node:crypto";
+// ── Helpers ──────────────────────────────────────────────────────────────────
+/** Generate a short unique message ID. */
+export function createMessageId() {
+    return randomBytes(12).toString("base64url");
+}
+/** Generate a unique instance ID (per-process, distinguishes restarts). */
+export function createInstanceId() {
+    return randomUUID().slice(0, 8);
+}
+/** Generate a cryptographically random room name. */
+export function generateRoomName() {
+    return "clawd_" + randomBytes(16).toString("hex");
+}
+/** Create a full message envelope. */
+export function createEnvelope(from, type, payload, options) {
+    return {
+        v: 1,
+        id: createMessageId(),
+        type,
+        from,
+        to: options?.to ?? null,
+        topic: options?.topic ?? null,
+        ts: Date.now(),
+        payload,
+    };
+}
+/** Validate that a received object looks like a MessageEnvelope. */
+export function isValidEnvelope(data) {
+    if (typeof data !== "object" || data === null)
+        return false;
+    const d = data;
+    return (d.v === 1 &&
+        typeof d.id === "string" &&
+        typeof d.type === "string" &&
+        typeof d.from === "object" &&
+        d.from !== null &&
+        typeof d.from.streamId === "string" &&
+        typeof d.ts === "number");
+}
+/** Parse raw data received from a data channel into an envelope. Returns null on failure. */
+export function parseEnvelope(raw) {
+    try {
+        const data = typeof raw === "string" ? JSON.parse(raw) : raw;
+        if (isValidEnvelope(data))
+            return data;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Wrap a payload into a sendable JSON object.
+ * The VDO.Ninja SDK sends objects via sendData — this ensures our envelope
+ * is the top-level object sent over the wire.
+ */
+export function envelopeToWire(envelope) {
+    return { ...envelope };
+}

package/dist/vdo-bridge.d.ts

@@ -0,0 +1,66 @@
+/**
+ * VDO Bridge
+ *
+ * Wraps the @vdoninja/sdk to provide a high-level P2P communication layer.
+ * Manages the SDK lifecycle, peers, message routing, auto-announce,
+ * heartbeat pings, offline queue flushing, and graceful shutdown.
+ *
+ * Zero dependencies on stevesbot internals.
+ */
+import { EventEmitter } from "node:events";
+import { MessageBus, type MessageBusOptions } from "./message-bus.js";
+import { PeerRegistry } from "./peer-registry.js";
+import { type AnnouncePayload, type MessageEnvelope, type PeerIdentity } from "./protocol.js";
+export type VDOBridgeOptions = {
+    room: string;
+    streamId: string;
+    identity: Omit<PeerIdentity, "instanceId">;
+    password?: string | false;
+    host?: string;
+    forceTurn?: boolean;
+    debug?: boolean;
+    /** Skills to announce. */
+    skills?: string[];
+    /** Topics to subscribe to. */
+    topics?: string[];
+    /** Heartbeat interval in ms. Default: 30000. */
+    heartbeatMs?: number;
+    /** MessageBus options. */
+    busOptions?: MessageBusOptions;
+};
+export declare class VDOBridge extends EventEmitter {
+    readonly peers: PeerRegistry;
+    readonly bus: MessageBus;
+    readonly identity: PeerIdentity;
+    private sdk;
+    private readonly options;
+    private heartbeatTimer;
+    private connected;
+    private skills;
+    private status;
+    private statusDetail;
+    private version;
+    constructor(options: VDOBridgeOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /** Update skills and broadcast the change. */
+    updateSkills(skills: string[]): void;
+    /** Update status and broadcast the change. */
+    updateStatus(status: string, detail?: string): void;
+    /** Get current announce payload. */
+    getAnnouncePayload(): AnnouncePayload;
+    /** Send a chat message to everyone or a specific peer. */
+    chat(text: string, to?: string): MessageEnvelope;
+    /** Send a chat message to a topic. */
+    chatTopic(topic: string, text: string): MessageEnvelope;
+    /** Send a command to a specific peer. */
+    command(targetStreamId: string, command: string, args?: unknown): MessageEnvelope;
+    /** Publish an event to a topic. */
+    publishEvent(topic: string, kind: string, data?: unknown): MessageEnvelope;
+    private wireSDKEvents;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private respondPong;
+    private broadcastSkillUpdate;
+}

package/dist/vdo-bridge.js

@@ -0,0 +1,318 @@
+/**
+ * VDO Bridge
+ *
+ * Wraps the @vdoninja/sdk to provide a high-level P2P communication layer.
+ * Manages the SDK lifecycle, peers, message routing, auto-announce,
+ * heartbeat pings, offline queue flushing, and graceful shutdown.
+ *
+ * Zero dependencies on stevesbot internals.
+ */
+import { EventEmitter } from "node:events";
+import { MessageBus } from "./message-bus.js";
+import { PeerRegistry } from "./peer-registry.js";
+import { createEnvelope, createInstanceId, envelopeToWire, parseEnvelope, } from "./protocol.js";
+// ── Class ────────────────────────────────────────────────────────────────────
+export class VDOBridge extends EventEmitter {
+    peers;
+    bus;
+    identity;
+    sdk = null;
+    options;
+    heartbeatTimer = null;
+    connected = false;
+    skills;
+    status = "idle";
+    statusDetail = "";
+    version = "0.1.0";
+    constructor(options) {
+        super();
+        this.options = options;
+        this.identity = {
+            streamId: options.streamId,
+            role: options.identity.role,
+            name: options.identity.name,
+            instanceId: createInstanceId(),
+        };
+        this.skills = options.skills ?? [];
+        this.peers = new PeerRegistry();
+        this.bus = new MessageBus(this.identity, this.peers, options.busOptions);
+        // Subscribe to requested topics
+        for (const topic of options.topics ?? []) {
+            this.bus.subscribe(topic);
+        }
+    }
+    // ── Lifecycle ────────────────────────────────────────────────────────────
+    async connect() {
+        if (this.connected)
+            return;
+        // Dynamic import for CJS SDK in ESM context
+        const { createRequire } = await import("node:module");
+        const require = createRequire(import.meta.url);
+        const VDONinjaSDK = require("@vdoninja/sdk");
+        this.sdk = new VDONinjaSDK({
+            host: this.options.host ?? "wss://wss.vdo.ninja",
+            debug: this.options.debug ?? false,
+            forceTURN: this.options.forceTurn ?? false,
+        });
+        this.wireSDKEvents();
+        // Set the send function on the bus
+        this.bus.setSendDataFn((data, target) => {
+            if (!this.sdk)
+                return;
+            try {
+                this.sdk.sendData(data, target ?? undefined);
+            }
+            catch (err) {
+                this.emit("error", err);
+            }
+        });
+        await this.sdk.connect();
+        // Build joinRoom options
+        const joinOpts = { room: this.options.room };
+        if (this.options.password !== undefined) {
+            joinOpts.password = this.options.password;
+        }
+        await this.sdk.joinRoom(joinOpts);
+        // Announce ourselves as a data-only publisher
+        await this.sdk.announce({ streamID: this.options.streamId });
+        this.connected = true;
+        this.startHeartbeat();
+        console.log(`[P2P] Connected to room "${this.options.room}" as "${this.options.streamId}"`);
+        this.emit("connected");
+    }
+    async disconnect() {
+        if (!this.connected || !this.sdk)
+            return;
+        this.stopHeartbeat();
+        // Send a leaving event to all peers
+        try {
+            const envelope = createEnvelope(this.identity, "event", { kind: "leaving" });
+            this.sdk.sendData(envelopeToWire(envelope));
+        }
+        catch { /* best effort */ }
+        try {
+            this.sdk.leaveRoom();
+        }
+        catch { /* best effort */ }
+        try {
+            this.sdk.disconnect();
+        }
+        catch { /* best effort */ }
+        this.connected = false;
+        this.sdk = null;
+        this.peers.clear();
+        console.log("[P2P] Disconnected.");
+        this.emit("disconnected");
+    }
+    isConnected() {
+        return this.connected;
+    }
+    // ── Identity Management ──────────────────────────────────────────────────
+    /** Update skills and broadcast the change. */
+    updateSkills(skills) {
+        this.skills = skills;
+        this.broadcastSkillUpdate();
+    }
+    /** Update status and broadcast the change. */
+    updateStatus(status, detail) {
+        this.status = status;
+        this.statusDetail = detail ?? "";
+        this.broadcastSkillUpdate();
+    }
+    /** Get current announce payload. */
+    getAnnouncePayload() {
+        return {
+            skills: this.skills,
+            status: this.status,
+            statusDetail: this.statusDetail,
+            version: this.version,
+            topics: this.bus.getSubscriptions(),
+        };
+    }
+    // ── Convenience Methods ──────────────────────────────────────────────────
+    /** Send a chat message to everyone or a specific peer. */
+    chat(text, to) {
+        if (to) {
+            return this.bus.send(to, "chat", { text });
+        }
+        return this.bus.broadcast("chat", { text });
+    }
+    /** Send a chat message to a topic. */
+    chatTopic(topic, text) {
+        return this.bus.publish(topic, "chat", { text });
+    }
+    /** Send a command to a specific peer. */
+    command(targetStreamId, command, args) {
+        return this.bus.send(targetStreamId, "command", { command, args });
+    }
+    /** Publish an event to a topic. */
+    publishEvent(topic, kind, data) {
+        return this.bus.publish(topic, "event", { kind, ...((data && typeof data === "object") ? data : { data }) });
+    }
+    // ── SDK Event Wiring ─────────────────────────────────────────────────────
+    wireSDKEvents() {
+        if (!this.sdk)
+            return;
+        // Peer connected (WebRTC connection established)
+        this.sdk.addEventListener("peerConnected", (event) => {
+            const uuid = event.detail?.uuid ?? "unknown";
+            const streamId = event.detail?.streamID ?? uuid;
+            this.peers.addPeer(streamId, uuid);
+            this.emit("peer:connected", { streamId, uuid });
+        });
+        // Data channel opened — send our announce
+        this.sdk.addEventListener("dataChannelOpen", (event) => {
+            const uuid = event.detail?.uuid ?? "unknown";
+            const mappedStreamId = this.peers.streamIdForUuid(uuid);
+            const eventStreamId = event.detail?.streamID;
+            const streamId = mappedStreamId ?? (eventStreamId && eventStreamId !== this.options.streamId ? eventStreamId : uuid);
+            // Send announce to this specific peer
+            const announce = createEnvelope(this.identity, "announce", this.getAnnouncePayload(), { to: streamId });
+            try {
+                this.sdk.sendData(envelopeToWire(announce), { UUID: uuid });
+            }
+            catch { /* peer may have disconnected */ }
+            // Flush any queued offline messages for this peer
+            const flushed = this.bus.flushOfflineQueue(streamId);
+            if (flushed.length > 0) {
+                console.log(`[P2P] Flushed ${flushed.length} queued messages to ${streamId}`);
+            }
+            this.emit("datachannel:open", { streamId, uuid });
+        });
+        // Data received — parse and route through MessageBus
+        this.sdk.addEventListener("dataReceived", (event) => {
+            const raw = event.detail?.data;
+            const uuid = event.detail?.uuid ?? "unknown";
+            const envelope = parseEnvelope(raw);
+            if (!envelope) {
+                // Not our protocol — emit as raw data for consumers who want it
+                this.emit("rawData", { data: raw, uuid });
+                return;
+            }
+            // If we don't have a streamId mapping for this uuid, use the envelope's from
+            const senderStreamId = envelope.from.streamId;
+            if (!this.peers.getPeer(senderStreamId)) {
+                const orphanPeer = this.peers.getPeer(uuid);
+                if (orphanPeer && orphanPeer.streamId === uuid) {
+                    this.peers.rekeyPeer(uuid, senderStreamId);
+                }
+                else {
+                    this.peers.addPeer(senderStreamId, uuid);
+                }
+            }
+            // Handle protocol-level messages
+            switch (envelope.type) {
+                case "announce":
+                    this.peers.updateFromAnnounce(senderStreamId, envelope.from, envelope.payload);
+                    this.emit("peer:announce", { streamId: senderStreamId, identity: envelope.from, announce: envelope.payload });
+                    break;
+                case "skill_update":
+                    this.peers.updateFromSkillUpdate(senderStreamId, envelope.payload);
+                    break;
+                case "ping":
+                    // Respond with pong
+                    this.respondPong(senderStreamId, envelope);
+                    break;
+                case "pong":
+                    // Just update last-seen (already done in bus.handleIncoming)
+                    break;
+                case "history_request": {
+                    // Send recent history to the requesting peer
+                    const count = typeof envelope.payload === "object" && envelope.payload !== null
+                        ? envelope.payload.count ?? 50
+                        : 50;
+                    const history = this.bus.getHistory(count);
+                    for (const msg of history) {
+                        const replay = createEnvelope(this.identity, "history_replay", msg, { to: senderStreamId });
+                        try {
+                            this.sdk.sendData(envelopeToWire(replay), { UUID: uuid });
+                        }
+                        catch { /* best effort */ }
+                    }
+                    break;
+                }
+            }
+            // Route through MessageBus for application-level handling
+            this.bus.handleIncoming(envelope);
+        });
+        // Peer disconnected
+        this.sdk.addEventListener("peerDisconnected", (event) => {
+            const uuid = event.detail?.uuid ?? "unknown";
+            const streamId = event.detail?.streamID ?? this.peers.streamIdForUuid(uuid) ?? uuid;
+            this.peers.markDisconnected(streamId);
+            console.log(`[P2P] Peer disconnected: ${streamId}`);
+            this.emit("peer:disconnected", { streamId, uuid });
+        });
+        // SDK-level connection events
+        this.sdk.addEventListener("disconnected", () => {
+            console.log("[P2P] WebSocket disconnected, SDK will attempt reconnect...");
+            this.emit("ws:disconnected");
+        });
+        this.sdk.addEventListener("reconnected", () => {
+            console.log("[P2P] WebSocket reconnected.");
+            this.emit("ws:reconnected");
+        });
+        // Room listing (existing peers when we join)
+        this.sdk.addEventListener("listing", (event) => {
+            const list = event.detail?.list ?? [];
+            for (const entry of list) {
+                if (entry.streamID && entry.streamID !== this.options.streamId) {
+                    // View each existing peer to establish data channels
+                    this.sdk.view(entry.streamID, { audio: false, video: false });
+                }
+            }
+        });
+        // Error handling
+        this.sdk.addEventListener("error", (event) => {
+            console.error("[P2P] SDK error:", event.detail?.error);
+            this.emit("error", event.detail?.error);
+        });
+    }
+    // ── Heartbeat ────────────────────────────────────────────────────────────
+    startHeartbeat() {
+        const interval = this.options.heartbeatMs ?? 30_000;
+        this.heartbeatTimer = setInterval(() => {
+            if (!this.connected || !this.sdk)
+                return;
+            const ping = createEnvelope(this.identity, "ping", { ts: Date.now() });
+            try {
+                this.sdk.sendData(envelopeToWire(ping));
+            }
+            catch { /* connection may be lost */ }
+        }, interval);
+        // Don't block process exit
+        if (this.heartbeatTimer.unref)
+            this.heartbeatTimer.unref();
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+    respondPong(targetStreamId, pingEnvelope) {
+        if (!this.sdk)
+            return;
+        const pong = createEnvelope(this.identity, "pong", {
+            pingId: pingEnvelope.id,
+            pingTs: pingEnvelope.payload?.ts,
+            pongTs: Date.now(),
+        }, { to: targetStreamId });
+        const peer = this.peers.getPeer(targetStreamId);
+        if (peer) {
+            try {
+                this.sdk.sendData(envelopeToWire(pong), { UUID: peer.uuid });
+            }
+            catch { /* best effort */ }
+        }
+    }
+    broadcastSkillUpdate() {
+        if (!this.connected)
+            return;
+        this.bus.broadcast("skill_update", {
+            skills: this.skills,
+            status: this.status,
+            statusDetail: this.statusDetail,
+        });
+    }
+}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@vdoninja/ninja-p2p",
+  "version": "0.1.0",
+  "description": "Reusable P2P agent communication module using VDO.Ninja WebRTC data channels",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./vdo-bridge": {
+      "types": "./dist/vdo-bridge.d.ts",
+      "import": "./dist/vdo-bridge.js"
+    },
+    "./message-bus": {
+      "types": "./dist/message-bus.d.ts",
+      "import": "./dist/message-bus.js"
+    },
+    "./peer-registry": {
+      "types": "./dist/peer-registry.d.ts",
+      "import": "./dist/peer-registry.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol.d.ts",
+      "import": "./dist/protocol.js"
+    },
+    "./dashboard.html": "./dashboard.html",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "dashboard.html",
+    "README.md",
+    "skills/ninja-p2p"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "test": "tsx --test tests/**/*.test.ts",
+    "prebuild": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "tsc -p tsconfig.json",
+    "prepare": "npm run build"
+  },
+  "keywords": ["p2p", "webrtc", "vdo.ninja", "agent", "pub-sub", "data-channel", "bot"],
+  "author": "Steve Seguin",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/steveseguin/ninja-p2p.git"
+  },
+  "bugs": {
+    "url": "https://github.com/steveseguin/ninja-p2p/issues"
+  },
+  "homepage": "https://github.com/steveseguin/ninja-p2p#readme",
+  "dependencies": {
+    "@vdoninja/sdk": "^1.3.18"
+  },
+  "peerDependencies": {
+    "@roamhq/wrtc": "^0.8.0"
+  },
+  "peerDependenciesMeta": {
+    "@roamhq/wrtc": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.0"
+  }
+}

package/skills/ninja-p2p/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: ninja-p2p
+description: Build bot-to-bot communication over VDO.Ninja WebRTC data channels. Use this skill when the user wants agents or services to meet in a room, discover peers, send private messages, broadcast events, or keep lightweight P2P presence without a central relay.
+---
+
+# ninja-p2p
+
+Use this skill when a project needs room-based peer discovery and direct messaging between bots over WebRTC.
+
+## What This Repo Provides
+
+- `VDOBridge` for connection lifecycle, room join, announce, heartbeat, and SDK wiring
+- `PeerRegistry` for presence, skills, topics, and status tracking
+- `MessageBus` for broadcast, direct messages, topic-based fanout, history replay, and offline queueing
+- `dashboard.html` for a browser-side room monitor and chat UI
+
+## Install The Library In A Project
+
+Install it from npm:
+
+```bash
+npm install @vdoninja/ninja-p2p @roamhq/wrtc
+```
+
+`@vdoninja/sdk` is installed transitively. `ws` comes from the SDK in Node environments.
+
+## Add This Skill To Codex
+
+Use Codex's built-in `skill-installer` helper and install the `skills/ninja-p2p` path from this repo, then restart Codex.
+
+## Default Integration Pattern
+
+1. Pick a shared `room` for the bots that should discover each other.
+2. Give each bot a unique `streamId`.
+3. Connect with `VDOBridge`.
+4. Use `bridge.chat(text)` for room-wide messages.
+5. Use `bridge.chat(text, targetStreamId)` or `bridge.command(targetStreamId, command, args)` for private messages.
+6. Use `bridge.publishEvent(topic, kind, data)` for topic fanout.
+
+## Example
+
+```ts
+import { VDOBridge } from "@vdoninja/ninja-p2p";
+
+const bridge = new VDOBridge({
+  room: "agents_room",
+  streamId: "planner_bot",
+  identity: {
+    streamId: "planner_bot",
+    role: "agent",
+    name: "Planner",
+  },
+  password: false,
+  skills: ["plan", "chat"],
+  topics: ["events"],
+});
+
+await bridge.connect();
+
+bridge.chat("Planner online");
+bridge.chat("sync now", "worker_bot");
+bridge.publishEvent("events", "status_change", { status: "busy" });
+
+bridge.bus.on("message:chat", (envelope) => {
+  console.log(`${envelope.from.name}: ${envelope.payload.text}`);
+});
+```
+
+## Notes
+
+- `room` and `streamId` should be stable and human-readable, but unique enough to avoid collisions.
+- Private messages target peer `streamId`s.
+- Topic messages are broadcast and filtered on the receiver side.
+- The browser dashboard can sit in the same room as the bots for live inspection.