@vdoninja/ninja-p2p 0.1.4 → 0.2.0

package/dist/cli.js

@@ -1,17 +1,23 @@
 #!/usr/bin/env node
 import { closeSync, cpSync, existsSync, mkdirSync, openSync } from "node:fs";
 import { spawn } from "node:child_process";
+import os from "node:os";
 import path from "node:path";
 import process from "node:process";
 import readline from "node:readline";
 import { setTimeout as delay } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
-import { appendIncomingTransferChunk, beginIncomingTransfer, completeIncomingTransfer, createFailedFileAckPayload, createFileAckPayload, sendFileFromPath, } from "./file-transfer.js";
+import { appendIncomingTransferChunk, beginIncomingTransfer, completeIncomingTransfer, createFailedFileAckPayload, createFileAckPayload, discardIncomingTransfer, sendFileFromPath, } from "./file-transfer.js";
 import { VDOBridge } from "./vdo-bridge.js";
 import { createEnvelope, envelopeToWire, } from "./protocol.js";
 import { ensureAgentState, getInboxSummary, isInboxWorthy, listQueuedAgentActions, queueAgentAction, readAgentSession, readPeersSnapshot, removeQueuedAgentAction, storeInboxMessage, takeInboxMessages, writeAgentSession, writePeersSnapshot, } from "./agent-state.js";
 import { getDefaultStateDir, getSkillInstallTarget, getSkillInstallTargets, helpText, parseCliArgs, parseJsonMaybe, } from "./cli-lib.js";
 import { listSharedFolderEntries, resolveSharedFile, } from "./shared-folders.js";
+import { DEFAULT_WAKE_DEBOUNCE_MS, DEFAULT_WAKE_LIMIT_PER_MINUTE, WakeRunner, } from "./wake.js";
+import { formatDemoResult, runDemo } from "./demo.js";
+import { describeSocialMessage, SocialStreamBridge } from "./social-stream.js";
+import { SwarmManager } from "./swarm-manager.js";
+import { checkNodeVersion, checkSidecars, checkSignaling, checkStateRoot, checkWebRtc, formatReport, summarizeChecks, } from "./doctor.js";
 const SIDECAR_SKILLS = ["cli", "chat", "command", "sidecar", "discovery"];
 export const SIDECAR_DISCOVERY_ASKS = [
     { name: "help", description: "Summarize this agent sidecar and its built-in commands.", via: "command", example: "ninja-p2p command --id <you> <peer> help" },
@@ -75,6 +81,24 @@ async function main(argv) {
                 messages: takeInboxMessages(parsed.stateDir, parsed.take, parsed.peek).map((item) => item.envelope),
             }, null, 2));
             return;
+        case "wait":
+            await waitForInbox(parsed.stateDir, parsed.timeoutMs, parsed.intervalMs);
+            return;
+        case "doctor":
+            await runDoctor(parsed.stateRoot);
+            return;
+        case "demo":
+            await runDemoCommand(parsed.room, parsed.password, parsed.timeoutMs, parsed.keep);
+            return;
+        case "seed":
+            await runSeed(parsed.options, parsed.filePath, parsed.chunkSize);
+            return;
+        case "fetch":
+            await runFetch(parsed.options, parsed.query, parsed.outDir, parsed.keepSeeding, parsed.timeoutMs);
+            return;
+        case "ssn":
+            await runSocialStreamBridge(parsed);
+            return;
         case "connect":
             await runConnect(parsed.options);
             return;
