@vdoninja/ninja-p2p 0.1.2 → 0.1.4

package/README.md

@@ -1,134 +1,84 @@
 # ninja-p2p
 
-`ninja-p2p` is a WebRTC room, DM, command, lightweight file-transfer, and narrow shared-folder transport for bots and operator consoles built on top of the [VDO.Ninja](https://vdo.ninja) SDK.
+## TL;DR
 
-It gives you peer discovery, room chat, private messages, topic pub/sub, file and image transfer between sidecars, explicit shared folders, in-memory history, and a simple browser dashboard. The transport is WebRTC data channels, so bots can usually talk to each other without opening inbound ports.
+Think of `ninja-p2p` as a small group chat for AI helpers. Put Codex, Claude, your own bots, and optionally a human operator in the same room. They can see who is there, send messages, ask each other for work, exchange files, and keep a small inbox while another agent is busy.
 
-Package: [`@vdoninja/ninja-p2p`](https://www.npmjs.com/package/@vdoninja/ninja-p2p)  
-Support: https://discord.vdo.ninja
+It runs over [VDO.Ninja](https://vdo.ninja) WebRTC data channels, so you do not need to build or host a new chat server.
+
+**Best for:** always-on agent rooms, shell automation, and agents that need a local inbox.
+
+**Not for:** general network tunnelling, durable cloud storage, or very large public communities.
+
+Package: [`@vdoninja/ninja-p2p`](https://www.npmjs.com/package/@vdoninja/ninja-p2p) | [Protocol and reliability](docs/protocol-and-reliability.md) | [Support](https://discord.vdo.ninja)
 
 <p align="center">
-  <img src="docs/images/readme-demo-claude.png" alt="Claude using ninja-p2p to read and reply in a room" width="32%">
-  <img src="docs/images/readme-demo-codex.png" alt="Codex using ninja-p2p to send and read messages in the same room" width="32%">
-  <img src="docs/images/readme-demo-dashboard.png" alt="The browser dashboard observing the same ninja-p2p room" width="32%">
+  <a href="docs/images/agent-room-dashboard.png"><img src="docs/images/agent-room-dashboard.png" alt="A live Ninja P2P room with Planner and Reviewer agents exchanging messages while an operator watches" width="900"></a>
 </p>
 
-<p align="center"><em>Claude, Codex, and the dashboard in the same room.</em></p>
+<p align="center"><em>A real room: two agent sidecars talking while a human watches from the browser dashboard.</em></p>
 
-## Quick Start For Claude Code
+## The Simple Mental Model
 
-Do not use `connect` for Claude Code. Use a persistent sidecar.
+- A **room** is the shared meeting place.
+- A **sidecar** keeps one agent connected and holds its local inbox.
+- The **CLI or skill** lets Codex and Claude read and write that inbox during their turns.
+- The optional **dashboard** lets a person watch, chat, inspect agents, and download shared files.
 
-This is the actual Claude Code setup:
+## Start Two Agents
 
-1. Install the CLI:
+Install once:
 
 ```bash
 npm install -g @vdoninja/ninja-p2p @roamhq/wrtc
 ```
 
-2. Install the Claude skill:
+Start the first agent. A private room name is generated automatically:
 
 ```bash
-ninja-p2p install-skill claude
-```
-
-3. In Claude Code, start the sidecar:
-
-```text
-/ninja-p2p start
-```
-
-That starts the background sidecar for `claude`. If you do not pass `--room`, `ninja-p2p` generates one automatically.
-
-4. Ask Claude which room it is in:
-
-```text
-/ninja-p2p room
+ninja-p2p start --id codex
+ninja-p2p room --id codex
 ```
 
-5. Start the second agent in that same room:
+Use the room name printed above to start the second agent:
 
 ```bash
-ninja-p2p start --room <that-room> --id codex
+ninja-p2p start --room <room-name> --id claude
 ```
 
-6. Then use:
-
-```text
-/ninja-p2p menu
-/ninja-p2p notify
-/ninja-p2p read --take 10
-/ninja-p2p dm codex "Can you review this plan?"
-/ninja-p2p send-file codex ./notes.txt
-```
-
-That is the whole model:
-
-- `/ninja-p2p start` launches the detached background sidecar
-- `/ninja-p2p room` shows the current room and how another agent joins it
-- Claude uses `/ninja-p2p ...` during its turns
-- `notify` tells Claude whether anything is waiting
-- `read` pulls pending messages into the current turn
-
-Restart Claude Code after installing the skill if it does not appear immediately.
-
-## Quick Start For Codex CLI
-
-Do not use `connect` for Codex CLI either. Use a persistent sidecar.
-
-This is the actual Codex CLI setup:
-
-1. Install the CLI:
+Now they can talk:
 
 ```bash
-npm install -g @vdoninja/ninja-p2p @roamhq/wrtc
+ninja-p2p dm --id codex claude "Please review my rollout plan"
+ninja-p2p notify --id claude
+ninja-p2p read --id claude --take 10
+ninja-p2p dm --id claude codex "I found two risks; sending notes now"
 ```
 
-2. Install the Codex skill:
+That is the core product. Profiles, commands, approvals, file transfer, shared folders, and the dashboard build on the same room and inbox.
 
-```bash
-ninja-p2p install-skill codex
-```
+## Make It Feel Native In Codex Or Claude
 
-3. In Codex, start the sidecar:
+The optional skill teaches the agent when and how to use the CLI:
 
 ```bash
-ninja-p2p start --id codex
-```
-
-That starts the background sidecar for `codex`. If you do not pass `--room`, `ninja-p2p` generates one automatically.
-
-4. Ask Codex which room it is in:
-
-```bash
-ninja-p2p room --id codex
-```
-
-5. Start the second agent in that same room:
-
-```text
-/ninja-p2p start --room <that-room>
+ninja-p2p install-skill codex
+ninja-p2p install-skill claude
 ```
 
-6. Then use:
-
-```text
-ninja-p2p menu --id codex
-ninja-p2p room --id codex
-ninja-p2p notify --id codex
-ninja-p2p read --id codex --take 10
-ninja-p2p dm --id codex claude "I pushed the patch"
-ninja-p2p shares --id codex claude
-```
+- In **Claude Code**, use `/ninja-p2p start`, `/ninja-p2p notify`, and `/ninja-p2p read`.
+- In **Codex**, mention `$ninja-p2p` or let Codex run the `ninja-p2p` command directly.
+- Restart the client after installing a skill if it does not appear immediately.
 
-Important:
+## Which VDO.Ninja Package Do I Need?
 
-- Codex does not get `/ninja-p2p`
-- the skill teaches Codex when and how to use the CLI
-- the CLI is the thing that actually runs
+| Your goal | Use |
+| --- | --- |
+| Give agents a persistent room and inbox | **`@vdoninja/ninja-p2p`** |
+| Give an MCP client connect/send/file/state tools | [`@vdoninja/mcp`](https://github.com/steveseguin/ninjamcp) |
+| Build directly with WebRTC media or data channels | [`@vdoninja/sdk`](https://github.com/steveseguin/ninjasdk) |
 
-Restart Codex after installing the skill if it does not appear immediately.
+`ninja-p2p` adds only its agent-friendly message envelope and local sidecar state. It uses VDO.Ninja's existing signaling behavior and does not invent new WebSocket commands.
 
 ## How Joining A Room Works
 

package/dashboard.html

@@ -162,7 +162,7 @@ input:focus,select:focus{border-color:var(--accent)}
   let connected = false;
   let myStreamId = '';
   let myIdentity = null;
-  const DASHBOARD_VERSION = '0.1.2';
+  const DASHBOARD_VERSION = '0.1.4';
   const peers = new Map(); // streamId -> {uuid, identity, skills, status, connected}
   const peerUuidToStream = new Map();
   const messages = [];

package/dist/agent-state.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { createMessageId, } from "./protocol.js";
 const SESSION_FILE = "session.json";
 const PEERS_FILE = "peers.json";
+let lastQueuedActionAt = 0;
 export function ensureAgentState(stateDir) {
     const resolved = path.resolve(stateDir);
     const paths = {
@@ -40,7 +41,9 @@ export function queueAgentAction(stateDir, action) {
     const queued = {
         ...action,
         id: createMessageId(),
-        createdAt: Date.now(),
+        // Date.now() can repeat during a burst. Keep timestamps monotonic so the
+        // filesystem outbox remains FIFO even when several actions share a tick.
+        createdAt: nextQueuedActionTimestamp(),
     };
     const filename = `${queued.createdAt}_${queued.id}.json`;
     writeJsonAtomic(path.join(paths.outboxDir, filename), queued);
@@ -173,6 +176,10 @@ function listJsonFiles(dir) {
         .map((name) => path.join(dir, name))
         .sort();
 }
+function nextQueuedActionTimestamp() {
+    lastQueuedActionAt = Math.max(Date.now(), lastQueuedActionAt + 1);
+    return lastQueuedActionAt;
+}
 function readJsonFile(filePath) {
     try {
         const raw = readFileSync(filePath, "utf8");

package/dist/message-bus.d.ts

@@ -16,7 +16,8 @@ export type KeywordTrigger = {
     pattern: RegExp;
     handler: (msg: MessageEnvelope) => void;
 };
-export type SendDataFn = (data: object, target?: unknown) => void;
+/** Return false when the transport could not accept the message yet. */
+export type SendDataFn = (data: object, target?: unknown) => boolean | void;
 export type MessageBusOptions = {
     /** Max messages kept in history ring buffer. Default: 200. */
     historySize?: number;

package/dist/message-bus.js

@@ -69,10 +69,7 @@ export class MessageBus extends EventEmitter {
     send(targetStreamId, type, payload) {
         const envelope = createEnvelope(this.identity, type, payload, { to: targetStreamId });
         this.addToHistory(envelope);
-        if (this.peers.isConnected(targetStreamId)) {
-            this.rawSend(envelope, targetStreamId);
-        }
-        else {
+        if (!this.peers.isConnected(targetStreamId) || !this.rawSend(envelope, targetStreamId)) {
             this.enqueueOffline(targetStreamId, envelope);
         }
         return envelope;
@@ -142,13 +139,21 @@ export class MessageBus extends EventEmitter {
         const queue = this.offlineQueues.get(streamId);
         if (!queue || queue.length === 0)
             return [];
-        this.offlineQueues.delete(streamId);
-        // Send each queued message wrapped as history_replay
+        const flushed = [];
         for (const msg of queue) {
-            const replay = createEnvelope(this.identity, "history_replay", msg, { to: streamId });
-            this.rawSend(replay, streamId);
+            // Preserve the original type and ID. Wrapping queued commands as
+            // history_replay prevented normal command/file handlers from seeing them.
+            if (!this.rawSend(msg, streamId))
+                break;
+            flushed.push(msg);
+        }
+        if (flushed.length === queue.length) {
+            this.offlineQueues.delete(streamId);
         }
-        return queue;
+        else if (flushed.length > 0) {
+            this.offlineQueues.set(streamId, queue.slice(flushed.length));
+        }
+        return flushed;
     }
     /** Get the number of queued messages for a peer. */
     getOfflineQueueSize(streamId) {
@@ -174,23 +179,27 @@ export class MessageBus extends EventEmitter {
     // ── Internals ────────────────────────────────────────────────────────────
     rawSend(envelope, target) {
         if (!this.sendDataFn)
-            return;
+            return false;
         const wire = envelopeToWire(envelope);
+        let accepted;
         if (target) {
             // Prefer uuid targeting once we know it; streamID targeting can be ambiguous
             // before announce/rekey completes on some SDK connection paths.
             const peer = this.peers.getPeer(target);
             if (peer?.uuid) {
-                this.sendDataFn(wire, { uuid: peer.uuid });
+                accepted = this.sendDataFn(wire, { uuid: peer.uuid });
             }
             else {
-                this.sendDataFn(wire, { streamID: target });
+                accepted = this.sendDataFn(wire, { streamID: target });
             }
         }
         else {
             // Broadcast to all
-            this.sendDataFn(wire);
+            accepted = this.sendDataFn(wire);
         }
+        // Void preserves compatibility with existing transports written before
+        // acceptance results were supported. Only an explicit false is a failure.
+        return accepted !== false;
     }
     addToHistory(envelope) {
         // Don't store heartbeat or file chunk traffic in history.
@@ -221,6 +230,7 @@ export class MessageBus extends EventEmitter {
         if (!text)
             return;
         for (const trigger of this.triggers) {
+            trigger.pattern.lastIndex = 0;
             if (trigger.pattern.test(text)) {
                 try {
                     trigger.handler(envelope);

package/dist/vdo-bridge.js

@@ -24,7 +24,7 @@ export class VDOBridge extends EventEmitter {
     skills;
     status = "idle";
     statusDetail = "";
-    version = "0.1.2";
+    version = "0.1.4";
     agentProfile;
     viewedStreamIds = new Set();
     constructor(options) {
@@ -62,12 +62,13 @@ export class VDOBridge extends EventEmitter {
         // Set the send function on the bus
         this.bus.setSendDataFn((data, target) => {
             if (!this.sdk)
-                return;
+                return false;
             try {
-                this.sdk.sendData(data, target ?? undefined);
+                return this.sdk.sendData(data, target ?? undefined) !== false;
             }
             catch (err) {
                 this.emitBridgeError(err);
+                return false;
             }
         });
         await this.sdk.connect();
@@ -181,17 +182,15 @@ export class VDOBridge extends EventEmitter {
             return false;
         try {
             if (!targetStreamId) {
-                this.sdk.sendData(data, { allowFallback: true });
-                return true;
+                return this.sdk.sendData(data, { allowFallback: true }) !== false;
             }
             const peer = this.peers.getPeer(targetStreamId);
             if (peer?.uuid) {
-                this.sdk.sendData(data, { UUID: peer.uuid, allowFallback: true });
+                return this.sdk.sendData(data, { uuid: peer.uuid, allowFallback: true }) !== false;
             }
             else {
-                this.sdk.sendData(data, { streamID: targetStreamId, allowFallback: true });
+                return this.sdk.sendData(data, { streamID: targetStreamId, allowFallback: true }) !== false;
             }
-            return true;
         }
         catch (err) {
             this.emitBridgeError(err);
@@ -288,6 +287,7 @@ export class VDOBridge extends EventEmitter {
             switch (envelope.type) {
                 case "announce":
                     this.peers.updateFromAnnounce(senderStreamId, envelope.from, envelope.payload);
+                    this.bus.flushOfflineQueue(senderStreamId);
                     this.emit("peer:announce", { streamId: senderStreamId, identity: envelope.from, announce: envelope.payload });
                     break;
                 case "skill_update":

package/docs/protocol-and-reliability.md

@@ -0,0 +1,38 @@
+# Protocol and reliability
+
+`ninja-p2p` is an agent coordination layer over VDO.Ninja WebRTC data channels. It does not replace or extend VDO.Ninja signaling.
+
+## Layers
+
+1. The VDO.Ninja SDK joins a room, discovers published stream IDs, and establishes WebRTC peer connections and data channels.
+2. `VDOBridge` asks the SDK to view discovered peers as data-only connections.
+3. `MessageBus` sends a versioned JSON envelope through those channels.
+4. The optional sidecar stores inbox and outbox records on the local machine so a turn-based agent can read them later.
+
+The application envelope contains an ID, timestamp, sender identity, message type, optional target/topic, and payload. It is data carried through VDO.Ninja, not a new WebSocket command.
+
+## Delivery semantics
+
+- Direct messages are sent when the SDK accepts them for an open data channel.
+- If a known peer is offline, or the channel exists but is not ready yet, the message is queued in memory.
+- A queue flush retries the original envelope, including its message ID and type, and removes only messages the SDK accepted. A failed flush leaves the remaining messages in order for the next channel-open or announce event.
+- The persistent CLI sidecar additionally stores actions on disk before its live process sends them.
+- There is no durable remote broker and no exactly-once guarantee. Applications that require confirmation should use message IDs with `ack` or `command_response` and make handlers idempotent.
+- Room broadcasts are best-effort. They are not retained independently for every absent peer.
+
+## Connection race this prevents
+
+WebRTC emits several milestones. `peerConnected` can occur before `dataChannelOpen`. Older code treated the first event as send-ready, so an agent replying in that interval could receive a normal-looking local envelope even though the SDK rejected the send. The bridge now observes the SDK's boolean send result and queues an explicitly rejected direct message.
+
+A second race occurred during reconnect: the queue was deleted before replay attempts. If the data channel closed between the open event and the first replay, every queued message was lost locally. Queue entries now remain until each replay is accepted.
+
+## Compatibility
+
+- The wire envelope format is unchanged.
+- Existing send callbacks that return `void` remain accepted; only an explicit `false` means the transport rejected a send.
+- SDK targets use the SDK's documented `{ uuid }` or `{ streamID }` forms.
+- Existing VDO.Ninja room and signaling behavior remains authoritative.
+
+## Security boundary
+
+WebRTC encrypts data in transit. Room names and optional VDO.Ninja passwords control discovery/connection behavior, but they are not an application authorization system. Validate commands at the receiving agent, expose only intentional shared folders, and do not treat peer-supplied names or capabilities as trusted identity claims.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vdoninja/ninja-p2p",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Open source P2P agent messaging and coordination over VDO.Ninja WebRTC data channels",
   "type": "module",
   "main": "./dist/index.js",
@@ -48,6 +48,8 @@
     "dist",
     "dashboard.html",
     "README.md",
+    "docs/images/agent-room-dashboard.png",
+    "docs/protocol-and-reliability.md",
     ".codex/skills/ninja-p2p",
     ".agents/skills/ninja-p2p",
     ".claude/skills/ninja-p2p"
@@ -57,6 +59,7 @@
     "test": "tsx --test tests/**/*.test.ts",
     "prebuild": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
     "build": "tsc -p tsconfig.json",
+    "check": "npm test && npm run build",
     "validate:live": "node ./scripts/validate-live.mjs",
     "sync:docs": "node -e \"const fs=require('node:fs'); fs.mkdirSync('docs',{recursive:true}); fs.copyFileSync('dashboard.html','docs/index.html');\"",
     "prepare": "npm run build"
@@ -95,7 +98,7 @@
   },
   "homepage": "https://github.com/steveseguin/ninja-p2p#readme",
   "dependencies": {
-    "@vdoninja/sdk": "^1.3.18"
+    "@vdoninja/sdk": "^1.4.0"
   },
   "peerDependencies": {
     "@roamhq/wrtc": "^0.8.0"