@vdoninja/ninja-p2p 0.1.1 → 0.1.4

package/dist/shared-folders.js

@@ -0,0 +1,137 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+export function parseSharedFolderSpecs(rawValues, cwd = process.cwd()) {
+    const shares = [];
+    const seen = new Set();
+    for (const raw of rawValues.map((value) => value.trim()).filter(Boolean)) {
+        const separatorIndex = raw.indexOf("=");
+        if (separatorIndex <= 0 || separatorIndex === raw.length - 1) {
+            throw new Error(`invalid share spec: ${raw}; use --share name=path`);
+        }
+        const name = raw.slice(0, separatorIndex).trim();
+        const folderPath = raw.slice(separatorIndex + 1).trim();
+        if (!/^[A-Za-z0-9._-]+$/.test(name)) {
+            throw new Error(`invalid share name: ${name}`);
+        }
+        const key = name.toLowerCase();
+        if (seen.has(key)) {
+            throw new Error(`duplicate share name: ${name}`);
+        }
+        const resolved = path.resolve(cwd, folderPath);
+        if (!existsSync(resolved)) {
+            throw new Error(`shared folder does not exist: ${resolved}`);
+        }
+        const stats = statSync(resolved);
+        if (!stats.isDirectory()) {
+            throw new Error(`shared folder is not a directory: ${resolved}`);
+        }
+        seen.add(key);
+        shares.push({
+            name,
+            path: resolved,
+        });
+    }
+    return shares;
+}
+export function toSharedFolderSummaries(sharedFolders) {
+    return sharedFolders.map((share) => {
+        const summary = { name: share.name };
+        if (share.description)
+            summary.description = share.description;
+        return summary;
+    });
+}
+export function listSharedFolderEntries(sharedFolders, shareName, relativePath = "", maxEntries = 200) {
+    const share = requireSharedFolder(sharedFolders, shareName);
+    const resolved = resolveSharedPath(share, relativePath);
+    const stats = statSync(resolved.filePath);
+    if (!stats.isDirectory()) {
+        throw new Error(`shared path is not a directory: ${resolved.path || "."}`);
+    }
+    const entries = readdirSync(resolved.filePath, { withFileTypes: true })
+        .map((entry) => {
+        const childPath = resolved.path ? `${resolved.path}/${entry.name}` : entry.name;
+        const absolutePath = path.join(resolved.filePath, entry.name);
+        if (entry.isDirectory()) {
+            return {
+                name: entry.name,
+                path: childPath,
+                type: "dir",
+                size: null,
+            };
+        }
+        return {
+            name: entry.name,
+            path: childPath,
+            type: "file",
+            size: statSync(absolutePath).size,
+        };
+    })
+        .sort((a, b) => Number(a.type === "file") - Number(b.type === "file") || a.name.localeCompare(b.name));
+    return {
+        share: share.name,
+        path: resolved.path,
+        entries: entries.slice(0, Math.max(1, maxEntries)),
+        truncated: entries.length > maxEntries,
+    };
+}
+export function resolveSharedFile(sharedFolders, shareName, relativePath) {
+    const share = requireSharedFolder(sharedFolders, shareName);
+    const resolved = resolveSharedPath(share, relativePath);
+    const stats = statSync(resolved.filePath);
+    if (!stats.isFile()) {
+        throw new Error(`shared path is not a file: ${resolved.path || "."}`);
+    }
+    return {
+        share: share.name,
+        path: resolved.path,
+        filePath: resolved.filePath,
+        name: path.basename(resolved.filePath),
+        kind: inferTransferKind(resolved.filePath),
+        size: stats.size,
+    };
+}
+export function inferTransferKind(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    if ([".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg", ".bmp"].includes(ext)) {
+        return "image";
+    }
+    return "file";
+}
+function requireSharedFolder(sharedFolders, shareName) {
+    const share = sharedFolders.find((item) => item.name.toLowerCase() === shareName.trim().toLowerCase());
+    if (!share) {
+        throw new Error(`unknown share: ${shareName}`);
+    }
+    return share;
+}
+function resolveSharedPath(share, relativePath) {
+    const normalized = normalizeRelativeSharePath(relativePath);
+    const target = path.resolve(share.path, normalized || ".");
+    if (target !== share.path && !target.startsWith(`${share.path}${path.sep}`)) {
+        throw new Error("shared path escapes the declared folder");
+    }
+    if (!existsSync(target)) {
+        throw new Error(`shared path does not exist: ${normalized || "."}`);
+    }
+    return {
+        filePath: target,
+        path: normalized,
+    };
+}
+function normalizeRelativeSharePath(relativePath) {
+    const raw = relativePath.replace(/\\/g, "/").trim();
+    if (!raw)
+        return "";
+    if (raw.startsWith("/")) {
+        throw new Error("shared path must be relative");
+    }
+    const normalized = path.posix.normalize(raw);
+    if (normalized === ".." || normalized.startsWith("../")) {
+        throw new Error("shared path escapes the declared folder");
+    }
+    if (normalized.includes("/../")) {
+        throw new Error("shared path escapes the declared folder");
+    }
+    return normalized === "." ? "" : normalized;
+}

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 MessageType, type PeerIdentity } from "./protocol.js";
+import { type AgentProfile, type FileOfferPayload, type AnnouncePayload, type MessageEnvelope, type MessageType, type PeerIdentity } from "./protocol.js";
 export type VDOBridgeOptions = {
     room: string;
     streamId: string;
@@ -23,6 +23,8 @@ export type VDOBridgeOptions = {
     skills?: string[];
     /** Topics to subscribe to. */
     topics?: string[];
+    /** Optional agent profile advertised to peers. */
+    agentProfile?: AgentProfile;
     /** Heartbeat interval in ms. Default: 30000. */
     heartbeatMs?: number;
     /** MessageBus options. */
@@ -40,14 +42,19 @@ export declare class VDOBridge extends EventEmitter {
     private status;
     private statusDetail;
     private version;
+    private agentProfile;
+    private readonly viewedStreamIds;
     constructor(options: VDOBridgeOptions);
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     isConnected(): boolean;
+    private emitBridgeError;
     /** Update skills and broadcast the change. */
     updateSkills(skills: string[]): void;
     /** Update status and broadcast the change. */
     updateStatus(status: string, detail?: string): void;
+    /** Update the advertised agent profile and broadcast the change. */
+    updateAgentProfile(profile: AgentProfile): void;
     /** Get current announce payload. */
     getAnnouncePayload(): AnnouncePayload;
     /** Send a chat message to everyone or a specific peer. */
@@ -58,6 +65,10 @@ 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 a file to a connected peer. */
+    sendFile(targetStreamId: string, filePath: string): FileOfferPayload;
+    /** Send an image to a connected peer. */
+    sendImage(targetStreamId: string, filePath: string): FileOfferPayload;
     /** 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. */
@@ -75,4 +86,5 @@ export declare class VDOBridge extends EventEmitter {
     private stopHeartbeat;
     private respondPong;
     private broadcastSkillUpdate;
+    private maybeViewPeer;
 }

package/dist/vdo-bridge.js

@@ -8,6 +8,7 @@
  * Zero dependencies on stevesbot internals.
  */
 import { EventEmitter } from "node:events";
+import { sendFileFromPath } from "./file-transfer.js";
 import { MessageBus } from "./message-bus.js";
 import { PeerRegistry } from "./peer-registry.js";
 import { createEnvelope, createInstanceId, envelopeToWire, parseEnvelope, } from "./protocol.js";
@@ -23,7 +24,9 @@ export class VDOBridge extends EventEmitter {
     skills;
     status = "idle";
     statusDetail = "";
-    version = "0.1.1";
+    version = "0.1.4";
+    agentProfile;
+    viewedStreamIds = new Set();
     constructor(options) {
         super();
         this.options = options;
@@ -34,6 +37,7 @@ export class VDOBridge extends EventEmitter {
             instanceId: createInstanceId(),
         };
         this.skills = options.skills ?? [];
+        this.agentProfile = options.agentProfile;
         this.peers = new PeerRegistry();
         this.bus = new MessageBus(this.identity, this.peers, options.busOptions);
         // Subscribe to requested topics
@@ -58,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.emit("error", err);
+                this.emitBridgeError(err);
+                return false;
             }
         });
         await this.sdk.connect();
@@ -100,6 +105,7 @@ export class VDOBridge extends EventEmitter {
         catch { /* best effort */ }
         this.connected = false;
         this.sdk = null;
+        this.viewedStreamIds.clear();
         this.peers.clear();
         console.log("[P2P] Disconnected.");
         this.emit("disconnected");
@@ -107,6 +113,13 @@ export class VDOBridge extends EventEmitter {
     isConnected() {
         return this.connected;
     }
+    emitBridgeError(err) {
+        if (this.listenerCount("error") > 0) {
+            this.emit("error", err);
+            return;
+        }
+        console.error("[P2P] Bridge error:", err);
+    }
     // ── Identity Management ──────────────────────────────────────────────────
     /** Update skills and broadcast the change. */
     updateSkills(skills) {
@@ -119,6 +132,11 @@ export class VDOBridge extends EventEmitter {
         this.statusDetail = detail ?? "";
         this.broadcastSkillUpdate();
     }
+    /** Update the advertised agent profile and broadcast the change. */
+    updateAgentProfile(profile) {
+        this.agentProfile = profile;
+        this.broadcastSkillUpdate();
+    }
     /** Get current announce payload. */
     getAnnouncePayload() {
         return {
@@ -127,6 +145,7 @@ export class VDOBridge extends EventEmitter {
             statusDetail: this.statusDetail,
             version: this.version,
             topics: this.bus.getSubscriptions(),
+            agent: this.agentProfile,
         };
     }
     // ── Convenience Methods ──────────────────────────────────────────────────
@@ -149,26 +168,32 @@ export class VDOBridge extends EventEmitter {
     publishEvent(topic, kind, data) {
         return this.bus.publish(topic, "event", { kind, ...((data && typeof data === "object") ? data : { data }) });
     }
+    /** Send a file to a connected peer. */
+    sendFile(targetStreamId, filePath) {
+        return sendFileFromPath(this, targetStreamId, filePath, "file");
+    }
+    /** Send an image to a connected peer. */
+    sendImage(targetStreamId, filePath) {
+        return sendFileFromPath(this, targetStreamId, filePath, "image");
+    }
     /** 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;
+                return this.sdk.sendData(data, { allowFallback: true }) !== false;
             }
             const peer = this.peers.getPeer(targetStreamId);
             if (peer?.uuid) {
-                this.sdk.sendData(data, { UUID: peer.uuid });
+                return this.sdk.sendData(data, { uuid: peer.uuid, allowFallback: true }) !== false;
             }
             else {
-                this.sdk.sendData(data, { streamID: targetStreamId });
+                return this.sdk.sendData(data, { streamID: targetStreamId, allowFallback: true }) !== false;
             }
-            return true;
         }
         catch (err) {
-            this.emit("error", err);
+            this.emitBridgeError(err);
             return false;
         }
     }
@@ -262,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":
@@ -297,6 +323,7 @@ export class VDOBridge extends EventEmitter {
         this.sdk.addEventListener("peerDisconnected", (event) => {
             const uuid = event.detail?.uuid ?? "unknown";
             const streamId = event.detail?.streamID ?? this.peers.streamIdForUuid(uuid) ?? uuid;
+            this.viewedStreamIds.delete(streamId);
             this.peers.markDisconnected(streamId);
             console.log(`[P2P] Peer disconnected: ${streamId}`);
             this.emit("peer:disconnected", { streamId, uuid });
@@ -315,15 +342,20 @@ export class VDOBridge extends EventEmitter {
             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 });
+                    this.maybeViewPeer(entry.streamID);
                 }
             }
         });
+        this.sdk.addEventListener("videoaddedtoroom", (event) => {
+            this.maybeViewPeer(event.detail?.streamID);
+        });
+        this.sdk.addEventListener("streamAdded", (event) => {
+            this.maybeViewPeer(event.detail?.streamID);
+        });
         // Error handling
         this.sdk.addEventListener("error", (event) => {
             console.error("[P2P] SDK error:", event.detail?.error);
-            this.emit("error", event.detail?.error);
+            this.emitBridgeError(event.detail?.error);
         });
     }
     // ── Heartbeat ────────────────────────────────────────────────────────────
@@ -371,6 +403,20 @@ export class VDOBridge extends EventEmitter {
             skills: this.skills,
             status: this.status,
             statusDetail: this.statusDetail,
+            agent: this.agentProfile,
         });
     }
+    maybeViewPeer(streamId) {
+        if (!this.sdk || !streamId || streamId === this.options.streamId || this.viewedStreamIds.has(streamId)) {
+            return;
+        }
+        this.viewedStreamIds.add(streamId);
+        try {
+            this.sdk.view(streamId, { audio: false, video: false });
+        }
+        catch (err) {
+            this.viewedStreamIds.delete(streamId);
+            this.emitBridgeError(err);
+        }
+    }
 }

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,10 +1,13 @@
 {
   "name": "@vdoninja/ninja-p2p",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "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",
+  "bin": {
+    "ninja-p2p": "./dist/cli.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -22,6 +25,18 @@
       "types": "./dist/peer-registry.d.ts",
       "import": "./dist/peer-registry.js"
     },
+    "./file-transfer": {
+      "types": "./dist/file-transfer.d.ts",
+      "import": "./dist/file-transfer.js"
+    },
+    "./agent-state": {
+      "types": "./dist/agent-state.d.ts",
+      "import": "./dist/agent-state.js"
+    },
+    "./shared-folders": {
+      "types": "./dist/shared-folders.d.ts",
+      "import": "./dist/shared-folders.js"
+    },
     "./protocol": {
       "types": "./dist/protocol.d.ts",
       "import": "./dist/protocol.js"
@@ -33,13 +48,20 @@
     "dist",
     "dashboard.html",
     "README.md",
-    "skills/ninja-p2p"
+    "docs/images/agent-room-dashboard.png",
+    "docs/protocol-and-reliability.md",
+    ".codex/skills/ninja-p2p",
+    ".agents/skills/ninja-p2p",
+    ".claude/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",
+    "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"
   },
   "keywords": [
@@ -48,6 +70,10 @@
     "vdo.ninja",
     "agent",
     "agent-mesh",
+    "cli",
+    "codex",
+    "claude-code",
+    "skill",
     "pub-sub",
     "data-channel",
     "bot",
@@ -72,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"

package/skills/ninja-p2p/SKILL.md

@@ -1,70 +0,0 @@
----
-name: ninja-p2p
-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 when a project needs agents to meet in a room and talk to each other over WebRTC.
-
-## What It Gives You
-
-- `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
-
-```bash
-npm install @vdoninja/ninja-p2p @roamhq/wrtc
-```
-
-`@vdoninja/sdk` is installed automatically. `ws` comes from the SDK in Node.
-
-## Default Pattern
-
-1. Pick a shared `room`.
-2. Give each peer a unique `streamId`.
-3. Connect with `VDOBridge`.
-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
-
-```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.
-- Private messages target peer `streamId`s.
-- Topic messages are broadcast and filtered on the receiver side.
-- 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.