clawnexus 0.0.1 → 0.2.0

package/README.md

@@ -1,8 +1,108 @@
-# ClawNexus
-
-> Discover, name, and connect OpenClaw instances across your network.
-
-**This package is under active development. Full release coming soon.**
-
-- GitHub: https://github.com/silverstreamsAI/ClawNexus
-- Author: alan-silverstreams <alan@silverstream.tech>
+# clawnexus
+
+ClawNexus daemon and CLI — AI instance registry for OpenClaw.
+
+Discovers OpenClaw instances on your local network, assigns human-readable aliases, and exposes an HTTP API for querying and managing them.
+
+## Installation
+
+```bash
+npm install -g clawnexus
+```
+
+Requires Node.js >= 22.
+
+## CLI Usage
+
+### Daemon Management
+
+```bash
+clawnexus start      # Start the daemon (background process)
+clawnexus stop       # Stop the daemon
+clawnexus restart    # Restart the daemon
+clawnexus status     # Show daemon status
+```
+
+### Instance Discovery
+
+```bash
+clawnexus scan       # Scan local network for OpenClaw instances
+clawnexus list       # List all known instances
+clawnexus list --json  # Machine-readable JSON output
+```
+
+### Instance Management
+
+```bash
+clawnexus alias <id|address> <name>   # Set a friendly alias
+clawnexus info <name|address>         # Show instance details
+clawnexus forget <name|address>       # Remove from registry
+```
+
+### Connection
+
+```bash
+clawnexus connect <name>       # Output ws:// address for an instance
+clawnexus open <name>          # Open WebChat UI in browser
+clawnexus relay status         # Show relay connection status
+clawnexus connect <name.claw>  # Connect via relay (v0.4)
+```
+
+### Global Flags
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--json` | Machine-readable JSON output | `false` |
+| `--timeout <ms>` | Request timeout | `5000` |
+| `--api <url>` | Daemon API URL | `http://localhost:17890` |
+
+## Daemon HTTP API
+
+The daemon listens on `http://localhost:17890` by default.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/health` | Daemon health status |
+| `GET` | `/instances` | List all instances |
+| `GET` | `/instances/:id` | Get a single instance |
+| `PUT` | `/instances/:id/alias` | Set/update alias |
+| `DELETE` | `/instances/:id` | Remove instance |
+| `POST` | `/scan` | Trigger network scan |
+| `POST` | `/relay/connect` | Connect via relay (v0.4) |
+| `GET` | `/relay/status` | Relay connection status |
+| `DELETE` | `/relay/disconnect/:room_id` | Disconnect relay room |
+
+See [docs/api.md](../../docs/api.md) for full request/response examples.
+
+## Configuration
+
+| Environment Variable | Description | Default |
+|---------------------|-------------|---------|
+| `CLAWNEXUS_PORT` | Daemon API port | `17890` |
+| `CLAWNEXUS_HOST` | Daemon bind address | `127.0.0.1` |
+| `CLAWNEXUS_API` | CLI target API URL | `http://localhost:17890` |
+
+Data is stored in `~/.clawnexus/`:
+
+```
+~/.clawnexus/
+├── registry.json    # Instance registry
+├── daemon.pid       # PID file
+└── policy.json      # Agent policy (v1.0)
+```
+
+## Programmatic Usage
+
+```typescript
+import { startDaemon } from "clawnexus";
+
+const handle = await startDaemon({ port: 17890, host: "127.0.0.1" });
+
+// Access components
+console.log(handle.store.getAll());  // List instances
+await handle.app.close();            // Graceful shutdown
+```
+
+## License
+
+MIT

package/dist/agent/engine.d.ts

