@vdoninja/ninja-p2p 0.1.2 → 0.2.0

package/dist/cli-lib.d.ts

@@ -1,5 +1,6 @@
 import { type AgentProfile } from "./protocol.js";
 import { type SharedFolderConfig } from "./shared-folders.js";
+import { type WakeConfig } from "./wake.js";
 export type CliCommonOptions = {
     room: string;
     streamId: string;
@@ -10,6 +11,7 @@ export type CliCommonOptions = {
     stateDir: string | null;
     agentProfile?: AgentProfile;
     sharedFolders: SharedFolderConfig[];
+    wake: WakeConfig | null;
 };
 export type SkillRuntime = "claude" | "codex";
 export type CliCommand = {
@@ -43,6 +45,42 @@ export type CliCommand = {
     stateDir: string;
     take: number;
     peek: boolean;
+} | {
+    kind: "wait";
+    stateDir: string;
+    timeoutMs: number;
+    intervalMs: number;
+} | {
+    kind: "doctor";
+    stateRoot: string;
+} | {
+    kind: "seed";
+    options: CliCommonOptions;
+    filePath: string;
+    chunkSize: number;
+} | {
+    kind: "fetch";
+    options: CliCommonOptions;
+    query: string;
+    outDir: string | null;
+    keepSeeding: boolean;
+    timeoutMs: number;
+} | {
+    kind: "demo";
+    room: string | null;
+    password: string | false;
+    timeoutMs: number;
+    keep: boolean;
+} | {
+    kind: "ssn";
+    options: CliCommonOptions;
+    session: string;
+    topic: string;
+    host: string;
+    inChannel: number;
+    outChannel: number;
+    echo: boolean;
+    readOnly: boolean;
 } | {
     kind: "connect";
     options: CliCommonOptions;
@@ -130,3 +168,5 @@ export declare function parseJsonMaybe(value: string): unknown;
 export declare function getSkillInstallTarget(runtime: SkillRuntime, env?: NodeJS.ProcessEnv): string;
 export declare function getSkillInstallTargets(runtime: SkillRuntime, env?: NodeJS.ProcessEnv): string[];
 export declare function getDefaultStateDir(streamId: string, env?: NodeJS.ProcessEnv): string;
+/** Parent folder holding every sidecar's state, used by `doctor`. */
+export declare function getStateRoot(env?: NodeJS.ProcessEnv): string;

package/dist/cli-lib.js

@@ -1,15 +1,41 @@
 import path from "node:path";
 import { createMessageId, generateRoomName } from "./protocol.js";
 import { parseSharedFolderSpecs, toSharedFolderSummaries } from "./shared-folders.js";
+import { DEFAULT_WAKE_DEBOUNCE_MS, DEFAULT_WAKE_LIMIT_PER_MINUTE, } from "./wake.js";
+import { DEFAULT_SSN_HOST, DEFAULT_SSN_IN_CHANNEL, DEFAULT_SSN_OUT_CHANNEL, DEFAULT_SSN_TOPIC, } from "./social-stream.js";
+import { DEFAULT_SWARM_CHUNK_SIZE } from "./swarm.js";
 export function helpText() {
     return [
         "ninja-p2p",
+        "A shared room and handoff layer that lets separate AI tools work as a team.",
         "",
         "Start here:",
         "  ninja-p2p menu",
+        "  ninja-p2p demo",
         "  ninja-p2p start --id claude",
         "  ninja-p2p start --id codex",
         "",
+        "Troubleshooting:",
+        "  ninja-p2p doctor",
+        "",
+        "Swarm file transfer (every downloader becomes a source):",
+        "  ninja-p2p seed ./big-file.zip --room my-room",
+        "  ninja-p2p fetch big-file.zip --room my-room --out ./downloads",
+        "  ninja-p2p fetch <file-id> --room my-room --seed",
+        "",
+        "  --seed              keep serving after the download finishes",
+        "  --out <dir>         where finished files land",
+        "  --chunk-size <n>    bytes per chunk (default 64000)",
+        "",
+        "Live chat bridge (Social Stream Ninja):",
+        "  ninja-p2p ssn --session <id> --room ai-room --read-only",
+        "  ninja-p2p ssn --session <ssn-session-id> --room ai-room",
+        "  ninja-p2p ssn --session <id> --room ai-room --topic social --read-only --echo",
+        "",
+        "  Publishes Twitch/YouTube/Kick chat into the room as shared team input.",
+        "  Start read-only. Without it, an agent can reply to every platform at once:",
+        "    ninja-p2p command --id claude social say '{\"text\":\"hi chat\"}'",
+        "",
         "Install:",
         "  npm install -g @vdoninja/ninja-p2p @roamhq/wrtc",
         "  ninja-p2p install-skill codex",
@@ -37,6 +63,20 @@ export function helpText() {
         "  ninja-p2p command --id codex claude capabilities",
         "  ninja-p2p stop --id codex",
         "",
+        "Wake on incoming messages (agents act without a human turn):",
+        "  ninja-p2p start --id claude --on-message \"claude -p 'Check your ninja-p2p inbox'\"",
+        "  ninja-p2p start --id codex --on-message \"codex exec 'Check your ninja-p2p inbox'\"",
+        "  ninja-p2p wait --id codex && echo \"mail arrived\"",
+        "  while ninja-p2p wait --id codex; do codex exec 'handle inbox'; done",
+        "",
+        "  --on-message <cmd>      shell command to run when messages arrive",
+        "  --wake-debounce <ms>    batch window before firing (default 750)",
+        "  --wake-limit <n>        max wakes per minute, 0 = unlimited (default 30)",
+        "  --timeout <ms>          wait: give up after this long, 0 = forever",
+        "",
+        "  The wake command receives NINJA_ID, NINJA_STATE_DIR, NINJA_WAKE_COUNT,",
+        "  NINJA_WAKE_FROM, NINJA_WAKE_TYPES, and NINJA_WAKE_TEXT.",
+        "",
         "Use:",
         "  ninja-p2p connect --room my-room --name Claude",
         "  ninja-p2p chat --room my-room --name Steve \"hello\"",
@@ -86,6 +126,24 @@ export function parseCliArgs(argv, env = process.env) {
             },
         };
     }
+    if (kind === "demo") {
+        const parsedDemo = parseOptions(args, env);
+        const passwordValue = getSingleValue(parsedDemo.values, "password") ?? env.NINJA_PASSWORD;
+        return {
+            kind,
+            room: getSingleValue(parsedDemo.values, "room") || null,
+            password: passwordValue === "false" ? false : (passwordValue || false),
+            timeoutMs: parsePositiveInt(getSingleValue(parsedDemo.values, "timeout"), 20_000),
+            keep: parsedDemo.flags.has("keep"),
+        };
+    }
+    if (kind === "doctor") {
+        const parsedDoctor = parseOptions(args, env);
+        return {
+            kind,
+            stateRoot: getSingleValue(parsedDoctor.values, "state-root") || getStateRoot(env),
+        };
+    }
     if (kind === "install-skill") {
         const runtime = (args.shift() ?? "").toLowerCase();
         if (runtime !== "codex" && runtime !== "claude") {
@@ -133,6 +191,77 @@ export function parseCliArgs(argv, env = process.env) {
                 take: parsePositiveInt(getSingleValue(parsed.values, "take"), 20),
                 peek: getSingleValue(parsed.values, "peek") === "true",
             };
+        case "wait":
+            return {
+                kind,
+                stateDir: resolveStateDir(parsed.values, env),
+                // 0 means wait indefinitely, which is what a `while` loop wants.
+                timeoutMs: parseNonNegativeInt(getSingleValue(parsed.values, "timeout"), 0),
+                intervalMs: parsePositiveInt(getSingleValue(parsed.values, "interval"), 500),
+            };
+        case "seed":
+            {
+                if (positional.length < 1) {
+                    throw new Error("seed requires a file path");
+                }
+                const options = buildCommonOptions(parsed.values, env, {
+                    requireRoom: false,
+                    requireStateDir: false,
+                    allowGeneratedRoom: true,
+                });
+                return {
+                    kind,
+                    options,
+                    filePath: positional.join(" "),
+                    chunkSize: parsePositiveInt(getSingleValue(parsed.values, "chunk-size"), DEFAULT_SWARM_CHUNK_SIZE),
+                };
+            }
+        case "fetch":
+            {
+                if (positional.length < 1) {
+                    throw new Error("fetch requires a file id or name");
+                }
+                const options = buildCommonOptions(parsed.values, env, {
+                    requireRoom: true,
+                    requireStateDir: false,
+                });
+                return {
+                    kind,
+                    options,
+                    query: positional.join(" "),
+                    outDir: getSingleValue(parsed.values, "out") ?? null,
+                    keepSeeding: parsed.flags.has("seed"),
+                    timeoutMs: parseNonNegativeInt(getSingleValue(parsed.values, "timeout"), 300_000),
+                };
+            }
+        case "ssn":
+            {
+                const session = getSingleValue(parsed.values, "session") || env.SSN_SESSION || positional[0];
+                if (!session) {
+                    throw new Error("ssn requires a Social Stream Ninja session id; use --session <id>");
+                }
+                const options = buildCommonOptions(parsed.values, env, {
+                    requireRoom: false,
+                    requireStateDir: false,
+                    allowGeneratedRoom: true,
+                });
+                return {
+                    kind,
+                    options: {
+                        ...options,
+                        name: getSingleValue(parsed.values, "name") || env.NINJA_NAME || "Social Stream",
+                        streamId: getSingleValue(parsed.values, "id") || env.NINJA_ID || "social",
+                        role: getSingleValue(parsed.values, "role") || env.NINJA_ROLE || "bridge",
+                    },
+                    session,
+                    topic: getSingleValue(parsed.values, "topic") || DEFAULT_SSN_TOPIC,
+                    host: getSingleValue(parsed.values, "ssn-host") || env.SSN_HOST || DEFAULT_SSN_HOST,
+                    inChannel: parseNonNegativeInt(getSingleValue(parsed.values, "in-channel"), DEFAULT_SSN_IN_CHANNEL),
+                    outChannel: parseNonNegativeInt(getSingleValue(parsed.values, "out-channel"), DEFAULT_SSN_OUT_CHANNEL),
+                    echo: parsed.flags.has("echo"),
+                    readOnly: parsed.flags.has("read-only"),
+                };
+            }
         case "connect":
             return { kind, options: buildCommonOptions(parsed.values, env, { requireRoom: false, requireStateDir: false, allowGeneratedRoom: true }) };
         case "chat":
@@ -402,15 +531,22 @@ export function getSkillInstallTargets(runtime, env = process.env) {
     return [primary];
 }
 export function getDefaultStateDir(streamId, env = process.env) {
+    return path.join(getStateRoot(env), streamId);
+}
+/** Parent folder holding every sidecar's state, used by `doctor`. */
+export function getStateRoot(env = process.env) {
     const home = env.USERPROFILE || env.HOME;
     if (!home) {
         throw new Error("cannot determine home directory");
     }
-    return path.join(home, ".ninja-p2p", streamId);
+    return path.join(home, ".ninja-p2p");
 }
+/** Flags that stand alone. Everything else still requires an explicit value. */
+const BOOLEAN_FLAGS = new Set(["keep", "echo", "read-only", "seed"]);
 function parseOptions(argv, env) {
     const values = {};
     const positional = [];
+    const flags = new Set();
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
         if (!arg.startsWith("--")) {
@@ -418,6 +554,10 @@ function parseOptions(argv, env) {
             continue;
         }
         const key = arg.slice(2);
+        if (BOOLEAN_FLAGS.has(key)) {
+            flags.add(key);
+            continue;
+        }
         const next = argv[i + 1];
         if (!next || next.startsWith("--")) {
             throw new Error(`missing value for --${key}`);
@@ -448,6 +588,8 @@ function parseOptions(argv, env) {
         values["state-dir"] = env.NINJA_STATE_DIR;
     if (!values["wait-ms"] && env.NINJA_WAIT_MS)
         values["wait-ms"] = env.NINJA_WAIT_MS;
+    if (!values["on-message"] && env.NINJA_ON_MESSAGE)
+        values["on-message"] = env.NINJA_ON_MESSAGE;
     if (!values.runtime && env.NINJA_RUNTIME)
         values.runtime = env.NINJA_RUNTIME;
     if (!values.provider && env.NINJA_PROVIDER)
@@ -464,7 +606,7 @@ function parseOptions(argv, env) {
         values.ask = env.NINJA_ASKS.split(";").map((item) => item.trim()).filter(Boolean);
     if (!values.share && env.NINJA_SHARE)
         values.share = env.NINJA_SHARE.split(";").map((item) => item.trim()).filter(Boolean);
-    return { values, positional };
+    return { values, positional, flags };
 }
 function buildCommonOptions(values, env, options) {
     const requireRoom = options?.requireRoom ?? true;
@@ -499,6 +641,7 @@ function buildCommonOptions(values, env, options) {
         stateDir,
         agentProfile,
         sharedFolders,
+        wake: buildWakeConfig(values, env),
     };
 }
 function resolveStateDir(values, env, fallbackStreamId) {
@@ -519,6 +662,26 @@ function parsePositiveInt(raw, fallback) {
         return fallback;
     return value;
 }
+function parseNonNegativeInt(raw, fallback) {
+    if (!raw)
+        return fallback;
+    const value = Number.parseInt(raw, 10);
+    if (!Number.isFinite(value) || value < 0)
+        return fallback;
+    return value;
+}
+function buildWakeConfig(values, env) {
+    const command = (getSingleValue(values, "on-message") || env.NINJA_ON_MESSAGE || "").trim();
+    if (!command)
+        return null;
+    return {
+        command,
+        debounceMs: parseNonNegativeInt(getSingleValue(values, "wake-debounce") ?? env.NINJA_WAKE_DEBOUNCE, DEFAULT_WAKE_DEBOUNCE_MS),
+        // 0 disables the rate limit. Keep a default ceiling so a pair of agents
+        // that reply to each other cannot spin unattended forever.
+        limitPerMinute: parseNonNegativeInt(getSingleValue(values, "wake-limit") ?? env.NINJA_WAKE_LIMIT, DEFAULT_WAKE_LIMIT_PER_MINUTE),
+    };
+}
 function shouldUseStateMode(values, env) {
     if (getSingleValue(values, "state-dir") || env.NINJA_STATE_DIR)
         return true;

package/dist/cli.d.ts

@@ -23,3 +23,5 @@ export declare function buildSidecarCommandResponse(bridge: VDOBridge, stateDir:
 export declare function maybeHandleSidecarCommand(bridge: VDOBridge, stateDir: string, envelope: MessageEnvelope): boolean;
 export declare function createPeerNoticeEnvelope(peerIdentity: PeerIdentity, kind: "peer_discovered" | "peer_updated" | "peer_left", details: Record<string, unknown>): MessageEnvelope;
 export declare function recordPeerNotice(fingerprints: Map<string, string>, peerIdentity: PeerIdentity, kind: "peer_discovered" | "peer_updated", details: Record<string, unknown>): MessageEnvelope | null;
+export declare const DASHBOARD_URL = "https://steveseguin.github.io/ninja-p2p/dashboard.html";
+export declare function buildDashboardUrl(room: string, password: string | false): string;