@vdoninja/ninja-p2p 0.1.0 → 0.1.1

package/README.md

@@ -1,17 +1,35 @@
 # ninja-p2p
 
-Reusable bot-to-bot P2P communication layer built on [VDO.Ninja](https://vdo.ninja) WebRTC data channels. It lets agents discover each other inside a room, announce skills and status, send room-wide or private messages, and keep lightweight message history without a central relay.
+`ninja-p2p` is a small TypeScript library for peer-to-peer agent messaging on top of the [VDO.Ninja](https://vdo.ninja) SDK.
 
-## What This Repo Is
+It gives you a shared room, peer discovery, direct messages, group chat, topics, in-memory history, and a simple browser dashboard. The transport is WebRTC data channels. You do not need to open inbound ports just to let agents talk to each other.
 
-- A TypeScript/Node library for room-based peer discovery and messaging
-- A standalone `dashboard.html` monitor/chat client
-- A Codex skill at `skills/ninja-p2p`
-- An npm package published as `@vdoninja/ninja-p2p`
+Package: [`@vdoninja/ninja-p2p`](https://www.npmjs.com/package/@vdoninja/ninja-p2p)  
+Support: https://discord.vdo.ninja
 
-## Install The Library
+## What It Does
 
-Install it from npm:
+- peers join the same room and discover each other
+- direct messages between named peers
+- room-wide chat
+- topic-based pub/sub
+- peer status, skills, and presence tracking
+- in-memory history replay
+- in-memory offline queue for peers that drop and reconnect
+- a standalone `dashboard.html` room monitor/chat client
+
+## What It Does Not Do
+
+- it is not a VPN
+- it is not a generic TCP tunnel
+- it is not a generic HTTP tunnel
+- it does not provide durable storage
+- it does not guarantee message delivery
+- it does not turn the dashboard into a remote shell
+
+This package is for agent coordination. If you want to expose a whole private network or front a public website, use a VPN or a tunnel made for that job.
+
+## Install
 
 ```bash
 npm install @vdoninja/ninja-p2p @roamhq/wrtc
@@ -19,10 +37,9 @@ npm install @vdoninja/ninja-p2p @roamhq/wrtc
 
 Notes:
 
-- `@vdoninja/sdk` is pulled in automatically as a dependency.
-- `ws` comes from `@vdoninja/sdk` in Node environments.
-- `@roamhq/wrtc` is recommended for Node-based bots that need WebRTC support.
-- This package is configured for public scoped publishing via `publishConfig.access = "public"`.
+- `@vdoninja/sdk` is installed automatically.
+- `ws` comes from `@vdoninja/sdk` in Node.
+- `@roamhq/wrtc` is recommended for Node bots that need WebRTC support.
 
 ## Add The Codex Skill
 
@@ -60,49 +77,137 @@ const bridge = new VDOBridge({
 
 await bridge.connect();
 
-// Send to everyone in the room
 bridge.chat("Planner online");
-
-// Send a private message to a specific peer
 bridge.chat("sync now", "worker_bot");
-
-// Publish a topic event
 bridge.publishEvent("events", "status_change", { status: "busy" });
 
-// Listen for incoming chat
 bridge.bus.on("message:chat", (envelope) => {
   console.log(`${envelope.from.name}: ${envelope.payload.text}`);
 });
 ```
 
-## Core Features
+## Human Operator Example
 
-- **Peer Registry**: Track peers, identity, skills, topics, and status
-- **Pub/Sub Messaging**: Broadcast, direct send, and topic fanout
-- **Offline Queue**: Queue messages for peers that are temporarily disconnected
-- **Message History**: Replay recent messages to late joiners
-- **Keyword Triggers**: Wake async bots from chat patterns
-- **Identity Protocol**: Peers announce skills and status changes
-- **Heartbeat**: Detect stale peers
-- **Browser Dashboard**: Monitor peers and chat from a single HTML file
+One simple pattern is to put a human-operated process in the same room as the bots.
 
-## Core Patterns
+Agent:
 
-- Room-wide chat: `bridge.chat("hello")`
-- Private message: `bridge.chat("hello", "target_stream_id")`
-- Targeted command: `bridge.command("target_stream_id", "do_work", { jobId: 123 })`
-- Topic event: `bridge.publishEvent("events", "status_change", { status: "busy" })`
+```ts
+import { VDOBridge } from "@vdoninja/ninja-p2p";
 
-## Browser Dashboard
+const worker = new VDOBridge({
+  room: "agents_room",
+  streamId: "worker_bot",
+  identity: {
+    streamId: "worker_bot",
+    role: "agent",
+    name: "Worker",
+  },
+  password: false,
+  skills: ["status", "say"],
+});
 
-`dashboard.html` is a standalone single-file SPA that connects to the same VDO.Ninja room. Open it locally in a browser or host it anywhere static files are supported.
+await worker.connect();
 
-Example:
+worker.bus.on("message:command", (envelope) => {
+  const payload = envelope.payload as { command?: string; args?: { text?: string } };
+
+  if (payload.command === "status") {
+    worker.commandResponse(envelope, {
+      status: "idle",
+      peers: worker.peers.toJSON(),
+    });
+    return;
+  }
+
+  if (payload.command === "say") {
+    console.log(payload.args?.text ?? "");
+    worker.commandResponse(envelope, { ok: true });
+    return;
+  }
+
+  worker.commandResponse(envelope, undefined, `unknown command: ${payload.command ?? "?"}`);
+});
+```
+
+Operator:
+
+```ts
+import { VDOBridge } from "@vdoninja/ninja-p2p";
+
+const operator = new VDOBridge({
+  room: "agents_room",
+  streamId: "steve_operator",
+  identity: {
+    streamId: "steve_operator",
+    role: "operator",
+    name: "Steve",
+  },
+  password: false,
+});
+
+await operator.connect();
+
+operator.command("worker_bot", "status");
+operator.command("worker_bot", "say", { text: "hello from the operator" });
+
+operator.bus.on("message:command_response", (envelope) => {
+  console.log(envelope.payload);
+});
+```
+
+The browser dashboard can also join the same room:
 
 ```text
 dashboard.html?room=agents_room&password=false&name=Steve&autoconnect=true
 ```
 
+The dashboard can chat, DM a peer, and send simple slash-command messages like `/status`, `/health`, `/history`, and `/peers`.
+
+## Coordination Helpers
+
+- `bridge.chat(text, to?)`
+- `bridge.chatTopic(topic, text)`
+- `bridge.command(targetStreamId, command, args?)`
+- `bridge.commandResponse(message, result?, error?)`
+- `bridge.publishEvent(topic, kind, data?)`
+- `bridge.reply(message, type, payload)`
+- `bridge.ack(message, payload?)`
+- `bridge.requestHistory(targetStreamId, count?)`
+
+These are lightweight coordination messages. They are useful, but they are not hard delivery guarantees.
+
+## Raw Data, Media, and Advanced SDK Access
+
+This package focuses on data-channel messaging.
+
+The underlying VDO.Ninja SDK goes further than that. It can also:
+
+- publish and view audio/video tracks
+- emit `track` events
+- send binary payloads over the data channel
+
+This wrapper exposes two escape hatches for that:
+
+- `bridge.sendRaw(data, targetStreamId?)` sends arbitrary data without wrapping it in the message envelope
+- `bridge.getSDK()` returns the underlying VDO.Ninja SDK instance after `connect()`
+
+Example:
+
+```ts
+const sdk = bridge.getSDK();
+
+sdk?.addEventListener("track", (event) => {
+  const track = event.detail?.track;
+  console.log("track", track?.kind);
+});
+
+const chunk = new Uint8Array([1, 2, 3]).buffer;
+bridge.sendRaw(chunk, "worker_bot");
+```
+
+If you want to turn video into frames for ingestion, or build a file-transfer layer, do it on top of the SDK or on top of `sendRaw`. That is possible with the current stack, but it is not wrapped into a higher-level API in this package yet.
+
 ## Public API
 
 Main entrypoint:
@@ -118,21 +223,28 @@ import { VDOBridge } from "@vdoninja/ninja-p2p/vdo-bridge";
 import { createEnvelope } from "@vdoninja/ninja-p2p/protocol";
 ```
 
-## Architecture
+## Files
 
-```text
-VDOBridge
-  |- PeerRegistry
-  |- MessageBus
-  `- Protocol helpers
-```
+- `src/vdo-bridge.ts`: connection lifecycle and SDK integration
+- `src/message-bus.ts`: chat, direct messages, topics, history, offline queue
+- `src/peer-registry.ts`: peer state and presence
+- `src/protocol.ts`: message envelope format
+- `dashboard.html`: browser monitor/chat client
+- `skills/ninja-p2p`: Codex skill
 
 ## Tests
 
 ```bash
 npm test
+npm run build
 ```
 
+## Support
+
+- Discord: https://discord.vdo.ninja
+- VDO.Ninja: https://vdo.ninja
+- Social Stream Ninja: https://socialstream.ninja
+
 ## License
 
 MIT

package/dist/vdo-bridge.d.ts

@@ -10,7 +10,7 @@
 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";
+import { type AnnouncePayload, type MessageEnvelope, type MessageType, type PeerIdentity } from "./protocol.js";
 export type VDOBridgeOptions = {
     room: string;
     streamId: string;
@@ -58,6 +58,18 @@ export declare class VDOBridge extends EventEmitter {
     command(targetStreamId: string, command: string, args?: unknown): MessageEnvelope;
     /** Publish an event to a topic. */
     publishEvent(topic: string, kind: string, data?: unknown): MessageEnvelope;
+    /** Send raw data through the underlying SDK without envelope wrapping. */
+    sendRaw(data: unknown, targetStreamId?: string): boolean;
+    /** Reply to a received message using its sender as the target. */
+    reply(message: MessageEnvelope, type: MessageType, payload: unknown): MessageEnvelope;
+    /** Acknowledge receipt of a received message. */
+    ack(message: MessageEnvelope, payload?: unknown): MessageEnvelope;
+    /** Respond to a command or request-style message. */
+    commandResponse(message: MessageEnvelope, result?: unknown, error?: string): MessageEnvelope;
+    /** Ask a peer to replay recent message history to this bridge. */
+    requestHistory(targetStreamId: string, count?: number): MessageEnvelope;
+    /** Access the underlying VDO.Ninja SDK instance for advanced media workflows. */
+    getSDK(): InstanceType<typeof import("@vdoninja/sdk")> | null;
     private wireSDKEvents;
     private startHeartbeat;
     private stopHeartbeat;

package/dist/vdo-bridge.js

@@ -23,7 +23,7 @@ export class VDOBridge extends EventEmitter {
     skills;
     status = "idle";
     statusDetail = "";
-    version = "0.1.0";
+    version = "0.1.1";
     constructor(options) {
         super();
         this.options = options;
@@ -149,6 +149,64 @@ export class VDOBridge extends EventEmitter {
     publishEvent(topic, kind, data) {
         return this.bus.publish(topic, "event", { kind, ...((data && typeof data === "object") ? data : { data }) });
     }
+    /** Send raw data through the underlying SDK without envelope wrapping. */
+    sendRaw(data, targetStreamId) {
+        if (!this.sdk)
+            return false;
+        try {
+            if (!targetStreamId) {
+                this.sdk.sendData(data);
+                return true;
+            }
+            const peer = this.peers.getPeer(targetStreamId);
+            if (peer?.uuid) {
+                this.sdk.sendData(data, { UUID: peer.uuid });
+            }
+            else {
+                this.sdk.sendData(data, { streamID: targetStreamId });
+            }
+            return true;
+        }
+        catch (err) {
+            this.emit("error", err);
+            return false;
+        }
+    }
+    /** Reply to a received message using its sender as the target. */
+    reply(message, type, payload) {
+        return this.bus.send(message.from.streamId, type, payload);
+    }
+    /** Acknowledge receipt of a received message. */
+    ack(message, payload) {
+        const ackPayload = { messageId: message.id };
+        if (payload !== undefined) {
+            ackPayload.data = payload;
+        }
+        return this.bus.send(message.from.streamId, "ack", ackPayload);
+    }
+    /** Respond to a command or request-style message. */
+    commandResponse(message, result, error) {
+        if (error) {
+            return this.bus.send(message.from.streamId, "command_response", {
+                requestId: message.id,
+                ok: false,
+                error,
+            });
+        }
+        return this.bus.send(message.from.streamId, "command_response", {
+            requestId: message.id,
+            ok: true,
+            result: result ?? null,
+        });
+    }
+    /** Ask a peer to replay recent message history to this bridge. */
+    requestHistory(targetStreamId, count = 50) {
+        return this.bus.send(targetStreamId, "history_request", { count });
+    }
+    /** Access the underlying VDO.Ninja SDK instance for advanced media workflows. */
+    getSDK() {
+        return this.sdk;
+    }
     // ── SDK Event Wiring ─────────────────────────────────────────────────────
     wireSDKEvents() {
         if (!this.sdk)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vdoninja/ninja-p2p",
-  "version": "0.1.0",
-  "description": "Reusable P2P agent communication module using VDO.Ninja WebRTC data channels",
+  "version": "0.1.1",
+  "description": "Open source P2P agent messaging and coordination over VDO.Ninja WebRTC data channels",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -42,7 +42,19 @@
     "build": "tsc -p tsconfig.json",
     "prepare": "npm run build"
   },
-  "keywords": ["p2p", "webrtc", "vdo.ninja", "agent", "pub-sub", "data-channel", "bot"],
+  "keywords": [
+    "p2p",
+    "webrtc",
+    "vdo.ninja",
+    "agent",
+    "agent-mesh",
+    "pub-sub",
+    "data-channel",
+    "bot",
+    "nat-traversal",
+    "hole-punching",
+    "remote-control"
+  ],
   "author": "Steve Seguin",
   "license": "MIT",
   "publishConfig": {

package/skills/ninja-p2p/SKILL.md

@@ -1,41 +1,36 @@
 ---
 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.
+description: Use VDO.Ninja WebRTC data channels for agent messaging, peer discovery, room presence, direct messages, topics, and lightweight operator control.
 ---
 
 # ninja-p2p
 
-Use this skill when a project needs room-based peer discovery and direct messaging between bots over WebRTC.
+Use this when a project needs agents to meet in a room and talk to each other over WebRTC.
 
-## What This Repo Provides
+## What It Gives You
 
-- `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
+- `VDOBridge` for connection lifecycle and SDK wiring
+- `PeerRegistry` for presence, skills, topics, and status
+- `MessageBus` for room chat, direct messages, topic fanout, history replay, and the in-memory offline queue
+- `dashboard.html` for a browser room monitor/chat client
 
-## Install The Library In A Project
-
-Install it from npm:
+## Install
 
 ```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.
+`@vdoninja/sdk` is installed automatically. `ws` comes from the SDK in Node.
 
-## Default Integration Pattern
+## Default Pattern
 
-1. Pick a shared `room` for the bots that should discover each other.
-2. Give each bot a unique `streamId`.
+1. Pick a shared `room`.
+2. Give each peer 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.
+4. Use `bridge.chat()` for room messages.
+5. Use `bridge.chat(..., targetStreamId)` or `bridge.command()` for direct messages.
+6. Use `bridge.publishEvent()` for topic messages.
+7. Use `bridge.commandResponse()`, `bridge.ack()`, or `bridge.reply()` when a peer should answer back.
 
 ## Example
 
@@ -68,7 +63,8 @@ bridge.bus.on("message:chat", (envelope) => {
 
 ## Notes
 
-- `room` and `streamId` should be stable and human-readable, but unique enough to avoid collisions.
+- `room` and `streamId` should be stable and human-readable.
 - 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.
+- The offline queue is in memory, not durable storage.
+- `sendRaw()` and `getSDK()` are there if you need lower-level SDK access for binary data or media work.