@@ -0,0 +1,17 @@
+import type { PolicyConfig, PolicyDecision, LayerBEnvelope } from "./types.js";
+export declare class PolicyEngine {
+    private config;
+    private readonly configDir;
+    private readonly configPath;
+    private rateCounters;
+    constructor(configDir?: string);
+    init(): Promise<void>;
+    evaluate(envelope: LayerBEnvelope, peerTrustScore?: number): PolicyDecision;
+    getConfig(): PolicyConfig;
+    updateConfig(full: PolicyConfig): Promise<void>;
+    patchConfig(partial: Partial<PolicyConfig>): Promise<void>;
+    resetConfig(): Promise<void>;
+    private isRateLimited;
+    private incrementRate;
+    private saveConfig;
+}

package/dist/agent/engine.js

@@ -0,0 +1,231 @@
+"use strict";
+// Layer B — Policy Decision Engine
+// Evaluates inbound proposals against local policy config
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PolicyEngine = void 0;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const os = __importStar(require("node:os"));
+const CLAWNEXUS_DIR = path.join(os.homedir(), ".clawnexus");
+const POLICY_PATH = path.join(CLAWNEXUS_DIR, "policy.json");
+const DEFAULT_POLICY = {
+    mode: "queue",
+    trust_threshold: 50,
+    rate_limit: {
+        max_per_minute: 10,
+        max_per_peer_minute: 3,
+    },
+    delegation: {
+        allow: false,
+        max_depth: 3,
+    },
+    capability_filter: [],
+    access_control: {
+        whitelist: [],
+        blacklist: [],
+    },
+    auto_approve_types: [],
+    max_concurrent_tasks: 5,
+};
+class PolicyEngine {
+    config = { ...DEFAULT_POLICY };
+    configDir;
+    configPath;
+    rateCounters = new Map();
+    constructor(configDir) {
+        this.configDir = configDir ?? CLAWNEXUS_DIR;
+        this.configPath = path.join(this.configDir, "policy.json");
+    }
+    async init() {
+        await fs.promises.mkdir(this.configDir, { recursive: true });
+        if (fs.existsSync(this.configPath)) {
+            try {
+                const raw = await fs.promises.readFile(this.configPath, "utf-8");
+                const data = JSON.parse(raw);
+                this.config = { ...DEFAULT_POLICY, ...data };
+            }
+            catch {
+                // Corrupted — use defaults
+                this.config = { ...DEFAULT_POLICY };
+            }
+        }
+        else {
+            await this.saveConfig();
+        }
+    }
+    evaluate(envelope, peerTrustScore = 0) {
+        const peer = envelope.from;
+        // 1. Blacklist check
+        if (this.config.access_control.blacklist.includes(peer)) {
+            return { result: "reject", reason: "policy_denied", details: "Peer is blacklisted" };
+        }
+        // 2. Rate limit check
+        if (this.isRateLimited(peer)) {
+            return { result: "reject", reason: "rate_limited", details: "Rate limit exceeded" };
+        }
+        this.incrementRate(peer);
+        // 3. Whitelist check — whitelisted peers bypass trust/capability checks
+        const isWhitelisted = this.config.access_control.whitelist.includes(peer);
+        // 4. Trust score check (skip for whitelisted)
+        if (!isWhitelisted && peerTrustScore < this.config.trust_threshold) {
+            return { result: "reject", reason: "trust_insufficient", details: `Score ${peerTrustScore} < threshold ${this.config.trust_threshold}` };
+        }
+        // 5. Delegation depth check
+        if (envelope.type === "delegate") {
+            const dp = envelope.payload;
+            if (!this.config.delegation.allow) {
+                return { result: "reject", reason: "policy_denied", details: "Delegation not allowed" };
+            }
+            if ((dp.task?.delegation_depth ?? 0) > this.config.delegation.max_depth) {
+                return { result: "reject", reason: "policy_denied", details: "Delegation depth exceeded" };
+            }
+        }
+        // 6. Capability filter (if non-empty, task_type must match)
+        if (envelope.type === "propose" || envelope.type === "delegate") {
+            const task = envelope.type === "propose"
+                ? envelope.payload.task
+                : envelope.payload.task;
+            if (this.config.capability_filter.length > 0) {
+                const matches = this.config.capability_filter.some((pattern) => task.task_type === pattern || matchGlob(pattern, task.task_type));
+                if (!matches) {
+                    return { result: "reject", reason: "capability_mismatch", details: `task_type "${task.task_type}" not in capability filter` };
+                }
+            }
+        }
+        // 7. Approval mode
+        switch (this.config.mode) {
+            case "auto":
+                return { result: "accept", reason: "auto_approved" };
+            case "queue":
+                return { result: "queue", reason: "queued_for_review" };
+            case "hybrid": {
+                if (isWhitelisted) {
+                    return { result: "accept", reason: "auto_approved", details: "Whitelisted peer" };
+                }
+                // Check auto_approve_types
+                if (envelope.type === "propose") {
+                    const taskType = envelope.payload.task.task_type;
+                    if (this.config.auto_approve_types.includes(taskType)) {
+                        return { result: "accept", reason: "auto_approved", details: `task_type "${taskType}" auto-approved` };
+                    }
+                }
+                return { result: "queue", reason: "queued_for_review" };
+            }
+            default:
+                return { result: "queue", reason: "queued_for_review" };
+        }
+    }
+    getConfig() {
+        return { ...this.config };
+    }
+    async updateConfig(full) {
+        this.config = { ...full };
+        await this.saveConfig();
+    }
+    async patchConfig(partial) {
+        this.config = deepMerge(this.config, partial);
+        await this.saveConfig();
+    }
+    async resetConfig() {
+        this.config = { ...DEFAULT_POLICY };
+        await this.saveConfig();
+    }
+    isRateLimited(peer) {
+        const now = Date.now();
+        // Global rate
+        const global = this.rateCounters.get("__global__");
+        if (global && global.resetAt > now && global.count >= this.config.rate_limit.max_per_minute) {
+            return true;
+        }
+        // Per-peer rate
+        const peerRate = this.rateCounters.get(peer);
+        if (peerRate && peerRate.resetAt > now && peerRate.count >= this.config.rate_limit.max_per_peer_minute) {
+            return true;
+        }
+        return false;
+    }
+    incrementRate(peer) {
+        const now = Date.now();
+        const windowEnd = now + 60_000;
+        for (const key of ["__global__", peer]) {
+            const existing = this.rateCounters.get(key);
+            if (!existing || existing.resetAt <= now) {
+                this.rateCounters.set(key, { count: 1, resetAt: windowEnd });
+            }
+            else {
+                existing.count++;
+            }
+        }
+    }
+    async saveConfig() {
+        const json = JSON.stringify(this.config, null, 2);
+        const tmpPath = this.configPath + ".tmp";
+        await fs.promises.writeFile(tmpPath, json, "utf-8");
+        await fs.promises.rename(tmpPath, this.configPath);
+    }
+}
+exports.PolicyEngine = PolicyEngine;
+function matchGlob(pattern, value) {
+    // Simple glob: only supports trailing *
+    if (pattern.endsWith("*")) {
+        return value.startsWith(pattern.slice(0, -1));
+    }
+    return pattern === value;
+}
+function deepMerge(target, source) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const result = { ...target };
+    const src = source;
+    const tgt = target;
+    for (const key of Object.keys(src)) {
+        const sv = src[key];
+        const tv = tgt[key];
+        if (sv !== null &&
+            sv !== undefined &&
+            typeof sv === "object" &&
+            !Array.isArray(sv) &&
+            tv !== null &&
+            tv !== undefined &&
+            typeof tv === "object" &&
+            !Array.isArray(tv)) {
+            result[key] = { ...tv, ...sv };
+        }
+        else if (sv !== undefined) {
+            result[key] = sv;
+        }
+    }
+    return result;
+}