@@ -500,6 +524,19 @@ async function runAgent(options) {
     const advertisedProfile = composeSidecarAgentProfile(options.agentProfile);
     const peerFingerprints = new Map();
     let shuttingDown = false;
+    // Wake hooks fire on real peer traffic only. Peer join/leave notices are
+    // generated locally and would otherwise wake the agent every reconnect.
+    const wake = options.wake
+        ? new WakeRunner({
+            config: options.wake,
+            context: {
+                streamId: options.streamId,
+                room: options.room,
+                stateDir: options.stateDir,
+            },
+            log: (message) => console.log(message),
+        })
+        : null;
     const syncSession = (connected = bridge.isConnected()) => {
         writeAgentSession(options.stateDir, {
             room: options.room,
@@ -576,6 +613,10 @@ async function runAgent(options) {
     await bridge.connect();
     syncSession(true);
     console.log(`agent ready: ${options.streamId} -> ${options.stateDir}`);
+    if (options.wake) {
+        console.log(`wake on message: ${options.wake.command}`);
+        console.log(`wake debounce=${options.wake.debounceMs}ms limit=${options.wake.limitPerMinute || "unlimited"}/min`);
+    }
     bridge.on("peer:connected", () => {
         syncSession(true);
     });
@@ -638,6 +679,7 @@ async function runAgent(options) {
         const autoHandled = transferHandled || maybeHandleSidecarCommand(bridge, options.stateDir, envelope);
         if (!autoHandled && isInboxWorthy(envelope.type)) {
             storeInboxMessage(options.stateDir, envelope);
+            wake?.notify(envelope);
             console.log(`[inbox] ${envelope.type} from ${envelope.from.streamId}`);
         }
         else if (transferHandled) {
@@ -659,6 +701,7 @@ async function runAgent(options) {
             return;
         shuttingDown = true;
         clearInterval(heartbeatTimer);
+        wake?.dispose();
         syncSession(false);
         await bridge.disconnect();
         syncSession(false);
@@ -898,6 +941,7 @@ function maybeHandleSidecarFileTransfer(bridge, stateDir, envelope) {
 }
 function handleIncomingFileOffer(bridge, stateDir, envelope) {
     const payload = envelope.payload;
+    const transferId = transferIdForError(envelope.payload);
     try {
         beginIncomingTransfer(stateDir, envelope.from, payload);
         storeInboxMessage(stateDir, createFileTransferEventEnvelope(envelope.from, "file_offered", {
@@ -910,9 +954,9 @@ function handleIncomingFileOffer(bridge, stateDir, envelope) {
         }));
     }
     catch (error) {
-        bridge.bus.send(envelope.from.streamId, "file_ack", createFailedFileAckPayload(payload.transferId, error));
+        bridge.bus.send(envelope.from.streamId, "file_ack", createFailedFileAckPayload(transferId, error));
         storeInboxMessage(stateDir, createFileTransferEventEnvelope(envelope.from, "file_receive_failed", {
-            transferId: payload.transferId,
+            transferId,
             error: error instanceof Error ? error.message : String(error),
         }));
     }
@@ -920,13 +964,15 @@ function handleIncomingFileOffer(bridge, stateDir, envelope) {
 }
 function handleIncomingFileChunk(bridge, stateDir, envelope) {
     const payload = envelope.payload;
+    const transferId = transferIdForError(envelope.payload);
     try {
-        appendIncomingTransferChunk(stateDir, payload);
+        appendIncomingTransferChunk(stateDir, payload, envelope.from.streamId);
     }
     catch (error) {
-        bridge.bus.send(envelope.from.streamId, "file_ack", createFailedFileAckPayload(payload.transferId, error));
+        discardIncomingTransfer(stateDir, transferId, envelope.from.streamId);
+        bridge.bus.send(envelope.from.streamId, "file_ack", createFailedFileAckPayload(transferId, error));
         storeInboxMessage(stateDir, createFileTransferEventEnvelope(envelope.from, "file_receive_failed", {
-            transferId: payload.transferId,
+            transferId,
             error: error instanceof Error ? error.message : String(error),
         }));
     }
@@ -934,22 +980,28 @@ function handleIncomingFileChunk(bridge, stateDir, envelope) {
 }
 function handleIncomingFileComplete(bridge, stateDir, envelope) {
     const payload = envelope.payload;
+    const transferId = transferIdForError(envelope.payload);
     try {
-        const completed = completeIncomingTransfer(stateDir, payload);
+        const completed = completeIncomingTransfer(stateDir, payload, envelope.from.streamId);
         bridge.bus.send(envelope.from.streamId, "file_ack", createFileAckPayload(completed));
         storeInboxMessage(stateDir, createReceivedFileEventEnvelope(envelope.from, completed));
     }
     catch (error) {
-        bridge.bus.send(envelope.from.streamId, "file_ack", createFailedFileAckPayload(payload.transferId, error));
+        discardIncomingTransfer(stateDir, transferId, envelope.from.streamId);
+        bridge.bus.send(envelope.from.streamId, "file_ack", createFailedFileAckPayload(transferId, error));
         storeInboxMessage(stateDir, createFileTransferEventEnvelope(envelope.from, "file_receive_failed", {
-            transferId: payload.transferId,
+            transferId,
             error: error instanceof Error ? error.message : String(error),
         }));
     }
     return true;
 }
 function handleIncomingFileAck(stateDir, envelope) {
+    if (typeof envelope.payload !== "object" || envelope.payload === null)
+        return true;
     const payload = envelope.payload;
+    if (typeof payload.transferId !== "string" || typeof payload.ok !== "boolean")
+        return true;
     storeInboxMessage(stateDir, createFileTransferEventEnvelope(envelope.from, payload.ok ? "file_delivered" : "file_delivery_failed", {
         transferId: payload.transferId,
         name: payload.name ?? null,
@@ -962,6 +1014,12 @@ function handleIncomingFileAck(stateDir, envelope) {
     }));
     return true;
 }
+function transferIdForError(payload) {
+    if (typeof payload !== "object" || payload === null)
+        return "invalid";
+    const transferId = payload.transferId;
+    return typeof transferId === "string" && transferId ? transferId.slice(0, 128) : "invalid";
+}
 function createReceivedFileEventEnvelope(from, completed) {
     return createFileTransferEventEnvelope(from, "file_received", {
         transferId: completed.transferId,
@@ -1317,8 +1375,416 @@ function buildAgentArgs(options) {
     for (const share of options.sharedFolders) {
         args.push("--share", `${share.name}=${share.path}`);
     }
+    if (options.wake) {
+        args.push("--on-message", options.wake.command);
+        if (options.wake.debounceMs !== DEFAULT_WAKE_DEBOUNCE_MS) {
+            args.push("--wake-debounce", String(options.wake.debounceMs));
+        }
+        if (options.wake.limitPerMinute !== DEFAULT_WAKE_LIMIT_PER_MINUTE) {
+            args.push("--wake-limit", String(options.wake.limitPerMinute));
+        }
+    }
     return args;
 }
+function createSwarmBridge(options, name, role) {
+    return new VDOBridge({
+        room: options.room,
+        streamId: options.streamId,
+        identity: { streamId: options.streamId, role, name },
+        password: options.password,
+        skills: ["swarm", "file-transfer"],
+        topics: [],
+    });
+}
+function swarmWorkDir() {
+    return path.join(os.tmpdir(), "ninja-p2p-swarm");
+}
+/** Publish a file to the room and serve it until interrupted. */
+async function runSeed(options, filePath, chunkSize) {
+    const bridge = createSwarmBridge(options, options.name || "Seeder", "seeder");
+    const manager = new SwarmManager({
+        bridge,
+        downloadDir: path.resolve("."),
+        workDir: swarmWorkDir(),
+        log: (message) => console.log(message),
+    });
+    await bridge.connect();
+    manager.start();
+    const manifest = manager.seed(filePath, chunkSize);
+    console.log("");
+    console.log(`seeding ${manifest.name}`);
+    console.log(`  room:    ${options.room}`);
+    console.log(`  id:      ${options.streamId}`);
+    console.log(`  file id: ${manifest.fileId}`);
+    console.log(`  size:    ${formatBytes(manifest.size)} in ${manifest.totalChunks} chunk(s)`);
+    console.log("");
+    console.log("Fetch it from anywhere with:");
+    console.log(`  ninja-p2p fetch ${manifest.name} --room ${options.room}`);
+    console.log("");
+    console.log("Anyone who finishes also becomes a source. Press Ctrl+C to stop.");
+    let shuttingDown = false;
+    const shutdown = async () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        manager.stop();
+        await bridge.disconnect();
+    };
+    process.on("SIGINT", () => { void shutdown(); });
+    process.on("SIGTERM", () => { void shutdown(); });
+    await new Promise((resolve) => {
+        bridge.once("disconnected", () => resolve());
+    });
+}
+/** Download a file from whoever in the room has it. */
+async function runFetch(options, query, outDir, keepSeeding, timeoutMs) {
+    const downloadDir = path.resolve(outDir ?? ".");
+    const bridge = createSwarmBridge(options, options.name || "Fetcher", "fetcher");
+    let done = null;
+    let failed = null;
+    const finished = new Promise((resolve) => { done = resolve; });
+    const manager = new SwarmManager({
+        bridge,
+        downloadDir,
+        workDir: swarmWorkDir(),
+        log: (message) => console.log(message),
+        onComplete: (completion) => done?.(completion),
+        onError: (message) => {
+            failed = message;
+            done?.(null);
+        },
+    });
+    await bridge.connect();
+    manager.start();
+    console.log(`joined ${options.room} as ${options.streamId}, looking for "${query}"`);
+    // Offers arrive on announce, so give the room a moment before giving up.
+    const deadline = timeoutMs > 0
+        ? Date.now() + Math.min(timeoutMs, 60_000)
+        : Number.POSITIVE_INFINITY;
+    let manifest = manager.resolveOffer(query);
+    while (!manifest && Date.now() < deadline) {
+        await delay(500);
+        manifest = manager.resolveOffer(query);
+    }
+    if (!manifest) {
+        const offers = manager.knownOffers();
+        console.error(`no offer matching "${query}" in room ${options.room}`);
+        if (offers.length > 0) {
+            console.error("available:");
+            for (const offer of offers) {
+                console.error(`  ${offer.name}  ${offer.fileId.slice(0, 16)}  ${formatBytes(offer.size)}`);
+            }
+        }
+        manager.stop();
+        await bridge.disconnect();
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`fetching ${manifest.name} (${formatBytes(manifest.size)}, ${manifest.totalChunks} chunks)`);
+    const startedAt = Date.now();
+    const accepted = manager.fetch(manifest.fileId);
+    if (!accepted && failed) {
+        console.error(failed);
+        manager.stop();
+        await bridge.disconnect();
+        process.exitCode = 1;
+        return;
+    }
+    const progressTimer = setInterval(() => {
+        const progress = manager.sessionFor(manifest.fileId)?.progress();
+        if (progress && !progress.complete) {
+            console.log(`  ${progress.percent}%  ${progress.haveChunks}/${progress.totalChunks} chunks  ${progress.peers} peer(s)  ${progress.inFlight} in flight`);
+        }
+    }, 2_000);
+    progressTimer.unref?.();
+    const timeoutTimer = timeoutMs > 0 ? setTimeout(() => done?.(null), timeoutMs) : null;
+    timeoutTimer?.unref?.();
+    const completion = await finished;
+    clearInterval(progressTimer);
+    if (timeoutTimer)
+        clearTimeout(timeoutTimer);
+    if (!completion) {
+        const progress = manager.sessionFor(manifest.fileId)?.progress();
+        if (failed) {
+            console.error(failed);
+        }
+        else {
+            console.error(`timed out after ${formatDuration(Date.now() - startedAt)} at ${progress?.percent ?? 0}%`);
+        }
+        manager.stop();
+        await bridge.disconnect();
+        process.exitCode = 1;
+        return;
+    }
+    const elapsed = Date.now() - startedAt;
+    console.log("");
+    console.log(`saved ${completion.savedPath}`);
+    console.log(`  ${formatBytes(completion.manifest.size)} in ${formatDuration(elapsed)} (${formatRate(completion.manifest.size, elapsed)})`);
+    if (keepSeeding) {
+        console.log("");
+        console.log("Still seeding for other peers. Press Ctrl+C to stop.");
+        let shuttingDown = false;
+        const shutdown = async () => {
+            if (shuttingDown)
+                return;
+            shuttingDown = true;
+            manager.stop();
+            await bridge.disconnect();
+        };
+        process.on("SIGINT", () => { void shutdown(); });
+        process.on("SIGTERM", () => { void shutdown(); });
+        await new Promise((resolve) => {
+            bridge.once("disconnected", () => resolve());
+        });
+        return;
+    }
+    manager.stop();
+    await bridge.disconnect();
+}
+function formatBytes(size) {
+    if (size < 1024)
+        return `${size} B`;
+    if (size < 1024 * 1024)
+        return `${(size / 1024).toFixed(1)} KB`;
+    if (size < 1024 * 1024 * 1024)
+        return `${(size / (1024 * 1024)).toFixed(1)} MB`;
+    return `${(size / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}
+function formatDuration(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    return `${(ms / 1000).toFixed(1)}s`;
+}
+function formatRate(bytes, ms) {
+    if (ms <= 0)
+        return "n/a";
+    return `${formatBytes(Math.round((bytes * 1000) / ms))}/s`;
+}
+/**
+ * Bridge Social Stream Ninja's live chat into a ninja-p2p room.
+ *
+ * Inbound: every chat message SSN aggregates becomes a topic event, so agents
+ * can watch a stream's chat the same way they watch any other room traffic.
+ *
+ * Outbound: the bridge advertises a `say` command, so an agent that wants to
+ * answer chat sends one message and SSN fans it out to every connected
+ * platform. That is the whole co-host loop in two directions.
+ */
+async function runSocialStreamBridge(parsed) {
+    const { options } = parsed;
+    // An SSN session id grants everything: send chat, block users, clear
+    // overlays, fake donations. Until SSN can issue read-scoped credentials, this
+    // is the next best thing — the bridge structurally refuses to speak, so a
+    // compromised or over-eager agent in the room cannot reach the audience.
+    const readOnly = parsed.readOnly;
+    const bridge = new VDOBridge({
+        room: options.room,
+        streamId: options.streamId,
+        identity: {
+            streamId: options.streamId,
+            role: options.role,
+            name: options.name,
+        },
+        password: options.password,
+        skills: ["social", "chat", "command", "bridge"],
+        topics: [parsed.topic, "events"],
+        agentProfile: {
+            ...options.agentProfile,
+            summary: options.agentProfile?.summary
+                ?? (readOnly
+                    ? "Read-only bridge for live stream chat from Social Stream Ninja."
+                    : "Bridges live stream chat from Social Stream Ninja into this room."),
+            can: [...new Set([
+                    ...(options.agentProfile?.can ?? []),
+                    "social-chat",
+                    ...(readOnly ? [] : ["broadcast"]),
+                ])],
+            asks: [
+                ...(options.agentProfile?.asks ?? []),
+                // Do not advertise an ability we will refuse to perform.
+                ...(readOnly ? [] : [{
+                        name: "say",
+                        description: "Send a message out to every live chat platform connected to Social Stream Ninja.",
+                        via: "command",
+                        example: `ninja-p2p command --id <you> ${options.streamId} say '{"text":"hello chat"}'`,
+                    }]),
+            ],
+        },
+    });
+    let forwarded = 0;
+    const social = new SocialStreamBridge({
+        session: parsed.session,
+        host: parsed.host,
+        inChannel: parsed.inChannel,
+        outChannel: parsed.outChannel,
+        log: (message) => console.log(message),
+        onMessage: (message) => {
+            forwarded += 1;
+            bridge.publishEvent(parsed.topic, "social_chat", message);
+            if (parsed.echo) {
+                console.log(describeSocialMessage(message));
+            }
+        },
+    });
+    bridge.bus.on("message:command", (envelope) => {
+        const payload = envelope.payload;
+        if (payload.command !== "say")
+            return;
+        if (readOnly) {
+            // Refuse loudly. Silently dropping it would let an agent believe it spoke
+            // to the audience when nothing was said.
+            bridge.commandResponse(envelope, undefined, "bridge is running read-only; restart without --read-only to allow sending");
+            console.log(`[ssn] refused say from ${envelope.from.streamId} (read-only)`);
+            return;
+        }
+        const text = extractSayText(payload.args);
+        if (!text) {
+            bridge.commandResponse(envelope, undefined, "say requires text, e.g. '{\"text\":\"hello chat\"}'");
+            return;
+        }
+        // Report the truth: if the relay is down the message did not reach chat.
+        if (!social.isConnected()) {
+            bridge.commandResponse(envelope, undefined, "not connected to Social Stream Ninja");
+            return;
+        }
+        const sent = social.sendChat(text);
+        bridge.commandResponse(envelope, sent ? { sent: true, text } : undefined, sent ? undefined : "failed to send to Social Stream Ninja");
+        console.log(`[ssn] ${envelope.from.streamId} -> chat: ${text}`);
+    });
+    await bridge.connect();
+    social.connect();
+    console.log(`social stream bridge ready`);
+    console.log(`  room:    ${options.room}`);
+    console.log(`  id:      ${options.streamId}`);
+    console.log(`  session: ${parsed.session}`);
+    console.log(`  topic:   ${parsed.topic}`);
+    console.log("");
+    if (readOnly) {
+        console.log("Read-only: agents can watch chat but cannot send to it.");
+    }
+    else {
+        console.log("Agents in this room can reply to every platform with:");
+        console.log(`  ninja-p2p command --id <you> ${options.streamId} say '{"text":"hello chat"}'`);
+        console.log("");
+        console.log("Anything an agent says here reaches your real audience.");
+        console.log("Use --read-only if you only want them to watch.");
+    }
+    console.log("");
+    console.log("Press Ctrl+C to stop.");
+    let shuttingDown = false;
+    const shutdown = async () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        console.log(`\nforwarded ${forwarded} chat message(s)`);
+        social.close();
+        await bridge.disconnect();
+    };
+    process.on("SIGINT", () => { void shutdown(); });
+    process.on("SIGTERM", () => { void shutdown(); });
+    await new Promise((resolve) => {
+        bridge.once("disconnected", () => resolve());
+    });
+}
+function extractSayText(args) {
+    if (typeof args === "string")
+        return args.trim();
+    if (typeof args === "object" && args !== null) {
+        const value = args.text;
+        if (typeof value === "string")
+            return value.trim();
+    }
+    return "";
+}
+export const DASHBOARD_URL = "https://steveseguin.github.io/ninja-p2p/dashboard.html";
+export function buildDashboardUrl(room, password) {
+    const params = new URLSearchParams({
+        room,
+        password: password === false ? "false" : password,
+        name: "You",
+        autoconnect: "true",
+    });
+    return `${DASHBOARD_URL}?${params.toString()}`;
+}
+/** One-command proof that the transport works on this machine and network. */
+async function runDemoCommand(room, password, timeoutMs, keep) {
+    console.log("ninja-p2p demo");
+    console.log("");
+    console.log("Two peers, no server of your own. Watch the round trip:");
+    console.log("");
+    const result = await runDemo({
+        room: room ?? undefined,
+        password,
+        timeoutMs,
+        log: (message) => console.log(message),
+        hold: keep
+            ? async (activeRoom) => {
+                console.log("");
+                console.log("Both peers are still in the room. Open this to watch:");
+                console.log(`  ${buildDashboardUrl(activeRoom, password)}`);
+                console.log("");
+                console.log("Press Ctrl+C to stop.");
+                await new Promise((resolve) => {
+                    process.on("SIGINT", () => resolve());
+                    process.on("SIGTERM", () => resolve());
+                });
+            }
+            : undefined,
+    });
+    console.log(formatDemoResult(result, buildDashboardUrl(result.room, password)));
+    if (!result.ok) {
+        process.exitCode = 1;
+    }
+}
+/** Run every diagnostic and exit non-zero if a required one failed. */
+async function runDoctor(stateRoot) {
+    const checks = [checkNodeVersion(process.version)];
+    checks.push(await checkWebRtc());
+    checks.push(await checkSignaling());
+    checks.push(checkStateRoot(stateRoot));
+    const sidecars = checkSidecars(stateRoot, readAgentSession, isPidRunning);
+    checks.push(sidecars.check);
+    const report = summarizeChecks(checks);
+    console.log(formatReport(report, sidecars.sidecars));
+    if (!report.ok) {
+        process.exitCode = 1;
+    }
+}
+/**
+ * Block until the sidecar's inbox has something in it.
+ *
+ * This is the pull half of the wake story: `--on-message` pushes a turn at the
+ * agent, `wait` lets a shell loop pull one. Exit code 0 means mail arrived,
+ * 1 means the timeout elapsed, so `while ninja-p2p wait --id x; do ...; done`
+ * behaves the way a shell author expects.
+ */
+async function waitForInbox(stateDir, timeoutMs, intervalMs) {
+    const startedAt = Date.now();
+    for (;;) {
+        const summary = getInboxSummary(stateDir);
+        if (summary.pending > 0) {
+            console.log(JSON.stringify({
+                stateDir,
+                pending: summary.pending,
+                senders: summary.senders,
+                types: summary.types,
+                waitedMs: Date.now() - startedAt,
+            }, null, 2));
+            return;
+        }
+        if (timeoutMs > 0 && Date.now() - startedAt >= timeoutMs) {
+            console.log(JSON.stringify({
+                stateDir,
+                pending: 0,
+                timedOut: true,
+                waitedMs: Date.now() - startedAt,
+            }, null, 2));
+            process.exitCode = 1;
+            return;
+        }
+        await delay(intervalMs);
+    }
+}
 function isPidRunning(pid) {
     try {
         process.kill(pid, 0);
@@ -1328,9 +1794,34 @@ function isPidRunning(pid) {
         return false;
     }
 }
+/**
+ * End the process explicitly once a command is done.
+ *
+ * `@roamhq/wrtc` segfaults during normal process teardown if a data channel
+ * has ever existed, which corrupts the exit code (139/127) even on a fully
+ * successful run. Any script doing `ninja-p2p wait && ...` would break on it.
+ * Calling process.exit() skips the native teardown path and the crash with it,
+ * so every command ends through here rather than by draining the event loop.
+ *
+ * This is safe because `VDOBridge.disconnect()` already waits for the SDK to
+ * finish its own cleanup, so nothing meaningful is still in flight.
+ */
+async function exitCleanly() {
+    // Let buffered stdout reach the terminal or pipe before we cut the process off.
+    await new Promise((resolve) => {
+        if (process.stdout.write("")) {
+            resolve();
+            return;
+        }
+        process.stdout.once("drain", () => resolve());
+    });
+    process.exit(process.exitCode ?? 0);
+}
 const entry = process.argv[1] ? fileURLToPath(import.meta.url) === process.argv[1] : false;
 if (entry) {
-    main(process.argv.slice(2)).catch((error) => {
+    main(process.argv.slice(2))
+        .then(exitCleanly)
+        .catch((error) => {
         console.error(error instanceof Error ? error.message : String(error));
         process.exit(1);
     });

package/dist/demo.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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.
+ */
+export declare const DEMO_ALICE = "demo_alice";
+export declare const DEMO_BOB = "demo_bob";
+export type DemoStep = {
+    name: string;
+    ok: boolean;
+    detail: string;
+    ms: number;
+};
+export type DemoResult = {
+    room: string;
+    ok: boolean;
+    steps: DemoStep[];
+};
+export type DemoOptions = {
+    room?: string;
+    password?: string | false;
+    timeoutMs?: number;
+    log?: (message: string) => void;
+    /**
+     * Called once the round trip succeeds, while both peers are still connected.
+     * `--keep` uses it to hold the room open so it can be watched in the browser.
+     */
+    hold?: (room: string) => Promise<void>;
+};
+export declare function runDemo(options?: DemoOptions): Promise<DemoResult>;
+export declare function formatDemoResult(result: DemoResult, dashboardUrl: string): string;