@vdoninja/ninja-p2p 0.1.4 → 0.2.0

package/dist/demo.js

@@ -0,0 +1,186 @@
+/**
+ * Live Self-Test
+ *
+ * Getting two agents talking used to take six commands and a room-name
+ * copy-paste, which is where most people gave up. `ninja-p2p demo` does the
+ * whole round trip in one command: two peers connect, find each other over
+ * WebRTC, exchange messages both ways, and complete a request/response.
+ *
+ * It doubles as a diagnostic. If this passes, the transport works on this
+ * machine and network, and any remaining problem is configuration.
+ */
+import { VDOBridge } from "./vdo-bridge.js";
+import { generateRoomName } from "./protocol.js";
+export const DEMO_ALICE = "demo_alice";
+export const DEMO_BOB = "demo_bob";
+export async function runDemo(options = {}) {
+    const room = options.room || generateRoomName();
+    const timeoutMs = options.timeoutMs ?? 20_000;
+    const password = options.password ?? false;
+    const log = options.log ?? (() => { });
+    const steps = [];
+    const alice = new VDOBridge({
+        room,
+        streamId: DEMO_ALICE,
+        identity: { streamId: DEMO_ALICE, role: "agent", name: "Alice" },
+        password,
+        skills: ["chat", "command"],
+        topics: ["events"],
+    });
+    const bob = new VDOBridge({
+        room,
+        streamId: DEMO_BOB,
+        identity: { streamId: DEMO_BOB, role: "agent", name: "Bob" },
+        password,
+        skills: ["chat", "command"],
+        topics: ["events"],
+    });
+    // Bob answers the demo command himself so the request/response leg is a real
+    // round trip rather than a message we quietly resolve locally.
+    bob.bus.on("message:command", (envelope) => {
+        const payload = envelope.payload;
+        if (payload.command === "ping") {
+            bob.commandResponse(envelope, { pong: true, from: DEMO_BOB });
+        }
+    });
+    const plan = [
+        {
+            name: "connect",
+            run: async () => {
+                await Promise.all([alice.connect(), bob.connect()]);
+                return `both peers joined room ${room}`;
+            },
+        },
+        {
+            name: "discover",
+            run: async () => {
+                await Promise.all([
+                    waitForPeer(alice, DEMO_BOB, timeoutMs),
+                    waitForPeer(bob, DEMO_ALICE, timeoutMs),
+                ]);
+                return "peers found each other over WebRTC";
+            },
+        },
+        {
+            name: "direct message",
+            run: async () => {
+                const received = waitForMessage(bob, "message:chat", DEMO_ALICE, timeoutMs);
+                alice.chat("hello from Alice", DEMO_BOB);
+                return `Bob received "${textOf(await received)}"`;
+            },
+        },
+        {
+            name: "reply",
+            run: async () => {
+                const received = waitForMessage(alice, "message:chat", DEMO_BOB, timeoutMs);
+                bob.chat("hello back from Bob", DEMO_ALICE);
+                return `Alice received "${textOf(await received)}"`;
+            },
+        },
+        {
+            name: "command",
+            run: async () => {
+                const received = waitForMessage(alice, "message:command_response", DEMO_BOB, timeoutMs);
+                alice.command(DEMO_BOB, "ping");
+                const envelope = await received;
+                const payload = envelope.payload;
+                return `Bob answered ${JSON.stringify(payload.result ?? envelope.payload)}`;
+            },
+        },
+    ];
+    try {
+        for (const item of plan) {
+            const startedAt = Date.now();
+            try {
+                const detail = await item.run();
+                steps.push({ name: item.name, ok: true, detail, ms: Date.now() - startedAt });
+                log(`  ok    ${item.name.padEnd(15)} ${detail}`);
+            }
+            catch (error) {
+                steps.push({
+                    name: item.name,
+                    ok: false,
+                    detail: errorMessage(error),
+                    ms: Date.now() - startedAt,
+                });
+                log(`  FAIL  ${item.name.padEnd(15)} ${errorMessage(error)}`);
+                // Later steps assume the earlier ones worked, so stop at the first break.
+                break;
+            }
+        }
+        if (options.hold && steps.length === plan.length && steps.every((step) => step.ok)) {
+            await options.hold(room);
+        }
+    }
+    finally {
+        await Promise.allSettled([alice.disconnect(), bob.disconnect()]);
+    }
+    return {
+        room,
+        ok: steps.length === plan.length && steps.every((step) => step.ok),
+        steps,
+    };
+}
+export function formatDemoResult(result, dashboardUrl) {
+    const lines = ["", result.ok ? "Demo passed." : "Demo failed."];
+    if (result.ok) {
+        lines.push("", "Two peers connected, found each other, and exchanged messages both ways", "with no server of your own. The same transport backs the agent sidecars.", "", "Watch a room like this in the browser:", `  ${dashboardUrl}`, "", "Start real agents in one room:", "  ninja-p2p start --id claude", "  ninja-p2p room --id claude", "  ninja-p2p start --room <that-room> --id codex", "", "Let them act on their own:", "  ninja-p2p start --id claude --on-message \"claude -p 'Check your ninja-p2p inbox'\"");
+    }
+    else {
+        const failed = result.steps.find((step) => !step.ok);
+        lines.push("", `First failure: ${failed?.name ?? "unknown"} — ${failed?.detail ?? "no detail"}`, "", "Run `ninja-p2p doctor` to check Node, WebRTC, and signaling reachability.");
+    }
+    return lines.join("\n");
+}
+function waitForPeer(bridge, streamId, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        if (bridge.peers.getPeer(streamId)?.identity) {
+            resolve();
+            return;
+        }
+        const cleanup = () => {
+            clearTimeout(timer);
+            bridge.off("peer:announce", onAnnounce);
+        };
+        const timer = setTimeout(() => {
+            cleanup();
+            reject(new Error(`timed out after ${timeoutMs}ms waiting for ${streamId}`));
+        }, timeoutMs);
+        const onAnnounce = (payload) => {
+            if (payload.streamId !== streamId)
+                return;
+            cleanup();
+            resolve();
+        };
+        bridge.on("peer:announce", onAnnounce);
+    });
+}
+function waitForMessage(bridge, event, fromStreamId, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            clearTimeout(timer);
+            bridge.bus.off(event, onMessage);
+        };
+        const timer = setTimeout(() => {
+            cleanup();
+            reject(new Error(`timed out after ${timeoutMs}ms waiting for ${event} from ${fromStreamId}`));
+        }, timeoutMs);
+        const onMessage = (envelope) => {
+            if (envelope.from.streamId !== fromStreamId)
+                return;
+            cleanup();
+            resolve(envelope);
+        };
+        bridge.bus.on(event, onMessage);
+    });
+}
+function textOf(envelope) {
+    const payload = envelope.payload;
+    if (typeof payload !== "object" || payload === null)
+        return "";
+    const text = payload.text;
+    return typeof text === "string" ? text : "";
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/doctor.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Diagnostics
+ *
+ * When a P2P connection fails, the user has no idea whether the problem is the
+ * native WebRTC module, the network, the room name, or a sidecar that quietly
+ * died. `ninja-p2p doctor` answers that in one command so "it does not connect"
+ * becomes an actionable report instead of a support thread.
+ */
+export type CheckStatus = "ok" | "warn" | "fail";
+export type DiagnosticCheck = {
+    name: string;
+    status: CheckStatus;
+    detail: string;
+    hint?: string;
+};
+export type DiagnosticsReport = {
+    ok: boolean;
+    checks: DiagnosticCheck[];
+};
+export declare const MINIMUM_NODE_MAJOR = 20;
+export declare const DEFAULT_SIGNALING_URL = "wss://wss.vdo.ninja";
+/** Node 20 is the documented floor; below that the ESM + native combo breaks. */
+export declare function checkNodeVersion(version: string): DiagnosticCheck;
+/**
+ * The native WebRTC module is optional for the library but required for a Node
+ * sidecar to actually hold a data channel. `doctor` diagnoses the Node sidecar,
+ * so reporting success without it sends users toward network debugging when
+ * the process cannot possibly connect.
+ */
+export declare function checkWebRtc(load?: () => Promise<unknown>): Promise<DiagnosticCheck>;
+/** Confirm the VDO.Ninja signaling server is reachable before blaming NAT. */
+export declare function checkSignaling(url?: string, timeoutMs?: number): Promise<DiagnosticCheck>;
+/** A sidecar that cannot write its state folder will fail in confusing ways. */
+export declare function checkStateRoot(stateRoot: string): DiagnosticCheck;
+export type SidecarSnapshot = {
+    id: string;
+    room: string | null;
+    pid: number | null;
+    running: boolean;
+};
+/** Report sidecars this machine believes it started, and whether they survived. */
+export declare function checkSidecars(stateRoot: string, readSession: (dir: string) => {
+    room?: string;
+    streamId?: string;
+    pid?: number;
+} | null, isRunning: (pid: number) => boolean): {
+    check: DiagnosticCheck;
+    sidecars: SidecarSnapshot[];
+};
+/** A report fails only on hard failures; warnings are survivable. */
+export declare function summarizeChecks(checks: DiagnosticCheck[]): DiagnosticsReport;
+export declare function formatReport(report: DiagnosticsReport, sidecars: SidecarSnapshot[]): string;

package/dist/doctor.js

@@ -0,0 +1,219 @@
+/**
+ * Diagnostics
+ *
+ * When a P2P connection fails, the user has no idea whether the problem is the
+ * native WebRTC module, the network, the room name, or a sidecar that quietly
+ * died. `ninja-p2p doctor` answers that in one command so "it does not connect"
+ * becomes an actionable report instead of a support thread.
+ */
+import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+export const MINIMUM_NODE_MAJOR = 20;
+export const DEFAULT_SIGNALING_URL = "wss://wss.vdo.ninja";
+const OPTIONAL_WEBRTC_MODULE = "@roamhq/wrtc";
+/** Node 20 is the documented floor; below that the ESM + native combo breaks. */
+export function checkNodeVersion(version) {
+    const major = Number.parseInt(version.replace(/^v/, "").split(".")[0] ?? "", 10);
+    if (!Number.isFinite(major)) {
+        return {
+            name: "node",
+            status: "warn",
+            detail: `could not parse Node version "${version}"`,
+        };
+    }
+    if (major < MINIMUM_NODE_MAJOR) {
+        return {
+            name: "node",
+            status: "fail",
+            detail: `Node ${version} is below the required v${MINIMUM_NODE_MAJOR}`,
+            hint: `install Node ${MINIMUM_NODE_MAJOR} or newer`,
+        };
+    }
+    return { name: "node", status: "ok", detail: `Node ${version}` };
+}
+/**
+ * The native WebRTC module is optional for the library but required for a Node
+ * sidecar to actually hold a data channel. `doctor` diagnoses the Node sidecar,
+ * so reporting success without it sends users toward network debugging when
+ * the process cannot possibly connect.
+ */
+export async function checkWebRtc(load = () => import(OPTIONAL_WEBRTC_MODULE)) {
+    try {
+        await load();
+        return { name: "webrtc", status: "ok", detail: "@roamhq/wrtc is installed" };
+    }
+    catch (error) {
+        return {
+            name: "webrtc",
+            status: "fail",
+            detail: `@roamhq/wrtc not loadable: ${errorMessage(error)}`,
+            hint: "npm install -g @roamhq/wrtc (Node sidecars need it to hold data channels)",
+        };
+    }
+}
+/** Confirm the VDO.Ninja signaling server is reachable before blaming NAT. */
+export async function checkSignaling(url = DEFAULT_SIGNALING_URL, timeoutMs = 8000) {
+    const startedAt = Date.now();
+    let SocketImpl = globalThis.WebSocket;
+    if (!SocketImpl) {
+        try {
+            const ws = await import("ws");
+            SocketImpl = (ws.default ?? ws);
+        }
+        catch (error) {
+            return {
+                name: "signaling",
+                status: "warn",
+                detail: `no WebSocket implementation available: ${errorMessage(error)}`,
+                hint: "use Node 22+, which ships a global WebSocket",
+            };
+        }
+    }
+    return new Promise((resolve) => {
+        let settled = false;
+        let socket;
+        const finish = (check) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            try {
+                socket?.close();
+            }
+            catch {
+                // The socket may already be closed; nothing useful to do here.
+            }
+            resolve(check);
+        };
+        const timer = setTimeout(() => {
+            finish({
+                name: "signaling",
+                status: "fail",
+                detail: `no response from ${url} within ${timeoutMs}ms`,
+                hint: "check your firewall or proxy; outbound wss:// must be allowed",
+            });
+        }, timeoutMs);
+        try {
+            socket = new SocketImpl(url);
+        }
+        catch (error) {
+            finish({
+                name: "signaling",
+                status: "fail",
+                detail: `could not open ${url}: ${errorMessage(error)}`,
+            });
+            return;
+        }
+        socket.onopen = () => {
+            finish({
+                name: "signaling",
+                status: "ok",
+                detail: `${url} reachable in ${Date.now() - startedAt}ms`,
+            });
+        };
+        socket.onerror = () => {
+            finish({
+                name: "signaling",
+                status: "fail",
+                detail: `could not reach ${url}`,
+                hint: "check your firewall or proxy; outbound wss:// must be allowed",
+            });
+        };
+    });
+}
+/** A sidecar that cannot write its state folder will fail in confusing ways. */
+export function checkStateRoot(stateRoot) {
+    const probe = path.join(stateRoot, ".doctor-write-probe");
+    try {
+        mkdirSync(stateRoot, { recursive: true });
+        writeFileSync(probe, "ok", "utf8");
+        rmSync(probe, { force: true });
+        return { name: "state", status: "ok", detail: `${stateRoot} is writable` };
+    }
+    catch (error) {
+        return {
+            name: "state",
+            status: "fail",
+            detail: `cannot write ${stateRoot}: ${errorMessage(error)}`,
+            hint: "set NINJA_STATE_DIR to a writable folder",
+        };
+    }
+}
+/** Report sidecars this machine believes it started, and whether they survived. */
+export function checkSidecars(stateRoot, readSession, isRunning) {
+    if (!existsSync(stateRoot)) {
+        return {
+            check: { name: "sidecars", status: "ok", detail: "no sidecars have been started yet" },
+            sidecars: [],
+        };
+    }
+    const sidecars = [];
+    for (const entry of safeReadDir(stateRoot)) {
+        const session = readSession(path.join(stateRoot, entry));
+        if (!session)
+            continue;
+        const pid = typeof session.pid === "number" ? session.pid : null;
+        sidecars.push({
+            id: session.streamId ?? entry,
+            room: session.room ?? null,
+            pid,
+            running: pid !== null && isRunning(pid),
+        });
+    }
+    const live = sidecars.filter((sidecar) => sidecar.running);
+    if (sidecars.length === 0) {
+        return {
+            check: { name: "sidecars", status: "ok", detail: "no sidecars have been started yet" },
+            sidecars,
+        };
+    }
+    const stale = sidecars.length - live.length;
+    return {
+        check: {
+            name: "sidecars",
+            status: live.length > 0 || stale === 0 ? "ok" : "warn",
+            detail: `${live.length} running, ${stale} stopped`,
+            hint: stale > 0 && live.length === 0 ? "start one with: ninja-p2p start --id <name>" : undefined,
+        },
+        sidecars,
+    };
+}
+/** A report fails only on hard failures; warnings are survivable. */
+export function summarizeChecks(checks) {
+    return {
+        ok: checks.every((check) => check.status !== "fail"),
+        checks,
+    };
+}
+export function formatReport(report, sidecars) {
+    const symbols = { ok: "ok  ", warn: "warn", fail: "FAIL" };
+    const lines = ["ninja-p2p doctor", ""];
+    for (const check of report.checks) {
+        lines.push(`[${symbols[check.status]}] ${check.name.padEnd(10)} ${check.detail}`);
+        if (check.hint) {
+            lines.push(`${" ".repeat(18)}-> ${check.hint}`);
+        }
+    }
+    if (sidecars.length > 0) {
+        lines.push("", "Sidecars:");
+        for (const sidecar of sidecars) {
+            const state = sidecar.running ? `running pid=${sidecar.pid}` : "stopped";
+            lines.push(`  ${sidecar.id.padEnd(16)} ${state}  room=${sidecar.room ?? "unknown"}`);
+        }
+    }
+    lines.push("", report.ok ? "All required checks passed." : "Some checks failed; see hints above.");
+    return lines.join("\n");
+}
+function safeReadDir(dir) {
+    try {
+        return readdirSync(dir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+    }
+    catch {
+        return [];
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/file-transfer.d.ts

@@ -1,6 +1,14 @@
 import { type FileAckPayload, type FileChunkPayload, type FileCompletePayload, type FileOfferPayload, type FileTransferKind, type PeerIdentity } from "./protocol.js";
 import type { VDOBridge } from "./vdo-bridge.js";
 export declare const DEFAULT_TRANSFER_CHUNK_SIZE = 12000;
+/** The simple transfer path buffers at the sender; use swarm transfer above this. */
+export declare const MAX_BASIC_TRANSFER_SIZE: number;
+export declare const MAX_BASIC_TRANSFER_CHUNK_SIZE: number;
+export declare const MAX_BASIC_TRANSFER_CHUNKS: number;
+export declare const MAX_INCOMPLETE_TRANSFER_BYTES: number;
+export declare const MAX_INCOMPLETE_TRANSFERS = 16;
+export declare const INCOMPLETE_TRANSFER_STALE_MS: number;
+export declare const TRANSFER_ID_PATTERN: RegExp;
 export type PreparedFileTransfer = {
     name: string;
     filePath: string;
@@ -42,11 +50,16 @@ export declare function prepareFileTransferFromPath(filePath: string, kind?: Fil
 export declare function sendPreparedFileTransfer(bridge: VDOBridge, targetStreamId: string, prepared: PreparedFileTransfer, chunkSize?: number): FileOfferPayload;
 export declare function sendFileFromPath(bridge: VDOBridge, targetStreamId: string, filePath: string, kind?: FileTransferKind, chunkSize?: number): FileOfferPayload;
 export declare function beginIncomingTransfer(stateDir: string, from: PeerIdentity, offer: FileOfferPayload): IncomingTransferManifest;
-export declare function appendIncomingTransferChunk(stateDir: string, payload: FileChunkPayload): IncomingTransferManifest;
-export declare function completeIncomingTransfer(stateDir: string, payload: FileCompletePayload): CompletedTransferResult;
+export declare function appendIncomingTransferChunk(stateDir: string, payload: FileChunkPayload, fromStreamId?: string): IncomingTransferManifest;
+export declare function completeIncomingTransfer(stateDir: string, payload: FileCompletePayload, fromStreamId?: string): CompletedTransferResult;
 export declare function createFileAckPayload(result: CompletedTransferResult): FileAckPayload;
 export declare function createFailedFileAckPayload(transferId: string, error: unknown): FileAckPayload;
 export declare function readTransferManifest(stateDir: string, transferId: string): IncomingTransferManifest | null;
+/**
+ * Remove a transfer that cannot be completed. Sender matching prevents a peer
+ * from aborting somebody else's transfer by guessing its id.
+ */
+export declare function discardIncomingTransfer(stateDir: string, transferId: string, expectedSender?: string): boolean;
 export declare function sha256Hex(bytes: Uint8Array): string;
 export declare function bytesToBase64(bytes: Uint8Array): string;
 export declare function base64ToBytes(value: string): Uint8Array;