package/dist/agent/protocol.d.ts

@@ -0,0 +1,12 @@
+import type { LayerBEnvelope, LayerBMessageType, LayerBPayload } from "./types.js";
+export interface EnvelopeOptions {
+    in_reply_to?: string;
+    ttl?: number;
+}
+export declare function createEnvelope(from: string, to: string, type: LayerBMessageType, payload: LayerBPayload, opts?: EnvelopeOptions): LayerBEnvelope;
+export declare class ProtocolError extends Error {
+    constructor(message: string);
+}
+export declare function parseEnvelope(raw: string): LayerBEnvelope;
+export declare function validatePayload(type: LayerBMessageType, payload: LayerBPayload): void;
+export declare function isExpired(envelope: LayerBEnvelope): boolean;

package/dist/agent/protocol.js

@@ -0,0 +1,159 @@
+"use strict";
+// Layer B — Message Protocol
+// Pure functions: envelope construction, parsing, validation
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProtocolError = void 0;
+exports.createEnvelope = createEnvelope;
+exports.parseEnvelope = parseEnvelope;
+exports.validatePayload = validatePayload;
+exports.isExpired = isExpired;
+const node_crypto_1 = require("node:crypto");
+const PROTOCOL = "clawnexus-agent";
+const VERSION = "1.0";
+const DEFAULT_TTL = 300; // 5 minutes
+const VALID_TYPES = new Set([
+    "query", "propose", "accept", "reject", "delegate",
+    "report", "cancel", "capability", "heartbeat",
+]);
+function createEnvelope(from, to, type, payload, opts) {
+    return {
+        protocol: PROTOCOL,
+        version: VERSION,
+        message_id: (0, node_crypto_1.randomUUID)(),
+        in_reply_to: opts?.in_reply_to,
+        from,
+        to,
+        type,
+        payload,
+        timestamp: new Date().toISOString(),
+        ttl: opts?.ttl ?? DEFAULT_TTL,
+    };
+}
+class ProtocolError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ProtocolError";
+    }
+}
+exports.ProtocolError = ProtocolError;
+function parseEnvelope(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new ProtocolError("Invalid JSON");
+    }
+    const obj = parsed;
+    if (obj.protocol !== PROTOCOL) {
+        throw new ProtocolError(`Unknown protocol: ${obj.protocol}`);
+    }
+    if (obj.version !== VERSION) {
+        throw new ProtocolError(`Unsupported version: ${obj.version}`);
+    }
+    if (!obj.message_id || typeof obj.message_id !== "string") {
+        throw new ProtocolError("Missing message_id");
+    }
+    if (!obj.from || typeof obj.from !== "string") {
+        throw new ProtocolError("Missing from");
+    }
+    if (!obj.to || typeof obj.to !== "string") {
+        throw new ProtocolError("Missing to");
+    }
+    if (!VALID_TYPES.has(obj.type)) {
+        throw new ProtocolError(`Invalid type: ${obj.type}`);
+    }
+    if (!obj.payload || typeof obj.payload !== "object") {
+        throw new ProtocolError("Missing payload");
+    }
+    if (!obj.timestamp || typeof obj.timestamp !== "string") {
+        throw new ProtocolError("Missing timestamp");
+    }
+    validatePayload(obj.type, obj.payload);
+    return obj;
+}
+function validatePayload(type, payload) {
+    switch (type) {
+        case "query": {
+            const p = payload;
+            if (!p.query_type)
+                throw new ProtocolError("query: missing query_type");
+            if (!["capabilities", "status", "availability"].includes(p.query_type)) {
+                throw new ProtocolError(`query: invalid query_type: ${p.query_type}`);
+            }
+            break;
+        }
+        case "propose": {
+            const p = payload;
+            if (!p.task)
+                throw new ProtocolError("propose: missing task");
+            if (!p.task.task_type)
+                throw new ProtocolError("propose: missing task.task_type");
+            if (!p.task.description)
+                throw new ProtocolError("propose: missing task.description");
+            if (p.task.delegation_depth !== undefined && p.task.delegation_depth > 5) {
+                throw new ProtocolError("propose: delegation_depth exceeds hard cap (5)");
+            }
+            break;
+        }
+        case "accept": {
+            const p = payload;
+            if (!p.task_id)
+                throw new ProtocolError("accept: missing task_id");
+            break;
+        }
+        case "reject": {
+            const p = payload;
+            if (!p.task_id)
+                throw new ProtocolError("reject: missing task_id");
+            if (!p.reason)
+                throw new ProtocolError("reject: missing reason");
+            break;
+        }
+        case "delegate": {
+            const p = payload;
+            if (!p.task_id)
+                throw new ProtocolError("delegate: missing task_id");
+            if (!p.original_from)
+                throw new ProtocolError("delegate: missing original_from");
+            if (!p.task)
+                throw new ProtocolError("delegate: missing task");
+            break;
+        }
+        case "report": {
+            const p = payload;
+            if (!p.task_id)
+                throw new ProtocolError("report: missing task_id");
+            if (!p.status)
+                throw new ProtocolError("report: missing status");
+            if (!["completed", "failed", "progress"].includes(p.status)) {
+                throw new ProtocolError(`report: invalid status: ${p.status}`);
+            }
+            break;
+        }
+        case "cancel": {
+            const p = payload;
+            if (!p.task_id)
+                throw new ProtocolError("cancel: missing task_id");
+            break;
+        }
+        case "capability": {
+            const p = payload;
+            if (!Array.isArray(p.capabilities)) {
+                throw new ProtocolError("capability: missing capabilities array");
+            }
+            break;
+        }
+        case "heartbeat": {
+            const p = payload;
+            if (!p.task_id)
+                throw new ProtocolError("heartbeat: missing task_id");
+            break;
+        }
+    }
+}
+function isExpired(envelope) {
+    const ttl = envelope.ttl ?? DEFAULT_TTL;
+    const created = new Date(envelope.timestamp).getTime();
+    return Date.now() - created > ttl * 1000;
+}

package/dist/agent/router.d.ts

@@ -0,0 +1,41 @@
+import { EventEmitter } from "node:events";
+import type { RelayConnector } from "../relay/connector.js";
+import type { PolicyEngine } from "./engine.js";
+import type { TaskManager } from "./tasks.js";
+import type { LayerBEnvelope, ProposePayload, TaskRecord } from "./types.js";
+export interface AgentRouterOptions {
+    connector: RelayConnector;
+    engine: PolicyEngine;
+    tasks: TaskManager;
+    localClawId: string;
+}
+export declare class AgentRouter extends EventEmitter {
+    private readonly connector;
+    private readonly engine;
+    private readonly tasks;
+    private readonly localClawId;
+    private dataHandler;
+    private inbox;
+    constructor(opts: AgentRouterOptions);
+    start(): void;
+    stop(): void;
+    sendMessage(roomId: string, envelope: LayerBEnvelope): boolean;
+    /** Initiate a propose to a peer (outbound task) */
+    propose(roomId: string, targetClawId: string, task: ProposePayload["task"]): TaskRecord;
+    /** Send a query to a peer */
+    query(roomId: string, targetClawId: string, queryType: "capabilities" | "status" | "availability"): LayerBEnvelope;
+    /** Approve a queued inbound proposal */
+    approveInbox(messageId: string): TaskRecord | null;
+    /** Deny a queued inbound proposal */
+    denyInbox(messageId: string, reason?: string): void;
+    /** Get pending inbox items */
+    getInbox(): Array<{
+        message_id: string;
+        envelope: LayerBEnvelope;
+        roomId: string;
+    }>;
+    private handleData;
+    private handleProposal;
+    private acceptProposal;
+    private handleQuery;
+}